fix: vanilla extract import triggers declaration mode sidecar. (#74)

Author: knightedcodemonkey

docs/loader.md

@@ -2,6 +2,18 @@
 
 `@knighted/css/loader` lets bundlers attach compiled CSS strings to any module by appending the `?knighted-css` query when importing. The loader mirrors the module graph, compiles every CSS dialect it discovers (CSS, Sass, Less, vanilla-extract, etc.), and exposes the concatenated result as `knightedCss`.
 
+## Loader vs bridge (quick comparison)
+
+Use this table to decide which loader you need before wiring up rules:
+
+| Capability               | @knighted/css/loader                                                           | @knighted/css/loader-bridge                                                                  |
+| ------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| Input                    | Original JS/TS module source + its style imports                               | Compiled CSS Modules output (post-hash)                                                      |
+| CSS extraction           | Yes (walks the import graph)                                                   | No (wraps upstream output)                                                                   |
+| Export behavior          | Appends `knightedCss` (and optional selector exports) onto the original module | Exposes `knightedCss`/`knightedCssModules` only; does **not** re-export JS/TS module exports |
+| When to use              | Default choice for `?knighted-css` in JS/TS modules                            | When you need hashed CSS Modules output for runtime `knightedCss`                            |
+| Combined wrapper needed? | Only for explicit `?knighted-css&combined` usage                               | **Yes** if you still need original JS/TS exports (use `&combined` via the resolver plugin)   |
+
 ## Loader example
 
 ```ts

docs/plugin.md

@@ -57,7 +57,9 @@ type KnightedCssResolverPluginOptions = {
   `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.cts`, `.mjs`, `.cjs`.
 - `debug` (optional): Logs rewrite decisions and a summary of cache hits/misses.
 - `combinedPaths` (optional): List of strings or regexes. Any resolved path that matches will
-  receive `&combined` alongside `?knighted-css`.
+  receive `&combined` alongside `?knighted-css`. Use this when the request is handled by
+  `@knighted/css/loader-bridge` (hashed CSS Modules) or whenever you need a wrapper module
+  that re-exports the original JS/TS exports plus `knightedCss`.
 - `strictSidecar` (optional): When true, only modules present in the manifest are rewritten.
   Defaults to true when `manifestPath` is provided.
 - `manifestPath` (optional): Path to the sidecar manifest generated by
@@ -118,6 +120,21 @@ export default {
 If you have modules that are consumed with combined exports (`?knighted-css&combined`),
 set `combinedPaths` to ensure the resolver appends `&combined` during rewrites.
 
+`&combined` is required when the underlying loader chain does **not** preserve the module’s
+original exports. The common case is declaration mode + `--hashed`, where requests flow through
+`@knighted/css/loader-bridge` and would otherwise only expose `knightedCss`/`knightedCssModules`.
+Appending `&combined` tells the loader to generate a small wrapper module that re-exports the
+original module and then appends the `knightedCss` exports.
+
+You typically **do not** need `combinedPaths` when requests are handled by `@knighted/css/loader`
+(non-hashed declaration mode), because that loader appends exports directly onto the original
+module.
+
+Outside of loader-bridge, `&combined` is still useful when you are **not** running
+`knighted-css-generate-types` but want a single runtime import that includes both the original
+JS/TS exports and `knightedCss` (for example, in runtime-only builds, tests, or tooling that
+cannot resolve the generated `.knighted-css` proxy modules).
+
 Example of an import that relies on `&combined` at runtime:
 
 ```ts

docs/type-generation.md

@@ -94,7 +94,8 @@ The CLI only emits `.d.ts` sidecars for files that pass all of the following che
 - **Within the project root**: if a candidate file resolves outside `--root`, the CLI skips it
   and logs a warning.
 - **Imports styles**: the file must import/require a style resource directly (e.g. `.css`,
-  `.scss`, `.sass`, `.less`) or resolve to one via tsconfig paths / resolver hooks.
+  `.scss`, `.sass`, `.less`, or vanilla-extract `.css.ts` / `.css.js`) or resolve to one via
+  tsconfig paths / resolver hooks.
 - **Produces selectors**: the extracted CSS must be non-empty and yield at least one selector
   token; otherwise the sidecar is skipped.
 

package-lock.json

@@ -13,6 +13,7 @@
   "engineStrict": true,
   "scripts": {
     "build": "npm run build -w @knighted/css",
+    "prepare": "husky",
     "test": "npm run test -w @knighted/css",
     "pretest": "npm run build",
     "test:e2e": "npm run test -w @knighted/css-playwright-fixture",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.2.0-rc.0",
+  "version": "1.2.0-rc.1",
   "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
   "type": "module",
   "main": "./dist/css.js",

packages/css/package.json

@@ -1061,6 +1061,18 @@ function isStyleResource(filePath: string): boolean {
   return STYLE_EXTENSIONS.some(ext => normalized.endsWith(ext))
 }
 
+function isVanillaExtractResource(filePath: string): boolean {
+  const normalized = filePath.toLowerCase()
+  return (
+    normalized.endsWith('.css.ts') ||
+    normalized.endsWith('.css.js') ||
+    normalized.endsWith('.css.mts') ||
+    normalized.endsWith('.css.cts') ||
+    normalized.endsWith('.css.mjs') ||
+    normalized.endsWith('.css.cjs')
+  )
+}
+
 function isCssModuleResource(filePath: string): boolean {
   return /\.module\.(css|scss|sass|less)$/i.test(filePath)
 }
@@ -1116,7 +1128,7 @@ async function hasStyleImports(
     if (!resource) {
       continue
     }
-    if (isStyleResource(resource)) {
+    if (isStyleResource(resource) || isVanillaExtractResource(resource)) {
       return true
     }
     const resolved = await resolveImportPath(
@@ -1128,7 +1140,7 @@ async function hasStyleImports(
       options.resolverFactory,
       RESOLUTION_EXTENSIONS,
     )
-    if (resolved && isStyleResource(resolved)) {
+    if (resolved && (isStyleResource(resolved) || isVanillaExtractResource(resolved))) {
       return true
     }
   }

packages/css/src/generateTypes.ts

@@ -27,6 +27,7 @@ const {
   resolveIndexFallback,
   readManifest,
   writeSidecarManifest,
+  hasStyleImports,
 } = __generateTypesInternals
 
 let cachedCliSnapshots: Record<string, string> | null = null
@@ -390,6 +391,46 @@ test('generateTypes declaration mode skips files without style imports', async (
   }
 })
 
+test('hasStyleImports treats vanilla extract modules as style imports', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'knighted-vanilla-'))
+  try {
+    const srcDir = path.join(root, 'src')
+    await fs.mkdir(srcDir, { recursive: true })
+    await fs.writeFile(
+      path.join(srcDir, 'styles.css.ts'),
+      "export const theme = { color: 'rebeccapurple' }\n",
+    )
+    const entryPath = path.join(srcDir, 'entry.ts')
+    await fs.writeFile(entryPath, "import './styles.css.ts'\n")
+
+    const hasStyles = await hasStyleImports(entryPath, { rootDir: root })
+    assert.equal(hasStyles, true)
+  } finally {
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
+
+test('hasStyleImports treats vanilla extract extension variants as style imports', async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'knighted-vanilla-variants-'))
+  try {
+    const srcDir = path.join(root, 'src')
+    await fs.mkdir(srcDir, { recursive: true })
+    const entryPath = path.join(srcDir, 'entry.ts')
+    const variants = ['.css.js', '.css.mjs', '.css.cjs', '.css.mts', '.css.cts']
+
+    for (const ext of variants) {
+      const stylePath = path.join(srcDir, `styles${ext}`)
+      await fs.writeFile(stylePath, '')
+      await fs.writeFile(entryPath, `import './styles${ext}'\n`)
+
+      const hasStyles = await hasStyleImports(entryPath, { rootDir: root })
+      assert.equal(hasStyles, true)
+    }
+  } finally {
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
+
 test('generateTypes hashed emits selector proxies for modules', async () => {
   const project = await setupFixtureProject()
   try {
@@ -616,7 +657,11 @@ test('generateTypes resolves hash-imports workspace package.json imports', async
     const sassModuleDir = path.join(appRoot, 'node_modules', 'sass')
     await fs.mkdir(path.dirname(sassModuleDir), { recursive: true })
     try {
-      await fs.symlink(sassPackageDir, sassModuleDir)
+      await fs.symlink(
+        sassPackageDir,
+        sassModuleDir,
+        process.platform === 'win32' ? 'junction' : 'dir',
+      )
     } catch {
       await fs.cp(sassPackageDir, sassModuleDir, { recursive: true })
     }

packages/css/test/generateTypes.test.ts

@@ -36,7 +36,7 @@
     "pretest": "npm run types && npm run build"
   },
   "dependencies": {
-    "@knighted/css": "1.2.0-rc.0",
+    "@knighted/css": "1.2.0-rc.1",
     "@knighted/jsx": "^1.7.5",
     "lit": "^3.2.1",
     "react": "^19.0.0",

packages/playwright/package.json

@@ -33,6 +33,18 @@ export default async () => ({
   },
   module: {
     rules: [
+      {
+        test: /\.css\.ts$/,
+        type: 'javascript/auto',
+        use: [
+          {
+            loader: '@knighted/css/loader',
+            options: {
+              vanilla: { transformToEsm: true },
+            },
+          },
+        ],
+      },
       {
         test: /\.module\.css$/,
         include: declarationHashedDir,