mizdra · mizdra · Apr 11, 2026 · Apr 11, 2026
diff --git a/.changeset/breaking-enabled-opt-in.md b/.changeset/breaking-enabled-opt-in.md
@@ -0,0 +1,10 @@
+---
+'@css-modules-kit/core': major
+'@css-modules-kit/ts-plugin': major
+'@css-modules-kit/codegen': major
+---
+
+feat(core, ts-plugin, codegen)!: require `cmkOptions.enabled: true` to activate
+
+ts-plugin and codegen are now only enabled when `cmkOptions.enabled` is explicitly set to `true` in tsconfig.json.
+Previously they worked even without the option. See #289 for background.
diff --git a/README.md b/README.md
@@ -122,9 +122,11 @@ css-modules-kit uses `tsconfig.json` as its configuration file. This configurati
 
 ### `cmkOptions.enabled`
 
-Type: `boolean`, Default: `true`
+Type: `boolean`, Default: `false`
+
+Enables or disables css-modules-kit. Language features in the ts-plugin and code generation in codegen are only activated when this option is set to `true`. When set to `false` or omitted, codegen will exit with an error and ts-plugin will not provide language features.
 
-Enables or disables css-modules-kit. When set to `false`, codegen will exit with an error. Currently, both codegen and the ts-plugin will work even if this option is omitted, but in the future, they will not work unless this option is set to `true`. For more details, see [#289](https://github.com/mizdra/css-modules-kit/issues/289).
+All `cmkOptions.*` options (including this one) can be inherited via `extends` in `tsconfig.json`, so you can share settings across multiple projects by putting them in a base config.
 
 ```jsonc
 {

diff --git a/packages/codegen/src/error.ts b/packages/codegen/src/error.ts
@@ -23,7 +23,7 @@ export class CMKDisabledError extends SystemError {
   constructor(config: CMKConfig) {
     super(
       'CMK_DISABLED_ERROR',
-      `css-modules-kit is disabled by configuration. Set \`"cmkOptions": { "enabled": true }\` in ${relative(config.basePath, config.configFileName)} to enable it.`,
+      `css-modules-kit is disabled for this project. Set \`"cmkOptions": { "enabled": true }\` in ${relative(config.basePath, config.configFileName)} to enable it.`,
     );
   }
 }
diff --git a/packages/codegen/src/project.test.ts b/packages/codegen/src/project.test.ts
@@ -394,22 +394,6 @@ describe('getDiagnostics', () => {
     const diagnostics = project.getDiagnostics();
     expect(diagnostics).toEqual([]);
   });
-  test('returns warning when enabled is not specified', async () => {
-    const iff = await createIFF({
-      'tsconfig.json': '{}',
-      'src/a.module.css': '.a_1 { color: red; }',
-    });
-    const project = createProject({ project: iff.rootDir });
-    const diagnostics = project.getDiagnostics();
-    expect(formatDiagnostics(diagnostics, iff.rootDir)).toMatchInlineSnapshot(`
-      [
-        {
-          "category": "warning",
-          "text": ""cmkOptions.enabled" will be required in a future version of css-modules-kit. Add \`"cmkOptions": { "enabled": true }\` to tsconfig.json. See https://github.com/mizdra/css-modules-kit/issues/289 for details.",
-        },
-      ]
-    `);
-  });
   test('returns project diagnostics', async () => {
     const iff = await createIFF({
       'tsconfig.json': '{ "cmkOptions": { "enabled": true, "dtsOutDir": 1 } }',

diff --git a/packages/codegen/src/project.ts b/packages/codegen/src/project.ts
@@ -10,7 +10,6 @@ import {
   getFileNamesByPattern,
   parseCSSModule,
   readConfigFile,
-  relative,
 } from '@css-modules-kit/core';
 import ts from 'typescript';
 import { writeDtsFile } from './dts-writer.js';
@@ -167,12 +166,6 @@ export function createProject(args: ProjectArgs): Project {
   function getProjectDiagnostics() {
     const diagnostics: Diagnostic[] = [];
     diagnostics.push(...config.diagnostics);
-    if (config.enabled === undefined) {
-      diagnostics.push({
-        category: 'warning',
-        text: `"cmkOptions.enabled" will be required in a future version of css-modules-kit. Add \`"cmkOptions": { "enabled": true }\` to ${relative(config.basePath, config.configFileName)}. See https://github.com/mizdra/css-modules-kit/issues/289 for details.`,
-      });
-    }
     if (cssModuleMap.size === 0) {
       diagnostics.push({
         category: 'error',

diff --git a/packages/codegen/src/runner.test.ts b/packages/codegen/src/runner.test.ts
@@ -20,7 +20,7 @@ describe('runCMK', () => {
     const iff = await createIFF({
       'tsconfig.json': dedent`
         {
-          "cmkOptions": { "dtsOutDir": "generated" }
+          "cmkOptions": { "enabled": true, "dtsOutDir": "generated" }
         }
       `,
       'src/a.module.css': '.a_1 { color: red; }',
@@ -101,7 +101,7 @@ describe('runCMK', () => {
     await expect(access(iff.join('generated/src/a.module.css.d.ts'))).resolves.not.toThrow();
     await expect(access(iff.join('generated/src/old.module.css.d.ts'))).rejects.toThrow();
   });
-  test('throws CMKDisabledError if enabled is false', async () => {
+  test('throws CMKDisabledError if enabled is not true', async () => {
     const iff = await createIFF({
       'tsconfig.json': '{ "cmkOptions": { "enabled": false } }',
       'src/a.module.css': '.a_1 { color: red; }',
@@ -122,7 +122,7 @@ describe('runCMKInWatchMode', () => {
     const iff = await createIFF({
       'tsconfig.json': dedent`
         {
-          "cmkOptions": { "dtsOutDir": "generated" }
+          "cmkOptions": { "enabled": true, "dtsOutDir": "generated" }
         }
       `,
       'src/a.module.css': '.a_1 { color: red; }',
@@ -313,7 +313,7 @@ describe('runCMKInWatchMode', () => {
     watcher = await runCMKInWatchMode(fakeParsedArgs({ project: iff.rootDir, preserveWatchOutput: true }), loggerSpy2);
     expect(loggerSpy2.clearScreen).toHaveBeenCalledTimes(0);
   });
-  test('throws CMKDisabledError if enabled is false', async () => {
+  test('throws CMKDisabledError if enabled is not true', async () => {
     const iff = await createIFF({
       'tsconfig.json': '{ "cmkOptions": { "enabled": false } }',
       'src/a.module.css': '.a_1 { color: red; }',

diff --git a/packages/codegen/src/runner.ts b/packages/codegen/src/runner.ts
@@ -34,7 +34,7 @@ export interface Watcher {
  */
 export async function runCMK(args: RunnerArgs, logger: Logger): Promise<boolean> {
   const project = createProject(args);
-  if (project.config.enabled === false) {
+  if (!project.config.enabled) {
     throw new CMKDisabledError(project.config);
   }
   if (args.clean) {
@@ -66,7 +66,7 @@ export async function runCMK(args: RunnerArgs, logger: Logger): Promise<boolean>
 export async function runCMKInWatchMode(args: RunnerArgs, logger: Logger): Promise<Watcher> {
   const fsWatchers: FSWatcher[] = [];
   const project = createProject(args);
-  if (project.config.enabled === false) {
+  if (!project.config.enabled) {
     throw new CMKDisabledError(project.config);
   }
   let emitAndReportDiagnosticsTimer: NodeJS.Timeout | undefined = undefined;

diff --git a/packages/core/src/config.test.ts b/packages/core/src/config.test.ts
@@ -27,7 +27,7 @@ describe('readConfigFile', () => {
         namedExports: false,
         prioritizeNamedImports: false,
         keyframes: true,
-        enabled: undefined,
+        enabled: false,
         compilerOptions: expect.any(Object),
         wildcardDirectories: [{ fileName: iff.rootDir, recursive: true }],
       }),

diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
@@ -13,7 +13,7 @@ const DEFAULT_INCLUDE_SPEC = '**/*';
 export interface CMKConfig {
   includes: string[];
   excludes: string[];
-  enabled: boolean | undefined;
+  enabled: boolean;
   dtsOutDir: string;
   arbitraryExtensions: boolean;
   namedExports: boolean;
@@ -266,7 +266,7 @@ export function readConfigFile(project: string): CMKConfig {
     namedExports: parsedTsConfig.config.namedExports ?? false,
     prioritizeNamedImports: parsedTsConfig.config.prioritizeNamedImports ?? false,
     keyframes: parsedTsConfig.config.keyframes ?? true,
-    enabled: parsedTsConfig.config.enabled,
+    enabled: parsedTsConfig.config.enabled ?? false,
     basePath,
     configFileName,
     compilerOptions: parsedTsConfig.compilerOptions,

diff --git a/packages/ts-plugin/e2e-test/feature/code-fix.test.ts b/packages/ts-plugin/e2e-test/feature/code-fix.test.ts
@@ -35,6 +35,7 @@ describe('Get Code Fixes', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/completion.test.ts b/packages/ts-plugin/e2e-test/feature/completion.test.ts
@@ -31,6 +31,7 @@ describe('Completion', async () => {
           "types": ["${reactDtsPath}"]
         },
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/find-all-references.test.ts b/packages/ts-plugin/e2e-test/feature/find-all-references.test.ts
@@ -32,6 +32,7 @@ describe('Find All References', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/go-to-definition.test.ts b/packages/ts-plugin/e2e-test/feature/go-to-definition.test.ts
@@ -39,6 +39,7 @@ describe('Go to Definition', async () => {
           "paths": { "@/*": ["./*"] }
         },
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/refactor.test.ts b/packages/ts-plugin/e2e-test/feature/refactor.test.ts
@@ -13,6 +13,7 @@ describe('Refactor', async () => {
       {
         "compilerOptions": { "jsx": "react-jsx" },
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/rename-file.test.ts b/packages/ts-plugin/e2e-test/feature/rename-file.test.ts
@@ -25,6 +25,7 @@ describe('Rename File', async () => {
           "paths": { "@/*": ["./*"] }
         },
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/rename-symbol.test.ts b/packages/ts-plugin/e2e-test/feature/rename-symbol.test.ts
@@ -40,6 +40,7 @@ describe('Rename Symbol', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/semantic-diagnostics.test.ts b/packages/ts-plugin/e2e-test/feature/semantic-diagnostics.test.ts
@@ -31,6 +31,7 @@ test('Semantic Diagnostics', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/feature/syntactic-diagnostics.test.ts b/packages/ts-plugin/e2e-test/feature/syntactic-diagnostics.test.ts
@@ -15,6 +15,7 @@ test('Syntactic Diagnostics', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/file-operation.test.ts b/packages/ts-plugin/e2e-test/file-operation.test.ts
@@ -13,7 +13,7 @@ test('adding file', async () => {
     'tsconfig.json': dedent`
       {
         "compilerOptions": {},
-        "cmkOptions": {}
+        "cmkOptions": { "enabled": true }
       }
     `,
   });
@@ -83,7 +83,7 @@ test('updating file', async () => {
     'tsconfig.json': dedent`
       {
         "compilerOptions": {},
-        "cmkOptions": {}
+        "cmkOptions": { "enabled": true }
       }
     `,
   });

diff --git a/packages/ts-plugin/e2e-test/ignore-generated-files.test.ts b/packages/ts-plugin/e2e-test/ignore-generated-files.test.ts
@@ -19,6 +19,9 @@ test('report the import of files where .d.ts exists but .module.css does not exi
       {
         "compilerOptions": {
           "rootDirs": [".", "generated"],
+        },
+        "cmkOptions": {
+          "enabled": true
         }
       }
     `,

diff --git a/packages/ts-plugin/e2e-test/invalid-syntax.test.ts b/packages/ts-plugin/e2e-test/invalid-syntax.test.ts
@@ -18,6 +18,7 @@ describe('handle invalid syntax CSS without crashing', async () => {
       {
         "compilerOptions": {},
         "cmkOptions": {
+          "enabled": true,
           "dtsOutDir": "generated"
         }
       }

diff --git a/packages/ts-plugin/e2e-test/named-exports.test.ts b/packages/ts-plugin/e2e-test/named-exports.test.ts
@@ -40,6 +40,7 @@ describe('supports basic language features', async () => {
     'tsconfig.json': dedent`
       {
         "cmkOptions": {
+          "enabled": true,
           "namedExports": true
         }
       }
@@ -209,6 +210,7 @@ describe('supports completions', async () => {
       'tsconfig.json': dedent`
         {
           "cmkOptions": {
+            "enabled": true,
             "namedExports": true
           }
         }
@@ -294,6 +296,7 @@ describe('supports completions', async () => {
       'tsconfig.json': dedent`
         {
           "cmkOptions": {
+            "enabled": true,
             "namedExports": true,
             "prioritizeNamedImports": true
           }
@@ -354,6 +357,7 @@ describe('supports code fixes', async () => {
       'tsconfig.json': dedent`
         {
           "cmkOptions": {
+            "enabled": true,
             "namedExports": true
           }
         }
@@ -415,6 +419,7 @@ describe('supports code fixes', async () => {
       'tsconfig.json': dedent`
         {
           "cmkOptions": {
+            "enabled": true,
             "namedExports": true,
             "prioritizeNamedImports": true
           }
@@ -482,6 +487,7 @@ describe('supports code fixes', async () => {
       'tsconfig.json': dedent`
         {
           "cmkOptions": {
+            "enabled": true,
             "namedExports": true
           }
         }

diff --git a/packages/ts-plugin/e2e-test/regression/pure-css-file.test.ts b/packages/ts-plugin/e2e-test/regression/pure-css-file.test.ts
@@ -10,7 +10,7 @@ test('ts-plugin does not process pure css files', async () => {
     'global.css': dedent`
       * { margin: 0; }
     `,
-    'tsconfig.json': '{}',
+    'tsconfig.json': '{ "cmkOptions": { "enabled": true } }',
   });
   await tsserver.sendUpdateOpen({
     openFiles: [{ file: iff.paths['tsconfig.json'] }],

diff --git a/packages/ts-plugin/src/index.cts b/packages/ts-plugin/src/index.cts
@@ -40,7 +40,7 @@ const plugin = createLanguageServicePlugin((ts, info) => {
     }
   }
 
-  if (config.enabled === false) {
+  if (!config.enabled) {
     return { languagePlugins: [] };
   }
 

diff --git a/packages/vscode/schemas/tsconfig.schema.json b/packages/vscode/schemas/tsconfig.schema.json
@@ -7,7 +7,7 @@
       "properties": {
         "enabled": {
           "type": "boolean",
-          "default": true,
+          "default": false,
           "markdownDescription": "Enables or disables css-modules-kit."
         },
         "dtsOutDir": {
-Original file line number
+Diff line change
@@ Expand Up / @@ -40,7 +40,7 @@ const plugin = createLanguageServicePlugin((ts, info) => { @@
         }
       }
-      if (config.enabled === false) {
+      if (!config.enabled) {
         return { languagePlugins: [] };
       }
@@ Expand Down @@