feat(cli): align object type with rollup (#8598)

h-a-n-a · h-a-n-a · commit 65196941c73b · 2026-03-09T10:58:14.000Z
This PR adds usage for `key:value` for object types to align with rollup's object-like type syntax. It also keeps `key=value` with a warning message for the backward compability. closes #8593
diff --git a/docs/apis/cli.md b/docs/apis/cli.md
@@ -108,7 +108,7 @@ export default defineConfig({
 
 ## Command Line Flags
 
-Flags can be passed as `--foo`, `--foo <value>`, or `--foo=<value>`. Boolean flags like `--minify` don't need a value, while key-value options like `--define` use comma-separated syntax: `--define key=value,key2=value2`. Many flags have short aliases (e.g., `-m` for `--minify`, `-f` for `--format`).
+Flags can be passed as `--foo`, `--foo <value>`, or `--foo=<value>`. Boolean flags like `--minify` don't need a value, while key-value options like `--transform.define` use comma-separated syntax: `--transform.define key:value,key2:value2`. Many flags have short aliases (e.g., `-m` for `--minify`, `-f` for `--format`).
 
 ::: info Integration into other tools
 
diff --git a/meta/design/cli.md b/meta/design/cli.md
@@ -22,7 +22,7 @@ bin/cli.mjs
           → rawArgs snapshot
           → remove unknown keys
           → type coercion (duplicate filtering + array wrapping)
-          → object option parsing (key=val,key=val)
+          → object option parsing (key:val,key:val)
       → arguments/normalize.ts
         → validateCliOptions() via valibot
         → split into input/output based on schema keys
@@ -141,7 +141,7 @@ cli.parse(process.argv, { run: true });
 5. Snapshot `rawArgs` (includes unknown keys)
 6. Remove unknown keys from `parsedOptions`
 7. Type coercion — duplicate filtering + array wrapping (single merged loop)
-8. Object option parsing (`key=val,key=val`)
+8. Object option parsing (`key:val,key:val`)
 9. `normalizeCliOptions()` — valibot validation + input/output splitting
 
 ## Implementation Notes
diff --git a/packages/rolldown/src/cli/arguments/index.ts b/packages/rolldown/src/cli/arguments/index.ts
@@ -189,7 +189,8 @@ export function parseCliArguments(): NormalizedCliOptions & {
     }
   }
 
-  // Object option parsing — parse "key=val,key=val" strings
+  // Object option parsing — parse "key:val,key:val" strings (Rollup-compatible)
+  // Also supports deprecated "key=val,key=val" syntax with a warning
   for (const [schemaKey, info] of Object.entries(schemaInfo)) {
     if (info.type !== 'object') continue;
 
@@ -205,15 +206,35 @@ export function parseCliArguments(): NormalizedCliOptions & {
     const values = Array.isArray(value) ? value : [value];
     if (typeof values[0] !== 'string') continue;
 
+    let usedDeprecatedSyntax = false;
     const result: Record<string, string> = {};
     for (const v of values) {
       for (const pair of String(v).split(',')) {
-        const [k, ...rest] = pair.split('=');
-        if (k && rest.length > 0) {
-          result[k] = rest.join('=');
+        // Prefer `:` only if it appears before `=` (or `=` doesn't exist)
+        // This ensures `key=value:with:colon` (deprecated) is parsed correctly
+        const colonIdx = pair.indexOf(':');
+        const eqIdx = pair.indexOf('=');
+        let k: string;
+        let val: string;
+        if (colonIdx > 0 && (eqIdx === -1 || colonIdx < eqIdx)) {
+          k = pair.slice(0, colonIdx);
+          val = pair.slice(colonIdx + 1);
+        } else if (eqIdx > 0) {
+          k = pair.slice(0, eqIdx);
+          val = pair.slice(eqIdx + 1);
+          usedDeprecatedSyntax = true;
+        } else {
+          continue;
         }
+        result[k] = val;
       }
     }
+    if (usedDeprecatedSyntax) {
+      const optionName = camelCaseToKebabCase(schemaKey);
+      logger.warn(
+        `Using \`key=value\` syntax for \`--${optionName}\` is deprecated. Use \`key:value\` instead.`,
+      );
+    }
     parent[leafKey] = result;
   }
 
diff --git a/packages/rolldown/src/utils/validator.ts b/packages/rolldown/src/utils/validator.ts
@@ -245,7 +245,7 @@ const TransformOptionsSchema = v.object({
   ),
   define: v.pipe(
     v.optional(v.record(v.string(), v.string())),
-    v.description('Define global variables (syntax: key=value,key2=value2)'),
+    v.description('Define global variables (syntax: key:value,key2:value2)'),
   ),
   inject: v.pipe(
     v.optional(v.record(v.string(), v.union([v.string(), v.tuple([v.string(), v.string()])]))),
@@ -879,7 +879,7 @@ const OutputOptionsSchema = v.strictObject({
   name: v.pipe(v.optional(v.string()), v.description('Name for UMD / IIFE format outputs')),
   globals: v.pipe(
     v.optional(v.union([v.record(v.string(), v.string()), GlobalsFunctionSchema])),
-    v.description('Global variable of UMD / IIFE dependencies (syntax: `key=value`)'),
+    v.description('Global variable of UMD / IIFE dependencies (syntax: `key:value`)'),
   ),
   paths: v.pipe(
     v.optional(v.union([v.record(v.string(), v.string()), PathsFunctionSchema])),
@@ -995,7 +995,7 @@ const OutputCliOverrideSchema = v.strictObject({
   ),
   globals: v.pipe(
     v.optional(v.record(v.string(), v.string())),
-    v.description('Global variable of UMD / IIFE dependencies (syntax: `key=value`)'),
+    v.description('Global variable of UMD / IIFE dependencies (syntax: `key:value`)'),
   ),
   codeSplitting: v.pipe(
     v.optional(
diff --git a/packages/rolldown/tests/cli/__snapshots__/cli-e2e.test.ts.snap b/packages/rolldown/tests/cli/__snapshots__/cli-e2e.test.ts.snap
@@ -11,7 +11,7 @@ OPTIONS
   --dir -d, <dir>             Output directory, defaults to \`dist\` if \`file\` is not set.
   --external -e, <external>   Comma-separated list of module ids to exclude from the bundle \`<module-id>,...\`.
   --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
-  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key=value\`).
+  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key:value\`).
   --help -h,                  Show help.
   --minify -m,                Minify the bundled file.
   --name -n, <name>           Name for UMD / IIFE format outputs.
@@ -97,7 +97,7 @@ OPTIONS
   --transform.assumptions.set-public-class-fields .
   --transform.decorator.emit-decorator-metadata .
   --transform.decorator.legacy .
-  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
+  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
   --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
   --transform.helpers.mode <transform.helpers.mode>.
   --transform.inject <transform.inject>Inject import statements on demand.
@@ -151,7 +151,7 @@ OPTIONS
   --dir -d, <dir>             Output directory, defaults to \`dist\` if \`file\` is not set.
   --external -e, <external>   Comma-separated list of module ids to exclude from the bundle \`<module-id>,...\`.
   --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
-  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key=value\`).
+  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key:value\`).
   --help -h,                  Show help.
   --minify -m,                Minify the bundled file.
   --name -n, <name>           Name for UMD / IIFE format outputs.
@@ -237,7 +237,7 @@ OPTIONS
   --transform.assumptions.set-public-class-fields .
   --transform.decorator.emit-decorator-metadata .
   --transform.decorator.legacy .
-  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
+  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
   --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
   --transform.helpers.mode <transform.helpers.mode>.
   --transform.inject <transform.inject>Inject import statements on demand.
@@ -291,7 +291,7 @@ OPTIONS
   --dir -d, <dir>             Output directory, defaults to \`dist\` if \`file\` is not set.
   --external -e, <external>   Comma-separated list of module ids to exclude from the bundle \`<module-id>,...\`.
   --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
-  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key=value\`).
+  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key:value\`).
   --help -h,                  Show help.
   --minify -m,                Minify the bundled file.
   --name -n, <name>           Name for UMD / IIFE format outputs.
@@ -377,7 +377,7 @@ OPTIONS
   --transform.assumptions.set-public-class-fields .
   --transform.decorator.emit-decorator-metadata .
   --transform.decorator.legacy .
-  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
+  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
   --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
   --transform.helpers.mode <transform.helpers.mode>.
   --transform.inject <transform.inject>Inject import statements on demand.
@@ -431,7 +431,7 @@ OPTIONS
   --dir -d, <dir>             Output directory, defaults to \`dist\` if \`file\` is not set.
   --external -e, <external>   Comma-separated list of module ids to exclude from the bundle \`<module-id>,...\`.
   --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
-  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key=value\`).
+  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key:value\`).
   --help -h,                  Show help.
   --minify -m,                Minify the bundled file.
   --name -n, <name>           Name for UMD / IIFE format outputs.
@@ -517,7 +517,7 @@ OPTIONS
   --transform.assumptions.set-public-class-fields .
   --transform.decorator.emit-decorator-metadata .
   --transform.decorator.legacy .
-  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
+  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
   --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
   --transform.helpers.mode <transform.helpers.mode>.
   --transform.inject <transform.inject>Inject import statements on demand.
@@ -571,7 +571,7 @@ OPTIONS
   --dir -d, <dir>             Output directory, defaults to \`dist\` if \`file\` is not set.
   --external -e, <external>   Comma-separated list of module ids to exclude from the bundle \`<module-id>,...\`.
   --format -f, <format>       Output format of the generated bundle (supports esm, cjs, and iife).
-  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key=value\`).
+  --globals -g, <globals>     Global variable of UMD / IIFE dependencies (syntax: \`key:value\`).
   --help -h,                  Show help.
   --minify -m,                Minify the bundled file.
   --name -n, <name>           Name for UMD / IIFE format outputs.
@@ -657,7 +657,7 @@ OPTIONS
   --transform.assumptions.set-public-class-fields .
   --transform.decorator.emit-decorator-metadata .
   --transform.decorator.legacy .
-  --transform.define <transform.define>Define global variables (syntax: key=value,key2=value2).
+  --transform.define <transform.define>Define global variables (syntax: key:value,key2:value2).
   --transform.drop-labels <transform.drop-labels>Remove labeled statements with these label names.
   --transform.helpers.mode <transform.helpers.mode>.
   --transform.inject <transform.inject>Inject import statements on demand.
@@ -765,6 +765,13 @@ exports[`cli options for bundling > should handle comma-separated object options
 "
 `;
 
+exports[`cli options for bundling > should handle deprecated key=value syntax with warning 1`] = `
+"Using \`key=value\` syntax for \`--module-types\` is deprecated. Use \`key:value\` instead.
+<DIR>/index.js  chunk │ size: 0.09 kB
+
+"
+`;
+
 exports[`cli options for bundling > should handle multiple define arguments with comma-separated syntax 1`] = `
 "<DIR>/index.js  chunk │ size: 0.10 kB
 
diff --git a/packages/rolldown/tests/cli/cli-e2e.test.ts b/packages/rolldown/tests/cli/cli-e2e.test.ts
@@ -123,7 +123,7 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-object');
     const status = await $({
       cwd,
-    })`rolldown index.ts --module-types .123=text --module-types notjson=json --module-types .b64=base64 -d dist`;
+    })`rolldown index.ts --module-types .123:text --module-types notjson:json --module-types .b64:base64 -d dist`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
   });
@@ -132,7 +132,7 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-object');
     const status = await $({
       cwd,
-    })`rolldown index.ts --module-types .123=text,notjson=json,.b64=base64 -d dist`;
+    })`rolldown index.ts --module-types .123:text,notjson:json,.b64:base64 -d dist`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
   });
@@ -141,9 +141,21 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-object');
     const status = await $({
       cwd,
-    })`rolldown index.ts --module-types .123=text,notjson=json --module-types .b64=base64 -d dist`;
+    })`rolldown index.ts --module-types .123:text,notjson:json --module-types .b64:base64 -d dist`;
+    expect(status.exitCode).toBe(0);
+    expect(cleanStdout(status.stdout)).toMatchSnapshot();
+  });
+
+  it('should handle deprecated key=value syntax with warning', async () => {
+    const cwd = cliFixturesDir('cli-option-object');
+    const status = await $({
+      cwd,
+    })`rolldown index.ts --module-types .123=text,notjson=json,.b64=base64 -d dist`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
+    expect(status.stdout).toContain(
+      'Using `key=value` syntax for `--module-types` is deprecated. Use `key:value` instead.',
+    );
   });
 
   it('should handle negative boolean options', async () => {
@@ -166,7 +178,7 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-nested');
     const status = await $({
       cwd,
-    })`rolldown index.js --transform.define __DEFINE__=defined`;
+    })`rolldown index.js --transform.define __DEFINE__:defined`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
   });
@@ -175,7 +187,7 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-multiple-define');
     const status = await $({
       cwd,
-    })`rolldown index.js --transform.define __A__=A,__B__=B,__C__=C -d dist`;
+    })`rolldown index.js --transform.define __A__:A,__B__:B,__C__:C -d dist`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
     const file = path.resolve(cwd, 'dist/index.js');
@@ -265,7 +277,7 @@ describe('cli options for bundling', () => {
     const cwd = cliFixturesDir('cli-option-object');
     const status = await $({
       cwd,
-    })`rolldown index.ts --moduleTypes .123=text,notjson=json,.b64=base64 -d dist`;
+    })`rolldown index.ts --moduleTypes .123:text,notjson:json,.b64:base64 -d dist`;
     expect(status.exitCode).toBe(0);
     expect(cleanStdout(status.stdout)).toMatchSnapshot();
   });
