feat(vscode): add oxc.requireConfig configuration (#11700)

Sysix · Sysix · commit 0b4261bb9444 · 2025-06-16T08:59:10.000Z
closes #11628 ![screen recording, showing that the language server will output diagnostics, when one `.oxlintrc.json` file is created](https://github.com/user-attachments/assets/7f4d6688-29da-479b-b19b-8cf25c82cac5)
diff --git a/editors/vscode/README.md b/editors/vscode/README.md
@@ -27,11 +27,12 @@ This is the linter for Oxc. The currently supported features are listed below.
 
 Following configuration are supported via `settings.json` and effect the window editor:
 
-| Key                | Default Value | Possible Values                  | Description                                                                 |
-| ------------------ | ------------- | -------------------------------- | --------------------------------------------------------------------------- |
-| `oxc.enable`       | `true`        | `true` \| `false`                | Enables the language server to receive lint diagnostics                     |
-| `oxc.trace.server` | `off`         | `off` \| `messages` \| `verbose` | Traces the communication between VS Code and the language server.           |
-| `oxc.path.server`  | -             | `<string>`                       | Path to Oxc language server binary. Mostly for testing the language server. |
+| Key                 | Default Value | Possible Values                  | Description                                                                                  |
+| ------------------- | ------------- | -------------------------------- | -------------------------------------------------------------------------------------------- |
+| `oxc.enable`        | `true`        | `true` \| `false`                | Enables the language server to receive lint diagnostics                                      |
+| `oxc.requireConfig` | `false`       | `true` \| `false`                | Start the language server only when a `.oxlintrc.json` file exists in one of the workspaces. |
+| `oxc.trace.server`  | `off`         | `off` \| `messages` \| `verbose` | Traces the communication between VS Code and the language server.                            |
+| `oxc.path.server`   | -             | `<string>`                       | Path to Oxc language server binary. Mostly for testing the language server.                  |
 
 ### Workspace Configuration
 
diff --git a/editors/vscode/client/VSCodeConfig.ts b/editors/vscode/client/VSCodeConfig.ts
@@ -5,6 +5,7 @@ export class VSCodeConfig implements VSCodeConfigInterface {
   private _enable!: boolean;
   private _trace!: TraceLevel;
   private _binPath: string | undefined;
+  private _requireConfig!: boolean;
 
   constructor() {
     this.refresh();
@@ -18,6 +19,7 @@ export class VSCodeConfig implements VSCodeConfigInterface {
     this._enable = this.configuration.get<boolean>('enable') ?? true;
     this._trace = this.configuration.get<TraceLevel>('trace.server') || 'off';
     this._binPath = this.configuration.get<string>('path.server');
+    this._requireConfig = this.configuration.get<boolean>('requireConfig') ?? false;
   }
 
   get enable(): boolean {
@@ -46,9 +48,19 @@ export class VSCodeConfig implements VSCodeConfigInterface {
     this._binPath = value;
     return this.configuration.update('path.server', value);
   }
+
+  get requireConfig(): boolean {
+    return this._requireConfig;
+  }
+
+  updateRequireConfig(value: boolean): PromiseLike<void> {
+    this._requireConfig = value;
+    return this.configuration.update('requireConfig', value);
+  }
 }
 
 type TraceLevel = 'off' | 'messages' | 'verbose';
+
 /**
  * See `"contributes.configuration"` in `package.json`
  */
@@ -72,4 +84,10 @@ interface VSCodeConfigInterface {
    * @default undefined
    */
   binPath: string | undefined;
+  /**
+   * Start the language server only when a `.oxlintrc.json` file exists in one of the workspaces.
+   * `oxc.requireConfig`
+   * @default false
+   */
+  requireConfig: boolean;
 }
diff --git a/editors/vscode/client/extension.ts b/editors/vscode/client/extension.ts
@@ -22,6 +22,7 @@ import { Executable, LanguageClient, LanguageClientOptions, ServerOptions } from
 
 import { join } from 'node:path';
 import { ConfigService } from './ConfigService';
+import { VSCodeConfig } from './VSCodeConfig';
 
 const languageClientName = 'oxc';
 const outputChannelName = 'Oxc';
@@ -42,8 +43,16 @@ let client: LanguageClient | undefined;
 
 let myStatusBarItem: StatusBarItem;
 
+// Global flag to check if the user allows us to start the server.
+// When `oxc.requireConfig` is `true`, make sure one `.oxlintrc.json` file is present.
+let allowedToStartServer: boolean;
+
 export async function activate(context: ExtensionContext) {
   const configService = new ConfigService();
+  allowedToStartServer = configService.vsCodeConfig.requireConfig
+    ? (await workspace.findFiles(`**/.oxlintrc.json`, '**/node_modules/**', 1)).length > 0
+    : true;
+
   const restartCommand = commands.registerCommand(
     OxcCommands.RestartServer,
     async () => {
@@ -77,7 +86,7 @@ export async function activate(context: ExtensionContext) {
     async () => {
       await configService.vsCodeConfig.updateEnable(!configService.vsCodeConfig.enable);
 
-      if (client === undefined) {
+      if (client === undefined || !allowedToStartServer) {
         return;
       }
 
@@ -245,7 +254,7 @@ export async function activate(context: ExtensionContext) {
   context.subscriptions.push(onDidChangeWorkspaceFoldersDispose);
 
   configService.onConfigChange = async function onConfigChange(event) {
-    updateStatsBar(this.vsCodeConfig.enable);
+    updateStatsBar(context, this.vsCodeConfig.enable);
 
     if (client === undefined) {
       return;
@@ -264,29 +273,13 @@ export async function activate(context: ExtensionContext) {
     }
   };
 
-  function updateStatsBar(enable: boolean) {
-    if (!myStatusBarItem) {
-      myStatusBarItem = window.createStatusBarItem(
-        StatusBarAlignment.Right,
-        100,
-      );
-      myStatusBarItem.command = OxcCommands.ToggleEnable;
-      context.subscriptions.push(myStatusBarItem);
-      myStatusBarItem.show();
+  updateStatsBar(context, configService.vsCodeConfig.enable);
+  if (allowedToStartServer) {
+    if (configService.vsCodeConfig.enable) {
+      await client.start();
     }
-    let bgColor = new ThemeColor(
-      enable
-        ? 'statusBarItem.activeBackground'
-        : 'statusBarItem.warningBackground',
-    );
-    myStatusBarItem.text = `oxc: ${enable ? '$(check-all)' : '$(check)'}`;
-
-    myStatusBarItem.backgroundColor = bgColor;
-  }
-
-  updateStatsBar(configService.vsCodeConfig.enable);
-  if (configService.vsCodeConfig.enable) {
-    await client.start();
+  } else {
+    generateActivatorByConfig(configService.vsCodeConfig, context);
   }
 }
 
@@ -297,3 +290,47 @@ export async function deactivate(): Promise<void> {
   await client.stop();
   client = undefined;
 }
+
+function updateStatsBar(
+  context: ExtensionContext,
+  enable: boolean,
+) {
+  if (!myStatusBarItem) {
+    myStatusBarItem = window.createStatusBarItem(
+      StatusBarAlignment.Right,
+      100,
+    );
+    myStatusBarItem.command = OxcCommands.ToggleEnable;
+    context.subscriptions.push(myStatusBarItem);
+    myStatusBarItem.show();
+  }
+  let bgColor: string;
+  let icon: string;
+  if (!allowedToStartServer) {
+    bgColor = 'statusBarItem.offlineBackground';
+    icon = '$(circle-slash)';
+  } else if (!enable) {
+    bgColor = 'statusBarItem.warningBackground';
+    icon = '$(check)';
+  } else {
+    bgColor = 'statusBarItem.activeBackground';
+    icon = '$(check-all)';
+  }
+
+  myStatusBarItem.text = `oxc: ${icon}`;
+  myStatusBarItem.backgroundColor = new ThemeColor(bgColor);
+}
+
+function generateActivatorByConfig(config: VSCodeConfig, context: ExtensionContext): void {
+  const watcher = workspace.createFileSystemWatcher('**/.oxlintrc.json', false, true, true);
+  watcher.onDidCreate(async () => {
+    watcher.dispose();
+    allowedToStartServer = true;
+    updateStatsBar(context, config.enable);
+    if (client && !client.isRunning() && config.enable) {
+      await client.start();
+    }
+  });
+
+  context.subscriptions.push(watcher);
+}
diff --git a/editors/vscode/package.json b/editors/vscode/package.json
@@ -80,6 +80,12 @@
           "scope": "window",
           "description": "enable oxc language server"
         },
+        "oxc.requireConfig": {
+          "scope": "resource",
+          "type": "boolean",
+          "default": false,
+          "description": "Start the language server only when a `.oxlintrc.json` file exists in one of the workspaces."
+        },
         "oxc.trace.server": {
           "type": "string",
           "scope": "window",
diff --git a/editors/vscode/tests/VSCodeConfig.spec.ts b/editors/vscode/tests/VSCodeConfig.spec.ts
@@ -7,13 +7,13 @@ const conf = workspace.getConfiguration('oxc');
 
 suite('VSCodeConfig', () => {
   setup(async () => {
-    const keys = ['enable', 'trace.server', 'path.server'];
+    const keys = ['enable', 'requireConfig', 'trace.server', 'path.server'];
 
     await Promise.all(keys.map(key => conf.update(key, undefined)));
   });
 
   teardown(async () => {
-    const keys = ['enable', 'trace.server', 'path.server'];
+    const keys = ['enable', 'requireConfig', 'trace.server', 'path.server'];
 
     await Promise.all(keys.map(key => conf.update(key, undefined)));
   });
@@ -22,6 +22,7 @@ suite('VSCodeConfig', () => {
     const config = new VSCodeConfig();
 
     strictEqual(config.enable, true);
+    strictEqual(config.requireConfig, false);
     strictEqual(config.trace, 'off');
     strictEqual(config.binPath, '');
   });
@@ -31,13 +32,15 @@ suite('VSCodeConfig', () => {
 
     await Promise.all([
       config.updateEnable(false),
+      config.updateRequireConfig(true),
       config.updateTrace('messages'),
       config.updateBinPath('./binary'),
     ]);
 
     const wsConfig = workspace.getConfiguration('oxc');
 
     strictEqual(wsConfig.get('enable'), false);
+    strictEqual(wsConfig.get('requireConfig'), true);
     strictEqual(wsConfig.get('trace.server'), 'messages');
     strictEqual(wsConfig.get('path.server'), './binary');
   });
