VSCode Window Messages Best Practices

Quick Reference: Critical Rules

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'));
}

Error Toast with Action Buttons

Non-modal error toast whose buttons run an action (e.g. Open Report): use NotificationModeService.showErrorWithActions, not showErrorMessage(...).then(...). It returns without waiting for the click and shows an error if the action rejects (notification-mode-api).

yield* notificationMode.showErrorWithActions(nls.localize('operation_completed_with_errors'), [
  { label: nls.localize('open_report_button'), run: () => openReport(uri) }
]);

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.