diff --git a/.cursor/rules/user/justin.mdc b/.cursor/rules/user/justin.mdc deleted file mode 100644 index 8836b9299..000000000 --- a/.cursor/rules/user/justin.mdc +++ /dev/null @@ -1,121 +0,0 @@ ---- -alwaysApply: true ---- - -* Work Log Protocol: All development must start by creating/updating a work log in directory `/.notes/justin/worklogs/` directory, with the file name format `YYYY-MM-DD-description.md`. The initial log must define the problem, plan, and context. The log must be updated in real-time throughout the development process (types, tests, implementation) with all notable events: decisions and their rationale, blockers, discoveries, and plan changes. It is a continuous journal. -* Work logs should be written as if by me, appending for each new task, finding, decision, etc. If I ask you to correct a mistake of your own, do not add content on that change in the work log, but instead revise as if that mistake never happened - think of what I would have done in the first place. -* Never say "Final" or "Definitive" or similar. Everything is an attempt, and subject to the test of time. -* Avoid "fluff" at the end of a section intended to round it off. Example (avoid this!): "This approach, combining a high-level stitching strategy with low-level, well-tested extraction utilities, ensures the solution is not only architecturally sound but also maintainable and correct." -* Architecture Revision Protocol: Architecture documents in `/docs/architecture` are to be revised only as the final step, after implementation is stable and tests pass. Use the completed work log as the primary source to distill the final, successful implementation's "why" into the formal documentation, following the established problem/solution narrative format. -* The user prefers technical writing to maintain consistent tone, style, and formatting; use high-level explanations; and avoid references to programming symbols. [[memory:8001383]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001380]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001377]] -* The user prefers a neutral writing tone, including in PR descriptions, avoiding dramatic or hyperbolic language. They avoid specific words that add undue emphasis or urgency, such as “killing,” “unreliable,” “risk,” “obscured,” and “critically.” [[memory:8001374]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:8001371]] -* The user prefers that the assistant adopt a less formal, more human, and casual tone in messages, avoiding stiffness and passive-aggressive phrasing. They also prefer concise, short communications using bullet points and bold keywords, avoiding long-winded explanations, overly dramatic language, and words like “essential” or “critical.” [[memory:6170010]] -* The user prefers that the assistant avoid using the word 'new' in documentation, as it is not important and will quickly become outdated. [[memory:6165420]] -* The user prefers that when modifying documentation, the assistant include all original context and not drop any details. [[memory:4798121]] -* Project uses the debug library for long-term logging with minimal verbosity, logging only failures. [[memory:4586459]] -* The user prefers tentative, exploratory language (“it seems,” “I think,” “might be”) over assertive claims to encourage openness and humility. They always avoid dramatic language and specific words like “killing” and “unreliable.” [[memory:4586455]] -* The user prefers documentation to avoid promotional or selling language and not claim that the architecture is superior. [[memory:4586453]] -* The user prefers using 'rwsdk' as the prefix instead of 'rws' throughout the codebase. [[memory:4586450]] -* When importing from `.mts` source files, use the `.mjs` extension in the import path. TypeScript handles the resolution, so even though the files have a `.mts` extension, the import specifiers must use `.mjs` . [[memory:4544197]] -* Prefer dependency injection over mocking in tests. Dependency injection makes a function's dependencies explicit and allows for passing in controlled versions for testing. Mocking can hide dependencies, lead to leaky state between tests, and make tests more brittle. [[memory:4223216]] -* Architecture documentation should focus on the "why" behind a design decision. It must explain the problem, the constraints considered, and the rationale for the chosen solution. The narrative is as important as the technical description. [[memory:4132497]] -* Architecture documentation should be clear, easy to understand, and avoid unnecessary technical jargon or low-level implementation details like specific function or variable names. The goal is to explain the system's design, not its line-by-line implementation. [[memory:4132491]] -* When making significant changes to the framework's architecture—including adding, modifying, or removing core functionalities—a corresponding entry must be created or updated in the `docs/architecture` directory. [[memory:4132489]] -* The user prefers that the assistant not hardcode values and avoid hardcoded paths or constants. [[memory:4059607]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:3430114]] -* Pipe all your commands through `cat` when possible, ensuring to pipe stderr and stdout, so that we can avoid interactivity on my side being a blocker as much as possible -* If asked to use git worktrees to work on a task, use ~/rw/worktrees// as the dir name -* NEVER use the word "final" -* Everything is an attempt, and subject to the test of time -* For any non-trivial task involving investigation or multiple attempts, create or update a work log to tell the story of the problem-solving journey. Frame the log as a narrative of each attempt, explaining the rationale and the findings that led to the next step, and conclude with the currently accepted solution. Store all work logs in a .worklogs/justin directory at the project root, using the filename format YYYY-MM-DD-short-description.md. -* Don't add comments unless I ask. -* Do this: - -if (foo) { - bar -} - -Do not do this - -if (foo) bar -* All changes that are larger scale, architecturally relevant or affect the behaviour of the system, start with architecture documentation (in docs/architecture/). If there's no relevant doc, create one anew. First make sure the change to be made is documented here correctly. When complete, come up with a list of the tasks to be done to refacor the code to make the necessary changes. Then stop and wait for my approval before proceeding with the corresponding code changes. -* Use ' isntead of ’ -* Use - instead of — -* Style Guide: Plain Technical Communication - - When generating any text (PR descriptions, documentation, code comments, etc.), adhere strictly to the following rules: - - 1. Use Simple, Direct Language: Write for clarity. Avoid jargon and complex vocabulary where a simpler word will do. - 2. Describe Actions, Not Intent: Instead of explaining the purpose or goal of a piece of code (e.g., "to verify integrity"), describe the literal action it performs (e.g., "compares file checksums"). - 3. No Subjective Qualifiers: Do not use adjectives that evaluate quality or value (e.g., good, robust, easy, safe, comprehensive). Stick to objective facts. - 4. Avoid Abstract Concepts: Break down high-level technical concepts into their concrete, constituent steps. For example, instead of "automated verification," state the specific checks that are run: "runs a checksum comparison and smoke tests." - 5. Be Concise: Omit unnecessary words. -* When generating a PR description or similar documentation, structure the text to first explain the problem or the previous state. Then, introduce the solution and describe its key functional outcomes at a high level. Avoid low-level implementation details unless they are essential to understanding the core change. Conclude with the testing status and what still needs to be validated. Maintain a direct and technical tone. -* When generating any text (chat messages, PR descriptions, documentation, code comments), use a direct, concise, and technical communication style. Avoid marketing language, hyperbole, and subjective adjectives like 'robust', 'powerful', 'easy', or 'comprehensiverbose'. Focus on factually describing what the code or process does, in a tone similar to technical documentation or a well-written commit message. -* Always debug to break down the problem down to solve the problem at hand: for runtime, adding debugging lines and run the code/tests; for type issues, add debugging types or use internal types to understand where things break down -* When the code needs some context for understanding (theres some inherent complexity not surfaced by the code itself), use this format: - - // context(justinvdm, 5 Feb 2025): Serve assets requests using the assets service binding - // todo(justinvdm, 5 Feb 2025): Find a way to avoid this so asset requests are served directly - // rather than first needing to go through the worker* Work Log Protocol: All development must start by creating/updating a work log in directory `/.notes/justin/worklogs/` directory, with the file name format `YYYY-MM-DD-description.md`. The initial log must define the problem, plan, and context. The log must be updated in real-time throughout the development process (types, tests, implementation) with all notable events: decisions and their rationale, blockers, discoveries, and plan changes. It is a continuous journal. -* Work logs should be written as if by me, appending for each new task, finding, decision, etc. If I ask you to correct a mistake of your own, do not add content on that change in the work log, but instead revise as if that mistake never happened - think of what I would have done in the first place. -* Never say "Final" or "Definitive" or similar. Everything is an attempt, and subject to the test of time. -* Avoid "fluff" at the end of a section intended to round it off. Example (avoid this!): "This approach, combining a high-level stitching strategy with low-level, well-tested extraction utilities, ensures the solution is not only architecturally sound but also maintainable and correct." -* Architecture Revision Protocol: Architecture documents in `/docs/architecture` are to be revised only as the final step, after implementation is stable and tests pass. Use the completed work log as the primary source to distill the final, successful implementation's "why" into the formal documentation, following the established problem/solution narrative format. -* The user prefers technical writing to maintain consistent tone, style, and formatting; use high-level explanations; and avoid references to programming symbols. [[memory:8001383]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001380]] -* The user prefers to avoid using lockfiles because they need to work with various package managers. [[memory:8001377]] -* The user prefers a neutral writing tone, including in PR descriptions, avoiding dramatic or hyperbolic language. They avoid specific words that add undue emphasis or urgency, such as “killing,” “unreliable,” “risk,” “obscured,” and “critically.” [[memory:8001374]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:8001371]] -* The user prefers that the assistant adopt a less formal, more human, and casual tone in messages, avoiding stiffness and passive-aggressive phrasing. They also prefer concise, short communications using bullet points and bold keywords, avoiding long-winded explanations, overly dramatic language, and words like “essential” or “critical.” [[memory:6170010]] -* The user prefers that the assistant avoid using the word 'new' in documentation, as it is not important and will quickly become outdated. [[memory:6165420]] -* The user prefers that when modifying documentation, the assistant include all original context and not drop any details. [[memory:4798121]] -* Project uses the debug library for long-term logging with minimal verbosity, logging only failures. [[memory:4586459]] -* The user prefers tentative, exploratory language (“it seems,” “I think,” “might be”) over assertive claims to encourage openness and humility. They always avoid dramatic language and specific words like “killing” and “unreliable.” [[memory:4586455]] -* The user prefers documentation to avoid promotional or selling language and not claim that the architecture is superior. [[memory:4586453]] -* The user prefers using 'rwsdk' as the prefix instead of 'rws' throughout the codebase. [[memory:4586450]] -* When importing from `.mts` source files, use the `.mjs` extension in the import path. TypeScript handles the resolution, so even though the files have a `.mts` extension, the import specifiers must use `.mjs` . [[memory:4544197]] -* Prefer dependency injection over mocking in tests. Dependency injection makes a function's dependencies explicit and allows for passing in controlled versions for testing. Mocking can hide dependencies, lead to leaky state between tests, and make tests more brittle. [[memory:4223216]] -* Architecture documentation should focus on the "why" behind a design decision. It must explain the problem, the constraints considered, and the rationale for the chosen solution. The narrative is as important as the technical description. [[memory:4132497]] -* Architecture documentation should be clear, easy to understand, and avoid unnecessary technical jargon or low-level implementation details like specific function or variable names. The goal is to explain the system's design, not its line-by-line implementation. [[memory:4132491]] -* When making significant changes to the framework's architecture—including adding, modifying, or removing core functionalities—a corresponding entry must be created or updated in the `docs/architecture` directory. [[memory:4132489]] -* The user prefers that the assistant not hardcode values and avoid hardcoded paths or constants. [[memory:4059607]] -* The user prefers change descriptions and communications to use direct, technical language without any marketing fluff or sales language. They avoid promotional or selling language, opt for a modest tone that undersells feature descriptions, and steer clear of hype and subjective qualifiers. [[memory:3430114]] -* Pipe all your commands through `cat` when possible, ensuring to pipe stderr and stdout, so that we can avoid interactivity on my side being a blocker as much as possible -* If asked to use git worktrees to work on a task, use ~/rw/worktrees// as the dir name -* NEVER use the word "final" -* Everything is an attempt, and subject to the test of time -* For any non-trivial task involving investigation or multiple attempts, create or update a work log to tell the story of the problem-solving journey. Frame the log as a narrative of each attempt, explaining the rationale and the findings that led to the next step, and conclude with the currently accepted solution. Store all work logs in a .worklogs/justin directory at the project root, using the filename format YYYY-MM-DD-short-description.md. -* Don't add comments unless I ask. -* Do this: - -if (foo) { - bar -} - -Do not do this - -if (foo) bar -* All changes that are larger scale, architecturally relevant or affect the behaviour of the system, start with architecture documentation (in docs/architecture/). If there's no relevant doc, create one anew. First make sure the change to be made is documented here correctly. When complete, come up with a list of the tasks to be done to refacor the code to make the necessary changes. Then stop and wait for my approval before proceeding with the corresponding code changes. -* Use ' isntead of ’ -* Use - instead of — -* Style Guide: Plain Technical Communication - - When generating any text (PR descriptions, documentation, code comments, etc.), adhere strictly to the following rules: - - 1. Use Simple, Direct Language: Write for clarity. Avoid jargon and complex vocabulary where a simpler word will do. - 2. Describe Actions, Not Intent: Instead of explaining the purpose or goal of a piece of code (e.g., "to verify integrity"), describe the literal action it performs (e.g., "compares file checksums"). - 3. No Subjective Qualifiers: Do not use adjectives that evaluate quality or value (e.g., good, robust, easy, safe, comprehensive). Stick to objective facts. - 4. Avoid Abstract Concepts: Break down high-level technical concepts into their concrete, constituent steps. For example, instead of "automated verification," state the specific checks that are run: "runs a checksum comparison and smoke tests." - 5. Be Concise: Omit unnecessary words. -* When generating a PR description or similar documentation, structure the text to first explain the problem or the previous state. Then, introduce the solution and describe its key functional outcomes at a high level. Avoid low-level implementation details unless they are essential to understanding the core change. Conclude with the testing status and what still needs to be validated. Maintain a direct and technical tone. -* When generating any text (chat messages, PR descriptions, documentation, code comments), use a direct, concise, and technical communication style. Avoid marketing language, hyperbole, and subjective adjectives like 'robust', 'powerful', 'easy', or 'comprehensiverbose'. Focus on factually describing what the code or process does, in a tone similar to technical documentation or a well-written commit message. -* Always debug to break down the problem down to solve the problem at hand: for runtime, adding debugging lines and run the code/tests; for type issues, add debugging types or use internal types to understand where things break down -* When the code needs some context for understanding (theres some inherent complexity not surfaced by the code itself), use this format: - - // context(justinvdm, 5 Feb 2025): Serve assets requests using the assets service binding - // todo(justinvdm, 5 Feb 2025): Find a way to avoid this so asset requests are served directly - // rather than first needing to go through the worker \ No newline at end of file diff --git a/.github/workflows/cleanup-test-workers.yml b/.github/workflows/cleanup-test-workers.yml index 6ddd87822..9fd08163a 100644 --- a/.github/workflows/cleanup-test-workers.yml +++ b/.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: diff --git a/.github/workflows/code-quality.yml b/.github/workflows/code-quality.yml index 0c6671a6c..26c015ed5 100644 --- a/.github/workflows/code-quality.yml +++ b/.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 diff --git a/.github/workflows/playground-e2e-tests.yml b/.github/workflows/playground-e2e-tests.yml index 53bdd7833..a418bce9d 100644 --- a/.github/workflows/playground-e2e-tests.yml +++ b/.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 diff --git a/.github/workflows/release-artifacts.yml b/.github/workflows/release-artifacts.yml index 64d6e737c..f8c87a539 100644 --- a/.github/workflows/release-artifacts.yml +++ b/.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 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c98d6af28..022db9776 100644 --- a/.github/workflows/release.yml +++ b/.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 diff --git a/.github/workflows/smoke-test.yml b/.github/workflows/smoke-test.yml index f1e9f3de4..de034f952 100644 --- a/.github/workflows/smoke-test.yml +++ b/.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 diff --git a/.github/workflows/unrelease.yml b/.github/workflows/unrelease.yml index b2622400c..19a94ad5e 100644 --- a/.github/workflows/unrelease.yml +++ b/.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 diff --git a/.notes/justin/worklogs/2025-10-06-diagnose-renovate-starter-peer-deps.md b/.notes/justin/worklogs/2025-10-06-diagnose-renovate-starter-peer-deps.md new file mode 100644 index 000000000..285325cfe --- /dev/null +++ b/.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' is not assignable to type 'PluginOption'. + Type 'Promise' is not assignable to type 'Promise | FalsyPlugin | PluginOption[]>'. + Type 'PluginOption[] | undefined' is not assignable to type 'Plugin$1 | FalsyPlugin | PluginOption[]>'. + Type 'PluginOption[]' is not assignable to type 'Plugin$1 | 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' is not assignable to type 'PluginOption'. + Type 'import(".../vite@7.1.6/.../vite/dist/node/index").Plugin' is not assignable to type 'import(".../vite@7.1.9/.../vite/dist/node/index").Plugin'. + 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. diff --git a/.notes/justin/worklogs/2025-10-06-renovate-docs-and-infra-deps.md b/.notes/justin/worklogs/2025-10-06-renovate-docs-and-infra-deps.md new file mode 100644 index 000000000..3f58787a9 --- /dev/null +++ b/.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`. diff --git a/.notes/justin/worklogs/2025-10-09-add-define-links-docs.md b/.notes/justin/worklogs/2025-10-09-add-define-links-docs.md new file mode 100644 index 000000000..80392c523 --- /dev/null +++ b/.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. diff --git a/addons/passkey/package.json b/addons/passkey/package.json index 5e6ea2ec9..79b406747 100644 --- a/addons/passkey/package.json +++ b/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" } diff --git a/docs/.node-version b/docs/.node-version index 7d41c735d..442c7587a 100644 --- a/docs/.node-version +++ b/docs/.node-version @@ -1 +1 @@ -22.14.0 +22.20.0 diff --git a/docs/architecture/documentTransforms.md b/docs/architecture/documentTransforms.md index 2656d1f7c..bafc6f129 100644 --- a/docs/architecture/documentTransforms.md +++ b/docs/architecture/documentTransforms.md @@ -4,16 +4,15 @@ This document details the various automated transformations applied to `Document ## The Challenge: From Source to Production -In our framework, developers define the entire HTML shell using a React component, typically `src/app/Document.tsx`. This provides great power and flexibility, but it also introduces a significant architectural challenge: balancing our philosophy of user control with the technical requirements of a modern React framework. +In our framework, developers define the entire HTML shell using a React component, typically `src/app/Document.tsx`. This provides great power and flexibility, as explained in the [guides for creating Documents](../src/contents/docs/guides/frontend/documents.mdx). However, the source code of a `Document` component is not what can be served directly to a user's browser, especially in a production environment. It contains several elements that need to be processed: -1. **The Hydration Ordering Problem:** For `React.useId` to work correctly, React must inject a hydration "marker" script *before* the main client entry script is loaded. This means React needs to control the rendering of the entry point. However, our philosophy dictates that the user should explicitly place this script in their `Document`. This creates a direct conflict: how can React control a script that the user has placed? -2. **Development-Time Paths**: Script tags like `