Skip to main content

Migrating to @walkeros/cli 4.x

The bundler now uses @vercel/nft to trace server flow dependencies and ship only the files actually used. flow.json field locations are unchanged. The migration is a small, mechanical edit to your Dockerfile and (if you used it) the walkerOS.bundle.external annotation.

flow.json schema is unchanged​

version: 4 stays. flow.<name>.config.bundle.packages, flow.<name>.config.bundle.overrides, and flow.<name>.config.bundle.traceInclude remain the canonical locations for build-time fields.

Remove flow.<name>.config.bundle.external entirely​

nft handles externalization automatically. Remove the field; it is no longer recognized.

 "config": {
   "platform": "server",
   "bundle": {
     "packages": {...},
-    "external": ["@google-cloud/bigquery-storage", "@grpc/grpc-js"]
   }
 }

The CLI prints a deprecation warning if it sees a v3-era config.bundle.external block. The same applies to step-package manifests carrying walkerOS.bundle.external (also no longer recognized).

Update the Dockerfile​

Server bundles are always a directory now: dist/{flow.mjs, package.json, node_modules/}. If your Dockerfile copied just bundle.mjs, change it to copy the whole directory and bump the runtime image:

 FROM node:22-alpine AS builder
 WORKDIR /build
 RUN npm init -y && npm install --save-dev @walkeros/cli
 COPY flow.json ./
-RUN npx walkeros bundle ./flow.json --output dist/bundle.mjs
+RUN npx walkeros bundle flow.json -o dist/

-FROM walkeros/flow:3.3.0
-COPY --from=builder /build/dist/bundle.mjs /app/flow/bundle.mjs
-ENV BUNDLE=/app/flow/bundle.mjs
-ENV FILES_PATH=/app/flow
+FROM walkeros/flow:4
+WORKDIR /app/flow
+COPY --from=builder /build/dist/ ./
 ENV PORT=8080
 EXPOSE 8080

The BUNDLE and FILES_PATH env vars are no longer needed: the runtime image's defaults match /app/flow/flow.mjs.

You no longer need npm install for step packages​

Pacote drives the install layer based on flow.<name>.config.bundle.packages. Your project's package.json only needs @walkeros/cli as a devDependency (plus any local code your project ships, of course). You can remove pinned @walkeros/... deps from package.json if you previously listed them just to satisfy the bundler.

Escape hatch: traceInclude​

If nft cannot statically reach a runtime asset (rare: require(somePathFromEnv)), declare it explicitly under the per-flow bundle block:

"flows": {
  "default": {
    "config": {
      "platform": "server",
      "bundle": {
        "packages": { "@walkeros/server-destination-gcp": {} },
        "traceInclude": [
          "node_modules/some-pkg/data/*.json"
        ]
      }
    }
  }
}

Paths and globs both work. They resolve against the install root (where pacote put files), not your project directory.

Output filename change​

Default output filename is now flow.mjs (was bundle.mjs). The runtime image expects /app/flow/flow.mjs. If you have scripts that read dist/bundle.mjs, update them.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)