workflow 5.0.0 → 5.1.0

package/docs/configuration/worlds.mdx

@@ -160,6 +160,12 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 - Number of concurrent workers polling for jobs.
 - Also bounds concurrent parent-to-child workflow return-value polls.
 
+### `pollInterval`
+
+- Environment variable: `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`
+- Default: `500`
+- Milliseconds between idle job fetches per worker.
+
 ### `applicationManagedShutdown`
 
 - Environment variable: `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN` (`1` enables)
@@ -290,6 +296,7 @@ Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, an
 - Default: `http`
 - Experimental stream-write transport capability. Set to exactly `ws` to attempt `workflow-stream-ws/v1`. The server authoritatively accepts or declines each upgrade; a decline uses HTTP directly for that writer lifetime. Stream reads remain HTTP and demand-driven.
 - This is not tenant rollout policy or a package-version check. HTTP remains the compatibility path. `/websockets/v1` is independent of REST v2/v4 and persisted workflow `specVersion` values.
+- A throttled (429) socket write or close is retried after the server's `Retry-After`, as over HTTP. It moves to HTTP if the connection ends during the wait or the cumulative wait passes 30 seconds.
 
 ### `WORKFLOW_DISABLE_ANALYTICS_READS`
 
@@ -310,6 +317,25 @@ When enabled (the default), a suspension's eager `step_created` and `wait_create
 
 - Factory option: none
 - CLI flag: none
-- Default: `http`
-- Set to `ws` to ship workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. Only `ws` (case-insensitive) opts in; any other value, including unset, empty, or `http`, keeps HTTP.
+- Default: `ws`
+- Ships workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. Set to exactly `http` to opt out; any other value, including unset or empty, uses the WebSocket.
 - Ignored when the World is configured with `projectConfig` and routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP.
+
+### `WORKFLOW_EVENTS_TRANSPORT_WS_OVERRIDE_WORKFLOWS`
+
+- Factory option: none
+- CLI flag: none
+- Default: none
+- Comma-separated workflows whose runs use the WebSocket events transport even when `WORKFLOW_EVENTS_TRANSPORT` is `http`. Each entry is a function name (`processOrder`) or a full workflow name (`workflow//./src/workflows/order//processOrder`), matched exactly and case-sensitively.
+- Has no effect unless `WORKFLOW_EVENTS_TRANSPORT=http`, since every workflow already uses the WebSocket by default.
+- See [`WORKFLOW_EVENTS_TRANSPORT_WS_OVERRIDE_WORKFLOWS`](/worlds/vercel#workflow_events_transport_ws_override_workflows) for details.
+
+### `WORKFLOW_WS_MAX_MESSAGE_BYTES`
+
+- Factory option: none
+- CLI flag: none
+- Default: `12582912` (12 MiB)
+- Clamp: `2097152` to `16777216` (values outside are clamped, with a warning)
+- Largest WebSocket message the Vercel World sends, header included, for both the events and stream-write transports. The ceiling is the 16 MiB WebSocket message limit.
+- Events: a larger frame is sent as several messages and rebuilt on the other side.
+- Stream writes: a larger write group is split into several ordered write requests; a single chunk too large for one message is written over HTTP, as are the rest of that writer's writes.

package/docs/cookbook/common-patterns/webhooks.mdx

@@ -50,7 +50,7 @@ export async function paymentWebhook(orderId: string) {
 
 ### Step function for processing
 
-Each webhook request is processed in its own step, giving you full Node.js access for validation, database writes, and responding to the caller:
+Each webhook request is processed in its own step, giving you full Node.js access for validation, database writes, and responding to the caller. In production, verify the provider's signature here before trusting the body; the example omits it for brevity.
 
 ```typescript
 import { type RequestWithResponse } from "workflow";
@@ -176,6 +176,7 @@ export async function POST(request: Request) {
 - **`respondWith: "manual"`** gives you control over the HTTP response from inside a step. Use this when you need to validate the request before responding.
 - **`for await` on a webhook** lets you process multiple events from the same URL. Use `break` to stop listening after a terminal event.
 - **Webhooks auto-generate URLs** at `/.well-known/workflow/v1/webhook/:token`. Pass this URL to external services.
+- **The URL is the only authorization.** Anyone with the webhook URL can send it a request, so verify the provider's signature in the processing step before acting on the payload. See [Hook and webhook security](/docs/foundations/hooks#security).
 - **Race webhooks against `sleep()`** for deadlines. If the callback doesn't arrive in time, the workflow can take a fallback action.
 - **For large payloads**, use a hook and reference token instead of passing the data through the workflow. The event log serializes all step inputs and outputs, so large payloads hurt performance.
 

package/docs/cookbook/integrations/ai-sdk.mdx

@@ -41,9 +41,9 @@ One workflow run represents one full conversation. The workflow suspends between
 Because the conversation is one workflow run, it stays on the deployment that started it. If each turn should run on the latest deployment while preserving selected state or streams, see [Versioning](/docs/foundations/versioning) for the child-run continuation pattern.
 </Callout>
 
-<Tabs items={['Workflow', 'API Route', 'Client']}>
+<TabsWithChildren tabs={["Workflow","API Route","Client"]}>
 
-<Tab value="Workflow">
+<TabContent order={1}>
 
 ```typescript title="workflows/support.ts" lineNumbers
 import { streamText, stepCountIs } from "ai";
@@ -129,9 +129,9 @@ export async function supportWorkflow(initialMessages: ModelMessage[]) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="API Route">
+<TabContent order={2}>
 
 One endpoint handles first turn, follow-ups, and the `/done` exit. The client sends `runId` in the body to distinguish first vs follow-up.
 
@@ -246,9 +246,9 @@ export async function POST(req: Request) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Client">
+<TabContent order={3}>
 
 Store the `runId` in a ref and pass it in the body of every follow-up. `WorkflowChatTransport` forwards it for you.
 
@@ -299,9 +299,9 @@ export function SupportChat() {
 }
 ```
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 ## How it works
 

package/docs/cookbook/integrations/chat-sdk.mdx

@@ -66,9 +66,9 @@ Because the session *is* a workflow run, its history is recoverable from the eve
 
 This pattern uses three files. The bot definition is separate from the workflow so adapter packages stay out of the workflow sandbox.
 
-<Tabs items={['Bot Setup', 'Workflow', 'Event Handlers']}>
+<TabsWithChildren tabs={["Bot Setup","Workflow","Event Handlers"]}>
 
-<Tab value="Bot Setup">
+<TabContent order={1}>
 
 Register the `Chat` instance as a singleton so step functions can dynamically import it and resolve adapters + state:
 
@@ -95,9 +95,9 @@ export const bot = new Chat<typeof adapters, ThreadState>({
 
 `registerSingleton()` is important: Chat SDK re-hydrates `Thread` objects inside step functions, and it needs a registered singleton to resolve adapters and state for those rehydrated instances.
 
-</Tab>
+</TabContent>
 
-<Tab value="Workflow">
+<TabContent order={2}>
 
 The workflow is a plain loop over a hook. It receives the serialized thread + first message from the handler, revives them via Chat SDK's standalone `reviver`, and every platform-side effect goes inside a `"use step"` helper:
 
@@ -174,9 +174,9 @@ export type ChatTurnPayload = {
 };
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Event Handlers">
+<TabContent order={3}>
 
 Handlers live outside the workflow file so adapter dependencies don't leak in. They decide whether to start a new workflow or resume an existing one, then store the `runId` in thread state:
 
@@ -256,9 +256,9 @@ export async function POST(
 }
 ```
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 ## How it works
 

package/docs/cookbook/integrations/sandbox.mdx

@@ -88,9 +88,9 @@ When the timer wins:
 
 The only way out is an explicit `/destroy` command.
 
-<Tabs items={['Workflow', 'API Routes', 'Client']}>
+<TabsWithChildren tabs={["Workflow","API Routes","Client"]}>
 
-<Tab value="Workflow">
+<TabContent order={1}>
 
 ```typescript title="workflows/sandbox-session.ts" lineNumbers
 import { defineHook, sleep, getWritable, getWorkflowMetadata } from "workflow";
@@ -298,9 +298,9 @@ export async function sandboxSessionWorkflow() {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="API Routes">
+<TabContent order={2}>
 
 Two endpoints manage the session. `/start` accepts an optional `{ runId }`: if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
 
@@ -379,9 +379,9 @@ export async function POST(req: Request) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Client">
+<TabContent order={3}>
 
 On mount, reconnect to the existing run if `localStorage` contains a `runId`. Otherwise, start a new run. Send commands to `/command` with POST requests. Output arrives on the `/start` stream.
 
@@ -472,9 +472,9 @@ export function SandboxRunner() {
 }
 ```
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 ## How it works
 

package/docs/errors/node-js-module-in-workflow.mdx

@@ -27,6 +27,42 @@ Workflow functions run in a sandboxed environment without full Node.js runtime a
 
 Node.js modules have side effects and non-deterministic behavior that could break workflow replay guarantees.
 
+## Transitive dependencies and dynamic `require()`
+
+The same error is reported for a module the workflow bundle could not inline, even when your own code never imports it directly:
+
+```text
+Workflow bundle cannot run in the workflow sandbox.
+
+Imports left external (1):
+  • "node:fs"
+    imported by node_modules/leaky-pkg/index.js
+    via app/workflows/order.ts → node_modules/wrapper-pkg/index.js → node_modules/leaky-pkg/index.js
+
+Unresolved require() calls (1):
+  • dynamic require() in node_modules/lazy-pkg/index.js (bundle 412:31)
+```
+
+The workflow sandbox has no `require`, so both would throw `ReferenceError: require is not defined` when the bundle loads. Follow the import chain to the first file you own and move that work into a step function, or replace a dynamic `require()` with a static import so the bundler can inline it.
+
+A `require()` wrapped in `try`/`catch`, or behind a `typeof require` check, is not reported — that is how packages probe for an optional dependency or for a CommonJS environment, and in the sandbox the error is caught or the call never runs:
+
+```js
+try {
+  loadOptional(require("@emotion/is-prop-valid").default);
+} catch {
+  // optional dependency, fall back
+}
+
+if (typeof require !== "undefined") {
+  crypto = require("crypto");
+}
+```
+
+A `typeof require` check only excuses the branch it skips when `require` is undefined, so `typeof require === "undefined" ? require(x) : y` is still reported. A `try` only counts when it has a `catch`. The checks read the code's structure without running it, so a `catch` that rethrows the error is still treated as a guard, and the bundle fails at runtime if that code is reached.
+
+As a last resort — for example a `require()` that can never run — set `WORKFLOW_ALLOW_UNSAFE_FLOW_BUNDLE=1` to downgrade the build failure to a warning. The bundle still fails at runtime if the code is reached.
+
 ## Quick fix
 
 Move any code using Node.js modules to a step function. Step functions have full Node.js runtime access.

package/docs/foundations/errors-and-retries.mdx

@@ -168,7 +168,7 @@ Uncaught, the run fails immediately with the `USER_ERROR` code, without retrying
 
 On Vercel, backend connection failures and interrupted event streams use the existing retry policies, even when their error codes are unrecognized. This lets workflows recover from network failures instead of immediately failing with `USER_ERROR`. Persistent failures can still exhaust the retry budget.
 
-The SDK also replaces its shared events connection pool after repeated HTTP/2 session failures. Invalid backend URLs, including unsupported protocols and embedded credentials, fail immediately. Fetch requests to blocked ports or with unsupported headers (such as `Expect`) also fail without retrying. Interrupted event writes retain their existing retries; caller cancellations do not trigger another write.
+The SDK also replaces its shared events connection pool after repeated HTTP/2 session failures, and retries event-log reads whose HTTP/2 stream the backend resets. An events request that receives no response data for 60 seconds fails and is retried instead of stalling the invocation. Invalid backend URLs, including unsupported protocols and embedded credentials, fail immediately. Fetch requests to blocked ports or with unsupported headers (such as `Expect`) also fail without retrying. Interrupted event writes retain their existing retries; caller cancellations do not trigger another write.
 
 A connection failure does not prove that the backend rejected a write: it may have accepted it before the response was lost. Continue to make step side effects [idempotent](/docs/foundations/idempotency).
 
@@ -206,9 +206,9 @@ try {
 | `REPLAY_TIMEOUT` | A workflow replay exceeded the maximum allowed duration |
 | `REPLAY_DIVERGENCE` | A replay could not consume the event log deterministically, usually because of non-deterministic workflow code. |
 | `CORRUPTED_EVENT_LOG` | The event log cannot be replayed: it contains orphaned or mismatched events, or one of its stored payloads is no longer readable from the World's storage. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
-| `STREAM_ERROR` | Workflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure rather than an error in workflow code |
+| `STREAM_ERROR` | Workflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure rather than an error in workflow code; retry the run and report persistent failures with the `runId` |
 | `WORLD_CONTRACT_ERROR` | A World response violated the SDK contract; points at a World implementation bug |
-| `DEPLOYMENT_MISMATCH` | The run was delivered to a deployment other than the one it is pinned to, and automatic re-routing did not recover it |
+| `DEPLOYMENT_MISMATCH` | The run was delivered to a deployment other than the one it is pinned to, and automatic re-routing did not recover it. See [deployment-mismatch](/docs/errors/deployment-mismatch) |
 | `RUNTIME_ERROR` | An internal runtime error. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
 
 <Callout type="info">

package/docs/foundations/hooks.mdx

@@ -82,7 +82,7 @@ export async function POST(request: Request) {
 
 The key points:
 - Hooks allow you to pass **any [serializable data](/docs/foundations/serialization)** as the payload
-- You need the hook's `token` to resume it
+- You need the hook's `token` to resume it, but knowing the token does not authorize the caller. Check who is calling before `resumeHook()`; see [Security](#security)
 - The workflow will resume execution right where it left off
 
 ### Checking for token conflicts
@@ -285,7 +285,7 @@ Hooks require you to manually handle HTTP requests and route them to workflows.
 When using Workflow SDK, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
 
 <Callout type="warn">
-`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes because you can share the webhook URL (endpoint) without creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. Make sure to read up on [security](#security) before using a webhook for calls that need to be authenticated.
 </Callout>
 
 <Callout type="info">
@@ -459,6 +459,94 @@ export async function eventCollectorWorkflow() {
 - You need to send HTTP responses back to the caller
 - You want automatic URL routing without writing API handlers
 
+## Security
+
+A hook token tells the runtime which hook a payload belongs to. It is not an authentication mechanism, and neither `resumeHook()` nor the webhook endpoint checks who is sending the payload.
+
+### Generated tokens are hard to guess, not secret
+
+When you don't pass a `token`, the SDK generates one inside the workflow function. Workflow code must produce the same values on every replay, so the generated token comes from the run's deterministic random number generator, the same one that backs [`Math.random()` and `crypto.randomUUID()`](/docs/api-reference/workflow-globals) in workflow functions. That generator is seeded from identifiers of the run, including the run ID, not from a secret key.
+
+A generated token is hard to guess without knowing the run, but the values it is derived from are not designed to be kept secret. Treat a generated token like an unlisted link, not like a credential.
+
+Custom tokens passed to `createHook({ token })` are usually built from domain data such as an order ID, so they are even easier to reconstruct. That is what makes them useful for routing, and it is why the route that resumes them must do its own authorization. If you can not perform your own authorization on the route that calls `resume` for any reason, and need to generate an unguessable token instead, generate it in a step where `crypto` is not seeded and pass it as `token`:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+async function generateToken() {
+  "use step";
+  // Steps run outside the workflow sandbox, so this uses the platform's
+  // cryptographic random source instead of the run's seed.
+  return crypto.randomUUID();
+}
+
+export async function approvalWorkflow() {
+  "use workflow";
+
+  const token = await generateToken(); // [!code highlight]
+  using hook = createHook<{ approved: boolean }>({ token }); // [!code highlight]
+
+  return (await hook).approved;
+}
+```
+
+The step result is recorded in the run's event log like any other step result. See [Encryption](/docs/how-it-works/encryption) to keep it encrypted at rest.
+
+### Webhook URLs
+
+[`createWebhook()`](/docs/api-reference/workflow/create-webhook) serves a public route at `/.well-known/workflow/v1/webhook/:token`, and matching the token is the only check it performs. Anyone who has the URL, or can compute its token, can resume the workflow with a request of their choosing. That is fine for low-stakes callbacks and prototypes. When a webhook request triggers something consequential, either:
+
+- Verify each request before acting on it, for example by checking the provider's HMAC signature in a step with [`respondWith: "manual"`](#dynamic-responses-manual-mode), and keep waiting for the next request when verification fails.
+- Use [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the caller before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook), as shown below.
+
+### Authorize before calling `resumeHook()`
+
+`resumeHook()` delivers the payload to whichever hook owns the token. The route that calls it has to authenticate the caller and check that they are allowed to resume that specific hook. Knowing the token is not proof of either. One way is to record who may resume the hook in its `metadata`, then compare it to the signed-in user:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function expenseWorkflow(approverId: string) {
+  "use workflow";
+
+  using hook = createHook<{ approved: boolean }>({
+    metadata: { approverId }, // [!code highlight]
+  });
+
+  return (await hook).approved;
+}
+```
+
+```typescript lineNumbers
+import { getHookByToken, resumeHook } from "workflow/api";
+
+declare function getSession(request: Request): Promise<{ userId: string } | null>; // @setup
+
+export async function POST(request: Request) {
+  const session = await getSession(request); // [!code highlight]
+  if (!session) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const { token, approved } = await request.json();
+  const hook = await getHookByToken(token);
+  const metadata = (await hook.metadata) as { approverId?: string } | undefined;
+  if (metadata?.approverId !== session.userId) { // [!code highlight]
+    return Response.json({ error: "Forbidden" }, { status: 403 });
+  }
+
+  await resumeHook(token, { approved });
+  return Response.json({ success: true });
+}
+```
+
+Take the user identity from your authentication layer, never from the request body. Other examples in these docs omit authorization to stay short.
+
+### Randomness in workflow functions
+
+The same determinism applies to your own code. `Math.random()`, `crypto.randomUUID()`, and `crypto.getRandomValues()` in a workflow function return values derived from the run's seed, so they are predictable to anyone who knows it. Don't use them for secrets, passwords, one-time codes, or any value that must be unguessable. Generate those in a step, as in the token example above.
+
 ## Advanced patterns
 
 ### Type-safe hooks with `defineHook()`
@@ -514,7 +602,7 @@ This pattern is especially valuable in larger applications where the workflow an
 
 ### Token design
 
-Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always generate their own unique tokens. A generated token is not trivial to guess, but it is not a strong security contract either, so anyone who obtains the URL can invoke an unintended webhook resumption. To prevent unauthenticated run resumptions entirely, prefer a **hook** over the **webhook** convenience and implement your own authentication on the route that calls `resumeHook()`.
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always generate their own unique tokens. Neither kind of token authorizes the sender; see [Security](#security).
 
 When using custom tokens with `createHook()`:
 

package/docs/foundations/serialization.mdx

@@ -36,7 +36,7 @@ The following types can be serialized and passed through workflow functions:
 - `BigInt64Array`, `BigUint64Array`
 - `DataView`
 - `Date`
-- `Float32Array`, `Float64Array`
+- `Float16Array`, `Float32Array`, `Float64Array`
 - `Int8Array`, `Int16Array`, `Int32Array`
 - `Map<Serializable, Serializable>`
 - `RegExp`

package/docs/foundations/streaming.mdx

@@ -337,7 +337,7 @@ async function runTurn(holderRunId: string, turn: number) {
 Pass `{ namespace: "name" }` to target a [namespaced stream](#namespaced-streams). The writable can also be forwarded through `start()` and into steps.
 
 <Callout type="warn">
-Contributors should call `releaseLock()`, which flushes pending writes. Calling `close()` closes the shared stream for every writer.
+Contributors should call `releaseLock()`, which flushes pending writes. Calling `close()` closes the shared stream for every writer. Calling `abort()` keeps the chunks already written and leaves the shared stream open.
 </Callout>
 
 The API grants append access, not read access or additional authorization. The owning run controls the stream's lifecycle, and writes to an unknown run fail.

package/docs/foundations/workflows-and-steps.mdx

@@ -49,7 +49,7 @@ export async function processOrderWorkflow(orderId: string) {
 
 Determinism in the workflow is required to resume the workflow from a suspension. Essentially, the workflow code gets re-run multiple times during its lifecycle, each time using the [event log](/docs/how-it-works/event-sourcing) to resume the workflow to the correct spot.
 
-The sandboxed environment that workflows run in already ensures determinism. For instance, `Math.random` and `Date` constructors are fixed in workflow runs, so you are safe to use them, and the framework ensures that the values don't change across replays.
+The sandboxed environment that workflows run in already ensures determinism. For instance, `Math.random` and `Date` constructors are fixed in workflow runs, so you are safe to use them, and the framework ensures that the values don't change across replays. Seeded random values are not secret, so generate secrets and unguessable tokens in a step (see [Hook and webhook security](/docs/foundations/hooks#security)).
 
 ## Step functions
 

package/docs/getting-started/astro.mdx

@@ -61,12 +61,12 @@ export default defineConfig({
 | --- | --- | --- | --- |
 | `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="text-sm">
-      ### Set up IntelliSense for TypeScript (optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary className="[&_h3]:my-0">
+
+### Set up IntelliSense for TypeScript (optional)
+
+</Summary>
 
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
@@ -83,9 +83,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 </Step>
 

package/docs/getting-started/express.mdx

@@ -72,12 +72,9 @@ export default defineNitroConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>
+
 To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -93,10 +90,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 }
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 ### Update `package.json`
 

package/docs/getting-started/fastify.mdx

@@ -72,12 +72,9 @@ export default defineNitroConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>
+
 To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -93,9 +90,7 @@ To enable helpful hints in your IDE, set up the workflow plugin in `tsconfig.jso
 }
 ```
 
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>
+</Details>
 
 ### Update `package.json`
 

package/docs/getting-started/hono.mdx

@@ -55,12 +55,9 @@ export default defineConfig({
 });
 ```
 
-<Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
-    <AccordionTrigger className="[&_p]:my-0 text-lg [&_p]:text-foreground">
-      Setup IntelliSense for TypeScript (Optional)
-    </AccordionTrigger>
-    <AccordionContent className="[&_p]:my-2">
+<Details>
+<Summary>Setup IntelliSense for TypeScript (Optional)</Summary>
+
 To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json`:
 
 ```json title="tsconfig.json" lineNumbers
@@ -76,10 +73,7 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 }
 ```
 
-    </AccordionContent>
-
-  </AccordionItem>
-</Accordion>
+</Details>
 
 ### Update `package.json`
 

package/docs/getting-started/index.mdx

@@ -80,14 +80,14 @@ import { SiReactrouter } from "@icons-pack/react-simple-icons";
       <div className="flex flex-col items-center justify-center gap-2">
         <Python className="size-16" />
         <span className="font-medium">Python</span>
-        <Badge variant="secondary">Beta</Badge>
+        <Badge variant="gray" size="sm">Beta</Badge>
       </div>
     </Card>
     <Card href="/docs/getting-started/nestjs">
       <div className="flex flex-col items-center justify-center gap-2">
         <Nest className="size-16 dark:invert" />
         <span className="font-medium">NestJS</span>
-        <Badge variant="secondary">Experimental</Badge>
+        <Badge variant="secondary">Beta</Badge>
       </div>
     </Card>
 </Cards>