styled-components-to-stylex-codemod 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kenneth Skovhus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# styled-components-to-stylex-codemod
+
+Transform styled-components to StyleX.
+
+## Installation
+
+```bash
+npm install styled-components-to-stylex-codemod
+# or
+pnpm add styled-components-to-stylex-codemod
+```
+
+## Usage
+
+Use `runTransform` to transform files matching a glob pattern:
+
+```ts
+import {
+  runTransform,
+  defineAdapter,
+} from "styled-components-to-stylex-codemod";
+
+const adapter = defineAdapter({
+  resolveValue(ctx) {
+    if (ctx.kind === "theme") {
+      // Called for patterns like: ${(props) => props.theme.colors.primary}
+      // `ctx.path` is the dotted path after `theme.`
+      const varName = ctx.path.replace(/\./g, "_");
+      return {
+        expr: `tokens.${varName}`,
+        imports: [
+          {
+            from: { kind: "specifier", value: "./design-system.stylex" },
+            names: [{ imported: "tokens" }],
+          },
+        ],
+      };
+    }
+
+    if (ctx.kind === "cssVariable") {
+      // Called for CSS values containing `var(--...)`
+      // Note: `fallback` is the raw fallback string inside `var(--x, <fallback>)` (if present).
+      // Note: `definedValue` is populated when the transformer sees a local `--x: <value>` definition.
+      const { name, fallback, definedValue } = ctx;
+
+      // Example: lift `var(--base-size)` to StyleX vars, and optionally drop a matching local definition.
+      if (name === "--base-size") {
+        return {
+          expr: "calcVars.baseSize",
+          imports: [
+            {
+              from: { kind: "specifier", value: "./css-calc.stylex" },
+              names: [{ imported: "calcVars" }],
+            },
+          ],
+          ...(definedValue === "16px" ? { dropDefinition: true } : {}),
+        };
+      }
+
+      // Generic mapping: `--kebab-case` -> `vars.kebabCase`
+      // e.g. `--color-primary` -> `vars.colorPrimary`
+      const toCamelCase = (cssVarName: string) =>
+        cssVarName
+          .replace(/^--/, "")
+          .split("-")
+          .filter(Boolean)
+          .map((part, i) =>
+            i === 0 ? part : part[0]?.toUpperCase() + part.slice(1)
+          )
+          .join("");
+
+      // If you care about fallbacks, you can use `fallback` here to decide whether to resolve or not.
+      void fallback;
+      return {
+        expr: `vars.${toCamelCase(name)}`,
+        imports: [
+          {
+            from: { kind: "specifier", value: "./css-variables.stylex" },
+            names: [{ imported: "vars" }],
+          },
+        ],
+      };
+    }
+
+    if (ctx.kind === "call") {
+      // Called for template interpolations like: ${transitionSpeed("slowTransition")}
+      // `calleeImportedName` is the imported symbol name (works even with aliasing).
+      // `calleeSource` tells you where it came from:
+      // - { kind: "absolutePath", value: "/abs/path" } for relative imports
+      // - { kind: "specifier", value: "some-package/foo" } for package imports
+
+      if (ctx.calleeImportedName !== "transitionSpeed") {
+        return null;
+      }
+
+      // If you need to scope resolution to a particular module, you can use:
+      // - ctx.calleeSource
+
+      const arg0 = ctx.args[0];
+      const key =
+        arg0?.kind === "literal" && typeof arg0.value === "string"
+          ? arg0.value
+          : null;
+      if (!key) {
+        return null;
+      }
+
+      return {
+        expr: `transitionSpeedVars.${key}`,
+        imports: [
+          {
+            from: { kind: "specifier", value: "./lib/helpers.stylex" },
+            names: [
+              { imported: "transitionSpeed", local: "transitionSpeedVars" },
+            ],
+          },
+        ],
+      };
+    }
+
+    return null;
+  },
+});
+
+const result = await runTransform({
+  files: "src/**/*.tsx",
+  adapter,
+  dryRun: false,
+  parser: "tsx", // "babel" | "babylon" | "flow" | "ts" | "tsx"
+  formatterCommand: "pnpm prettier --write", // optional: format transformed files
+});
+
+console.log(result);
+```
+
+### Adapter
+
+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", ... })`)
+
+#### Dynamic interpolations
+
+When the codemod encounters an interpolation inside a styled template literal, it runs an internal dynamic resolution pipeline which covers common cases like:
+
+- theme access (`props.theme...`) via `resolveValue({ kind: "theme", path })`
+- prop access (`props.foo`) and conditionals (`props.foo ? "a" : "b"`, `props.foo && "color: red;"`)
+- simple helper calls (`transitionSpeed("slowTransition")`) via `resolveValue({ kind: "call", calleeImportedName, calleeSource, args, ... })`
+
+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
+
+- **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

@@ -0,0 +1,83 @@
+import { a as defineAdapter, i as Adapter, r as TransformWarning } from "./transform-types-CCX_WVPh.mjs";
+
+//#region src/internal/logger.d.ts
+interface CollectedWarning extends TransformWarning {
+  filePath: string;
+}
+//#endregion
+//#region src/run.d.ts
+interface RunTransformOptions {
+  /**
+   * Glob pattern(s) for files to transform
+   * @example "src/**\/*.tsx" or ["src/**\/*.ts", "src/**\/*.tsx"]
+   */
+  files: string | string[];
+  /**
+   * Adapter for customizing the transform.
+   * Controls value resolution and resolver-provided imports.
+   */
+  adapter: Adapter;
+  /**
+   * Dry run - don't write changes to files
+   * @default false
+   */
+  dryRun?: boolean;
+  /**
+   * Print transformed output to stdout
+   * @default false
+   */
+  print?: boolean;
+  /**
+   * jscodeshift parser to use
+   * @default "tsx"
+   */
+  parser?: "babel" | "babylon" | "flow" | "ts" | "tsx";
+  /**
+   * Command to run after transformation to format the output files.
+   * The transformed file paths will be appended as arguments.
+   * @example "pnpm prettier --write"
+   */
+  formatterCommand?: string;
+}
+interface RunTransformResult {
+  /** Number of files that had errors */
+  errors: number;
+  /** Number of files that were unchanged */
+  unchanged: number;
+  /** Number of files that were skipped */
+  skipped: number;
+  /** Number of files that were transformed */
+  transformed: number;
+  /** Total time in seconds */
+  timeElapsed: number;
+  /** Warnings emitted during transformation */
+  warnings: CollectedWarning[];
+}
+/**
+ * Run the styled-components to StyleX transform on files matching the glob pattern.
+ *
+ * @example
+ * ```ts
+ * import { runTransform } from 'styled-components-to-stylex-codemod';
+ * import { defineAdapter } from 'styled-components-to-stylex-codemod';
+ *
+ * const adapter = defineAdapter({
+ *   resolveValue(ctx) {
+ *     if (ctx.kind !== "theme") return null;
+ *     return {
+ *       expr: `themeVars.${ctx.path.replace(/\\./g, "_")}`,
+ *       imports: [{ from: { kind: "specifier", value: "./theme.stylex" }, names: [{ imported: "themeVars" }] }],
+ *     };
+ *   },
+ * });
+ *
+ * await runTransform({
+ *   files: 'src/**\/*.tsx',
+ *   adapter,
+ *   dryRun: true,
+ * });
+ * ```
+ */
+declare function runTransform(options: RunTransformOptions): Promise<RunTransformResult>;
+//#endregion
+export { defineAdapter, runTransform };

package/dist/index.mjs

@@ -0,0 +1,142 @@
+import { n as logWarning, t as flushWarnings } from "./logger-D09HOyqF.mjs";
+import { run } from "jscodeshift/src/Runner.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+import { glob } from "node:fs/promises";
+import { spawn } from "node:child_process";
+
+//#region src/adapter.ts
+/**
+* Helper for nicer user authoring + type inference.
+*
+* Usage:
+*   export default defineAdapter({
+*     resolveValue(ctx) {
+*       if (ctx.kind === "theme") {
+*         return {
+*           expr: `tokens.${ctx.path}`,
+*           imports: [
+*             { from: { kind: "specifier", value: "./tokens" }, names: [{ imported: "tokens" }] },
+*           ],
+*         };
+*       }
+*       return null;
+*     },
+*
+*     // Optional: Enable className/style/rest support for exported components
+*     shouldSupportExternalStyles(ctx) {
+*       // Example: Enable for all exported components in a shared components folder
+*       return ctx.filePath.includes("/shared/components/");
+*     },
+*   });
+*/
+function defineAdapter(adapter) {
+	return adapter;
+}
+
+//#endregion
+//#region src/run.ts
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+* Run the styled-components to StyleX transform on files matching the glob pattern.
+*
+* @example
+* ```ts
+* import { runTransform } from 'styled-components-to-stylex-codemod';
+* import { defineAdapter } from 'styled-components-to-stylex-codemod';
+*
+* const adapter = defineAdapter({
+*   resolveValue(ctx) {
+*     if (ctx.kind !== "theme") return null;
+*     return {
+*       expr: `themeVars.${ctx.path.replace(/\\./g, "_")}`,
+*       imports: [{ from: { kind: "specifier", value: "./theme.stylex" }, names: [{ imported: "themeVars" }] }],
+*     };
+*   },
+* });
+*
+* await runTransform({
+*   files: 'src/**\/*.tsx',
+*   adapter,
+*   dryRun: true,
+* });
+* ```
+*/
+async function runTransform(options) {
+	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;
+		}
+	} };
+	const patterns = Array.isArray(files) ? files : [files];
+	const filePaths = [];
+	const cwd = process.cwd();
+	for (const pattern of patterns) for await (const file of glob(pattern, { cwd })) filePaths.push(file);
+	if (filePaths.length === 0) {
+		logWarning("No files matched the provided glob pattern(s)\n");
+		return {
+			errors: 0,
+			unchanged: 0,
+			skipped: 0,
+			transformed: 0,
+			timeElapsed: 0,
+			warnings: []
+		};
+	}
+	const result = await run((() => {
+		const adjacent = join(__dirname, "transform.mjs");
+		if (existsSync(adjacent)) return adjacent;
+		const distSibling = join(__dirname, "..", "dist", "transform.mjs");
+		if (existsSync(distSibling)) return distSibling;
+		throw new Error([
+			"Could not locate transform module.",
+			`Tried: ${adjacent}`,
+			`       ${distSibling}`,
+			"Run `pnpm build` to generate dist artifacts."
+		].join("\n"));
+	})(), filePaths, {
+		parser,
+		dry: dryRun,
+		print,
+		adapter: adapterWithLogging,
+		runInBand: true
+	});
+	if (formatterCommand && result.ok > 0 && !dryRun) {
+		const [cmd, ...cmdArgs] = formatterCommand.split(/\s+/);
+		if (cmd) try {
+			await new Promise((resolve$1, reject) => {
+				const proc = spawn(cmd, [...cmdArgs, ...filePaths], {
+					stdio: "inherit",
+					shell: true
+				});
+				proc.on("close", (code) => {
+					if (code === 0) resolve$1();
+					else reject(/* @__PURE__ */ new Error(`Formatter command exited with code ${code}`));
+				});
+				proc.on("error", reject);
+			});
+		} catch (e) {
+			logWarning(`[styled-components-to-stylex] Formatter command failed: ${e instanceof Error ? e.message : String(e)}\n`);
+		}
+	}
+	return {
+		errors: result.error,
+		unchanged: result.nochange,
+		skipped: result.skip,
+		transformed: result.ok,
+		timeElapsed: parseFloat(result.timeElapsed) || 0,
+		warnings: flushWarnings()
+	};
+}
+
+//#endregion
+export { defineAdapter, runTransform };

package/dist/logger-D09HOyqF.mjs

@@ -0,0 +1,32 @@
+//#region src/internal/logger.ts
+let collected = [];
+/**
+* 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`);
+	}
+}
+
+//#endregion
+export { logWarning as n, logWarnings as r, flushWarnings as t };

package/dist/transform-types-CCX_WVPh.d.mts

@@ -0,0 +1,157 @@
+import "stylis";
+import { Options } from "jscodeshift";
+
+//#region src/adapter.d.ts
+/**
+ * Adapter - Single user entry point for customizing the codemod.
+ */
+type ResolveContext = {
+  kind: "theme";
+  path: string;
+} | {
+  kind: "cssVariable";
+  name: string;
+  fallback?: string;
+  definedValue?: string;
+} | {
+  kind: "call";
+  /**
+   * Absolute path of the file currently being transformed.
+   * Useful for adapter logic that wants to branch by caller file.
+   */
+  callSiteFilePath: string;
+  /**
+   * Imported name when the callee is a named import (including aliases).
+   * Example: `import { transitionSpeed as ts } ...; ts("x")` -> "transitionSpeed"
+   */
+  calleeImportedName: string;
+  /**
+   * Import source for this call: either an absolute file path (relative imports)
+   * or the module specifier (package imports).
+   */
+  calleeSource: {
+    kind: "absolutePath";
+    value: string;
+  } | {
+    kind: "specifier";
+    value: string;
+  };
+  /**
+   * Call arguments (only literals are surfaced precisely; everything else is `unknown`).
+   */
+  args: Array<{
+    kind: "literal";
+    value: string | number | boolean | null;
+  } | {
+    kind: "unknown";
+  }>;
+};
+type ResolveResult = {
+  /**
+   * JS expression string to inline into generated output.
+   * Example: `vars.spacingSm` or `calcVars.baseSize`
+   */
+  expr: string;
+  /**
+   * Import statements required by `expr`.
+   * These are rendered and merged into the file by the codemod.
+   */
+  imports: ImportSpec[];
+  /**
+   * If true, the transformer should drop the corresponding `--name: ...` definition
+   * from the emitted style object (useful when replacing with StyleX vars).
+   */
+  dropDefinition?: boolean;
+};
+type ImportSource = {
+  kind: "absolutePath";
+  value: string;
+} | {
+  kind: "specifier";
+  value: string;
+};
+type ImportSpec = {
+  from: ImportSource;
+  names: Array<{
+    imported: string;
+    local?: string;
+  }>;
+};
+interface ExternalStylesContext {
+  /** Absolute path of the file being transformed */
+  filePath: string;
+  /** Local name of the styled component */
+  componentName: string;
+  /** The export name (may differ from componentName for renamed exports) */
+  exportName: string;
+  /** Whether it's a default export */
+  isDefaultExport: boolean;
+}
+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.
+   */
+  shouldSupportExternalStyles?: (context: ExternalStylesContext) => boolean;
+}
+/**
+ * Helper for nicer user authoring + type inference.
+ *
+ * Usage:
+ *   export default defineAdapter({
+ *     resolveValue(ctx) {
+ *       if (ctx.kind === "theme") {
+ *         return {
+ *           expr: `tokens.${ctx.path}`,
+ *           imports: [
+ *             { from: { kind: "specifier", value: "./tokens" }, names: [{ imported: "tokens" }] },
+ *           ],
+ *         };
+ *       }
+ *       return null;
+ *     },
+ *
+ *     // Optional: Enable className/style/rest support for exported components
+ *     shouldSupportExternalStyles(ctx) {
+ *       // Example: Enable for all exported components in a shared components folder
+ *       return ctx.filePath.includes("/shared/components/");
+ *     },
+ *   });
+ */
+declare function defineAdapter(adapter: Adapter): Adapter;
+//#endregion
+//#region src/internal/transform-types.d.ts
+/**
+ * Warning emitted during transformation for unsupported features
+ */
+interface TransformWarning {
+  type: "unsupported-feature" | "dynamic-node";
+  feature: string;
+  message: string;
+  loc?: {
+    line: number;
+    column: number;
+  };
+}
+/**
+ * Result of the transform including any warnings
+ */
+interface TransformResult {
+  code: string | null;
+  warnings: TransformWarning[];
+}
+/**
+ * Options for the transform
+ */
+interface TransformOptions extends Options {
+  /**
+   * Adapter for customizing the transform.
+   * Controls value resolution and resolver-provided imports.
+   */
+  adapter: Adapter;
+}
+//#endregion
+export { defineAdapter as a, Adapter as i, TransformResult as n, TransformWarning as r, TransformOptions as t };

package/dist/transform.d.mts

@@ -0,0 +1,18 @@
+import { n as TransformResult, r as TransformWarning, t as TransformOptions } from "./transform-types-CCX_WVPh.mjs";
+import { API, FileInfo, Options } from "jscodeshift";
+
+//#region src/transform.d.ts
+
+/**
+ * Transform styled-components to StyleX
+ *
+ * This is a sample transform that serves as a starting point.
+ * You'll need to implement the actual transformation logic based on your needs.
+ */
+declare function transform(file: FileInfo, api: API, options: Options): string | null;
+/**
+ * Transform with detailed warnings returned (for testing)
+ */
+declare function transformWithWarnings(file: FileInfo, api: API, options: TransformOptions): TransformResult;
+//#endregion
+export { type TransformOptions, type TransformResult, type TransformWarning, transform as default, transformWithWarnings };