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: walkeros bundle ignores it and prints a warning, and walkeros validate reports it as an error (Unrecognized key: "external").
"config": {
"platform": "server",
"bundle": {
"packages": {...},
- "external": ["@google-cloud/bigquery-storage", "@grpc/grpc-js"]
}
}
A step package whose package.json still declares walkerOS.bundle.external is treated the same way: walkeros bundle ignores the field and prints a warning naming the package.
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.23.0-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:<version>
+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. Use the same <version> as the @walkeros/cli that builds the flow; the canonical Dockerfile pins both with one WALKEROS_VERSION.
You no longer need npm install for step packages
walkeros bundle installs the package of every step itself, together with flow.<name>.config.bundle.packages. Your project's package.json only needs @walkeros/cli as a devDependency (plus any local code your project ships). 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 the bundler installs the packages), not your project directory.
Output filename change
A server bundle written to a directory (-o dist/) is named flow.mjs (was bundle.mjs). The runtime image expects /app/flow/flow.mjs. If you have scripts that read dist/bundle.mjs, update them.