virtual module error with workflow

Discussed in https://github.com/vercel/workflow/discussions/3805

^{Originally posted by xmlking August 26, 2026}

I am using vite-env i.e., import ViteEnv from "@vite-env/core/plugin"; in Vite environment along with workflow-devkit plugin.

I am getting this error when I start the dev server

Please advice if there is any workaround

Error

 vpr web#dev
workflows build complete (13 steps, 1 workflow, time 717ms)
~/apps/web$ vp dev ⊘ cache disabled
✘ [ERROR] Could not resolve "virtual:env/server"

    ../../packages/db/src/index.ts:3:20:
      3 │ import { env } from "virtual:env/server";
        ╵                     ~~~~~~~~~~~~~~~~~~~~

  You can mark the path "virtual:env/server" as external to exclude it from the bundle, which will
  remove this error and leave the unresolved path in the bundle.

error when starting dev server:
Error: Build failed with 1 error:
../../packages/db/src/index.ts:3:20: ERROR: Could not resolve "virtual:env/server"

Claude Root Cause Analysis

packages/db/src/index.ts does import { env } from "virtual:env/server" — that's a virtual module only resolvable by the @vite-env/core Vite plugin (ViteEnv() in apps/web/vite.config.ts).

Your new workflow file apps/web/src/workflows/my.workflow.ts has "use step" functions that call into ../server/workflows/my.service.ts, which imports the live db client from @workspace/db. The Workflow DevKit's dev builder (LocalBuilder in @workflow/nitro) bundles workflow files with a plain esbuild pass, completely separate from Vite. Per its own comment in builders.js:

"In dev, Nitro dynamically imports the generated workflow files from disk, so there is no later Rollup pass to resolve externalized local TypeScript imports" → so it sets bundleTransitiveLocalStepDependencies: true in dev.

That means it inlines local workspace TS packages (like @workspace/db, since it's raw source, not a prebuilt npm package) transitively into the steps bundle. When esbuild hits packages/db/src/index.ts, it can't resolve virtual:env/server because there's no Vite plugin container in that pass — hence the error, happening at the workflows build step, before vp dev's own Vite pipeline even starts.

This isn't a config typo — it's an architecture mismatch: packages/db assumes it's always processed through Vite, but workflow "steps" (which are meant to do real I/O like DB calls) get bundled independently.

Start by reproducing the workflows build and dev-server failure, then read packages/db/src/index.ts, apps/web/vite.config.ts, and the workflow files named in the report. Trace LocalBuilder in @workflow/nitro and its builders.js handling of local dependencies and virtual modules. Done means the reported workflow can start without the unresolved virtual:env/server error, or the supported workaround is clearly documented.