feat(adapter): add markerFile option for custom sidecar path

Allow adapters to redirect defineMarker() sidecar declarations to a
shared file instead of generating one per source file. Test fixtures
now use a single markers.stylex.ts.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: skovhus

scripts/regenerate-test-case-outputs.mts

@@ -81,6 +81,9 @@ async function listFixtureNames(): Promise<Array<{ name: string; ext: string }>>
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+// Accumulate all sidecar files across fixtures for merging (shared marker files)
+const allSidecarFiles = new Map<string, string>();
+
 async function updateFixture(name: string, ext: string) {
   const inputPath = join(testCasesDir, `${name}.input.${ext}`);
   const outputPath = join(testCasesDir, `${name}.output.${ext}`);
@@ -107,9 +110,24 @@ async function updateFixture(name: string, ext: string) {
   const out = result || input;
   await writeFile(outputPath, await normalizeCode(out, ext), "utf-8");
 
-  // Write sidecar .stylex.ts files (defineMarker declarations)
+  // Accumulate sidecar files for merging after all fixtures are processed
   for (const [sidecarPath, content] of sidecarFiles) {
-    await writeFile(sidecarPath, content, "utf-8");
+    const existing = allSidecarFiles.get(sidecarPath);
+    if (existing) {
+      // Merge: extract new marker lines and append any that don't already exist
+      const markerLineRe = /^export const \w+ = stylex\.defineMarker\(\);$/gm;
+      const newMarkers = [...content.matchAll(markerLineRe)].map((m) => m[0]);
+      const markersToAdd = newMarkers.filter((line) => !existing.includes(line));
+      if (markersToAdd.length > 0) {
+        const trailingNewline = existing.endsWith("\n") ? "" : "\n";
+        allSidecarFiles.set(
+          sidecarPath,
+          existing + trailingNewline + markersToAdd.join("\n") + "\n",
+        );
+      }
+    } else {
+      allSidecarFiles.set(sidecarPath, content);
+    }
   }
 
   return outputPath;
@@ -140,3 +158,8 @@ const targetFixtures = (() => {
 for (const { name, ext } of targetFixtures) {
   await updateFixture(name, ext);
 }
+
+// Write accumulated sidecar files (merged across all fixtures)
+for (const [sidecarPath, content] of allSidecarFiles) {
+  await writeFile(sidecarPath, content, "utf-8");
+}

src/__tests__/fixture-adapters.ts

@@ -34,6 +34,9 @@ export const fixtureAdapter = defineAdapter({
   // Emit sx={} JSX attributes instead of {...stylex.props()} spreads (StyleX ≥0.18)
   useSxProp: true,
 
+  // Write all defineMarker() declarations to a single shared sidecar file
+  markerFile: () => ({ kind: "specifier", value: "./markers.stylex" }),
+
   // Configure external interface for exported components
   externalInterface(ctx): ExternalInterfaceResult {
     // Enable external styles + polymorphic `as` prop for test cases that need both

src/__tests__/transform.test.ts

@@ -406,14 +406,19 @@ describe("transform", () => {
     const normalizedExpected = await normalizeCode(output, outputPath);
     expect(normalizedResult).toEqual(normalizedExpected);
 
-    // Compare sidecar .stylex.ts content if the test case has one
-    const sidecarPath = inputPath.replace(/\.\w+$/, ".stylex.ts");
-    if (existsSync(sidecarPath)) {
-      const expectedSidecar = readFileSync(sidecarPath, "utf-8");
-      expect(diagnostics.sidecarContent).toBeDefined();
-      expect(diagnostics.sidecarContent).toEqual(expectedSidecar);
-    } else {
-      expect(diagnostics.sidecarContent).toBeUndefined();
+    // Verify sidecar marker content: all marker declarations should be present in the shared markers file
+    if (diagnostics.sidecarContent) {
+      const sharedMarkersPath = join(testCasesDir, "markers.stylex.ts");
+      const sharedMarkers = readFileSync(sharedMarkersPath, "utf-8");
+      const markerLines = diagnostics.sidecarContent
+        .split("\n")
+        .filter((line) => line.startsWith("export const"));
+      expect(markerLines.length).toBeGreaterThan(0);
+      for (const line of markerLines) {
+        expect(sharedMarkers).toContain(line);
+      }
+      // Verify sidecarFilePath points to the shared markers file
+      expect(diagnostics.sidecarFilePath).toBe(sharedMarkersPath);
     }
   });
 });

src/adapter.ts

@@ -547,6 +547,15 @@ export type ExternalInterfaceResult = {
   spreadProps?: boolean;
 };
 
+// ────────────────────────────────────────────────────────────────────────────
+// Marker File Configuration
+// ────────────────────────────────────────────────────────────────────────────
+
+export interface MarkerFileContext {
+  /** Absolute path of the file being transformed */
+  filePath: string;
+}
+
 // ────────────────────────────────────────────────────────────────────────────
 // Style Merger Configuration
 // ────────────────────────────────────────────────────────────────────────────
@@ -736,6 +745,23 @@ export interface Adapter {
    * @default false
    */
   usePhysicalProperties?: boolean;
+
+  /**
+   * Optional function to customize where marker sidecar files (`stylex.defineMarker()`)
+   * are written. By default, markers are placed in a `.stylex.ts` file next to the source.
+   *
+   * When provided, the function receives the source file path and returns an `ImportSource`
+   * that determines both the import path in the transformed file and the file path where
+   * markers are written.
+   *
+   * Example:
+   * ```typescript
+   * markerFile(ctx) {
+   *   return { kind: "absolutePath", value: "/path/to/shared/markers.stylex.ts" };
+   * }
+   * ```
+   */
+  markerFile?: (context: MarkerFileContext) => ImportSource;
 }
 
 // ────────────────────────────────────────────────────────────────────────────
@@ -770,6 +796,7 @@ export interface AdapterInput {
   themeHook?: Adapter["themeHook"];
   useSxProp: Adapter["useSxProp"];
   usePhysicalProperties?: Adapter["usePhysicalProperties"];
+  markerFile?: Adapter["markerFile"];
 }
 
 // ────────────────────────────────────────────────────────────────────────────

src/index.ts

@@ -3,5 +3,5 @@
  * Core concepts: adapter configuration and transform execution.
  */
 export { defineAdapter } from "./adapter.js";
-export type { AdapterInput } from "./adapter.js";
+export type { AdapterInput, ImportSource, MarkerFileContext } from "./adapter.js";
 export { runTransform } from "./run.js";

src/internal/public-api-validation.ts

@@ -212,6 +212,20 @@ function assertAdapterShape(candidate: unknown, where: string, allowAutoExtIf: b
     });
   }
 
+  // Validate markerFile (optional function)
+  const markerFile = obj?.markerFile;
+  if (markerFile !== undefined && markerFile !== null && typeof markerFile !== "function") {
+    throw new Error(
+      [
+        `${where}: adapter.markerFile must be a function when provided.`,
+        `Received: markerFile=${describeValue(markerFile)}`,
+        "",
+        "Expected signature:",
+        '  markerFile(ctx: { filePath: string }) => { kind: "specifier" | "absolutePath", value: string }',
+      ].join("\n"),
+    );
+  }
+
   // Validate themeHook config (null/undefined or object with functionName/importSource)
   const themeHook = obj?.themeHook;
   if (themeHook !== null && themeHook !== undefined) {

src/internal/transform-context.ts

@@ -107,6 +107,8 @@ export class TransformContext {
   ancestorAttrsByStyleKey?: Map<string, Set<string>>;
   /** Content for the sidecar .stylex.ts file (defineMarker declarations), populated by emitStylesStep */
   sidecarStylexContent?: string;
+  /** Absolute file path for the sidecar file, when adapter.markerFile provides a custom location */
+  sidecarFilePath?: string;
   /** Bridge components emitted for unconverted consumer selectors. */
   bridgeResults?: import("./transform-types.js").BridgeComponentResult[];
   /** Transient prop renames for exported components (for consumer patching). */

src/internal/transform-steps/emit-styles.ts

@@ -2,7 +2,8 @@
  * Step: emit stylex.create objects and resolver imports.
  * Core concepts: style emission and import aliasing.
  */
-import { basename } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
+import type { ImportSource } from "../../adapter.js";
 import { emitStylesAndImports } from "../emit-styles.js";
 import { CONTINUE, type StepResult } from "../transform-types.js";
 import { TransformContext } from "../transform-context.js";
@@ -112,9 +113,17 @@ function emitDefineMarkerDeclarations(
     .join("\n");
   ctx.sidecarStylexContent = `import * as stylex from "@stylexjs/stylex";\n\n${markerDecls}\n`;
 
-  // Derive sidecar import path from file basename
-  const fileBase = basename(ctx.file.path).replace(/\.\w+$/, "");
-  const sidecarImportPath = `./${fileBase}.stylex`;
+  // Determine sidecar import path — use adapter.markerFile if provided, otherwise derive from basename
+  let sidecarImportPath: string;
+  const adapterMarkerFile = ctx.adapter.markerFile;
+  if (adapterMarkerFile) {
+    const importSource = adapterMarkerFile({ filePath: ctx.file.path });
+    sidecarImportPath = importSourceToModuleSpecifier(importSource, ctx.file.path);
+    ctx.sidecarFilePath = importSourceToAbsolutePath(importSource, ctx.file.path);
+  } else {
+    const fileBase = basename(ctx.file.path).replace(/\.\w+$/, "");
+    sidecarImportPath = `./${fileBase}.stylex`;
+  }
 
   // Insert `import { XMarker, ... } from "./file.stylex"` after existing imports
   const importDecl = j.importDeclaration(
@@ -131,3 +140,33 @@ function emitDefineMarkerDeclarations(
   const insertAt = lastImportIdx >= 0 ? lastImportIdx + 1 : 0;
   programBody.splice(insertAt, 0, importDecl as unknown as { type?: string });
 }
+
+/** Convert an ImportSource to a module specifier string for use in import declarations. */
+function importSourceToModuleSpecifier(source: ImportSource, filePath: string): string {
+  if (source.kind === "specifier") {
+    return source.value;
+  }
+  // absolutePath → relative module specifier from current file
+  const baseDir = dirname(filePath);
+  let rel = relative(baseDir, source.value).split(sep).join("/");
+  // Strip .ts/.tsx extension for module specifier
+  rel = rel.replace(/\.tsx?$/, "");
+  if (!rel.startsWith(".")) {
+    rel = `./${rel}`;
+  }
+  return rel;
+}
+
+/** Resolve an ImportSource to an absolute file path for writing the sidecar file. */
+function importSourceToAbsolutePath(source: ImportSource, filePath: string): string {
+  if (source.kind === "absolutePath") {
+    return source.value;
+  }
+  // specifier → resolve relative to source file directory, append .ts if no real file extension
+  const baseDir = dirname(filePath);
+  let resolved = join(baseDir, source.value);
+  if (!/\.[jt]sx?$/.test(resolved)) {
+    resolved += ".ts";
+  }
+  return resolved;
+}

src/internal/transform-steps/finalize.ts

@@ -52,6 +52,7 @@ export function finalize(ctx: TransformContext): TransformResult {
     code,
     warnings: ctx.warnings,
     sidecarContent: ctx.sidecarStylexContent,
+    sidecarFilePath: ctx.sidecarFilePath,
     bridgeResults: ctx.bridgeResults,
     transientPropRenames: ctx.transientPropRenames,
   };

src/internal/transform-types.ts

@@ -20,6 +20,8 @@ export interface TransformResult {
   warnings: WarningLog[];
   /** Content for the sidecar .stylex.ts file (defineMarker declarations). Undefined when no markers needed. */
   sidecarContent?: string;
+  /** Absolute file path for the sidecar file, when adapter.markerFile provides a custom location. */
+  sidecarFilePath?: string;
   /** Bridge components emitted for unconverted consumer selectors. */
   bridgeResults?: BridgeComponentResult[];
   /** Transient prop renames for exported components, keyed by export name. */