nuxt-processor 0.0.1

package/README.md

@@ -0,0 +1,131 @@
+# Nuxt Processor
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Background job processing for Nuxt using BullMQ with a dedicated workers process.
+
+- [✨  Release Notes](/CHANGELOG.md)
+<!-- - [📖 &nbsp;Documentation](https://example.com) -->
+
+## Features
+
+- **Dedicated processing**: Workers run in a separate Node process – no coupling to your web server.
+- **Scalability**: Run multiple worker processes and instances across machines; backed by Redis.
+- **Simple DX**: Define queues/workers in `server/queues` and `server/workers` using first-class helpers.
+
+## Install
+
+```bash
+npm i -D nuxt-processor
+```
+
+Add the module in `nuxt.config.ts` and set your Redis connection.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-processor'],
+  workers: {
+    redis: {
+      host: process.env.NUXT_REDIS_HOST ?? '127.0.0.1', // defaults '127.0.0.1'
+      port: Number(process.env.NUXT_REDIS_PORT ?? 6379), // defaults 6379
+      password: process.env.NUXT_REDIS_PASSWORD ?? '', // defaults ''
+    },
+  },
+})
+```
+
+## Define a queue and enqueue from your app
+
+Create `server/queues/index.ts`:
+
+```ts
+import { defineQueue } from '#workers'
+
+export default defineQueue({
+  name: 'hello',
+})
+```
+
+## Define a worker
+
+Create `server/workers/index.ts`:
+
+```ts
+import { defineWorker } from '#workers'
+import type { Job } from '#bullmq'
+
+export default defineWorker({
+  name: 'hello',
+  async processor(job: Job) {
+    // do work
+    console.log('processed', job.name, job.data)
+    return job.data
+  },
+  options: {},
+})
+```
+
+## Running
+
+- Start your Nuxt app normally (dev or build). This module generates a dedicated workers entry.
+- Start workers explicitly in a separate terminal:
+
+```bash
+# after a build
+nuxi build
+node .output/server/workers/index.mjs
+```
+
+## Shutdown
+
+The workers process handles graceful shutdown on `SIGINT/SIGTERM` and logs worker start/stop.
+
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+  
+  ```bash
+  # Install dependencies
+  npm install
+  
+  # Generate type stubs
+  npm run dev:prepare
+  
+  # Develop with the playground
+  npm run dev
+  
+  # Build the playground
+  npm run dev:build
+  
+  # Run ESLint
+  npm run lint
+  
+  # Run Vitest
+  npm run test
+  npm run test:watch
+  
+  # Release new version
+  npm run release
+  ```
+
+</details>
+
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/my-module
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/my-module
+
+[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/my-module
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,12 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { RedisOptions } from 'bullmq';
+
+interface ModuleOptions {
+    redis: RedisOptions;
+    queues: string[];
+    workers: string[];
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-processor",
+  "version": "0.0.1",
+  "compatibility": {
+    "nuxt": "^4.0.0"
+  },
+  "configKey": "processor",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,244 @@
+import { defineNuxtModule, createResolver, addTemplate, logger } from '@nuxt/kit';
+import { readdir } from 'node:fs/promises';
+import { relative } from 'node:path';
+
+const name = "nuxt-processor";
+const version = "0.0.1";
+const configKey = "processor";
+const compatibility = {
+	nuxt: "^4.0.0"
+};
+
+const module = defineNuxtModule({
+  meta: {
+    name,
+    version,
+    compatibility,
+    configKey
+  },
+  // Default configuration options of the Nuxt module
+  defaults: {
+    redis: {
+      host: process.env.NUXT_REDIS_HOST ?? "127.0.0.1",
+      port: Number(process.env.NUXT_REDIS_PORT ?? 6379),
+      password: process.env.NUXT_REDIS_PASSWORD ?? ""
+    },
+    queues: [],
+    workers: []
+  },
+  setup(_options, _nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    const buildDir = _nuxt.options.buildDir;
+    const srcDir = _nuxt.options.srcDir;
+    const allowedExtensions = /* @__PURE__ */ new Set([".ts", ".js", ".mjs", ".mts", ".cjs", ".cts"]);
+    async function collectFiles(fromDir) {
+      const results = [];
+      async function walk(dir) {
+        let entries = [];
+        try {
+          entries = await readdir(dir, { withFileTypes: true });
+        } catch (err) {
+          logger.withTag("nuxt-processor").warn("failed to read directory", dir, err);
+          return;
+        }
+        await Promise.all(entries.map(async (entry) => {
+          const fullPath = resolve(dir, entry.name);
+          if (entry.isDirectory()) {
+            await walk(fullPath);
+          } else {
+            const dotIndex = fullPath.lastIndexOf(".");
+            const ext = dotIndex >= 0 ? fullPath.slice(dotIndex) : "";
+            if (allowedExtensions.has(ext)) {
+              results.push(fullPath);
+            }
+          }
+        }));
+      }
+      await walk(fromDir);
+      return results;
+    }
+    function generateWorkersEntryContent(workerFiles) {
+      const redisInline = JSON.stringify(_options.redis ?? {});
+      const toImportArray = workerFiles.map((id) => `() => import(${JSON.stringify(id)})`).join(",\n    ");
+      return `
+import { fileURLToPath } from 'node:url'
+import { resolve as resolvePath } from 'node:path'
+import { consola } from 'consola'
+import { $workers } from '#workers-utils'
+
+// Initialize connection as early as possible so any imports that register
+// workers/queues have a valid connection available.
+const api = $workers()
+api.setConnection(${redisInline})
+
+export async function createWorkersApp() {
+  // Avoid EPIPE when stdout/stderr are closed by terminal (e.g., Ctrl+C piping)
+  const handleStreamError = (err) => {
+    try {
+      const code = (typeof err === 'object' && err && 'code' in err) ? err.code : null
+      if (code === 'EPIPE') return
+    } catch (e) { console.warn?.('nuxt-processor: stream error inspection failed', e) }
+    throw err
+  }
+  try { process.stdout?.on?.('error', handleStreamError) } catch (err) { console.warn('nuxt-processor: failed to attach stdout error handler', err) }
+  try { process.stderr?.on?.('error', handleStreamError) } catch (err) { console.warn('nuxt-processor: failed to attach stderr error handler', err) }
+  const modules = [
+    ${toImportArray}
+  ]
+  for (const loader of modules) {
+    await loader()
+  }
+  const logger = consola.create({}).withTag('nuxt-processor')
+  try {
+    const workerNames = Array.isArray(api.workers) ? api.workers.map(w => w && w.name).filter(Boolean) : []
+    logger.info('starting workers:\\n' + workerNames.map(n => ' - ' + n).join('\\n'))
+    for (const w of api.workers) {
+      w.on('error', (err) => logger.error('worker error', err))
+    }
+    // Explicitly start workers since autorun is disabled
+    for (const w of api.workers) {
+      try {
+        // run() returns a promise that resolves when the worker stops; do not await to avoid blocking
+        // eslint-disable-next-line promise/catch-or-return
+        w.run().catch((err) => logger.error('worker run error', err))
+      }
+      catch (err) {
+        logger.error('failed to start worker', err)
+      }
+    }
+    logger.success('workers started')
+  } catch (err) {
+    logger.error('failed to initialize workers', err)
+  }
+  return { stop: api.stopAll, workers: api.workers }
+}
+
+const isMain = (() => {
+  try {
+    if (typeof process === 'undefined' || !process.argv || !process.argv[1]) return false
+    const argvPath = resolvePath(process.cwd?.() || '.', process.argv[1])
+    const filePath = fileURLToPath(import.meta.url)
+    return filePath === argvPath
+  } catch {
+    return false
+  }
+})()
+if (isMain) {
+  const logger = consola.create({}).withTag('nuxt-processor')
+  const appPromise = createWorkersApp().catch((err) => {
+    logger.error('failed to start workers', err)
+    process.exit(1)
+  })
+  const shutdown = async () => {
+    try { logger.info('closing workers...') } catch (err) { console.warn('nuxt-processor: failed to log shutdown start', err) }
+    try {
+      const app = await appPromise
+      try {
+        const names = (app?.workers || []).map(w => w && w.name).filter(Boolean)
+        logger.info('closing workers:\\n' + names.map(n => ' - ' + n).join('\\n'))
+      } catch (eL) { console.warn('nuxt-processor: failed to log workers list on shutdown', eL) }
+      await app.stop()
+      try { logger.success('workers closed') } catch (err2) { console.warn('nuxt-processor: failed to log shutdown complete', err2) }
+    }
+    finally { process.exit(0) }
+  }
+  ;['SIGINT','SIGTERM','SIGQUIT'].forEach(sig => process.on(sig, shutdown))
+  process.on('beforeExit', shutdown)
+}
+
+export default { createWorkersApp }
+`;
+    }
+    const { resolve: r } = createResolver(import.meta.url);
+    _nuxt.options.alias = _nuxt.options.alias || {};
+    _nuxt.options.alias["nuxt-processor"] = r("./runtime/server/handlers");
+    _nuxt.options.alias["#workers"] = r("./runtime/server/handlers");
+    _nuxt.options.alias["#workers-utils"] = r("./runtime/server/utils/workers");
+    if (!_nuxt.options.alias["#bullmq"]) {
+      _nuxt.options.alias["#bullmq"] = "bullmq";
+    }
+    const typesDtsPath = addTemplate({
+      filename: "types/nuxt-processor.d.ts",
+      write: true,
+      getContents: () => `
+declare module 'nuxt-processor' {
+  export { defineQueue } from '${r("./runtime/server/handlers/defineQueue")}'
+  export { defineWorker } from '${r("./runtime/server/handlers/defineWorker")}'
+}
+
+declare module '#workers' {
+  export { defineQueue } from '${r("./runtime/server/handlers/defineQueue")}'
+  export { defineWorker } from '${r("./runtime/server/handlers/defineWorker")}'
+}
+
+declare module '#workers-utils' {
+  export { $workers } from '${r("./runtime/server/utils/workers")}'
+}
+
+declare module '#bullmq' {
+  export * from 'bullmq'
+}
+`
+    }).dst;
+    _nuxt.hooks.hook("prepare:types", (opts) => {
+      if (!opts.tsConfig.include) opts.tsConfig.include = [];
+      opts.tsConfig.include.push(resolve(buildDir, typesDtsPath));
+    });
+    function createWorkersRollupPlugin() {
+      const VIRTUAL_ID = "\0nuxt-processor-entry";
+      let virtualCode = "";
+      let entryRefId = null;
+      return {
+        name: "nuxt-processor-emit",
+        async buildStart() {
+          const workerFiles = await collectFiles(resolve(srcDir, "server/workers"));
+          if (workerFiles.length === 0) {
+            virtualCode = "";
+            return;
+          }
+          virtualCode = generateWorkersEntryContent(workerFiles);
+          for (const id of workerFiles) {
+            this.addWatchFile(id);
+          }
+          entryRefId = this.emitFile({ type: "chunk", id: VIRTUAL_ID, fileName: "workers/_entry.mjs" });
+        },
+        resolveId(id) {
+          if (id === VIRTUAL_ID) return VIRTUAL_ID;
+        },
+        load(id) {
+          if (id === VIRTUAL_ID) return virtualCode || "export {}\n";
+        },
+        generateBundle() {
+          if (!virtualCode || !entryRefId) return;
+          const entryFile = this.getFileName(entryRefId);
+          const fromDir = "workers";
+          const rel = "./" + relative(fromDir, entryFile).split("\\").join("/");
+          const wrapper = `import { createWorkersApp } from '${rel}'
+import { consola } from 'consola'
+const logger = consola.create({}).withTag('nuxt-processor')
+const appPromise = createWorkersApp().catch((err) => { logger.error('failed to start workers', err); process.exit(1) })
+let shuttingDown = false
+const shutdown = async (signal) => { if (shuttingDown) return; shuttingDown = true; try { logger.info('closing workers' + (signal ? ' ('+signal+')' : '') + '...') } catch (e) { console.warn('nuxt-processor: failed to log shutdown start', e) } ; try { const app = await appPromise; try { const names = (app?.workers || []).map(w => w && w.name).filter(Boolean); logger.info('closing workers:\\n' + names.map(n => ' - ' + n).join('\\n')) } catch (eL) { console.warn('nuxt-processor: failed to log workers list on shutdown', eL) } await app.stop(); try { logger.success('workers closed') } catch (e2) { console.warn('nuxt-processor: failed to log shutdown complete', e2) } } catch (err) { try { logger.error('shutdown error', err) } catch (e3) { console.warn('nuxt-processor: failed to log shutdown error', e3) } } finally { setTimeout(() => process.exit(0), 0) } }
+[ 'SIGINT','SIGTERM','SIGQUIT' ].forEach(sig => process.on(sig, () => shutdown(sig)))
+process.on('beforeExit', () => shutdown('beforeExit'))
+`;
+          this.emitFile({ type: "asset", fileName: "workers/index.mjs", source: wrapper });
+        }
+      };
+    }
+    _nuxt.hooks.hook("nitro:config", (nitroConfig) => {
+      nitroConfig.rollupConfig = nitroConfig.rollupConfig ?? {};
+      const plugin = createWorkersRollupPlugin();
+      const current = nitroConfig.rollupConfig.plugins;
+      if (Array.isArray(current)) {
+        nitroConfig.rollupConfig.plugins = [...current, plugin];
+      } else if (current) {
+        nitroConfig.rollupConfig.plugins = [current, plugin];
+      } else {
+        nitroConfig.rollupConfig.plugins = [plugin];
+      }
+    });
+  }
+});
+
+export { module as default };

package/dist/runtime/server/handlers/defineQueue.d.ts

@@ -0,0 +1,9 @@
+import type { Queue, QueueOptions, JobsOptions } from '../utils/workers.js';
+type DefineQueueArgs = {
+    name: Queue['name'];
+    options?: Omit<QueueOptions, 'connection'> & {
+        defaultJobOptions?: JobsOptions;
+    };
+};
+export declare function defineQueue({ name, options }: DefineQueueArgs): Queue;
+export default defineQueue;

package/dist/runtime/server/handlers/defineQueue.js

@@ -0,0 +1,6 @@
+import { $workers } from "../utils/workers.js";
+export function defineQueue({ name, options }) {
+  const { createQueue } = $workers();
+  return createQueue(name, options);
+}
+export default defineQueue;

package/dist/runtime/server/handlers/defineWorker.d.ts

@@ -0,0 +1,8 @@
+import type { Worker, WorkerOptions, Processor } from 'bullmq';
+type DefineWorkerArgs = {
+    name: Worker['name'];
+    processor: Processor;
+    options?: Omit<WorkerOptions, 'connection'>;
+};
+export declare function defineWorker(args: DefineWorkerArgs): Worker;
+export default defineWorker;

package/dist/runtime/server/handlers/defineWorker.js

@@ -0,0 +1,7 @@
+import { $workers } from "../utils/workers.js";
+export function defineWorker(args) {
+  const { name, options, processor } = args;
+  const { createWorker } = $workers();
+  return createWorker(name, processor, options);
+}
+export default defineWorker;

package/dist/runtime/server/handlers/index.d.ts

@@ -0,0 +1,2 @@
+export { defineQueue } from './defineQueue.js';
+export { defineWorker } from './defineWorker.js';

package/dist/runtime/server/handlers/index.js

@@ -0,0 +1,2 @@
+export { defineQueue } from "./defineQueue.js";
+export { defineWorker } from "./defineWorker.js";

package/dist/runtime/server/utils/workers.d.ts

@@ -0,0 +1,13 @@
+import type { Job, JobsOptions, QueueOptions, WorkerOptions, Processor } from 'bullmq';
+import { Queue, Worker } from 'bullmq';
+export declare function $workers(): {
+    setConnection: (connection: QueueOptions["connection"]) => void;
+    createQueue: (name: string, options?: Omit<QueueOptions, "connection"> & {
+        defaultJobOptions?: JobsOptions;
+    }) => Queue<any, any, string, any, any, string>;
+    createWorker: (name: string, processor: Processor, options?: Omit<WorkerOptions, "connection">) => Worker<any, any, string>;
+    stopAll: () => Promise<void>;
+    readonly queues: Queue<any, any, string, any, any, string>[];
+    readonly workers: Worker<any, any, string>[];
+};
+export type { Queue, Worker, Processor, QueueOptions, WorkerOptions, JobsOptions, Job };

package/dist/runtime/server/utils/workers.js

@@ -0,0 +1,44 @@
+import { Queue, Worker } from "bullmq";
+const registry = {
+  connection: void 0,
+  queues: [],
+  workers: []
+};
+export function $workers() {
+  function setConnection(connection) {
+    registry.connection = connection;
+  }
+  function createQueue(name, options) {
+    const queue = new Queue(name, {
+      connection: registry.connection,
+      ...options
+    });
+    registry.queues.push(queue);
+    return queue;
+  }
+  function createWorker(name, processor, options) {
+    const worker = new Worker(name, processor, {
+      connection: registry.connection,
+      ...options,
+      autorun: false
+    });
+    registry.workers.push(worker);
+    return worker;
+  }
+  async function stopAll() {
+    await Promise.allSettled(registry.workers.map((w) => w.close()));
+    await Promise.allSettled(registry.queues.map((q) => q.close()));
+  }
+  return {
+    setConnection,
+    createQueue,
+    createWorker,
+    stopAll,
+    get queues() {
+      return registry.queues;
+    },
+    get workers() {
+      return registry.workers;
+    }
+  };
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "nuxt-processor",
+  "version": "0.0.1",
+  "description": "Nuxt Processor",
+  "repository": "https://github.com/aidanhibbard/nuxt-processor",
+  "license": "MIT",
+  "type": "module",
+  "configKey": "processor",
+  "compatibility": {
+    "nuxt": "^4.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "release": "npm run lint && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "vp:dev": "vitepress dev docs",
+    "vp:build": "vitepress build docs",
+    "vp:preview": "vitepress preview docs"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.0.3",
+    "bullmq": "^5.58.2",
+    "ioredis": "^5.7.0"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^2.6.3",
+    "@nuxt/eslint": "^1.9.0",
+    "@nuxt/eslint-config": "^1.9.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.0.3",
+    "@nuxt/test-utils": "^3.19.2",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.34.0",
+    "nuxt": "^4.0.3",
+    "typescript": "~5.9.2",
+    "vitepress": "^2.0.0-alpha.12",
+    "vitest": "^3.2.4",
+    "vue-tsc": "^3.0.6"
+  }
+}