OpenParable
Skip to content
← Back to skills

Vscode Window Messages

Development
vscode-window-messages

Vscode Window Messages is an Agent Skill for development published in the forcedotcom/salesforcedx-vscode repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Guidelines for using vscode.window.show*Message methods. Use when working with showInformationMessage, showWarningMessage, showErrorMessage.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/forcedotcom/salesforcedx-vscode/blob/HEAD/.claude/skills/vscode-window-messages/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/vscode-window-messages, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

VSCode Window Messages Best Practices

Quick Reference: Critical Rules

CategoryDODON'T
APIDirect vscode.window.show*MessageLegacy NotificationService
Messagesnls.localize('key', ...args)String literals or template literals without nls
Return ValuesHandle Thenable<string | undefined> or Thenable<MessageItem | undefined>Ignore return values
Button ActionsCheck return value for button clicksAssume user always clicks
Button Actionsnls.localizeString literals or template literals without nls
Modal Options{ modal: true, detail: ... } for blocking dialogsdetail without modal: true (detail modal-only); explicit 'Cancel' buttons (VS Code adds one automatically)
Effect (wait)Effect.promise() when response neededEffect.promise() for fire-and-forget
Effect (no wait)Effect.sync() for fire-and-forgetEffect.promise() when not waiting

Use Direct vscode.window Calls

Use vscode.window.show*Message directly. Don't use legacy NotificationService in new code.

import * as vscode from 'vscode';
import { nls } from '../messages/messages';

// CORRECT
await vscode.window.showInformationMessage(nls.localize('retrieve_canceled'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', String(error)));

// WRONG
await notificationService.showInformationMessage(nls.localize('retrieve_canceled'));

Internationalization with nls.localize()

All message strings and button labels must use nls.localize(). Enforced by no-vscode-message-literals ESLint rule.

Button labels should use nls.localize() even for command titles. Importing package.nls.json directly strips locale context—only manifest %key% reads locale-specific JSON files. Use nls.localize() to preserve Japanese and other locales via i18n.ja.ts.

// CORRECT
await vscode.window.showInformationMessage(nls.localize('retrieve_canceled'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', String(error)));
await vscode.window.showInformationMessage(`${nls.localize('prefix')} ${nls.localize('suffix')}`);

const answer = await vscode.window.showWarningMessage(
  nls.localize('confirm_delete'),
  nls.localize('yes_button'),
  nls.localize('no_button')
);

// WRONG
await vscode.window.showInformationMessage('Operation successful');
await vscode.window.showInformationMessage(`Operation ${status} successful`);
await vscode.window.showWarningMessage(nls.localize('confirm_delete'), 'Yes', 'No');

Adding new messages:

  1. Add key/value to i18n.ts in package
  2. Use nls.localize('your_message_key', ...args)

Handling Return Values

Returns clicked button or undefined if dismissed.

Return types:

  • String buttons: Thenable<string | undefined>
  • MessageItem buttons: Thenable<MessageItem | undefined>
// CORRECT - String buttons
const selection = await vscode.window.showWarningMessage(
  nls.localize('unsaved_changes'),
  nls.localize('save_button'),
  nls.localize('discard_button')
);

if (selection === nls.localize('save_button')) {
  await saveFile();
}

// CORRECT - MessageItem buttons
const item = await vscode.window.showWarningMessage(
  nls.localize('unsaved_changes'),
  { modal: true },
  { title: nls.localize('save_button') },
  { title: nls.localize('discard_button') }
);

if (item?.title === nls.localize('save_button')) {
  await saveFile();
}

// CORRECT - Fire and forget
void vscode.window.showInformationMessage(nls.localize('operation_completed'));

// WRONG
vscode.window.showInformationMessage(nls.localize('operation_completed')); // Missing void

Integration with Effect

When User Response is Required

Use Effect.promise() to wait for user response. Blocks execution until user responds.

import { Effect } from 'effect';

// CORRECT - Wait for response
const selection =
  yield *
  Effect.promise(() =>
    vscode.window.showWarningMessage(nls.localize('confirm_action'), nls.localize('yes'), nls.localize('no'))
  );

if (selection === nls.localize('yes')) {
  yield * performAction();
}

// CORRECT - Wait for error acknowledgment
yield * Effect.promise(() => vscode.window.showErrorMessage(nls.localize('critical_error')));

When User Response is NOT Required (Fire-and-Forget)

Use Effect.sync() for non-blocking messages. Execution continues immediately.

import { Effect } from 'effect';

// CORRECT - Fire and forget
yield *
  Effect.sync(() => {
    void vscode.window.showInformationMessage(nls.localize('background_task_started'));
  });

yield * performBackgroundTask();

// WRONG - Blocks unnecessarily
yield * Effect.promise(() => vscode.window.showInformationMessage(nls.localize('background_task_started')));

// WRONG - Direct call in Effect.gen
yield *
  Effect.gen(function* () {
    await vscode.window.showErrorMessage('Error'); // Type error
  });

Message Types

  • showInformationMessage: Success, info, non-critical
  • showWarningMessage: Warnings, recoverable errors, user decisions
  • showErrorMessage: Errors, failures, critical issues
await vscode.window.showInformationMessage(nls.localize('retrieve_completed'));
await vscode.window.showWarningMessage(nls.localize('unsaved_changes'));
await vscode.window.showErrorMessage(nls.localize('retrieve_failed', errorMessage));

// Modal with detail (detail only shown for modal)
await vscode.window.showWarningMessage(
  nls.localize('destructive_action_warning'),
  { modal: true, detail: nls.localize('destructive_action_detail') },
  nls.localize('confirm')
);

Note: VS Code automatically adds a 'Cancel' button to modal dialogs. Do not add an explicit nls.localize('cancel_button') as an item when modal: true. Dismissing the dialog (via 'Cancel' or ESC) returns undefined.

MessageOptions and MessageItem

MessageOptions

  • modal?: boolean - System modal dialog, blocks interaction
  • detail?: string - Extra text (modal only)

Button Types

Strings or MessageItem objects:

// String buttons (prefer)
const result = await vscode.window.showWarningMessage(
  nls.localize('confirm_action'),
  nls.localize('yes'),
  nls.localize('no')
);
// result: string | undefined

// MessageItem (for modal ESC handling)
const result = await vscode.window.showWarningMessage(
  nls.localize('confirm_action'),
  { modal: true },
  { title: nls.localize('yes'), isCloseAffordance: false },
  { title: nls.localize('no'), isCloseAffordance: true }
);
// result: MessageItem | undefined

isCloseAffordance: true = button handles ESC. Modal-only. Modals auto-add Cancel; use this to control which custom button handles ESC.

Common Patterns

Conditional Messages

// Fire-and-forget
if (hasErrors) {
  void vscode.window.showErrorMessage(nls.localize('operation_completed_with_errors'));
} else {
  void vscode.window.showInformationMessage(nls.localize('operation_completed_successfully'));
}

User Confirmation (Requires Response)

import { Effect } from 'effect';

const confirm =
  yield *
  Effect.promise(() =>
    vscode.window.showWarningMessage(
      nls.localize('confirm_destructive_action'),
      nls.localize('proceed_button')
    )
  );

if (confirm === nls.localize('proceed_button')) {
  yield * performDestructiveAction();
}

ESLint Rule

no-vscode-message-literals enforces:

  • No string literals as first argument
  • No template literals unless they contain nls.localize() calls
  • Applies to showInformationMessage, showWarningMessage, showErrorMessage

Run npm run lint before committing.