Use my Nitro functions in a worker?

[drewbaker]

I have Sidequest.js setup to run job tasks outside of Nitro (they run in a Node worker): sidequestjs/sidequest#125 (comment)

I want to call functions in this jobs, that are defined in my Nitro server/utils folder. The problem is, those files just don't exist at the paths Sidequest job thinks they do, because of the way Nitro just bundles everything when it gets deployed to the server.

Sidequest runs without a build step I think.

So when the job runs, it gives this error:

Package import specifier "#nitro-internal-virtual/storage" is not defined in package /opt/render/project/src/node_modules/nitropack/package.json imported from /opt/render/project/src/node_modules/nitropack/dist/runtime/internal/storage.mjs at
Attempt 1 by sidequest@srv-d6fglta4d50c73ed7o2g-5766c9747f-m7qzd-79
Stack Trace

      TypeError [ERR_PACKAGE_IMPORT_NOT_DEFINED]: Package import specifier "#nitro-internal-virtual/storage" is not defined in package /opt/render/project/src/node_modules/nitropack/package.json imported from /opt/render/project/src/node_modules/nitropack/dist/runtime/internal/storage.mjs
    at importNotDefined (node:internal/modules/esm/resolve:297:10)
    at packageImportsResolve (node:internal/modules/esm/resolve:747:9)
    at moduleResolve (node:internal/modules/esm/resolve:844:16)
    at defaultResolve (node:internal/modules/esm/resolve:988:11)
    at #cachedDefaultResolve (node:internal/modules/esm/loader:697:20)
    at #resolveAndMaybeBlockOnLoaderThread (node:internal/modules/esm/loader:714:38)
    at ModuleLoader.resolveSync (node:internal/modules/esm/loader:746:52)
    at #resolve (node:internal/modules/esm/loader:679:17)
    at ModuleLoader.getOrCreateModuleJob (node:internal/modules/esm/loader:599:35)
    at ModuleJob.syncLink (node:internal/modules/esm/module_job:160:33)

So whats involved with calling Nitro functions from outside Nitro?

A workaround I had thought of was to use a Nitro task, and call it via a CLI command or perhaps get runTask() working in a job. But the limitation on tasks only being able to run one instance at a time prevents that from working. I'd need to run the same task concurrently, but with different payloads.

[drewbaker]

I got this working today, I can't even believe it. Have been at this for months!

The problem

Sidequest's manualJobResolution mode works by finding sidequest.jobs.js on the filesystem at runtime and loading it via import() in a piscina worker thread — completely outside of Nitro's bundle context. Our sidequest.jobs.js imported raw TypeScript job files using #server/ and #root/ path aliases, which only resolve inside Nitro's bundled virtual module system. In a plain Node.js import(), this immediately hits:

ERR_PACKAGE_IMPORT_NOT_DEFINED: Package import specifier "#nitro-internal-virtual/storage"

Why import.meta.url doesn't work for path resolution

Our first instinct was to use dirname(fileURLToPath(import.meta.url)) in the Sidequest init plugin to locate the correct shim file. This fails because of ESM evaluation order: Nitro compiles import.meta.url to globalThis._importMeta_.url, which is set from index.mjs. But since nitro.mjs is a static import of index.mjs, it evaluates fully before index.mjs's body runs — leaving the fake file:///_entry.js placeholder. We switched to process.argv[1] which is set by Node before any module code runs.

Why we can't just re-export from nitro.mjs

We tried writing a thin shim that re-exported job classes from the compiled nitro.mjs chunk. Two problems:

• Mangled export names — Rollup renames exports (TemplateProcessJob becomes T, etc.) and job classes not referenced by route handlers get tree-shaken out of the public export map entirely.
• Server startup side effects — nitro.mjs contains top-level code that starts the HTTP server, scheduler, and error handlers. Importing it in a piscina worker thread runs all of that in every worker, causing race conditions and failures on first run.

The solution: esbuild standalone bundle + nitropack/runtime shim

After each Nitro build, a compiled hook in nitro.config.ts runs esbuild on the original sidequest.jobs.js source file, producing a self-contained .output/server/sidequest.jobs.js that:

• Bundles only the job files and their transitive dependencies from the server/ source tree
• Keeps all node_modules packages external (they're available in the worker's module scope)
• Aliases nitropack/runtime to a local shim

The nitropack/runtime shim is needed because server utility files use useRuntimeConfig() to read config values — but the real nitropack/runtime immediately tries to load #nitro-internal-virtual/storage and other virtual modules that only exist inside Nitro's bundle. The shim replaces useRuntimeConfig() with a Proxy that reads NITRO_*-prefixed environment variables, which is exactly what Nitro's runtime does at runtime anyway:

// server/_lib/nitropack-runtime-shim.ts
export function useRuntimeConfig() {
    return new Proxy({} as Record<string, string>, {
        get(_target, key: string) {
            const envKey = `NITRO_${key.replace(/([A-Z])/g, "_$1").toUpperCase()}`;
            return process.env[envKey] ?? process.env[key] ?? "";
        },
    });
}

Some server files were using useRuntimeConfig as a bare global (via Nitro's auto-import system) with no explicit import statement. esbuild doesn't do auto-imports, so those had to be given explicit import { useRuntimeConfig } from "nitropack/runtime" statements so the alias could take effect.

The jobsFilePath config

In the Sidequest init plugin, we pass jobsFilePath pointing at .output/server/sidequest.jobs.js so Sidequest uses the esbuild bundle instead of finding the raw source sidequest.jobs.js by filesystem search. In dev mode this is omitted entirely since workers never run locally.

// Only set in staging/production — dev mode never runs workers
const jobsFilePath = !isDev
    ? resolvePath(dirname(process.argv[1]), "sidequest.jobs.js")
    : undefined;

The nitro.config.ts hook in full

hooks: {
    "compiled": async function () {
        const outputDir = resolve(__dirname, ".output/server");
        await esbuild({
            entryPoints: [resolve(__dirname, "sidequest.jobs.js")],
            outfile: resolve(outputDir, "sidequest.jobs.js"),
            bundle: true,
            format: "esm",
            platform: "node",
            packages: "external",
            alias: {
                "#root": resolve(__dirname, "./"),
                "#server": resolve(__dirname, "server"),
                "nitropack/runtime": resolve(__dirname, "server/_lib/nitropack-runtime-shim.ts"),
            },
            tsconfig: resolve(__dirname, "tsconfig.json"),
        });
    },
},