mizdra · mizdra · Dec 30, 2025 · Dec 30, 2025 · Dec 30, 2025
diff --git a/.changeset/gold-moles-lead.md b/.changeset/gold-moles-lead.md
@@ -0,0 +1,5 @@
+---
+'@css-modules-kit/codegen': minor
+---
+
+feat: add --preserveWatchOutput option
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -6,7 +6,7 @@
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}/examples/1-basic",
-      "program": "${workspaceFolder}/packages/codegen/bin/cmk.mjs",
+      "program": "${workspaceFolder}/packages/codegen/bin/cmk.js",
       "console": "integratedTerminal",
       "preLaunchTask": "npm: build - packages/codegen",
       "presentation": {
@@ -18,8 +18,8 @@
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}/examples/1-basic",
-      "program": "${workspaceFolder}/packages/codegen/bin/cmk.mjs",
-      "args": ["--watch"],
+      "program": "${workspaceFolder}/packages/codegen/bin/cmk.js",
+      "args": ["--watch", "--preserveWatchOutput"],
       "console": "integratedTerminal",
       "preLaunchTask": "npm: build - packages/codegen",
       "presentation": {
@@ -31,7 +31,7 @@
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}/examples/2-named-exports",
-      "program": "${workspaceFolder}/packages/codegen/bin/cmk.mjs",
+      "program": "${workspaceFolder}/packages/codegen/bin/cmk.js",
       "console": "integratedTerminal",
       "preLaunchTask": "npm: build - packages/codegen",
       "presentation": {
@@ -43,7 +43,7 @@
       "type": "node",
       "request": "launch",
       "cwd": "${workspaceFolder}/examples/3-import-alias",
-      "program": "${workspaceFolder}/packages/codegen/bin/cmk.mjs",
+      "program": "${workspaceFolder}/packages/codegen/bin/cmk.js",
       "console": "integratedTerminal",
       "preLaunchTask": "npm: build - packages/codegen",
       "presentation": {

diff --git a/packages/codegen/README.md b/packages/codegen/README.md
@@ -36,12 +36,13 @@ $ npx cmk --help
 Usage: cmk [options]
 
 Options:
-  --help, -h     Show help information
-  --version, -v  Show version number
-  --project, -p  The path to its configuration file, or to a folder with a 'tsconfig.json'.
-  --pretty       Enable color and formatting in output to make errors easier to read.
-  --clean        Remove the output directory before generating files.                       [default: false]
-  --watch, -w    Watch for changes and regenerate files.                                    [default: false]
+  --help, -h             Show help information
+  --version, -v          Show version number
+  --project, -p          The path to its configuration file, or to a folder with a 'tsconfig.json'.
+  --pretty               Enable color and formatting in output to make errors easier to read.
+  --clean                Remove the output directory before generating files.                       [default: false]
+  --watch, -w            Watch for changes and regenerate files.                                    [default: false]
+  --preserveWatchOutput  Disable wiping the console in watch mode.                                  [default: false]
 ```
 
 ## Configuration

diff --git a/packages/codegen/src/cli.test.ts b/packages/codegen/src/cli.test.ts
@@ -15,6 +15,7 @@ describe('parseCLIArgs', () => {
       pretty: undefined,
       clean: false,
       watch: false,
+      preserveWatchOutput: false,
     });
   });
   it('should parse --help option', () => {
@@ -47,6 +48,10 @@ describe('parseCLIArgs', () => {
     expect(parseCLIArgs(['--no-watch'], cwd).watch).toBe(false);
     expect(parseCLIArgs(['-w'], cwd).watch).toBe(true);
   });
+  it('should parse --preserveWatchOutput option', () => {
+    expect(parseCLIArgs(['--preserveWatchOutput'], cwd).preserveWatchOutput).toBe(true);
+    expect(parseCLIArgs(['--no-preserveWatchOutput'], cwd).preserveWatchOutput).toBe(false);
+  });
   it('should throw ParseCLIArgsError for invalid options', () => {
     expect(() => parseCLIArgs(['--invalid-option'], cwd)).toThrow(ParseCLIArgsError);
   });

diff --git a/packages/codegen/src/cli.ts b/packages/codegen/src/cli.ts
@@ -3,16 +3,18 @@ import { resolve } from '@css-modules-kit/core';
 import packageJson from '../package.json' with { type: 'json' };
 import { ParseCLIArgsError } from './error.js';
 
+// NOTE: Keep this help text in sync with the one in packages/codegen/README.md.
 const helpText = `
 Usage: cmk [options]
 
 Options:
-  --help, -h     Show help information
-  --version, -v  Show version number
-  --project, -p  The path to its configuration file, or to a folder with a 'tsconfig.json'.
-  --pretty       Enable color and formatting in output to make errors easier to read.
-  --clean        Remove the output directory before generating files.                       [default: false]
-  --watch, -w    Watch for changes and regenerate files.                                    [default: false]
+  --help, -h             Show help information
+  --version, -v          Show version number
+  --project, -p          The path to its configuration file, or to a folder with a 'tsconfig.json'.
+  --pretty               Enable color and formatting in output to make errors easier to read.
+  --clean                Remove the output directory before generating files.                       [default: false]
+  --watch, -w            Watch for changes and regenerate files.                                    [default: false]
+  --preserveWatchOutput  Disable wiping the console in watch mode.                                  [default: false]
 `;
 
 export function printHelpText(): void {
@@ -32,6 +34,7 @@ export interface ParsedArgs {
   pretty: boolean | undefined;
   clean: boolean;
   watch: boolean;
+  preserveWatchOutput: boolean;
 }
 
 /**
@@ -49,6 +52,7 @@ export function parseCLIArgs(args: string[], cwd: string): ParsedArgs {
         pretty: { type: 'boolean' },
         clean: { type: 'boolean', default: false },
         watch: { type: 'boolean', short: 'w', default: false },
+        preserveWatchOutput: { type: 'boolean', default: false },
       },
       allowNegative: true,
     });
@@ -59,6 +63,7 @@ export function parseCLIArgs(args: string[], cwd: string): ParsedArgs {
       pretty: values.pretty,
       clean: values.clean,
       watch: values.watch,
+      preserveWatchOutput: values.preserveWatchOutput,
     };
   } catch (cause) {
     throw new ParseCLIArgsError(cause);

diff --git a/packages/codegen/src/runner.test.ts b/packages/codegen/src/runner.test.ts
@@ -289,4 +289,20 @@ describe('runCMKInWatchMode', () => {
       expect(formatDiagnostics(loggerSpy.logDiagnostics.mock.calls[0]![0], iff.rootDir)).length(3);
     });
   });
+  test('does not clear screen when preserveWatchOutput is true', async () => {
+    const iff = await createIFF({
+      'tsconfig.json': '{}',
+      'src/a.module.css': '.a_1 { color: red; }',
+    });
+
+    const loggerSpy1 = createLoggerSpy();
+    watcher = await runCMKInWatchMode(fakeParsedArgs({ project: iff.rootDir, preserveWatchOutput: false }), loggerSpy1);
+    expect(loggerSpy1.clearScreen).toHaveBeenCalledTimes(1);
+    await watcher.close();
+
+    const loggerSpy2 = createLoggerSpy();
+    // eslint-disable-next-line require-atomic-updates
+    watcher = await runCMKInWatchMode(fakeParsedArgs({ project: iff.rootDir, preserveWatchOutput: true }), loggerSpy2);
+    expect(loggerSpy2.clearScreen).toHaveBeenCalledTimes(0);
+  });
 });
diff --git a/packages/codegen/src/runner.ts b/packages/codegen/src/runner.ts
@@ -7,6 +7,7 @@ import { createProject, type Project } from './project.js';
 interface RunnerArgs {
   project: string;
   clean: boolean;
+  preserveWatchOutput: boolean;
 }
 
 export interface Watcher {
@@ -129,7 +130,9 @@ export async function runCMKInWatchMode(args: RunnerArgs, logger: Logger): Promi
    * @throws {WriteDtsFileError}
    */
   async function emitAndReportDiagnostics() {
-    logger.clearScreen();
+    if (!args.preserveWatchOutput) {
+      logger.clearScreen();
+    }
     await project.emitDtsFiles();
     const diagnostics = project.getDiagnostics();
     if (diagnostics.length > 0) {
@@ -139,6 +142,9 @@ export async function runCMKInWatchMode(args: RunnerArgs, logger: Logger): Promi
       `Found ${diagnostics.length} error${diagnostics.length === 1 ? '' : 's'}. Watching for file changes.`,
       { time: true },
     );
+    if (args.preserveWatchOutput) {
+      logger.logMessage('');
+    }
   }
 
   async function close() {

diff --git a/packages/codegen/src/test/faker.ts b/packages/codegen/src/test/faker.ts
@@ -8,6 +8,7 @@ export function fakeParsedArgs(args?: Partial<ParsedArgs>): ParsedArgs {
     pretty: undefined,
     clean: false,
     watch: false,
+    preserveWatchOutput: false,
     ...args,
   };
 }