@workflow/next 4.0.1-beta.6 → 4.0.1-beta.61

package/dist/socket-server.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeMessage = serializeMessage;
+exports.parseMessage = parseMessage;
+exports.createSocketServer = createSocketServer;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_net_1 = require("node:net");
+const node_path_1 = require("node:path");
+/**
+ * Magic preamble that must prefix all messages to authenticate them as workflow messages.
+ * This prevents accidental processing of messages from port scanners or other local processes.
+ */
+const MESSAGE_PREAMBLE = 'WF:';
+/**
+ * Generate a random authentication token for this server session.
+ * Clients must include this token in all messages.
+ */
+function generateAuthToken() {
+    return (0, node_crypto_1.randomBytes)(16).toString('hex');
+}
+function getDefaultSocketInfoFilePath() {
+    return (0, node_path_1.join)(process.cwd(), '.next', 'cache', 'workflow-socket.json');
+}
+/**
+ * Serialize a message with authentication preamble
+ */
+function serializeMessage(message, authToken) {
+    return `${MESSAGE_PREAMBLE}${authToken}:${JSON.stringify(message)}\n`;
+}
+/**
+ * Parse and authenticate a message from the socket
+ * Returns the parsed message if valid, null otherwise
+ */
+function parseMessage(line, authToken) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+        return null;
+    }
+    // Check for preamble
+    if (!trimmed.startsWith(MESSAGE_PREAMBLE)) {
+        console.warn('Received message without valid preamble, ignoring');
+        return null;
+    }
+    // Extract auth token and payload
+    const withoutPreamble = trimmed.slice(MESSAGE_PREAMBLE.length);
+    const colonIndex = withoutPreamble.indexOf(':');
+    if (colonIndex === -1) {
+        console.warn('Received message without auth token separator, ignoring');
+        return null;
+    }
+    const messageToken = withoutPreamble.slice(0, colonIndex);
+    const payload = withoutPreamble.slice(colonIndex + 1);
+    // Verify auth token
+    if (messageToken !== authToken) {
+        console.warn('Received message with invalid auth token, ignoring');
+        return null;
+    }
+    // Parse JSON payload
+    try {
+        return JSON.parse(payload);
+    }
+    catch (error) {
+        console.error('Failed to parse socket message JSON:', error);
+        return null;
+    }
+}
+/**
+ * Create a TCP socket server for loader<->builder communication.
+ * Returns a SocketIO interface for broadcasting messages and the auth token.
+ *
+ * SECURITY: Server listens on 127.0.0.1 (localhost only) and uses
+ * message authentication to prevent processing of unauthorized messages.
+ */
+async function createSocketServer(config) {
+    const authToken = generateAuthToken();
+    const clients = new Set();
+    let buildTriggered = false;
+    const server = (0, node_net_1.createServer)((socket) => {
+        socket.setNoDelay(true);
+        clients.add(socket);
+        // Send build-complete if build already finished (production mode)
+        if (buildTriggered && !config.isDevServer) {
+            socket.write(serializeMessage({ type: 'build-complete' }, authToken));
+        }
+        let buffer = '';
+        socket.on('data', (data) => {
+            buffer += data.toString();
+            // Process complete messages (newline-delimited)
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex);
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf('\n');
+                const message = parseMessage(line, authToken);
+                if (!message) {
+                    continue;
+                }
+                if (message.type === 'file-discovered') {
+                    config.onFileDiscovered(message.filePath, message.hasWorkflow, message.hasStep, message.hasSerde);
+                }
+                else if (message.type === 'trigger-build') {
+                    config.onTriggerBuild();
+                }
+            }
+        });
+        socket.on('end', () => {
+            clients.delete(socket);
+        });
+        socket.on('error', (err) => {
+            console.error('Socket error:', err);
+            clients.delete(socket);
+        });
+    });
+    // Listen on random available port (localhost only)
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address && typeof address === 'object') {
+                const socketInfoFilePath = config.socketInfoFilePath || getDefaultSocketInfoFilePath();
+                void (async () => {
+                    try {
+                        await (0, promises_1.mkdir)((0, node_path_1.dirname)(socketInfoFilePath), { recursive: true });
+                        await (0, promises_1.writeFile)(socketInfoFilePath, JSON.stringify({
+                            port: address.port,
+                            authToken,
+                        }, null, 2));
+                        process.env.WORKFLOW_SOCKET_INFO_PATH = socketInfoFilePath;
+                        process.env.WORKFLOW_SOCKET_PORT = String(address.port);
+                        process.env.WORKFLOW_SOCKET_AUTH = authToken;
+                        resolve();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                })();
+                return;
+            }
+            reject(new Error('Failed to obtain workflow socket server address'));
+        });
+    });
+    return {
+        emit: (_event) => {
+            buildTriggered = true;
+            const message = serializeMessage({ type: 'build-complete' }, authToken);
+            for (const client of clients) {
+                client.write(message);
+            }
+        },
+        getAuthToken: () => authToken,
+    };
+}
+//# sourceMappingURL=socket-server.js.map

package/dist/socket-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-server.js","sourceRoot":"","sources":["../src/socket-server.ts"],"names":[],"mappings":"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"}

package/dist/step-copy-utils.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFERRED_STEP_COPY_DIR_NAME = "__workflow_step_files__";
+export declare const DEFERRED_STEP_SOURCE_METADATA_PREFIX = "WORKFLOW_STEP_SOURCE_B64:";
+export interface DeferredStepSourceMetadata {
+    relativeFilename: string;
+    absolutePath: string;
+}
+export declare function isDeferredStepCopyFilePath(filePath: string): boolean;
+export declare function createDeferredStepSourceMetadataComment(metadata: DeferredStepSourceMetadata): string;
+export declare function createDeferredStepCopyInlineSourceMapComment({ sourcePath, sourceContent, generatedContent, }: {
+    sourcePath: string;
+    sourceContent: string;
+    generatedContent?: string;
+}): string;
+export declare function parseInlineSourceMapComment(source: string): {
+    sourceWithoutMapComment: string;
+    sourceMap: string | null;
+};
+export declare function parseDeferredStepSourceMetadata(source: string): DeferredStepSourceMetadata | null;
+//# sourceMappingURL=step-copy-utils.d.ts.map

package/dist/step-copy-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-copy-utils.d.ts","sourceRoot":"","sources":["../src/step-copy-utils.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,4BAA4B,CAAC;AACrE,eAAO,MAAM,oCAAoC,8BAA8B,CAAC;AAIhF,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAUD,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKpE;AAED,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,0BAA0B,GACnC,MAAM,CAKR;AAiBD,wBAAgB,4CAA4C,CAAC,EAC3D,UAAU,EACV,aAAa,EACb,gBAAgB,GACjB,EAAE;IACD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,MAAM,CAiBT;AAED,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG;IAC3D,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B,CAuBA;AAED,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,MAAM,GACb,0BAA0B,GAAG,IAAI,CA8BnC"}

package/dist/step-copy-utils.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFERRED_STEP_SOURCE_METADATA_PREFIX = exports.DEFERRED_STEP_COPY_DIR_NAME = void 0;
+exports.isDeferredStepCopyFilePath = isDeferredStepCopyFilePath;
+exports.createDeferredStepSourceMetadataComment = createDeferredStepSourceMetadataComment;
+exports.createDeferredStepCopyInlineSourceMapComment = createDeferredStepCopyInlineSourceMapComment;
+exports.parseInlineSourceMapComment = parseInlineSourceMapComment;
+exports.parseDeferredStepSourceMetadata = parseDeferredStepSourceMetadata;
+exports.DEFERRED_STEP_COPY_DIR_NAME = '__workflow_step_files__';
+exports.DEFERRED_STEP_SOURCE_METADATA_PREFIX = 'WORKFLOW_STEP_SOURCE_B64:';
+const INLINE_SOURCE_MAP_PATTERN = /(?:^|\r?\n)\s*\/\/[#@]\s*sourceMappingURL=data:application\/json(?:;charset=[^;,]+)?;base64,([A-Za-z0-9+/=]+)\s*$/;
+function escapeRegExp(input) {
+    return input.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function normalizePath(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+function isDeferredStepCopyFilePath(filePath) {
+    const normalizedPath = normalizePath(filePath);
+    return normalizedPath.includes(`/.well-known/workflow/v1/step/${exports.DEFERRED_STEP_COPY_DIR_NAME}/`);
+}
+function createDeferredStepSourceMetadataComment(metadata) {
+    const encoded = Buffer.from(JSON.stringify(metadata), 'utf-8').toString('base64');
+    return `// ${exports.DEFERRED_STEP_SOURCE_METADATA_PREFIX}${encoded}`;
+}
+function getLineCount(source) {
+    if (source.length === 0) {
+        return 1;
+    }
+    const lineBreakMatches = source.match(/\r\n|\r|\n/g);
+    return (lineBreakMatches?.length ?? 0) + 1;
+}
+function createIdentityLineMappings(lineCount) {
+    if (lineCount <= 1) {
+        return 'AAAA';
+    }
+    return `AAAA${';AACA'.repeat(lineCount - 1)}`;
+}
+function createDeferredStepCopyInlineSourceMapComment({ sourcePath, sourceContent, generatedContent, }) {
+    const normalizedSourcePath = normalizePath(sourcePath);
+    const sourceMap = {
+        version: 3,
+        file: normalizedSourcePath.split('/').pop() ?? normalizedSourcePath,
+        sources: [normalizedSourcePath],
+        sourcesContent: [sourceContent],
+        names: [],
+        mappings: createIdentityLineMappings(getLineCount(generatedContent ?? sourceContent)),
+    };
+    const encodedSourceMap = Buffer.from(JSON.stringify(sourceMap), 'utf-8').toString('base64');
+    return `//# sourceMappingURL=data:application/json;base64,${encodedSourceMap}`;
+}
+function parseInlineSourceMapComment(source) {
+    const mapMatch = source.match(INLINE_SOURCE_MAP_PATTERN);
+    if (!mapMatch?.[1]) {
+        return {
+            sourceWithoutMapComment: source,
+            sourceMap: null,
+        };
+    }
+    const sourceWithoutMapComment = source.replace(INLINE_SOURCE_MAP_PATTERN, '');
+    try {
+        const decodedMap = Buffer.from(mapMatch[1], 'base64').toString('utf-8');
+        JSON.parse(decodedMap);
+        return {
+            sourceWithoutMapComment,
+            sourceMap: decodedMap,
+        };
+    }
+    catch {
+        return {
+            sourceWithoutMapComment,
+            sourceMap: null,
+        };
+    }
+}
+function parseDeferredStepSourceMetadata(source) {
+    const pattern = new RegExp(`^\\s*//\\s*${escapeRegExp(exports.DEFERRED_STEP_SOURCE_METADATA_PREFIX)}([A-Za-z0-9+/=]+)\\s*$`, 'm');
+    const match = source.match(pattern);
+    const encoded = match?.[1];
+    if (!encoded) {
+        return null;
+    }
+    try {
+        const decoded = Buffer.from(encoded, 'base64').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        if (typeof parsed.relativeFilename !== 'string' ||
+            parsed.relativeFilename.length === 0 ||
+            typeof parsed.absolutePath !== 'string' ||
+            parsed.absolutePath.length === 0) {
+            return null;
+        }
+        return {
+            relativeFilename: parsed.relativeFilename,
+            absolutePath: normalizePath(parsed.absolutePath),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=step-copy-utils.js.map

package/dist/step-copy-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-copy-utils.js","sourceRoot":"","sources":["../src/step-copy-utils.ts"],"names":[],"mappings":"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"}

package/docs/api-reference/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/next"
+description: Next.js integration for automatic bundling and runtime configuration.
+type: overview
+summary: Explore the Next.js integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/next
+---
+
+Next.js integration for Workflow DevKit that automatically configures bundling and runtime support.
+
+## Functions
+
+<Cards>
+    <Card title="withWorkflow" href="/docs/api-reference/workflow-next/with-workflow">
+        Configures webpack/turbopack loaders to transform workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

package/docs/api-reference/with-workflow.mdx

@@ -0,0 +1,56 @@
+---
+title: withWorkflow
+description: Configure webpack/turbopack to transform workflow directives in Next.js.
+type: reference
+summary: Wrap your Next.js config with withWorkflow to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/next
+---
+
+Configures webpack/turbopack loaders to transform workflow code (`"use step"`/`"use workflow"` directives)
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, wrap your `nextConfig` with `withWorkflow`.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next"; // [!code highlight]
+import type { NextConfig } from "next";
+ 
+const nextConfig: NextConfig = {
+  // … rest of your Next.js config
+};
+
+// not required but allows configuring workflow options
+const workflowConfig = {} 
+
+export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
+```
+
+If you are exporting a function in your `next.config` you will need to ensure you call the function returned from `withWorkflow`.
+
+```typescript title="next.config.ts" lineNumbers
+import { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+import createNextIntlPlugin from "next-intl/plugin";
+
+const withNextIntl = createNextIntlPlugin();
+
+export default async function config(
+  phase: string,
+  ctx: {
+    defaultConfig: NextConfig
+  }
+): Promise<NextConfig> {
+  let nextConfig: NextConfig | typeof config = {};
+
+  for (const configModifier of [withNextIntl, withWorkflow]) {
+    nextConfig = configModifier(nextConfig);
+
+    if (typeof nextConfig === "function") {
+      nextConfig = await nextConfig(phase, ctx);
+    }
+  }
+  return nextConfig;
+}
+``` 

package/docs/next.mdx

@@ -0,0 +1,288 @@
+---
+title: Next.js
+description: This guide will walk through setting up your first workflow in a Next.js app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
+type: guide
+summary: Set up Workflow DevKit in a Next.js app.
+prerequisites:
+  - /docs/getting-started
+related:
+  - /docs/api-reference/workflow-next
+  - /docs/deploying/world/vercel-world
+---
+
+<Steps>
+
+<Step>
+## Create Your Next.js Project
+
+Start by creating a new Next.js project. This command will create a new directory named `my-workflow-app` and set up a Next.js project inside it.
+
+```bash
+npm create next-app@latest my-workflow-app
+```
+
+Enter the newly created directory:
+
+```bash
+cd my-workflow-app
+```
+
+### Install `workflow`
+
+```package-install
+npm i workflow
+```
+
+### Configure Next.js
+
+Wrap your `next.config.ts` with `withWorkflow()`. This enables usage of the `"use workflow"` and `"use step"` directives.
+
+```typescript title="next.config.ts" lineNumbers
+import { withWorkflow } from "workflow/next"; // [!code highlight]
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // … rest of your Next.js config
+};
+
+export default withWorkflow(nextConfig); // [!code highlight]
+```
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+    <AccordionTrigger className="text-sm">
+      ### Setup IntelliSense for TypeScript (Optional)
+    </AccordionTrigger>
+    <AccordionContent className="[&_p]:my-2">
+
+To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
+
+```json title="tsconfig.json" lineNumbers
+{
+  "compilerOptions": {
+    // ... rest of your TypeScript config
+    "plugins": [
+      {
+        "name": "workflow" // [!code highlight]
+      }
+    ]
+  }
+}
+```
+
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+    <AccordionTrigger className="text-sm">
+      ### Configure Proxy Handler (if applicable)
+    </AccordionTrigger>
+    <AccordionContent className="[&_p]:my-2">
+
+If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-reference/file-conventions/proxy)
+(formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
+internal paths to prevent the proxy handler from running on them.
+
+Add `.well-known/workflow/*` to your middleware's exclusion list:
+
+```typescript title="proxy.ts" lineNumbers
+import { NextResponse } from "next/server";
+import type { NextRequest } from "next/server";
+
+export function proxy(request: NextRequest) {
+  // Your middleware logic
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: [
+    // ... your existing matchers
+    {
+      source: "/((?!_next/static|_next/image|favicon.ico|.well-known/workflow/).*)", // [!code highlight]
+    },
+  ],
+};
+```
+
+This ensures that internal Workflow paths are not intercepted by your middleware, which could interfere with workflow execution and resumption.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+</Step>
+
+<Step>
+
+## Create Your First Workflow
+
+Create a new file for our first workflow:
+
+```typescript title="workflows/user-signup.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function handleUserSignup(email: string) {
+ "use workflow"; // [!code highlight]
+
+ const user = await createUser(email);
+ await sendWelcomeEmail(user);
+
+ await sleep("5s"); // Pause for 5s - doesn't consume any resources
+ await sendOnboardingEmail(user);
+
+ console.log("Workflow is complete! Run 'npx workflow web' to inspect your run")
+
+ return { userId: user.id, status: "onboarded" };
+}
+
+```
+
+We'll fill in those functions next, but let's take a look at this code:
+
+* We define a **workflow** function with the directive `"use workflow"`. Think of the workflow function as the _orchestrator_ of individual **steps**.
+* The Workflow DevKit's `sleep` function allows us to suspend execution of the workflow without using up any resources. A sleep can be a few seconds, hours, days, or even months long.
+
+## Create Your Workflow Steps
+
+Let's now define those missing functions.
+
+```typescript title="workflows/user-signup.ts" lineNumbers
+import { FatalError } from "workflow"
+
+// Our workflow function defined earlier
+
+async function createUser(email: string) {
+  "use step"; // [!code highlight]
+
+  console.log(`Creating user with email: ${email}`);
+
+  // Full Node.js access - database calls, APIs, etc.
+  return { id: crypto.randomUUID(), email };
+}
+
+async function sendWelcomeEmail(user: { id: string; email: string; }) {
+  "use step"; // [!code highlight]
+
+  console.log(`Sending welcome email to user: ${user.id}`);
+
+  if (Math.random() < 0.3) {
+  // By default, steps will be retried for unhandled errors
+   throw new Error("Retryable!");
+  }
+}
+
+async function sendOnboardingEmail(user: { id: string; email: string}) {
+ "use step"; // [!code highlight]
+
+  if (!user.email.includes("@")) {
+    // To skip retrying, throw a FatalError instead
+    throw new FatalError("Invalid Email");
+  }
+
+ console.log(`Sending onboarding email to user: ${user.id}`);
+}
+```
+
+Taking a look at this code:
+
+* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
+* Steps can throw a `FatalError` if an error is intentional and should not be retried.
+
+<Callout>
+We'll dive deeper into workflows, steps, and other ways to suspend or handle events in [Foundations](/docs/foundations).
+</Callout>
+
+</Step>
+
+<Step>
+
+## Create Your Route Handler
+
+To invoke your new workflow, we'll need to add your workflow to a `POST` API Route Handler, `app/api/signup/route.ts`, with the following code:
+
+```typescript title="app/api/signup/route.ts"
+import { start } from "workflow/api";
+import { handleUserSignup } from "@/workflows/user-signup";
+import { NextResponse } from "next/server";
+
+export async function POST(request: Request) {
+ const { email } = await request.json();
+
+ // Executes asynchronously and doesn't block your app
+ await start(handleUserSignup, [email]);
+
+ return NextResponse.json({
+  message: "User signup workflow started",
+ });
+}
+```
+
+This Route Handler creates a `POST` request endpoint at `/api/signup` that will trigger your workflow.
+
+<Callout>
+Workflows can be triggered from API routes, Server Actions, or any server-side code.
+</Callout>
+
+</Step>
+
+</Steps>
+
+## Run in development
+
+To start your development server, run the following command in your terminal in the Next.js root directory:
+
+```bash
+npm run dev
+```
+
+Once your development server is running, you can trigger your workflow by running this command in the terminal:
+
+```bash
+curl -X POST --json '{"email":"hello@example.com"}' http://localhost:3000/api/signup
+```
+
+Check the Next.js development server logs to see your workflow execute, as well as the steps that are being processed.
+
+Additionally, you can use the [Workflow DevKit CLI or Web UI](/docs/observability) to inspect your workflow runs and steps in detail.
+
+```bash
+# Open the observability Web UI
+npx workflow web
+# or if you prefer a terminal interface, use the CLI inspect command
+npx workflow inspect runs
+```
+
+![Workflow DevKit Web UI](/o11y-ui.png)
+
+## Deploying to production
+
+Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and need no special configuration.
+
+<FluidComputeCallout />
+
+Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
+
+## Troubleshooting
+
+### Next.js 16.1+ compatibility
+
+If you see this error when upgrading to Next.js 16.1 or later:
+
+```
+Build error occurred
+Error: Cannot find module 'next/dist/lib/server-external-packages.json'
+```
+
+Upgrade to `workflow@4.0.1-beta.26` or later:
+
+```package-install
+workflow@latest
+```
+
+## Next Steps
+
+* Learn more about the [Foundations](/docs/foundations).
+* Check [Errors](/docs/errors) if you encounter issues.
+* Explore the [API Reference](/docs/api-reference).