styled-components-to-stylex-codemod 0.0.1 → 0.0.3

package/README.md

@@ -2,6 +2,12 @@
 
 Transform styled-components to StyleX.
 
+**[Try it in the online playground](https://skovhus.github.io/styled-components-to-stylex-codemod/)** — experiment with the transform in your browser.
+
+> [!WARNING]
+>
+> **Very much under construction (alpha):** this codemod is still early in development — expect rough edges! 🚧
+
 ## Installation
 
 ```bash
@@ -140,6 +146,82 @@ Adapters are the main extension point. They let you control:
 - how theme paths and CSS variables are turned into StyleX-compatible JS values (`resolveValue`)
 - what extra imports to inject into transformed files (returned from `resolveValue`)
 - how helper calls are resolved (via `resolveValue({ kind: "call", ... })`)
+- which exported components should support external className/style extension (`shouldSupportExternalStyling`)
+- how className/style merging is handled for components accepting external styling (`styleMerger`)
+
+#### Style Merger
+
+When a component accepts external `className` and/or `style` props (e.g., via `shouldSupportExternalStyling`, or when wrapping a base component that already accepts these props), the generated code needs to merge StyleX styles with externally passed values.
+
+> **Note:** Allowing external className/style props is generally discouraged in StyleX as it bypasses the type-safe styling system. However, it can be useful during migration to maintain compatibility with existing code that passes these props.
+
+By default, this generates verbose inline merging code. You can provide a `styleMerger` to use a helper function instead for cleaner output:
+
+```ts
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    // ... value resolution logic
+    return null;
+  },
+
+  shouldSupportExternalStyling(ctx) {
+    return ctx.filePath.includes("/shared/components/");
+  },
+
+  // Use a custom merger function for cleaner output
+  styleMerger: {
+    functionName: "mergedSx",
+    importSource: { kind: "specifier", value: "./lib/mergedSx" },
+  },
+});
+```
+
+The merger function should have this signature:
+
+```ts
+function mergedSx(
+  styles: StyleXStyles,
+  className?: string,
+  style?: React.CSSProperties
+): ReturnType<typeof stylex.props>;
+```
+
+See [`test-cases/lib/mergedSx.ts`](./test-cases/lib/mergedSx.ts) for a reference implementation.
+
+#### External Styles Support
+
+Transformed components are "closed" by default — they don't accept external `className` or `style` props. Use `shouldSupportExternalStyling` to control which exported components should support external styling:
+
+```ts
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    // ... value resolution logic
+    return null;
+  },
+
+  shouldSupportExternalStyling(ctx) {
+    // ctx: { filePath, componentName, exportName, isDefaultExport }
+
+    // Example: Enable for all exports in shared components folder
+    if (ctx.filePath.includes("/shared/components/")) {
+      return true;
+    }
+
+    // Example: Enable for specific component names
+    if (ctx.componentName === "Button" || ctx.componentName === "Card") {
+      return true;
+    }
+
+    return false;
+  },
+});
+```
+
+When `shouldSupportExternalStyling` returns `true`, the generated component will:
+
+- Accept `className` and `style` props
+- Merge them with the StyleX-generated styles
+- Forward remaining props via `...rest`
 
 #### Dynamic interpolations
 
@@ -154,23 +236,12 @@ If the pipeline can’t resolve an interpolation:
 - for `withConfig({ shouldForwardProp })` wrappers, the transform preserves the value as an inline style so output keeps visual parity
 - otherwise, the declaration containing that interpolation is **dropped** and a warning is produced (manual follow-up required)
 
-### Notes / Limitations
+### Limitations
 
+- **Flow** type generation is non-existing, works best with TypeScript or plain JS right now. Contributions more than welcome!
 - **ThemeProvider**: if a file imports and uses `ThemeProvider` from `styled-components`, the transform **skips the entire file** (theming strategy is project-specific).
 - **createGlobalStyle**: detected usage is reported as an **unsupported-feature** warning (StyleX does not support global styles in the same way).
 
-### Transform Result
-
-```ts
-interface RunTransformResult {
-  errors: number; // Files that had errors
-  unchanged: number; // Files that were unchanged
-  skipped: number; // Files that were skipped
-  transformed: number; // Files that were transformed
-  timeElapsed: number; // Total time in seconds
-}
-```
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-CCX_WVPh.mjs";
+import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-t2Vk9Bka.mjs";
 
 //#region src/internal/logger.d.ts
 interface CollectedWarning extends TransformWarning {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as logWarning, t as flushWarnings } from "./logger-D09HOyqF.mjs";
+import { a as describeValue, i as assertValidAdapter, n as logWarning, t as flushWarnings } from "./logger-Dhb8r1Ry.mjs";
 import { run } from "jscodeshift/src/Runner.js";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -8,6 +8,9 @@ import { spawn } from "node:child_process";
 
 //#region src/adapter.ts
 /**
+* Adapter - Single user entry point for customizing the codemod.
+*/
+/**
 * Helper for nicer user authoring + type inference.
 *
 * Usage:
@@ -24,14 +27,15 @@ import { spawn } from "node:child_process";
 *       return null;
 *     },
 *
-*     // Optional: Enable className/style/rest support for exported components
-*     shouldSupportExternalStyles(ctx) {
+*     // Enable className/style/rest support for exported components
+*     shouldSupportExternalStyling(ctx) {
 *       // Example: Enable for all exported components in a shared components folder
 *       return ctx.filePath.includes("/shared/components/");
 *     },
 *   });
 */
 function defineAdapter(adapter) {
+	assertValidAdapter(adapter, "defineAdapter(adapter)");
 	return adapter;
 }
 
@@ -64,19 +68,46 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 * ```
 */
 async function runTransform(options) {
+	if (!options || typeof options !== "object") throw new Error([
+		"[styled-components-to-stylex] runTransform(options) was called with an invalid argument.",
+		"Expected: runTransform({ files: string | string[], adapter: Adapter, ... })",
+		`Received: ${describeValue(options)}`,
+		"",
+		"Example (plain JS):",
+		"  import { runTransform, defineAdapter } from \"styled-components-to-stylex-codemod\";",
+		"  const adapter = defineAdapter({ resolveValue() { return null; } });",
+		"  await runTransform({ files: \"src/**/*.tsx\", adapter });"
+	].join("\n"));
+	const filesValue = options.files;
+	if (typeof filesValue !== "string" && !Array.isArray(filesValue)) throw new Error([
+		"[styled-components-to-stylex] runTransform(options): `files` is required.",
+		"Expected: files: string | string[]",
+		`Received: files=${describeValue(filesValue)}`
+	].join("\n"));
+	if (typeof filesValue === "string" && filesValue.trim() === "") throw new Error(["[styled-components-to-stylex] runTransform(options): `files` must be a non-empty string.", "Example: files: \"src/**/*.tsx\""].join("\n"));
+	if (Array.isArray(filesValue)) {
+		if (filesValue.length === 0) throw new Error(["[styled-components-to-stylex] runTransform(options): `files` must not be an empty array.", "Example: files: [\"src/**/*.ts\", \"src/**/*.tsx\"]"].join("\n"));
+		if (filesValue.find((p) => typeof p !== "string" || p.trim() === "") !== void 0) throw new Error(["[styled-components-to-stylex] runTransform(options): `files` array must contain non-empty strings.", `Received: files=${describeValue(filesValue)}`].join("\n"));
+	}
 	const { files, dryRun = false, print = false, parser = "tsx", formatterCommand } = options;
 	const adapter = options.adapter;
-	if (!adapter || typeof adapter.resolveValue !== "function") throw new Error("Adapter must provide resolveValue(ctx) => { expr, imports } | null");
-	const adapterWithLogging = { resolveValue(ctx) {
-		try {
-			return adapter.resolveValue(ctx);
-		} catch (e) {
-			const kind = ctx?.kind;
-			const details = kind === "theme" ? `path=${String(ctx.path ?? "")}` : kind === "cssVariable" ? `name=${String(ctx.name ?? "")}` : kind === "call" ? `callee=${String(ctx.calleeImportedName ?? "")} source=${String(ctx.calleeSource?.value ?? "")} file=${String(ctx.callSiteFilePath ?? "")}` : "";
-			logWarning(`[styled-components-to-stylex] adapter.resolveValue threw${kind ? ` (kind=${kind}${details ? ` ${details}` : ""})` : ""}: ${e?.stack ?? String(e)}\n`);
-			throw e;
+	assertValidAdapter(adapter, "runTransform(options)");
+	const adapterWithLogging = {
+		styleMerger: adapter.styleMerger,
+		shouldSupportExternalStyling(ctx) {
+			return adapter.shouldSupportExternalStyling(ctx);
+		},
+		resolveValue(ctx) {
+			try {
+				return adapter.resolveValue(ctx);
+			} catch (e) {
+				const kind = ctx?.kind;
+				const details = kind === "theme" ? `path=${String(ctx.path ?? "")}` : kind === "cssVariable" ? `name=${String(ctx.name ?? "")}` : kind === "call" ? `callee=${String(ctx.calleeImportedName ?? "")} source=${String(ctx.calleeSource?.value ?? "")} file=${String(ctx.callSiteFilePath ?? "")}` : "";
+				logWarning(`[styled-components-to-stylex] adapter.resolveValue threw${kind ? ` (kind=${kind}${details ? ` ${details}` : ""})` : ""}: ${e?.stack ?? String(e)}\n`);
+				throw e;
+			}
 		}
-	} };
+	};
 	const patterns = Array.isArray(files) ? files : [files];
 	const filePaths = [];
 	const cwd = process.cwd();

package/dist/logger-Dhb8r1Ry.mjs

@@ -0,0 +1,116 @@
+//#region src/internal/public-api-validation.ts
+function describeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return `Array(${value.length})`;
+	if (typeof value === "string") return `"${value}"`;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "symbol") return value.description ? `Symbol(${value.description})` : "Symbol()";
+	if (typeof value === "function") return "[Function]";
+	if (typeof value === "object") {
+		const ctor = value?.constructor?.name ?? "Object";
+		let keys = [];
+		try {
+			keys = Object.keys(value);
+		} catch {}
+		const preview = keys.slice(0, 5).join(", ");
+		const suffix = keys.length > 5 ? ", ..." : "";
+		return keys.length ? `${ctor} { ${preview}${suffix} }` : ctor;
+	}
+	return "[Unknown]";
+}
+function assertValidAdapter(candidate, where) {
+	const obj = candidate;
+	const resolveValue = obj?.resolveValue;
+	const shouldSupportExternalStyling = obj?.shouldSupportExternalStyling;
+	if (!candidate || typeof candidate !== "object") throw new Error([
+		`[styled-components-to-stylex] ${where}: expected an adapter object.`,
+		`Received: ${describeValue(candidate)}`,
+		"",
+		"Adapter requirements:",
+		"  - adapter.resolveValue(context) is required",
+		"  - adapter.shouldSupportExternalStyling(context) is required",
+		"",
+		"resolveValue(context) is called with one of these shapes:",
+		"  - { kind: \"theme\", path }",
+		"  - { kind: \"cssVariable\", name, fallback?, definedValue? }",
+		"  - { kind: \"call\", callSiteFilePath, calleeImportedName, calleeSource, args }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
+	if (typeof resolveValue !== "function") throw new Error([
+		`[styled-components-to-stylex] ${where}: adapter.resolveValue must be a function.`,
+		`Received: resolveValue=${describeValue(resolveValue)}`,
+		"",
+		"Adapter shape:",
+		"  {",
+		"    resolveValue(context) { return { expr: string, imports: ImportSpec[] } | null }",
+		"  }",
+		"",
+		`Docs/examples: ${ADAPTER_DOCS_URL}`
+	].join("\n"));
+	if (typeof shouldSupportExternalStyling !== "function") throw new Error([`[styled-components-to-stylex] ${where}: adapter.shouldSupportExternalStyling must be a function.`, `Received: shouldSupportExternalStyling=${describeValue(shouldSupportExternalStyling)}`].join("\n"));
+	const styleMerger = obj?.styleMerger;
+	if (styleMerger !== null && styleMerger !== void 0) {
+		if (typeof styleMerger !== "object") throw new Error([
+			`[styled-components-to-stylex] ${where}: adapter.styleMerger must be null or an object.`,
+			`Received: styleMerger=${describeValue(styleMerger)}`,
+			"",
+			"Expected shape:",
+			"  {",
+			"    functionName: \"stylexProps\",",
+			"    importSource: { kind: \"specifier\", value: \"@company/ui-utils\" }",
+			"  }"
+		].join("\n"));
+		const { functionName, importSource } = styleMerger;
+		if (typeof functionName !== "string" || !functionName.trim()) throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.functionName must be a non-empty string.`, `Received: functionName=${describeValue(functionName)}`].join("\n"));
+		if (!importSource || typeof importSource !== "object") throw new Error([
+			`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource must be an object.`,
+			`Received: importSource=${describeValue(importSource)}`,
+			"",
+			"Expected shape:",
+			"  { kind: \"specifier\", value: \"@company/ui-utils\" }",
+			"  or",
+			"  { kind: \"absolutePath\", value: \"/path/to/module.ts\" }"
+		].join("\n"));
+		const { kind, value } = importSource;
+		if (kind !== "specifier" && kind !== "absolutePath") throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource.kind must be "specifier" or "absolutePath".`, `Received: kind=${describeValue(kind)}`].join("\n"));
+		if (typeof value !== "string" || !value.trim()) throw new Error([`[styled-components-to-stylex] ${where}: adapter.styleMerger.importSource.value must be a non-empty string.`, `Received: value=${describeValue(value)}`].join("\n"));
+	}
+}
+const ADAPTER_DOCS_URL = `https://github.com/skovhus/styled-components-to-stylex-codemod#adapter`;
+
+//#endregion
+//#region src/internal/logger.ts
+/**
+* Clear collected warnings and return them.
+*/
+function flushWarnings() {
+	const result = collected;
+	collected = [];
+	return result;
+}
+/**
+* Log a warning message to stderr.
+* All codemod warnings go through this so tests can mock it.
+*/
+function logWarning(message) {
+	process.stderr.write(message);
+}
+/**
+* Log transform warnings to stderr and collect them.
+*/
+function logWarnings(warnings, filePath) {
+	for (const warning of warnings) {
+		collected.push({
+			...warning,
+			filePath
+		});
+		logWarning(`[styled-components-to-stylex] Warning${warning.loc ? ` (${filePath}:${warning.loc.line}:${warning.loc.column})` : ` (${filePath})`}: ${warning.message}\n`);
+	}
+}
+let collected = [];
+
+//#endregion
+export { describeValue as a, assertValidAdapter as i, logWarning as n, logWarnings as r, flushWarnings as t };

package/dist/{transform-types-CCX_WVPh.d.mts → transform-types-t2Vk9Bka.d.mts}

@@ -87,15 +87,51 @@ interface ExternalStylesContext {
   /** Whether it's a default export */
   isDefaultExport: boolean;
 }
+/**
+ * Configuration for a custom style merger function that combines stylex.props()
+ * results with external className/style props.
+ *
+ * When configured, generates cleaner output:
+ *   `{...stylexProps(styles.foo, className, style)}`
+ * instead of the verbose pattern:
+ *   `{...sx} className={[sx.className, className].filter(Boolean).join(" ")} style={{...sx.style, ...style}}`
+ */
+interface StyleMergerConfig {
+  /**
+   * Function name to use for merging (e.g., "stylexProps" or "mergeStylexProps").
+   */
+  functionName: string;
+  /**
+   * Import source for the merger function.
+   * Example: `{ kind: "specifier", value: "@company/ui-utils" }`
+   */
+  importSource: ImportSource;
+}
 interface Adapter {
   /** Unified resolver for theme paths + CSS variables. Return null to leave unresolved. */
   resolveValue: (context: ResolveContext) => ResolveResult | null;
   /**
    * Called for exported styled components to determine if they should support
    * external className/style extension. Return true to generate wrapper with
-   * className/style/rest merging. Default: false.
+   * className/style/rest merging.
+   */
+  shouldSupportExternalStyling: (context: ExternalStylesContext) => boolean;
+  /**
+   * Custom merger function for className/style combining.
+   * When provided, generates cleaner output using this function instead of
+   * the verbose className/style merging pattern.
+   * Set to `null` to use the verbose pattern (default).
+   *
+   * Expected merger function signature:
+   * ```typescript
+   * function merger(
+   *   styles: StyleXStyles | StyleXStyles[],
+   *   className?: string,
+   *   style?: React.CSSProperties
+   * ): { className?: string; style?: React.CSSProperties }
+   * ```
    */
-  shouldSupportExternalStyles?: (context: ExternalStylesContext) => boolean;
+  styleMerger: StyleMergerConfig | null;
 }
 /**
  * Helper for nicer user authoring + type inference.
@@ -114,8 +150,8 @@ interface Adapter {
  *       return null;
  *     },
  *
- *     // Optional: Enable className/style/rest support for exported components
- *     shouldSupportExternalStyles(ctx) {
+ *     // Enable className/style/rest support for exported components
+ *     shouldSupportExternalStyling(ctx) {
  *       // Example: Enable for all exported components in a shared components folder
  *       return ctx.filePath.includes("/shared/components/");
  *     },

package/dist/transform.d.mts

@@ -1,4 +1,4 @@
-import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-CCX_WVPh.mjs";
+import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-t2Vk9Bka.mjs";
 import { API, FileInfo, Options } from "jscodeshift";
 
 //#region src/transform.d.ts