Potential workflow/builders@4.0.1-beta.64 regression: Next.js build fails to resolve relative `.ts` imports in step files

[pablodecm]

Description

After upgrading workflow from 4.2.0-beta.72 to 4.2.0-beta.73, Next.js production builds fail with Module not found errors for relative TypeScript imports inside step files.

The regression is in the transitive dependency @workflow/builders@4.0.1-beta.64, which introduced "Corrected dependency resolution for step imports with TypeScript extensions (.ts, .mts, .cts)". This "correction" breaks resolution of extensionless relative imports to .ts modules — the bundler looks for .js instead of .ts.

Is very strange, but seems that only happens in the vercel build not in local but not totally sure yet about this.

Reproduction

A step file imports a local utility with a standard extensionless relative path:

// upload-video-and-build-output.step.ts
import { getVideoDimensions, getVideoFeatureCost, getVideoOriginAndFetchOptions } from "../utils/model-config";

The file ../utils/model-config.ts exists. The build compiles workflow steps into apps/web/app/.well-known/workflow/v1/step/route.js, which fails:

Module not found: Can't resolve '../../../../../src/server/lib/tasks/video-clip/utils/model-config.js'

Environment

• workflow: 4.2.0-beta.73
• @workflow/next: 4.0.1-beta.69 (transitive)
• @workflow/builders: 4.0.1-beta.64 (transitive — this is the breaking change)
• @workflow/rollup: 4.0.0-beta.30 (transitive)
• next: 16.2.1
• Node: 24
• macOS

Working versions

Everything builds correctly with workflow@4.2.0-beta.72 and its transitive deps:

• @workflow/builders@4.0.1-beta.63
• @workflow/next@4.0.1-beta.68
• @workflow/rollup@4.0.0-beta.29

Workaround

Pin workflow to 4.2.0-beta.72 or add pnpm overrides for the transitive deps:

# pnpm-workspace.yaml
overrides:
  "@workflow/builders": 4.0.1-beta.63
  "@workflow/next": 4.0.1-beta.68
  "@workflow/rollup": 4.0.0-beta.29

Related

• Support projects with Node.js step dependencies in vitest plugin #1524 — suspected cause (not 100% certain)
• [Nuxt/Nitro dev] Workflow step bundle still externalizes transitive local TS modules (native ESM crash) #1179 — same root cause (transitive local TS modules not bundled) but for Nuxt/Nitro
• Inability to import .ts files to workflow or step files when using Nuxt #278 — original fix for direct .ts imports, which beta.64 attempted to extend

[pablodecm]

My best guess of cause is in #1524 in @workflow/builders modifies the esbuild plugin’s externalizeNonSteps resolver. When a step file imports a local module that is not a step/workflow (so it gets externalized), the plugin now rewrites the extension from .ts → .js:

externalPath = externalPath
  .replace(/\.tsx?$/, '.js')   // .ts → .js, .tsx → .js
  .replace(/\.mts$/, '.mjs')
  .replace(/\.cts$/, '.cjs');

The likely problem: the resolvedPath passed to relative() is the resolved filesystem path (e.g., .../utils/model-config.ts). After relative(), the extension is .ts, which gets rewritten to .js. But the output bundle is consumed by Next.js’s webpack bundler (not Node’s native ESM loader), and Next.js resolves model-config.js — which doesn’t exist on disk (the file is model-config.ts).

The PR was specifically targeting @workflow/vitest (where Node’s native ESM loader runs the externalized bundles directly), but the same esbuild plugin is also used by @workflow/next for building the production step route — and Next.js webpack can resolve .ts just fine, so the rewrite breaks it.

So the issue is not in my code. It’s a bug in @workflow/builders@4.0.1-beta.64 — the .ts → .js rewrite is applied unconditionally, but it should only apply in the vitest context (Node ESM loader), not when the bundle target is Next.js (webpack).

[VaguelySerious]

(AI) Reproduction

Confirmed. The .ts → .js extension rewrite in @workflow/builders's externalizeNonSteps resolver (introduced in #1524) is applied unconditionally to all framework builders. When Next.js webpack processes the output bundle, it looks for .js files that don't exist on disk — the source is .ts.

Reproduced by inspecting the esbuild plugin output: without the flag, ./dep.ts gets rewritten to ./dep.js; with the flag, it stays as ./dep.ts. Next.js turbopack workbench build confirms the fix.

Related issues

• [Nuxt/Nitro dev] Workflow step bundle still externalizes transitive local TS modules (native ESM crash) #1179 — overlapping root cause (externalized local TS modules in Nuxt/Nitro dev), but that issue is about transitive dependencies not being bundled at all, not the extension rewriting
• Inability to import .ts files to workflow or step files when using Nuxt #278 — original .ts import fix for Nuxt (closed)

Fix

#1560 adds a rewriteTsExtensions option to SwcPluginOptions. Only the vitest builder enables it (since it loads bundles via Node's native ESM loader which requires .js). All other framework builders (Next.js, SvelteKit, Astro, Nitro, NestJS) preserve the original .ts extension so their downstream bundlers resolve correctly.

To see if this fix solves your issue, could you try to install the pre-release in your package.json? Just replace the workflow dep like so:

{
  "dependencies": {
    "workflow": "https://workflow-docs-cjt8jvjwi.vercel.sh/workflow.tgz",
    "@workflow/ai": "https://workflow-docs-cjt8jvjwi.vercel.sh/workflow-ai.tgz"
  }
}

[NathanColosimo]

@VaguelySerious I got the same issue, trying the fix now

[NathanColosimo]

yes this worked

[pablodecm]

Confirmed also from my side, thanks @VaguelySerious !