turbopack-unocss-transform 1.0.0 → 1.1.1

package/README.md

@@ -1,30 +1,141 @@
 # turbopack-unocss-transform
-A Turbopack loader for Next.js that applies UnoCSS transformers (like variant-group and attributify-jsx) directly to your TS/JS/TSX/JSX source before CSS generation. Actual CSS is produced by @unocss/postcss; this loader only transforms source code.
 
-**Usage**
+Turbopack loader for Next.js that applies UnoCSS transformers (`transformerAttributifyJsx`, `transformerVariantGroup`, `transformerDirectives`) to source files.
+
+`@unocss/postcss` handles CSS generation; this loader transforms JS/TS/JSX/TSX source code.
+
+## Requirements
+
+| Dependency | Version                                                            |
+| ---------- | ------------------------------------------------------------------ |
+| Node.js    | **≥23.6.0** (native TypeScript support if you use `uno.config.ts`) |
+| Next.js    | ≥15.0.0                                                            |
+| UnoCSS     | ≥66.0.0                                                            |
+
+## Installation
+
+```bash
+pnpm add -D turbopack-unocss-transform @unocss/postcss
+```
+
+## Setup
+
+### 1. next.config.ts
 
-`next.config.ts`
 ```typescript
 import type {NextConfig} from "next"
 import withUnoTransform from "turbopack-unocss-transform"
 
 const nextConfig: NextConfig = withUnoTransform({
-  // your Next.js config
+  // your config
 })
 
 export default nextConfig
 ```
 
-`postcss.config.mjs`
-```js
-import unoConfig from "./src/styles/uno.config"
+### 2. postcss.config.mjs
+
+> [!IMPORTANT]
+> **Import the config object, not a path string.** Passing a string or without the `configOrPath` setting disables HMR - Turbopack won't detect config changes.
+
+```javascript
+import config from "./uno.config.ts"
 
 export default {
   plugins: [
-    ["@unocss/postcss", {
-      configOrPath: unoConfig
-    }],
-    "autoprefixer"
+    ["@unocss/postcss", {configOrPath: config}]
   ]
 }
 ```
+
+### 3. tsconfig.json
+
+> [!IMPORTANT]
+> **Required.** Node.js 23+ executes TypeScript natively but requires explicit `.ts` extensions in imports. This flag allows TypeScript to accept them.
+
+```json
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "noEmit": true
+  }
+}
+```
+
+### 4. uno.config.ts
+
+> [!WARNING]
+> **All local imports must include `.ts` extension.** PostCSS runs via Node.js worker (not Turbopack), which requires explicit extensions for TypeScript files.
+
+```typescript
+import type {UserConfig} from "@unocss/core"
+import {presetAttributify} from "@unocss/preset-attributify"
+import {presetWind4} from "@unocss/preset-wind4"
+import transformerAttributifyJsx from "@unocss/transformer-attributify-jsx"
+import transformerDirectives from "@unocss/transformer-directives"
+import transformerVariantGroup from "@unocss/transformer-variant-group"
+import theme from "./src/styles/theme/index.ts"
+import preflights from "./src/styles/theme/preflights.ts"
+
+export default {
+  presets: [presetWind4(), presetAttributify()],
+  transformers: [
+    transformerAttributifyJsx(),
+    transformerDirectives(),
+    transformerVariantGroup()
+  ],
+  theme,
+  preflights
+} satisfies UserConfig
+```
+
+> [!CAUTION]
+> **Avoid importing from the `unocss` meta-package.** It re-exports all presets including `@unocss/preset-icons`, which depends on `mlly` that uses dynamic `import(dataURL)` - not supported by Turbopack.
+>
+> This will fail:
+>
+> ```typescript
+> import {defineConfig, presetWind4} from "unocss" // ❌ Pulls in mlly
+> ```
+>
+> Use separate packages instead:
+>
+> ```typescript
+> import {presetWind4} from "@unocss/preset-wind4" // ✅
+> ```
+>
+> You can try the meta-package - it might work in future versions, but this setup was tested with separate packages only.
+
+### 5. Global styles (e.g., global.sass)
+
+```sass
+@unocss all
+
+html, body
+  @apply text-dark font-sans
+```
+
+## Why explicit `.ts` extensions?
+
+PostCSS config is executed by a **Node.js worker**, not Turbopack. Node.js 23+ runs TypeScript natively but doesn't resolve `.ts` extensions automatically — they must be explicit.
+
+Without explicit extensions:
+
+```
+Module not found: Can't resolve './src/styles/theme'
+```
+
+## HMR behavior
+
+| postcss.config.mjs                     | HMR      |
+| -------------------------------------- | -------- |
+| `import config from "./uno.config.ts"` | ✅ Works  |
+| `{configOrPath: "./uno.config.ts"}`    | ❌ No HMR |
+
+When using path string, Turbopack doesn't track `uno.config.ts` as a dependency — changes require `next dev` restart.
+
+## Tested with
+
+- Next.js **16.1.3**
+- UnoCSS **66.5.6**
+- Node.js **23.11.0**

package/dist/index.cjs

@@ -0,0 +1,50 @@
+const path = require("node:path")
+
+function getLoaderPath() {
+  return path.resolve(__dirname, "loader.mjs")
+}
+
+function withUnoTransform(userConfig = {}) {
+  const loaderPath = getLoaderPath()
+
+  const base = {
+    turbopack: {
+      rules: {
+        "**/*.{ts,tsx,js,jsx}": {
+          loaders: [loaderPath]
+        }
+      }
+    }
+  }
+
+  return merge(base, userConfig)
+}
+
+function merge(a, b) {
+  if (!b) return a
+
+  const out = JSON.parse(JSON.stringify(a))
+
+  mergeInto(out, b)
+
+  return out
+}
+
+function mergeInto(t, s) {
+  for (const k of Object.keys(s)) {
+    const sv = s[k]
+    const tv = t[k]
+
+    if (Array.isArray(sv)) {
+      t[k] = Array.isArray(tv) ? [...tv, ...sv] : [...sv]
+    } else if (sv && typeof sv === "object") {
+      if (!tv || typeof tv !== "object") t[k] = {}
+      mergeInto(t[k], sv)
+    } else {
+      t[k] = sv
+    }
+  }
+}
+
+module.exports = withUnoTransform
+module.exports.default = withUnoTransform

package/dist/index.mjs

@@ -1,7 +1,23 @@
 import path from "node:path"
+import {fileURLToPath} from "node:url"
+
+function getLoaderPath() {
+  try {
+    const __filename = fileURLToPath(import.meta.url)
+    const __dirname = path.dirname(__filename)
+
+    return path.resolve(__dirname, "loader.mjs")
+  } catch {
+    return path.resolve(
+      process.cwd(),
+      "node_modules/turbopack-unocss-transform/dist/loader.mjs"
+    )
+  }
+}
 
 export default function withUnoTransform(userConfig = {}) {
-  const loaderPath = path.resolve(process.cwd(), "node_modules/turbopack-unocss-transform/dist/loader.mjs")
+  const loaderPath = getLoaderPath()
+
   const base = {
     turbopack: {
       rules: {
@@ -27,15 +43,13 @@ function merge(a, b) {
 
 function mergeInto(t, s) {
   for (const k of Object.keys(s)) {
-    const sv = s[k], tv = t[k]
+    const sv = s[k]
+    const tv = t[k]
 
     if (Array.isArray(sv)) {
       t[k] = Array.isArray(tv) ? [...tv, ...sv] : [...sv]
-    }
-
-    else if (sv && typeof sv === "object") {
+    } else if (sv && typeof sv === "object") {
       if (!tv || typeof tv !== "object") t[k] = {}
-
       mergeInto(t[k], sv)
     } else {
       t[k] = sv

package/dist/loader.cjs

@@ -0,0 +1,15 @@
+let loaderPromise = null
+
+async function getLoader() {
+  if (!loaderPromise) {
+    loaderPromise = import("./loader.mjs").then((m) => m.default)
+  }
+
+  return loaderPromise
+}
+
+module.exports = async function unoLoader(source) {
+  const loader = await getLoader()
+
+  return loader.call(this, source)
+}

package/dist/loader.mjs

@@ -1,98 +1,328 @@
+import fs from "node:fs"
+import {createRequire} from "node:module"
 import path from "node:path"
+import {createGenerator} from "@unocss/core"
 import MagicString from "magic-string"
-import {createGenerator} from "unocss"
-import {createRequire} from "node:module"
 
+const PREFIX = "[UnoCSS-Turbopack]"
 const nodeRequire = createRequire(import.meta.url)
 
+const DEFAULT_CONFIG_PATHS = [
+  "uno.config.ts",
+  "uno.config.js",
+  "uno.config.mjs",
+  "unocss.config.ts",
+  "unocss.config.js",
+  "unocss.config.mjs"
+]
+
 let uno = null
 let unoInitPromise = null
 let cfg = null
 let cfgLoaded = false
+let cfgPath = null
+let cfgMtime = 0
+
+function createJiti() {
+  try {
+    return nodeRequire("jiti")(import.meta.url, {
+      interopDefault: true,
+      esmResolve: true
+    })
+  } catch (error) {
+    throw new Error(
+      `${PREFIX} Failed to initialize jiti: ${error?.message || error}`
+    )
+  }
+}
+
+function resolveConfigPath(configPath) {
+  if (path.isAbsolute(configPath)) {
+    return configPath
+  }
+
+  return path.resolve(process.cwd(), configPath)
+}
+
+function loadConfigFromPath(configPath) {
+  const jiti = createJiti()
+  const resolved = resolveConfigPath(configPath)
+
+  try {
+    const mod = jiti(resolved)
+
+    return mod?.default ?? mod
+  } catch (error) {
+    throw new Error(
+      `${PREFIX} Failed to load config from "${resolved}": ${error?.message || error}`
+    )
+  }
+}
+
+function findDefaultConfigPath() {
+  for (const p of DEFAULT_CONFIG_PATHS) {
+    const fullPath = path.join(process.cwd(), p)
+
+    if (fs.existsSync(fullPath)) {
+      return fullPath
+    }
+  }
+
+  return null
+}
 
 function loadPostcssConfig() {
-  const jiti = nodeRequire("jiti")(import.meta.url, {
-    interopDefault: true,
-    esmResolve: true
-  })
-  const pcPath = path.join(process.cwd(), "postcss.config.mjs")
+  const jiti = createJiti()
+  const possiblePaths = [
+    "postcss.config.mjs",
+    "postcss.config.js",
+    "postcss.config.cjs"
+  ]
+
+  let mod = null
+
+  for (const p of possiblePaths) {
+    const fullPath = path.join(process.cwd(), p)
+
+    try {
+      mod = jiti(fullPath)
+      break
+    } catch {
+      // File not found, try next
+    }
+  }
 
-  let mod = jiti(pcPath)
+  if (!mod) {
+    throw new Error(
+      `${PREFIX} Could not find postcss.config.{mjs,js,cjs} in ${process.cwd()}`
+    )
+  }
 
   return mod?.default ?? mod
 }
 
+function checkIsUnoPlugin(entry) {
+  if (typeof entry === "string") {
+    return entry === "@unocss/postcss"
+  }
+
+  if (typeof entry === "function") {
+    const name = entry.name || ""
+
+    return name.toLowerCase().includes("unocss") || name.includes("Uno")
+  }
+
+  if (typeof entry === "object" && entry !== null) {
+    const postcssPlugin = entry.postcssPlugin || ""
+
+    return postcssPlugin.toLowerCase().includes("unocss")
+  }
+
+  return false
+}
+
+function extractConfigFromPlugin(entry) {
+  if (Array.isArray(entry)) {
+    const [nameOrFn, opts] = entry
+
+    if (checkIsUnoPlugin(nameOrFn) && opts?.configOrPath) {
+      return opts.configOrPath
+    }
+
+    if (checkIsUnoPlugin(nameOrFn)) {
+      return null
+    }
+  }
+
+  if (checkIsUnoPlugin(entry)) {
+    if (typeof entry === "object" && entry.configOrPath) {
+      return entry.configOrPath
+    }
+
+    return null
+  }
+
+  return undefined
+}
+
+function invalidateIfConfigChanged() {
+  if (!cfgPath) return false
+
+  try {
+    const stat = fs.statSync(cfgPath)
+
+    if (stat.mtimeMs !== cfgMtime) {
+      cfgMtime = stat.mtimeMs
+      cfgLoaded = false
+      cfg = null
+      uno = null
+      unoInitPromise = null
+
+      return true
+    }
+  } catch {
+    // File not accessible, keep cache
+  }
+
+  return false
+}
+
 function loadUnoConfigFromPostcss() {
   if (cfgLoaded) return cfg
 
   try {
     nodeRequire("tsconfig-paths/register")
-  } catch {}
+  } catch {
+    // Optional dependency
+  }
 
-  const pc = loadPostcssConfig()
+  let pc
+
+  try {
+    pc = loadPostcssConfig()
+  } catch (error) {
+    throw new Error(
+      `${PREFIX} Failed to load postcss config: ${error?.message || error}`
+    )
+  }
 
-  if (!pc || !Array.isArray(pc.plugins)) {
-    throw new Error("[UnoCSS-TP] postcss.config.mjs is invalid (no plugins).")
+  if (!(pc && Array.isArray(pc.plugins))) {
+    throw new Error(
+      `${PREFIX} postcss.config is invalid: "plugins" must be an array`
+    )
   }
 
-  let found = null
+  let found
 
   for (const entry of pc.plugins) {
-    if (!Array.isArray(entry)) continue
+    const result = extractConfigFromPlugin(entry)
 
-    const [nameOrFn, opts] = entry
-    const isUno = (
-      typeof nameOrFn === "string" && nameOrFn === "@unocss/postcss"
-    ) || (
-      typeof nameOrFn === "function" && (nameOrFn.name?.toLowerCase().includes("unocss") || nameOrFn.name?.includes("Uno"))
+    if (result !== undefined) {
+      found = result
+      break
+    }
+  }
+
+  if (found === undefined) {
+    throw new Error(
+      `${PREFIX} UnoCSS plugin not found in postcss.config plugins`
     )
+  }
 
-    if (!isUno) continue
+  if (found === null) {
+    const defaultPath = findDefaultConfigPath()
 
-    found = opts?.configOrPath
+    if (defaultPath) {
+      cfgPath = defaultPath
+
+      try {
+        const stat = fs.statSync(cfgPath)
+        cfgMtime = stat.mtimeMs
+      } catch {
+        // Will be handled below
+      }
+
+      try {
+        cfg = loadConfigFromPath(defaultPath)
+      } catch (error) {
+        throw new Error(
+          `${PREFIX} Failed to load default UnoCSS config from "${defaultPath}": ${error?.message || error}`
+        )
+      }
+    } else {
+      throw new Error(
+        `${PREFIX} No configOrPath provided and no default config found. Expected one of: ${DEFAULT_CONFIG_PATHS.join(", ")}`
+      )
+    }
+  } else if (typeof found === "string") {
+    cfgPath = resolveConfigPath(found)
+
+    try {
+      const stat = fs.statSync(cfgPath)
+      cfgMtime = stat.mtimeMs
+    } catch {
+      // Will be handled below
+    }
 
-    break
+    try {
+      cfg = loadConfigFromPath(found)
+    } catch (error) {
+      throw new Error(
+        `${PREFIX} Failed to load UnoCSS config from path "${found}": ${error?.message || error}`
+      )
+    }
+  } else if (typeof found === "object" && found !== null) {
+    cfg = found
+  } else {
+    throw new Error(
+      `${PREFIX} configOrPath must be an object (UnoCSS config) or a string (path to config file). Got: ${typeof found}`
+    )
   }
 
-  if (!found || typeof found !== "object") {
-    throw new Error("[UnoCSS-TP] Required object unoConfig: [\"@unocss/postcss\", { configOrPath: unoConfig }]")
+  if (!cfg || typeof cfg !== "object") {
+    throw new Error(`${PREFIX} Loaded config is not a valid object`)
   }
 
-  cfg = found
   cfgLoaded = true
 
   return cfg
 }
 
 async function getUno() {
+  invalidateIfConfigChanged()
+
   if (uno) return uno
   if (unoInitPromise) return unoInitPromise
 
-  const config = loadUnoConfigFromPostcss()
+  let config
 
-  unoInitPromise = createGenerator(config).then(u => (uno = u))
+  try {
+    config = loadUnoConfigFromPostcss()
+  } catch (error) {
+    console.error(error.message)
+    throw error
+  }
 
-  return unoInitPromise
+  try {
+    unoInitPromise = createGenerator(config).then((u) => {
+      uno = u
+      return u
+    })
+
+    return unoInitPromise
+  } catch (error) {
+    throw new Error(
+      `${PREFIX} Failed to create UnoCSS generator: ${error?.message || error}`
+    )
+  }
 }
 
 function isProcessable(id) {
-  return !!id
-    && !id.includes("node_modules")
-    && !/\.d\.ts$/.test(id)
-    && !/\.(test|spec)\.(t|j)sx?$/.test(id)
-    && /\.(t|j)sx?$/.test(id)
+  if (!id) return false
+  if (id.includes("node_modules")) return false
+  if (/\.d\.ts$/.test(id)) return false
+  if (/\.(test|spec)\.(t|j)sx?$/.test(id)) return false
+
+  return /\.(t|j)sx?$/.test(id)
 }
 
 function pickTransformers(enforce = "default") {
-  const list = (cfg?.transformers || [])
+  const list = cfg?.transformers || []
 
-  return list.filter(t => (t?.enforce || "default") === enforce)
+  return list.filter((t) => (t?.enforce || "default") === enforce)
 }
 
 async function applyTransformersPipeline(code, id) {
-  const u = await getUno()
+  let u
+
+  try {
+    u = await getUno()
+  } catch {
+    return null
+  }
+
   const original = code
-  const phases = ["pre","default","post"]
+  const phases = ["pre", "default", "post"]
   let current = code
 
   for (const phase of phases) {
@@ -101,7 +331,6 @@ async function applyTransformersPipeline(code, id) {
     if (!transformers.length) continue
 
     let s = new MagicString(current)
-    let changed = false
 
     for (const t of transformers) {
       if (!t) continue
@@ -109,7 +338,12 @@ async function applyTransformersPipeline(code, id) {
       if (t.idFilter) {
         try {
           if (!t.idFilter(id)) continue
-        } catch {}
+        } catch (error) {
+          console.warn(
+            `${PREFIX} idFilter failed for transformer "${t.name || "unknown"}": ${error?.message || error}`
+          )
+          continue
+        }
       }
 
       const fn = t.transform || t
@@ -126,23 +360,21 @@ async function applyTransformersPipeline(code, id) {
       try {
         await fn(s, id, ctx)
       } catch (error) {
-        console.error(`[UnoCSS-TP] transform failed in ${t.name || "transform"} for ${path.relative(process.cwd(), id)}:`, error?.stack || error?.message || error)
+        const relativePath = path.relative(process.cwd(), id)
+        console.error(
+          `${PREFIX} Transform failed in "${t.name || "unknown"}" for ${relativePath}: ${error?.stack || error?.message || error}`
+        )
       }
 
       if (s.hasChanged()) {
         current = s.toString()
         s = new MagicString(current)
-        changed = true
       }
     }
-
-    if (!changed) continue
   }
 
   if (current !== original) {
-    return {
-      code: current
-    }
+    return {code: current}
   }
 
   return null
@@ -152,10 +384,14 @@ const memo = new Map()
 const MEMO_LIMIT = 500
 
 function sha1Sync(s) {
-  const {createHash} = nodeRequire("node:crypto")
-
-  return createHash("sha1").update(s).digest("hex")
+  try {
+    const {createHash} = nodeRequire("node:crypto")
+    return createHash("sha1").update(s).digest("hex")
+  } catch {
+    return `${s.length}_${s.slice(0, 100)}`
+  }
 }
+
 function memoGet(key) {
   if (!memo.has(key)) return null
 
@@ -182,15 +418,23 @@ export default async function unoLoader(source) {
   if (!isProcessable(file)) return code
   if (code.length < 10) return code
 
-  const key = file + ":" + sha1Sync(code)
+  const key = `${file}:${sha1Sync(code)}`
   const cached = memoGet(key)
 
   if (cached) return cached
 
-  const res = await applyTransformersPipeline(code, file)
-  const out = (res?.code && res.code !== code) ? res.code : code
+  try {
+    const res = await applyTransformersPipeline(code, file)
+    const out = res?.code && res.code !== code ? res.code : code
+
+    memoSet(key, out)
 
-  memoSet(key, out)
+    return out
+  } catch (error) {
+    console.error(
+      `${PREFIX} Loader error for ${path.relative(process.cwd(), file)}: ${error?.message || error}`
+    )
 
-  return out
+    return code
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "turbopack-unocss-transform",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "license": "MIT",
   "author": "vizet <v@kogita.net>",
   "description": "A Turbopack loader for Next.js that applies UnoCSS transformers (like variant-group and attributify-jsx) directly to your TS/JS/TSX/JSX source before CSS generation.",
@@ -22,24 +22,31 @@
     "attributify-jsx"
   ],
   "type": "module",
-  "main": "dist/loader.mjs",
+  "main": "dist/index.mjs",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "default": "./dist/index.mjs"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
     },
-    "./loader": "./dist/loader.mjs"
+    "./loader": {
+      "import": "./dist/loader.mjs",
+      "require": "./dist/loader.cjs"
+    }
   },
   "files": [
     "dist"
   ],
   "peerDependencies": {
-    "unocss": ">=0.58.0"
+    "next": ">=15.0.0"
   },
   "dependencies": {
-    "jiti": "^1.21.0",
-    "magic-string": "^0.30.10",
-    "next": "^16.0.1",
+    "@unocss/core": "66.5.6",
+    "jiti": "^2.4.0",
+    "magic-string": "^0.30.17",
     "tsconfig-paths": "^4.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11"
   }
-}
+}