feat: Add defineLinks documentation and optimize router entry points

.github/workflows/cleanup-test-workers.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Run cleanup script
         env:

.github/workflows/code-quality.yml

@@ -20,16 +20,19 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Enable Corepack
+        run: corepack enable
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
+          cache: "pnpm"
 
-      - run: |
-          corepack enable
-          pnpm install
+      - name: Install dependencies
+        run: pnpm install
 
       - name: Build SDK
         run: pnpm build

.github/workflows/playground-e2e-tests.yml

@@ -116,18 +116,20 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Enable Corepack
+        run: corepack enable
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Install dependencies
         shell: bash
-        run: |
-          corepack enable
-          pnpm install
+        run: pnpm install
 
       - name: Build SDK
         shell: bash

.github/workflows/release-artifacts.yml

@@ -18,12 +18,16 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Enable Corepack
+        run: corepack enable
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Get tag or input version
         id: vars
@@ -36,7 +40,6 @@ jobs:
 
       - name: Update starter package.json
         run: |
-          corepack enable
           version_without_v="${{ steps.vars.outputs.version }}"
           (cd starter && npm pkg set dependencies.rwsdk=${version_without_v#v})
           pnpm install --ignore-scripts --no-frozen-lockfile

.github/workflows/release.yml

@@ -37,7 +37,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           # We need to fetch all history for semver to work correctly and to push changes.
           fetch-depth: 0
@@ -51,15 +51,17 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
 
+      - name: Enable Corepack
+        run: corepack enable
+
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Install dependencies
-        run: |
-          corepack enable
-          pnpm install
+        run: pnpm install
 
       - name: Setup .npmrc for publishing
         working-directory: sdk

.github/workflows/smoke-test.yml

@@ -111,18 +111,20 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Enable Corepack
+        run: corepack enable
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
+          cache: "pnpm"
 
       - name: Install dependencies
         shell: bash
-        run: |
-          corepack enable
-          pnpm install
+        run: pnpm install
 
       - name: Run Smoke Tests
         id: smoke-test

.github/workflows/unrelease.yml

@@ -20,13 +20,13 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           # This token should have write permissions to the repository.
           token: ${{ secrets.GH_TOKEN_FOR_RELEASES }}
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v5
         with:
           node-version: 22
 

.notes/justin/worklogs/2025-10-06-diagnose-renovate-starter-peer-deps.md

@@ -0,0 +1,92 @@
+# 2025-10-06: Diagnose Renovate PR for `starter-peer-deps`
+
+## Problem
+
+A Renovate PR updating several dependencies in the `starter` package is failing with a TypeScript type error in `vite.config.mts`. The error points to an incompatibility between different versions of Vite/Rollup and a custom Vite plugin.
+
+## Plan
+
+1.  Analyze the provided TypeScript error to understand the root cause.
+2.  Examine `starter/vite.config.mts` to see how the plugins are configured.
+3.  Locate the source code of the custom Vite plugin (`rwsdk`).
+4.  Identify the specific code in the plugin that is causing the type conflict.
+5.  Formulate a hypothesis and a proposed solution without implementing it.
+
+## Investigation
+
+### Renovate PR Details
+
+The PR includes the following dependency updates:
+
+| Package                      | Change                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `@cloudflare/vite-plugin`    | `1.13.3` -> `1.13.10`                                                  |
+| `@cloudflare/workers-types`  | `4.20250921.0` -> `4.20251004.0`                                        |
+| `react`                      | `19.2.0-canary-d415fd3e-20250919` -> `19.3.0-canary-4fdf7cf2-20251003` |
+| `react-dom`                  | `19.2.0-canary-d415fd3e-20250919` -> `19.3.0-canary-4fdf7cf2-20251003` |
+| `react-server-dom-webpack`   | `19.2.0-canary-d415fd3e-20250919` -> `19.3.0-canary-4fdf7cf2-20251003` |
+| `vite`                       | `7.1.6` -> `7.1.9`                                                     |
+| `wrangler`                   | `4.38.0` -> `4.42.0`                                                   |
+
+### Type Error in `vite.config.mts`
+
+The core issue is a TypeScript error in `starter/vite.config.mts` when initializing the `redwood()` plugin. The error message is extensive, but the key part points to an incompatibility in the `hotUpdate` hook signature between different versions of Rollup (a dependency of Vite).
+
+```typescript
+No overload matches this call.
+  The last overload gave the following error.
+    Type 'Promise<PluginOption[] | undefined>' is not assignable to type 'PluginOption'.
+      Type 'Promise<PluginOption[] | undefined>' is not assignable to type 'Promise<Plugin$1<any> | FalsyPlugin | PluginOption[]>'.
+        Type 'PluginOption[] | undefined' is not assignable to type 'Plugin$1<any> | FalsyPlugin | PluginOption[]>'.
+          Type 'PluginOption[]' is not assignable to type 'Plugin$1<any> | FalsyPlugin | PluginOption[]'.
+            Type 'import(".../vite@7.1.6/.../vite/dist/node/index").PluginOption[]' is not assignable to type 'import(".../vite@7.1.9/.../vite/dist/node/index").PluginOption[]'.
+              Type 'import(".../vite@7.1.6/.../vite/dist/node/index").PluginOption' is not assignable to type 'import(".../vite@7.1.9/.../vite/dist/node/index").PluginOption'.
+                Type 'Plugin$1<any>' is not assignable to type 'PluginOption'.
+                  Type 'import(".../vite@7.1.6/.../vite/dist/node/index").Plugin<any>' is not assignable to type 'import(".../vite@7.1.9/.../vite/dist/node/index").Plugin<any>'.
+                    Types of property 'hotUpdate' are incompatible.
+                      Type 'import(".../rollup@4.50.1/.../rollup").ObjectHook<(this: import(".../rollup@4.50.1/.../rollup").MinimalPluginContext & { ...; }, ...' is not assignable to type 'import(".../rollup@4.52.4/.../rollup").ObjectHook<(this: import(".../rollup@4.52.4/.../rollup").MinimalPluginContext & { ...; }, ...'.
+```
+
+This indicates that the update from `vite@7.1.6` to `vite@7.1.9` (and its underlying Rollup dependency) has introduced a breaking change in the plugin API.
+
+### Analysis
+
+The `redwood()` plugin, defined in `sdk/src/vite/redwoodPlugin.mts`, aggregates several other internal plugins. The investigation pointed towards `sdk/src/vite/miniflareHMRPlugin.mts` as the source of the incompatibility, because it implements a `hotUpdate` function. The signature of this function no longer matches what the new version of Vite expects.
+
+The problem lies within the SDK's internal plugin implementation, which is not compatible with the updated peer dependencies. Therefore, this PR cannot be merged as is.
+
+## Next Steps
+
+- Create a new task to update the `rwsdk` Vite plugin to be compatible with `vite@7.1.9`.
+- This will involve modifying the `hotUpdate` function in `sdk/src/vite/miniflareHMRPlugin.mts` to match the new API signature.
+- Once the SDK is updated and a new version is released, the Renovate PR for `starter-peer-deps` can be re-evaluated.
+
+## Update: Attempting a fix in the SDK
+
+Based on the analysis, the next logical step was to see if the type error could be reproduced within the `sdk` package itself.
+
+1.  **Updated `vite` dev dependency:** In `sdk/package.json`, the `vite` version in `devDependencies` was updated from a pinned `7.1.6` to `^7.1.9` to match the version in the failing PR. The thinking was that this should surface the same type incompatibility during the SDK's own build process.
+2.  **Ran `pnpm install` and `pnpm build`:** After updating the dependency, I ran the install and build commands for the SDK.
+3.  **Observation:** Unexpectedly, no TypeScript error occurred. The SDK package builds successfully, even with the updated `vite` version that is causing issues in the `starter` project.
+
+This is suspicious. The type error should theoretically appear in any environment where the incompatible plugin signature is checked against the updated Vite/Rollup types. The fact that it doesn't suggests that the SDK's internal build process might not be performing the same type-checking as when the plugin is consumed downstream in the `starter` project.
+
+## Debugging Strategy: Minimal Reproduction
+
+To effectively debug this, we need to reproduce the type error within the `sdk` package's development environment. The plan is to create a temporary file that simulates the conditions of the `starter` project's `vite.config.mts`.
+
+1.  **Create a temporary test file:** I'll create a new file, `sdk/src/vite/temp-debug-vite-config.mts`, right next to the `miniflareHMRPlugin.mts`.
+2.  **Simulate `defineConfig`:** This file will import `defineConfig` from `vite` and the `miniflareHMRPlugin` from the local file.
+3.  **Isolate the plugin:** The `defineConfig` call will be configured with *only* the `miniflareHMRPlugin`. This should trigger the same TypeScript error we're seeing in the `starter` project, but in a much more controlled environment.
+4.  This will allow for direct debugging and iteration on the plugin's code until the type incompatibility is resolved.
+
+## Resolution: Mismatched Dev Dependency
+
+The root cause of the issue has been identified. It was not a bug in the plugin code itself, but a dependency resolution conflict caused by a pinned version in the SDK's `package.json`.
+
+1.  **The Conflict:** The `sdk` package had a `devDependency` on a pinned version of `vite`, specifically `7.1.6`. The Renovate PR updated the `starter` project's `devDependency` to `vite@7.1.9`.
+2.  **Resolution Problem:** When `pnpm` installed dependencies for the `starter` project, it saw two different version requirements for `vite`. It provided `vite@7.1.9` to the `starter` project, but the imported `rwsdk` was linked to its own dependency, `vite@7.1.6`.
+3.  **The Type Error:** This resulted in the TypeScript compiler seeing two different definitions for the same Vite types (e.g., `Plugin`, `HotUpdateOptions`). The types from `vite@7.1.6` were not assignable to the types from `vite@7.1.9`, causing the build to fail.
+4.  **The Fix:** The solution was to change the `vite` `devDependency` in `sdk/package.json` from the pinned `7.1.6` to a compatible version range, `~7.1.9`. This allows `pnpm` to resolve a single, shared version of `vite` (`7.1.9`) for both the `sdk` and the `starter` project, eliminating the type conflict.
+
+With this change, the `starter` project should now build successfully.

.notes/justin/worklogs/2025-10-06-renovate-docs-and-infra-deps.md

@@ -0,0 +1,68 @@
+# 2025-10-06: Renovate Docs and Infra Deps
+
+## Problem
+
+The Renovate PR for `docs-and-infra-deps` introduced several dependency updates. These updates caused two separate failures in the CI/CD pipeline: one in the GitHub Actions workflows and another in the Cloudflare Pages deployment for the documentation site.
+
+## GitHub Actions Workflow Failures
+
+### Observation
+
+The `Code Quality`, `Smoke Tests`, and other workflows began failing with the error `Error: Unable to locate executable file: pnpm`. This coincided with the upgrade of the `actions/setup-node` action from `v4` to `v5`.
+
+### Diagnosis and Fix
+
+Version 5 of `actions/setup-node` automatically detects the project's package manager from the root `package.json` (`pnpm` in this case) and attempts to configure it. However, our workflows were set up to enable `corepack` (which makes `pnpm` available) *after* the `setup-node` step. The action was therefore running before `pnpm` was in the environment's `PATH`.
+
+The solution was to modify the workflows to ensure `corepack` is enabled *before* `setup-node` runs.
+
+**Changes Implemented:**
+
+1.  Added a dedicated "Enable Corepack" step (`run: corepack enable`) before the "Setup Node.js" step.
+2.  Added `cache: 'pnpm'` to the `setup-node` step to speed up dependency installation.
+3.  Removed the redundant `corepack enable` from the subsequent `pnpm install` step.
+
+This fix was applied to all relevant workflow files and resolved the GitHub Actions failures.
+
+## Cloudflare Docs Deployment Failure
+
+### Observation
+
+After fixing the GitHub Actions workflows, the Cloudflare Pages deployment for the docs site started failing with a new error during the `astro build` step: `Dynamic require of "path" is not supported`.
+
+The stack trace pointed to `@fujocoded/expressive-code-output`, which had been updated by Renovate from `0.0.1` to `0.1.0`.
+
+### Attempt 1: Dynamic Import
+
+**Hypothesis:** The error suggested a CommonJS vs. ES Module compatibility issue. It seemed possible that the new version of the package was a CJS module being improperly imported into our ESM-based Astro configuration (`ec.config.mjs`).
+
+**Action:** I modified `docs/ec.config.mjs` to use a dynamic `await import(...)` for `@fujocoded/expressive-code-output`, as Astro's configuration files support top-level await.
+
+**Result:** The local development server failed with the exact same error. This proved the issue was not with how the module was being imported.
+
+### Attempt 2: Deeper Investigation
+
+**Hypothesis:** The problem must be internal to the package itself.
+
+**Action:** Using the full file path from the local error log, I inspected the contents of the problematic file: `.../node_modules/.pnpm/@fujocoded+expressive-code-output@0.1.0/node_modules/@fujocoded/expressive-code-output/dist/index.js`.
+
+**Finding:** The bundled JavaScript file contains a compatibility shim for `require`. The error is thrown by this shim because a `require('path')` call was not correctly processed and replaced by the package's build tool. This is a build issue within the dependency itself and cannot be fixed by configuration changes in our project.
+
+### Conclusion
+
+The investigation confirmed a bug within the `@fujocoded/expressive-code-output@0.1.0` package. After discussing the findings, I have reverted the attempts to fix it, and will now investigate a proper solution myself.
+
+### Update: Pinpointing the Bug
+
+After further investigation, the precise issue was identified. The `package.json` for `@fujocoded/expressive-code-output` has its `exports` map conditions swapped.
+
+- The `import` condition points to `./dist/index.js`, which incorrectly contains CommonJS `require()` calls.
+- The `require` condition points to `./dist/index.cjs`, which is the correct CommonJS bundle.
+
+This is a packaging bug in the dependency. When our ESM-based Astro build tries to import the package, it's served the wrong file, causing the build to fail.
+
+### Final Resolution
+
+After reviewing the dependency's repository and observing an unstable versioning history (`1.0.0` then `0.1.0`), the decision was made to revert to the last known stable version to ensure stability and avoid further issues. The `pnpm patch` solution was considered but ultimately rejected in favor of using a stable version.
+
+The `@fujocoded/expressive-code-output` package has been downgraded to `0.0.1`.

.notes/justin/worklogs/2025-10-09-add-define-links-docs.md

@@ -0,0 +1,47 @@
+# 2025-10-09: Add defineLinks Documentation
+
+## Problem
+
+The `defineLinks` function is a useful utility for creating type-safe links, but it is not documented. This makes it hard for users to discover and understand its purpose.
+
+## Plan
+
+1.  Create a new section in `docs/src/content/docs/core/routing.mdx` called "Generating Links".
+2.  Explain the purpose of `defineLinks`: centralized route definition, type safety, and dynamic parameter handling.
+3.  Include code examples for each of these points.
+4.  Add an API reference for `defineLinks` within the new section.
+5.  Keep the style consistent with the rest of the document.
+6.  Update the API reference to be more descriptive, following the style of `renderToStream` in `react-server-components.mdx`.
+7.  Move the "Generating Links" section to the end of the document.
+
+## Create Conditional Router Entry Points
+
+### Problem
+
+The `rwsdk/router` module includes server-side routing logic that is unnecessary in the client bundle. We need to provide a client-specific entry point that only exports `defineLinks` to reduce bundle size.
+
+### Plan
+
+1.  Create a client-specific entry point for the router at `sdk/src/runtime/entries/routerClient.ts` that only exports `defineLinks`.
+2.  Update `sdk/package.json` to:
+    -   Add the new client entry point to the `tsup` build configuration.
+    -   Modify the `exports` map for `"./router"` to use conditional exports. The `workerd` condition will point to the full router, and the `default` condition will point to the client-specific bundle.
+3.  Update `sdk/src/vite/configPlugin.mts` to add `"rwsdk/router"` to the `optimizeDeps.include` list for the client build configuration.
+
+---
+
+## PR Title
+
+feat: Add defineLinks documentation and optimize router entry points
+
+## PR Description
+
+This PR introduces documentation for the `defineLinks` function and optimizes the router module by creating conditional entry points for different environments.
+
+### Changes
+
+-   **Documentation**: Adds a "Generating Links" section to the routing documentation. This new section explains how to use `defineLinks` for type-safe URL generation and includes a detailed API reference.
+-   **Router Entry Points**: The router module now has separate entry points for client and server environments. A client-specific entry point (`routerClient.ts`) is introduced, which only exports the `defineLinks` function. This change reduces the client bundle size by excluding server-side routing logic.
+-   **Build Configuration**:
+    -   The `package.json` `exports` map for `./router` is updated to use conditional exports, serving the appropriate bundle to either the `workerd` (`worker`+`ssr` environments) or `default` (`client` environment) condition.
+    -   `"rwsdk/router"` is added to the `optimizeDeps.include` array in the Vite client configuration.

addons/passkey/package.json

@@ -3,12 +3,12 @@
   "private": true,
   "version": "0.0.0",
   "dependencies": {
-    "@simplewebauthn/browser": "13.2.0",
-    "@simplewebauthn/server": "13.2.0",
+    "@simplewebauthn/browser": "13.2.2",
+    "@simplewebauthn/server": "13.2.2",
     "rwsdk": "workspace:*"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "4.20250921.0",
+    "@cloudflare/workers-types": "4.20251004.0",
     "@types/react": "18.3.5",
     "@types/react-dom": "18.3.0"
   }

docs/.node-version

@@ -1 +1 @@
-22.14.0
+22.20.0