Adjust markerFile logic: allow undefined return, only use for cross-file markers

Two changes to marker file handling:

1. markerFile adapter function can now return undefined, which falls back
   to the default behavior (local sidecar file next to the source).

2. The adapter's markerFile is only consulted when a file has cross-file
   marker relations. Internal-only markers (e.g. sibling selectors within
   the same file) always use a local sidecar file, avoiding pollution of
   a shared marker file with file-local concerns.

Co-authored-by: Kenneth Skovhus <skovhus@users.noreply.github.com>

Author: cursoragent

src/__tests__/transform.test.ts

@@ -406,19 +406,24 @@ describe("transform", () => {
     const normalizedExpected = await normalizeCode(output, outputPath);
     expect(normalizedResult).toEqual(normalizedExpected);
 
-    // Verify sidecar marker content: all marker declarations should be present in the shared markers file
+    // Verify sidecar marker content
     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);
+
+      if (diagnostics.sidecarFilePath) {
+        // Cross-file markers: sidecarFilePath points to the shared markers file
+        const sharedMarkersPath = join(testCasesDir, "markers.stylex.ts");
+        const sharedMarkers = readFileSync(sharedMarkersPath, "utf-8");
+        for (const line of markerLines) {
+          expect(sharedMarkers).toContain(line);
+        }
+        expect(diagnostics.sidecarFilePath).toBe(sharedMarkersPath);
       }
-      // Verify sidecarFilePath points to the shared markers file
-      expect(diagnostics.sidecarFilePath).toBe(sharedMarkersPath);
+      // Internal-only markers (e.g. sibling selectors): no sidecarFilePath,
+      // default local sidecar file is used
     }
   });
 });

src/adapter.ts

@@ -752,7 +752,12 @@ export interface Adapter {
    *
    * 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.
+   * markers are written. Return `undefined` to fall back to the default behavior (local
+   * sidecar file next to the source).
+   *
+   * Only consulted when a file has cross-file marker relations. Files that only
+   * reference markers internally (e.g., sibling selectors within the same file)
+   * always use a local sidecar file regardless of this setting.
    *
    * Example:
    * ```typescript
@@ -761,7 +766,7 @@ export interface Adapter {
    * }
    * ```
    */
-  markerFile?: (context: MarkerFileContext) => ImportSource;
+  markerFile?: (context: MarkerFileContext) => ImportSource | undefined;
 }
 
 // ────────────────────────────────────────────────────────────────────────────

src/internal/lower-rules.ts

@@ -22,6 +22,8 @@ export function lowerRules(ctx: TransformContext): {
   ancestorSelectorParents: Set<string>;
   usedCssHelperFunctions: Set<string>;
   crossFileMarkers: Map<string, string>;
+  /** True when at least one marker originates from a cross-file relation (not just internal sibling selectors) */
+  hasCrossFileMarkerRelations: boolean;
   siblingMarkerKeys: Set<string>;
   parentsNeedingDefaultMarker: Set<string>;
   /** Maps style key → set of CSS attribute selector strings used in ancestor attribute conditions */
@@ -121,9 +123,11 @@ export function lowerRules(ctx: TransformContext): {
   // Cross-file overrides use markers for parents that need them;
   // sibling selectors use per-component markers for scoped matching.
   const crossFileMarkers = new Map<string, string>();
+  let hasCrossFileMarkerRelations = false;
   for (const o of state.relationOverrides) {
     if (o.crossFile && o.markerVarName && parentsNeedingMarker.has(o.parentStyleKey)) {
       crossFileMarkers.set(o.parentStyleKey, o.markerVarName);
+      hasCrossFileMarkerRelations = true;
     }
   }
   for (const [styleKey, markerName] of state.siblingMarkerNames) {
@@ -159,6 +163,7 @@ export function lowerRules(ctx: TransformContext): {
     ancestorSelectorParents: filteredAncestorParents,
     usedCssHelperFunctions: state.usedCssHelperFunctions,
     crossFileMarkers,
+    hasCrossFileMarkerRelations,
     siblingMarkerKeys: new Set(state.siblingMarkerNames.keys()),
     parentsNeedingDefaultMarker,
     ancestorAttrsByStyleKey: state.ancestorAttrsByStyleKey,

src/internal/transform-context.ts

@@ -99,6 +99,8 @@ export class TransformContext {
   bridgeComponentNames?: Set<string>;
   /** Marker variable names generated for cross-file parent components and sibling selectors (parentStyleKey → markerName) */
   crossFileMarkers?: Map<string, string>;
+  /** True when at least one marker originates from a cross-file relation (not just internal sibling selectors) */
+  hasCrossFileMarkerRelations?: boolean;
   /** Style keys that use sibling markers (scoped marker replaces defaultMarker) */
   siblingMarkerKeys?: Set<string>;
   /** Parent style keys that need defaultMarker() (have at least one override without a scoped marker) */

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

@@ -116,11 +116,13 @@ function emitDefineMarkerDeclarations(
     .join("\n\n");
   ctx.sidecarStylexContent = `import * as stylex from "@stylexjs/stylex";\n\n${markerDecls}\n`;
 
-  // Determine sidecar import path — use adapter.markerFile if provided, otherwise derive from basename
+  // Use adapter.markerFile only when at least one marker is truly cross-file.
+  // Internal-only markers (sibling selectors within the same file) use the default
+  // local sidecar so they don't pollute a shared marker file.
   let sidecarImportPath: string;
-  const adapterMarkerFile = ctx.adapter.markerFile;
-  if (adapterMarkerFile) {
-    const importSource = adapterMarkerFile({ filePath: ctx.file.path });
+  const adapterMarkerFile = ctx.hasCrossFileMarkerRelations ? ctx.adapter.markerFile : undefined;
+  const importSource = adapterMarkerFile?.({ filePath: ctx.file.path });
+  if (importSource) {
     sidecarImportPath = importSourceToModuleSpecifier(importSource, ctx.file.path);
     ctx.sidecarFilePath = importSourceToAbsolutePath(importSource, ctx.file.path);
   } else {

src/internal/transform-steps/lower-rules.ts

@@ -21,6 +21,7 @@ export function lowerRulesStep(ctx: TransformContext): StepResult {
   ctx.relationOverrides = lowered.relationOverrides;
   ctx.ancestorSelectorParents = lowered.ancestorSelectorParents;
   ctx.crossFileMarkers = lowered.crossFileMarkers;
+  ctx.hasCrossFileMarkerRelations = lowered.hasCrossFileMarkerRelations;
   ctx.siblingMarkerKeys = lowered.siblingMarkerKeys;
   ctx.parentsNeedingDefaultMarker = lowered.parentsNeedingDefaultMarker;
   ctx.ancestorAttrsByStyleKey = lowered.ancestorAttrsByStyleKey;

test-cases/selector-componentSiblingCombinator.input.stylex.ts

@@ -0,0 +1,4 @@
+import * as stylex from "@stylexjs/stylex";
+
+/** Custom marker for Link */
+export const LinkMarker = stylex.defineMarker();

test-cases/selector-componentSiblingCombinator.output.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import * as stylex from "@stylexjs/stylex";
-import { LinkMarker } from "./markers.stylex";
+import { LinkMarker } from "./selector-componentSiblingCombinator.input.stylex";
 
 function Link(props: React.ComponentProps<"a">) {
   const { children, ...rest } = props;

test-cases/selector-generalSibling.input.stylex.ts

@@ -0,0 +1,4 @@
+import * as stylex from "@stylexjs/stylex";
+
+/** Custom marker for Thing */
+export const ThingMarker = stylex.defineMarker();

test-cases/selector-generalSibling.output.tsx

@@ -1,6 +1,6 @@
 import React from "react";
 import * as stylex from "@stylexjs/stylex";
-import { ThingMarker } from "./markers.stylex";
+import { ThingMarker } from "./selector-generalSibling.input.stylex";
 
 function Thing(props: React.PropsWithChildren<{}>) {
   return <div sx={[styles.thing, ThingMarker]}>{props.children}</div>;