fixes

.github/workflows/ci.yml

@@ -18,5 +18,6 @@ jobs:
           cache: 'npm'
           cache-dependency-path: package-lock.json
       - run: npm ci
-      - run: npm ci --prefix playground
+      - run: npm ci --prefix playground/nitro
+      - run: npm ci --prefix playground/vite-nitro
       - run: npm run ci

CONTRIBUTING.md

@@ -35,20 +35,32 @@ npm install
 npm run dev:prepare
 ```
 
-### Playground
+### Playgrounds
+
+Two sample apps live under `playground/`:
+
+| Path | Stack | Dev command |
+| --- | --- | --- |
+| `playground/nitro/` | Standalone Nitro | `npm run dev` |
+| `playground/vite-nitro/` | Vite + Nitro plugin | `npm run dev:vite` |
 
 ```bash
-# Nitro app + hot reload
+# Standalone Nitro app + hot reload
 npm run dev
 
-# Production build of the playground
+# Vite + Nitro app + hot reload
+npm run dev:vite
+
+# Production builds
 npm run dev:build
+npm run dev:vite:build
 ```
 
-Workers run in a separate process (see README). From the project root after `npm run dev`:
+Workers run in a separate process (see README). From the project root after starting the app:
 
 ```bash
-npm run processor:dev
+npm run processor:dev        # playground/nitro
+npm run processor:dev:vite   # playground/vite-nitro
 ```
 
 ### Quality checks
@@ -88,7 +100,8 @@ Breaking changes should be called out in the PR description and documented in
 | `src/module.ts` | Nitro module entry |
 | `src/runtime/` | `defineQueue`, `defineWorker`, `useProcessor` |
 | `src/utils/` | Build-time helpers (workers entry, Redis config) |
-| `playground/` | Development app |
+| `playground/nitro/` | Standalone Nitro development app |
+| `playground/vite-nitro/` | Vite + Nitro development app |
 | `docs/` | VitePress documentation |
 | `spec/` | Vitest unit tests |
 | `scripts/` | Build verification helpers |

README.md

@@ -101,6 +101,7 @@ See [Redis configuration](https://aidanhibbard.github.io/nitro-processor/redis)
 
 ```ts
 import { defineQueue } from '#processor'
+// or: import { defineQueue } from 'nitro-processor/runtime'
 
 export default defineQueue({
   name: 'hello',

build.config.ts

@@ -4,7 +4,7 @@ export default defineBuildConfig({
   entries: [
     { type: 'bundle', input: ['src/module.ts'], dts: true },
     { type: 'bundle', input: ['src/cli.ts'] },
+    { type: 'bundle', input: ['src/runtime-entry.ts'], dts: true },
     { type: 'transform', input: './src/runtime', outDir: './dist/runtime' },
-    { type: 'transform', input: './src/types.d.mts', outDir: './dist' },
   ],
 })

docs/api.md

@@ -8,17 +8,35 @@ Reference for module options, runtime config, helpers, and the CLI.
 
 ## Imports
 
-| Alias | Exports |
+Use Nitro virtual aliases in server code, or import from the published runtime entry when typechecking with plain `tsc` (before Nitro generates types):
+
+| Import | Exports |
 | --- | --- |
 | `#processor` | `defineQueue`, `defineWorker` |
 | `#processor-utils` | `useProcessor`, BullMQ types (`Queue`, `Worker`, `Processor`, …) |
 | `#bullmq` | Re-exports from `bullmq` |
+| `nitro-processor/runtime` | `defineQueue`, `defineWorker`, `useProcessor`, BullMQ types |
 
 ```ts
 import { defineQueue, defineWorker } from '#processor'
+import { useProcessor } from 'nitro-processor/runtime'
 import type { Job } from '#bullmq'
 ```
 
+### TypeScript
+
+The package ships ambient declarations for `#processor`, `#processor-utils`, and `#bullmq`, plus a path map for plain `tsc`:
+
+```json
+{
+  "extends": ["nitro/tsconfig", "nitro-processor/tsconfig.paths.json"]
+}
+```
+
+For project references (`tsc -b`), extend the same path map from your app tsconfig. The repo includes reference playgrounds under `playground/nitro/` (standalone Nitro) and `playground/vite-nitro/` (Vite + Nitro).
+
+When the Nitro module is registered, `types:extend` adds the same paths to Nitro's generated tsconfig automatically.
+
 ## Module options
 
 Configure when registering the module in `nitro.config.ts` or `vite.config.ts`. See [Configuration](/configuration) for Vite setup and `buildDir`.

package.json

@@ -18,13 +18,27 @@
     ".": {
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
-    }
+    },
+    "./runtime": {
+      "types": "./dist/runtime-entry.d.mts",
+      "import": "./dist/runtime-entry.mjs"
+    },
+    "./virtual": {
+      "types": "./dist/virtual.d.mts"
+    },
+    "./tsconfig.paths.json": "./tsconfig.paths.json"
   },
   "main": "./dist/module.mjs",
   "typesVersions": {
     "*": {
       ".": [
         "./dist/types.d.mts"
+      ],
+      "runtime": [
+        "./dist/runtime-entry.d.mts"
+      ],
+      "virtual": [
+        "./dist/virtual.d.mts"
       ]
     }
   },
@@ -34,23 +48,32 @@
   "files": [
     "dist",
     "bin",
-    "docs/**/*.md"
+    "docs/**/*.md",
+    "tsconfig.paths.json"
   ],
   "scripts": {
-    "prepack": "obuild",
-    "dev": "npm run dev:prepare && nitro dev playground",
-    "dev:build": "nitro build playground",
-    "processor:dev": "nitro-processor dev playground",
+    "prepack": "obuild && tsx scripts/assemble-types.ts",
+    "dev": "npm run dev:prepare && nitro dev playground/nitro",
+    "dev:build": "nitro build playground/nitro",
+    "dev:vite": "npm run dev:prepare && vite dev playground/vite-nitro",
+    "dev:vite:build": "vite build playground/vite-nitro",
+    "processor:dev": "nitro-processor dev playground/nitro",
+    "processor:dev:vite": "nitro-processor dev playground/vite-nitro",
     "dev:prepare": "obuild --stub",
     "release": "npm run ci && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --coverage",
-    "ci": "npm run lint && npm run typecheck && npm run test:types && npm run test",
+    "ci": "npm run lint && npm run typecheck && npm run prepack && npm run test:types && npm run test:playgrounds && npm run test",
+    "pretest:playgrounds": "npm ci --prefix playground/nitro && npm ci --prefix playground/vite-nitro",
+    "test:playgrounds": "npm run test:playground:build && npm run test:playground:processor",
+    "test:playground:build": "npm run build --prefix playground/vite-nitro",
+    "test:playground:processor": "tsx scripts/playground-vite-processor-dev.ts",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest watch",
-    "test:types": "tsc --noEmit -p playground/tsconfig.json",
+    "pretest:types": "tsx scripts/ensure-dist-types.ts",
+    "test:types": "tsc --noEmit -p playground/nitro/tsconfig.json && tsc -b playground/vite-nitro/tsconfig.json",
     "vp:dev": "vitepress dev docs",
     "vp:build": "vitepress build docs",
     "vp:preview": "vitepress preview docs"

playground/nitro.config.ts → playground/nitro/nitro.config.ts

@@ -1,5 +1,5 @@
 import { defineConfig } from 'nitro/config'
-import nitroProcessor from '../src/module'
+import nitroProcessor from '../../src/module'
 
 export default defineConfig({
   modules: [nitroProcessor({ workers: 'server/workers' })],

playground/package.json → playground/nitro/package.json

@@ -1,12 +1,13 @@
 {
   "private": true,
-  "name": "nitro-processor-playground",
+  "name": "nitro-processor-playground-nitro",
   "type": "module",
   "scripts": {
     "dev": "nitro dev",
     "build": "nitro build"
   },
   "dependencies": {
-    "nitro": "latest"
+    "nitro": "latest",
+    "nitro-processor": "file:../.."
   }
 }

playground/tsconfig.json → playground/nitro/tsconfig.json

@@ -1,6 +1,6 @@
 {
-  "extends": "nitro/tsconfig",
-  "include": ["server/**/*.ts", "types/**/*.d.ts", "nitro.config.ts"],
+  "extends": ["nitro/tsconfig", "nitro-processor/tsconfig.paths.json"],
+  "include": ["server/**/*.ts", "nitro.config.ts"],
   "compilerOptions": {
     "strict": true,
     "noUncheckedIndexedAccess": true,

playground/vite-nitro/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>nitro-processor vite playground</title>
+  </head>
+  <body>
+    <h1>nitro-processor vite playground</h1>
+  </body>
+</html>