Warn when cmkOptions.enabled is not set, and exit with error when cmkOptions.enabled is false

.changeset/great-weeks-remain.md

@@ -0,0 +1,5 @@
+---
+'@css-modules-kit/codegen': minor
+---
+
+feat: exit with error when `cmkOptions.enabled` is false

.changeset/silly-results-eat.md

@@ -0,0 +1,5 @@
+---
+'@css-modules-kit/codegen': minor
+---
+
+feat: warn when `cmkOptions.enabled` is not set

README.md

@@ -127,6 +127,23 @@ In TypeScript, the `include`/`exclude` properties specify which `*.ts` files to
 }
 ```
 
+### `cmkOptions.enabled`
+
+Type: `boolean`, Default: `true`
+
+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).
+
+```jsonc
+{
+  "compilerOptions": {
+    // ...
+  },
+  "cmkOptions": {
+    "enabled": true,
+  },
+}
+```
+
 ### `cmkOptions.dtsOutDir`
 
 Type: `string`, Default: `"generated"`

docs/get-started.md

@@ -47,50 +47,33 @@ Configure npm-script to run `cmk` command before building and type checking. Thi
 
 ## Configure `tsconfig.json`
 
-Finally, you need to configure your tsconfig.json so that the ts-plugin and codegen work correctly.
-
-- Set the `include` option so that files like `*.module.css` are considered for type-checking:
-  - For example: `["src"]`, `["src/**/*"]`, or omitting the `include` option (which is equivalent to `["**/*"]`)
-  - Not recommended: `["src/**/*.ts"]`, `["src/index.ts"]`
+Finally, you need to configure your tsconfig.json so that css-modules-kit works correctly.
+
+- Set `cmkOptions.enabled` to `true` to enable css-modules-kit.
+- Omit the `include` options or ensure that `*.module.css` files are included when specifying them explicitly.
+  - ✅ Good cases:
+    - Omit `include` (equivalent to `["**/*"]`)
+    - Use patterns like `["src"]`, `["src/**/*"]`
+  - ❌ Bad cases:
+    - `["src/**/*.ts"]`
+    - `["src/index.ts"]` (excludes `*.module.css` files)
 - Set the `rootDirs` option to include both the directory containing `tsconfig.json` and the `generated` directory.
   - Example: `[".", "generated"]`
 
 Below is an example configuration:
 
 ```jsonc
 {
-  // Omitting the `include` option is equivalent to using `["**/*"]`
   "compilerOptions": {
-    /* Projects */
     "rootDirs": [".", "generated"],
-
-    /* Language and Environment */
-    "target": "ESNext",
-    "lib": ["ESNext"],
-
-    /* Modules */
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-
-    /* Emit */
-    "noEmit": true,
-
-    /* Interop Constraints */
-    "verbatimModuleSyntax": true,
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-
-    /* Type Checking */
-    "strict": true,
-
-    /* Completeness */
-    "skipLibCheck": true,
+    // ...
+  },
+  "cmkOptions": {
+    "enabled": true,
   },
 }
 ```
 
-This completes the minimal setup.
-
 ## Install linter plugin (Optional)
 
 We provide linter plugin for CSS Modules. Currently, we support the following linters:

examples/1-basic/tsconfig.json

@@ -11,5 +11,8 @@
     "incremental": false,
     "rootDirs": [".", "generated"],
     "types": [] // Simplify tsserver.log
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

examples/2-named-exports/tsconfig.json

@@ -13,6 +13,7 @@
     "types": [] // Simplify tsserver.log
   },
   "cmkOptions": {
+    "enabled": true,
     "namedExports": true
   }
 }

examples/3-import-alias/tsconfig.json

@@ -13,5 +13,8 @@
     "types": [], // Simplify tsserver.log
 
     "paths": { "@/*": ["./*"] }
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

examples/4-multiple-tsconfig/tsconfig.dir-1.json

@@ -14,5 +14,8 @@
     "types": [], // Simplify tsserver.log
 
     "paths": { "@/*": ["./*"] }
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

examples/4-multiple-tsconfig/tsconfig.dir-2.json

@@ -14,5 +14,8 @@
     "types": [], // Simplify tsserver.log
 
     "paths": { "@/*": ["./*"] }
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

examples/5-normal-css/tsconfig.json

@@ -11,5 +11,8 @@
     "incremental": false,
     "rootDirs": [".", "generated"],
     "types": [] // Simplify tsserver.log
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

examples/6-project-external-file/tsconfig.json

@@ -12,5 +12,8 @@
     "incremental": false,
     "rootDirs": [".", "generated"],
     "types": [] // Simplify tsserver.log
+  },
+  "cmkOptions": {
+    "enabled": true
   }
 }

packages/codegen/e2e-test/index.test.ts

@@ -33,7 +33,8 @@ test('generates .d.ts', async () => {
           "noEmit": true,
           "paths": { "@/*": ["./src/*"] },
           "rootDirs": [".", "generated"]
-        }
+        },
+        "cmkOptions": { "enabled": true }
       }
     `,
   });
@@ -91,7 +92,7 @@ test('prints version number', () => {
 test('reports CSS syntax error', async () => {
   const iff = await createIFF({
     'src/a.module.css': `badword`,
-    'tsconfig.json': '{}',
+    'tsconfig.json': '{ "cmkOptions": { "enabled": true } }',
   });
   const cmk = spawnSync('node', [binPath, '--pretty'], { cwd: iff.rootDir });
   expect(cmk.status).toBe(1);
@@ -138,7 +139,8 @@ test('generates .d.ts with circular import', async () => {
           "lib": ["ES2015"],
           "noEmit": true,
           "rootDirs": [".", "generated"]
-        }
+        },
+        "cmkOptions": { "enabled": true }
       }
     `,
   });

packages/codegen/src/error.ts

@@ -1,4 +1,5 @@
-import { SystemError } from '@css-modules-kit/core';
+import type { CMKConfig } from '@css-modules-kit/core';
+import { relative, SystemError } from '@css-modules-kit/core';
 
 export class ParseCLIArgsError extends SystemError {
   constructor(cause: unknown) {
@@ -17,3 +18,12 @@ export class ReadCSSModuleFileError extends SystemError {
     super('READ_CSS_MODULE_FILE_ERROR', `Failed to read CSS Module file ${fileName}.`, cause);
   }
 }
+
+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.`,
+    );
+  }
+}

packages/codegen/src/index.ts

@@ -1,5 +1,5 @@
 export { runCMK, runCMKInWatchMode } from './runner.js';
 export { type Logger, createLogger } from './logger/logger.js';
-export { WriteDtsFileError, ReadCSSModuleFileError } from './error.js';
+export { WriteDtsFileError, ReadCSSModuleFileError, CMKDisabledError } from './error.js';
 export { parseCLIArgs, printHelpText, printVersion } from './cli.js';
 export { shouldBePretty } from './3rd-party/typescript.js';

packages/codegen/src/logger/logger.test.ts

@@ -26,6 +26,7 @@ describe('createLogger', () => {
         start: { line: 1, column: 2 },
         length: 3,
       },
+      { text: 'text4', category: 'warning' },
     ];
     logger.logDiagnostics(diagnostics);
     expect(stripVTControlCharacters(stderrWriteSpy.mock.lastCall![0] as string)).toMatchInlineSnapshot(`
@@ -35,6 +36,8 @@ describe('createLogger', () => {
 
       a.module.css(1,2): error: text3
 
+      warning: text4
+
       "
     `);
   });