[ { "path": ".agents/skills/add-package/SKILL.md", "content": "---\nname: add-package\ndescription: Create or align a package in the Remix monorepo to match existing package conventions. Use when adding a brand new package under packages/, or when fixing an existing package's structure, test setup, TypeScript/build config, code style, and README layout to match the rest of Remix 3.\n---\n\n# Add Package\n\n## Overview\n\nUse this skill to scaffold and standardize packages so they look and behave like the existing `@remix-run/*` packages.\nFollow this exactly when creating package files, public exports, tests, and docs.\n\n## Workflow\n\n1. Create the package directory and baseline files.\n\n- Create `packages//`.\n- Add:\n - `package.json`\n - `tsconfig.json`\n - `tsconfig.build.json`\n - `CHANGELOG.md`\n - `README.md`\n - `LICENSE`\n - `.changes/README.md`\n - `src/`\n- For new packages, start `CHANGELOG.md` with `## Unreleased` as the first section to indicate changes are not released yet.\n\n2. Set up `package.json` using monorepo conventions.\n\n- Use:\n - `name`: `@remix-run/`\n - `version` (for brand-new packages): `\"0.0.0\"`\n - `type`: `\"module\"`\n - `license`: `\"MIT\"`\n - `repository.directory`: `packages/`\n - `homepage`: `https://github.com/remix-run/remix/tree/main/packages/#readme`\n- Include `files`:\n - `LICENSE`\n - `README.md`\n - `dist`\n - `src`\n - `!src/**/*.test.ts`\n- Add standard scripts:\n - `build`: `tsgo -p tsconfig.build.json`\n - `clean`: `git clean -fdX`\n - `prepublishOnly`: `pnpm run build`\n - `test`: `node --disable-warning=ExperimentalWarning --test`\n - `typecheck`: `tsgo --noEmit`\n- Use baseline dev dependencies:\n - `\"@types/node\": \"catalog:\"`\n - `\"@typescript/native-preview\": \"catalog:\"`\n- Add `keywords` like existing packages (short, lowercase, feature-focused).\n\n3. Define exports with `src` entry files only.\n\n- In `exports`, map each public subpath to a dedicated file in `src`.\n- Always include `./package.json`.\n- Mirror each export in `publishConfig.exports` with `dist` output:\n - `types`: `./dist/.d.ts`\n - `default`: `./dist/.js`\n- Rule: every export must have a `src` file that re-exports from `src/lib`.\n - Example: export `./foo` -> `src/foo.ts` -> `export { ... } from './lib/foo.ts'`\n\n4. Add TypeScript config files with shared defaults.\n\nUse this `tsconfig.json` pattern:\n\n```json\n{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true\n }\n}\n```\n\nUse this `tsconfig.build.json` pattern:\n\n```json\n{\n \"extends\": \"./tsconfig.json\",\n \"compilerOptions\": {\n \"declaration\": true,\n \"declarationMap\": true,\n \"outDir\": \"./dist\"\n },\n \"include\": [\"src\"],\n \"exclude\": [\"src/**/*.test.ts\"]\n}\n```\n\n5. Implement source structure and test setup.\n\n- Structure source as:\n - `src/.ts` for public entry points\n - `src/lib/*.ts` for implementation\n - `src/lib/*.test.ts` for tests (colocated with implementation)\n- Tests use Node's built-in test runner:\n - `import * as assert from 'node:assert/strict'`\n - `import { describe, it } from 'node:test'`\n- Keep tests IDE-friendly:\n - Do not generate tests with loops/conditionals inside `describe()`.\n\n6. Follow monorepo code style rules while implementing.\n\n- Use `import type { ... }` and `export type { ... }` for types.\n- Include `.ts` extensions in relative imports.\n- Prefer `let` for locals; use `const` only at module scope.\n- Never use `var`.\n- Prefer function declarations/expressions for normal functions.\n- Use arrow functions for callbacks; use concise callbacks when returning a single expression.\n- Use object method shorthand (`method() {}`) instead of arrow properties.\n- Use native class fields and `#private` members.\n- Avoid Node-specific APIs when Web APIs are available.\n\n7. Write README in the same style and section order as existing packages.\n\n- Start with:\n - `# `\n - One short paragraph describing purpose.\n- Typical section order:\n - `## Features`\n - `## Installation`\n - `## Usage`\n - Optional deep-dive sections (only if needed)\n - `## Related Packages` (if applicable)\n - `## License`\n- Installation instructions must always include installing the `remix` package.\n- If using the package requires a peer dependency, installation instructions must also include that peer dependency in the command.\n- Preferred installation pattern:\n\n```sh\nnpm i remix\n```\n\n- Example when a peer dependency is required:\n\n```sh\nnpm i remix \n```\n\n- Usage examples must always import from `remix` package exports, not from `@remix-run/` directly.\n\n- License section format:\n - `See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)`\n\n8. Do not manually update the generated `remix` package in PRs.\n\n- `packages/remix` is generated automatically in CI.\n- Do not manually edit `packages/remix/package.json` or `packages/remix/src/*` in new pull requests.\n- Do not add `packages/remix/.changes/*` change files in new pull requests.\n- If user asks for full surfacing, you can still update root `README.md` package list when applicable.\n\n9. Validate before finishing.\n\n- Run package checks:\n - `pnpm --filter @remix-run/ run typecheck`\n - `pnpm --filter @remix-run/ run test`\n - `pnpm --filter @remix-run/ run build`\n- Run repo lint (required):\n - `pnpm run lint`\n- Add or update a change file under `packages//.changes/` when requested by contribution workflow.\n- For a brand-new package, the initial change file should use a `minor.` filename (for example, `minor.initial-release.md`) so the first release bumps `0.0.0` to `0.1.0`.\n- Exception: do not add a change file under `packages/remix/.changes/`; `remix` package updates are CI-generated.\n\n## Templates\n\nUse this minimal `src/index.ts` style:\n\n```ts\nexport { createThing, type ThingOptions } from './lib/thing.ts'\n```\n\nUse this minimal test style:\n\n```ts\nimport * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { createThing } from './thing.ts'\n\ndescribe('createThing', () => {\n it('returns expected value', () => {\n let result = createThing()\n assert.equal(result, 'ok')\n })\n})\n```\n" }, { "path": ".agents/skills/add-package/agents/openai.yaml", "content": "interface:\n display_name: 'Add Package'\n short_description: 'Create new Remix monorepo packages consistently'\n default_prompt: 'Use $add-package to scaffold and wire a new package in the Remix monorepo with the standard layout, scripts, tests, and README structure.'\n" }, { "path": ".agents/skills/make-change-file/SKILL.md", "content": "---\nname: make-change-file\ndescription: Create or update Remix repo change files under `packages/*/.changes`. Use when a user asks for release notes, a change file, a missing changelog entry, a prerelease note, or an update to existing unpublished release notes.\n---\n\n# Make Change File\n\n## Overview\n\nWrite release notes that match this repository's `.changes` conventions. Use it for both new change files and edits to existing unpublished ones.\n\n## Workflow\n\n1. Read the package's `package.json`, `.changes/` directory, and any relevant PR diff or commit range before writing anything.\n2. Check whether an unpublished change file already exists for the same work. If it does, update it in place instead of creating a duplicate note.\n3. Choose the bump type from the package version and the user-facing impact.\n4. Write concise, user-facing release notes that describe shipped behavior, APIs, or exports.\n5. Run `pnpm changes:preview` to verify the rendered changelog output.\n6. Run `pnpm run lint` before finishing.\n\n## Naming\n\n- Use `packages//.changes/[major|minor|patch].short-description.md`.\n- Keep the slug short, specific, and stable.\n- Reuse existing deterministic names when the repo already has a pattern for that class of note.\n- For Remix export-only changes, update `packages/remix/.changes/minor.remix.update-exports.md` in place.\n- For brand-new package releases, prefer `minor.initial-release.md`.\n\n## Bump Rules\n\n- For `0.x` packages: use `minor` for new features and breaking changes, `patch` for bug fixes.\n- Do not use `major` for `0.x` packages unless explicitly instructed.\n- For `1.x+` packages: use standard semver.\n- Breaking changes are relative to `main`, not relative to earlier commits in the same PR.\n- In `0.x`, breaking change notes must start with `BREAKING CHANGE: `.\n- For `remix` prerelease mode, the bump type mostly controls changelog categorization while the prerelease counter advances.\n\n## Content Rules\n\n- Document user-visible behavior, public API changes, exports, migrations, or upgrade work.\n- Do not write release notes for internal refactors unless they surface as real API or behavior changes.\n- Prefer a small number of logically grouped notes over many tiny files.\n- If one package changes internally and another package re-exports the new surface, add notes for both when users can consume the change from both package entrypoints.\n- Do not manually hard-wrap prose in `.changes/*.md` files. Keep each paragraph or bullet on a single source line and let rendered changelogs wrap naturally.\n- Use flat bullets only when they add clarity. Short paragraphs are usually better.\n\n## Remix-Specific Rules\n\n- `packages/remix/src/*` re-export files are generated. Do not hand-edit them unless the task explicitly requires generated output.\n- When `packages/remix/package.json` gains or changes public exports, capture that in `minor.remix.update-exports.md` instead of inventing a one-off filename.\n- If the change exposes another package's new APIs through `remix/...`, describe the surfaced `remix/...` entrypoints, not just the underlying workspace package name.\n\n## Checklist\n\n- Did you inspect existing unpublished `.changes` files first?\n- Is the bump type correct for the package version?\n- Did you reuse any deterministic filename the repo already expects?\n- Does the note describe user-facing changes instead of implementation details?\n- Does each paragraph or bullet stay on one source line without manual hard wrapping?\n- Did `pnpm changes:preview` render the expected changelog entry?\n" }, { "path": ".agents/skills/make-change-file/agents/openai.yaml", "content": "interface:\n display_name: 'Make Change File'\n short_description: 'Create or update Remix change files using repo conventions.'\n default_prompt: 'Use $make-change-file to add or revise package change files for this Remix repo.'\n" }, { "path": ".agents/skills/make-demo/SKILL.md", "content": "---\nname: make-demo\ndescription: Create or revise demos in the Remix repository. Use when adding a new demo under demos/, updating an existing demo, or reviewing demo code to ensure it showcases Remix packages, strong code hygiene, and production-quality patterns.\n---\n\n# Make Demo\n\n## Overview\n\nDemos in this repository are not throwaway prototypes. They are durable code artifacts that should teach people and other agents how to write Remix code well.\n\nA good demo should:\n\n- exercise Remix framework behavior in a realistic way\n- push the target APIs through meaningful edge cases and composition points\n- model clean structure, naming, and accessibility\n- be code that a reader could adapt into a real application\n\n## Workflow\n\n1. Read the target APIs and at least one or two existing demos before writing new code.\n2. Choose a focused scenario that exists to demonstrate Remix behavior, not a generic app shell.\n3. Build the demo under `demos//` using the same conventions as the existing demos.\n4. Treat the code as a reference artifact, not as temporary sample code.\n5. Validate the demo locally before finishing.\n\n## Rules\n\n- Use Remix library packages for the demo's framework behavior. Do not introduce unrelated routers, component frameworks, state managers, or middleware stacks that distract from the Remix patterns being demonstrated.\n- Keep any non-Remix dependency incidental to the runtime environment only. If a database driver, asset bundler, or type package is needed, it should support the demo rather than define its architecture.\n- Demos should push Remix to its limits in a focused way. Prefer realistic edge cases, composition, streaming, middleware, routing, navigation, forms, or request-handling scenarios over toy examples.\n- When demos use `remix/component`, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in styling/mixin props such as `css={...}` or `mix={css(...)}`\n and `mix={[...]}` instead of dropping down to manual DOM mutation or ad hoc class management.\n- Demo code must have good hygiene. Use clear names, small focused modules, explicit control flow, and accessible markup. Avoid hacks, dead code, unexplained shortcuts, or patterns that would be poor examples for users to copy.\n- Make the demo teach good patterns. Assume readers and future agents will study it as an example of how Remix code should be written in this repository.\n- All demo servers should use port `44100`.\n- Demo servers should handle `SIGINT` and `SIGTERM` cleanly by closing the server and exiting.\n\n## Typical Structure\n\nUse only the files the scenario needs, but prefer this shape:\n\n- `demos//package.json`\n- `demos//server.ts`\n- `demos//README.md`\n- `demos//app/`\n- `demos//public/` when serving built assets or other static files\n\n## README Expectations\n\n- Explain what the demo proves or teaches.\n- Document how to run it locally.\n- Point out the key Remix APIs or patterns being demonstrated.\n- Keep code examples and imports aligned with repo guidance: use `remix` package exports where available.\n\n## Validation\n\n- Run `pnpm -C demos/ typecheck` when the demo defines a typecheck script.\n- Run `pnpm -C demos/ test` when the demo defines tests.\n- Smoke-test the demo server locally when behavior depends on live requests or browser interaction.\n- Run `pnpm run lint` before finishing.\n" }, { "path": ".agents/skills/make-demo/agents/openai.yaml", "content": "interface:\n display_name: 'Make Demo'\n short_description: 'Create high-quality Remix demos'\n default_prompt: 'Use $make-demo to add or revise a demo under demos/ that showcases Remix packages with clean, artifact-quality code and strong repo conventions.'\n" }, { "path": ".agents/skills/make-pr/SKILL.md", "content": "---\nname: make-pr\ndescription: Create GitHub pull requests with clear, reviewer-friendly descriptions. Use when asked to open or prepare a PR, especially when the PR needs strong context, related links, and feature usage examples. This skill enforces concise PR structure, avoids redundant sections like validation/testing, and creates the PR with gh CLI.\n---\n\n# Make PR\n\n## Overview\n\nUse this skill to draft and open a PR with consistent, high-signal writing.\nKeep headings sparse and focus on the problem/feature explanation, context links, and practical code examples.\nOptimize for the shortest path to a credible PR, not the fullest possible context-gathering pass.\n\n## Workflow\n\n1. Check the fast-path blockers first.\n\n- Check `git status --short --branch` and `git branch --show-current` before doing deeper prep.\n- If the repo is in a detached HEAD or worktree state and the user wants a PR opened, create a branch early.\n\n1. Gather only the context needed to write the PR.\n\n- Capture what changed, why it changed, and who it affects.\n- Find related issues/PRs and include links when relevant.\n- Prefer `git diff --stat` plus the relevant diff over broad repo archaeology when the change is small.\n- If the user supplies a report, issue, or related PR, treat that as the primary context source.\n\n1. Get the branch into a PR-ready state quickly.\n\n- If changes are still uncommitted and the user wants a PR, branch first, then commit.\n- Prefer a single clean commit unless the user asks for a different history shape.\n\n1. Check whether this PR also needs a change file.\n\n- Do not assume every PR needs one.\n- Before opening the PR, decide whether the change is user-facing enough to require release notes in `packages/*/.changes`.\n- If a change file is needed or likely needed, use the `make-change-file` skill instead of re-deriving that workflow here.\n\n1. Draft the PR body with minimal structure.\n\n- Start with 1-2 short introductory paragraphs.\n- After the intro, include clear bullets describing:\n - the feature and/or issue addressed\n - key behavior/API changes\n - expected impact\n- If the change is extensive, expand to up to 3-4 paragraphs and include background context with related links.\n\n1. Add required usage examples for feature work.\n\n- If the PR introduces a new feature, include a comprehensive usage snippet.\n- If it replaces or improves an older approach, include before/after examples.\n\n1. Exclude redundant sections.\n\n- Do not include `Validation`, `Testing`, or other process sections that are already implicit in PR workflow.\n- Do not add boilerplate sections that do not help review.\n\n1. Create the PR.\n\n- Save the body to a temporary file and run:\n\n```bash\ngh pr create --base main --head --title \"\" --body-file <file>\n```\n\n- If `gh pr create` fails, leave the branch pushed when possible and give the user a ready-to-open compare URL plus the prepared title/body details.\n\n## Body Template\n\nUse this as a base and fill with concrete repo-specific details:\n\n````md\n<One or two short intro paragraphs explaining the change and why it matters.>\n\n- <Feature/issue addressed>\n- <What changed in behavior or API>\n- <Why this is needed now>\n\n<Optional additional context paragraph(s), up to 3-4 total for large changes, including links to related PRs/issues.>\n\n```ts\n// New feature usage example\n```\n\n```ts\n// Before\n```\n\n```ts\n// After\n```\n````\n" }, { "path": ".agents/skills/make-pr/agents/openai.yaml", "content": "interface:\n display_name: 'Make PR'\n short_description: 'Create high-quality GitHub pull requests'\n default_prompt: 'Use $make-pr to draft and create a GitHub pull request with clear context and examples.'\n" }, { "path": ".agents/skills/publish-placeholder-package/SKILL.md", "content": "---\nname: publish-placeholder-package\ndescription: Publish a placeholder npm package at version 0.0.0 so package names are reserved and npm OIDC permissions can be configured before CI publishing. Use when creating a brand-new package that is not ready for full release.\n---\n\n# Publish Placeholder Package\n\n## Overview\n\nUse this skill to publish a minimal placeholder package to npm at `0.0.0`.\nThis is used to reserve the package name and unblock npm-side OIDC configuration for CI publishing.\n\n## Workflow\n\n1. Confirm publish target.\n\n- Collect:\n - npm package name (for example, `@remix-run/my-package`)\n - package directory in repo (for example, `packages/my-package`)\n- Validate the package does not already exist at `0.0.0`:\n\n```sh\nnpm view <package-name>@0.0.0 version\n```\n\n- If it already exists, stop and report that no placeholder publish is needed.\n\n2. Build a temporary placeholder package outside the repo.\n\n- Always publish from a temp directory to avoid shipping real package files by mistake.\n- Create the temp directory and write a minimal `package.json`:\n\n```sh\ntmp_dir=\"$(mktemp -d)\"\ncd \"$tmp_dir\"\n\ncat > package.json <<'JSON'\n{\n \"name\": \"<package-name>\",\n \"version\": \"0.0.0\",\n \"description\": \"Placeholder package for Remix CI/OIDC setup\",\n \"license\": \"MIT\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/remix-run/remix.git\",\n \"directory\": \"<repo-package-dir>\"\n },\n \"publishConfig\": {\n \"access\": \"public\"\n }\n}\nJSON\n```\n\n- Add a short README:\n\n```sh\ncat > README.md <<'MD'\n# Placeholder Package\n\nThis package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.\nMD\n```\n\n3. Ensure npm auth is valid (expect re-auth/OTP).\n\n- Check session:\n\n```sh\nnpm whoami\n```\n\n- If not authenticated, run:\n\n```sh\nnpm login\n```\n\n- Expect npm to require a fresh login and/or one-time password. If prompted for OTP, request it from the user and continue.\n\n4. Publish the placeholder.\n\n- Publish with public access:\n\n```sh\nnpm publish --access public\n```\n\n- If the account enforces 2FA for writes, publish with OTP:\n\n```sh\nnpm publish --access public --otp <code>\n```\n\n5. Verify and report.\n\n- Verify the published version:\n\n```sh\nnpm view <package-name>@0.0.0 version\n```\n\n- Report:\n - package name\n - published version (`0.0.0`)\n - confirmation that npm package exists for OIDC permission setup\n\n6. Clean up temp files.\n\n```sh\nrm -rf \"$tmp_dir\"\n```\n\n## Notes\n\n- Keep placeholder publish minimal. Do not publish full source code for this step.\n- This is a one-time bootstrap step. Normal releases should continue through CI.\n" }, { "path": ".agents/skills/publish-placeholder-package/agents/openai.yaml", "content": "interface:\n display_name: 'Publish Placeholder Package'\n short_description: 'Publish npm placeholder package at 0.0.0'\n default_prompt: 'Use $publish-placeholder-package to publish a minimal npm placeholder package at 0.0.0 so we can configure npm OIDC permissions for CI publishing.'\n" }, { "path": ".agents/skills/supersede-pr/SKILL.md", "content": "---\nname: supersede-pr\ndescription: Safely replace one GitHub pull request with another. Use when a user says a PR supersedes/replaces an older PR, asks to auto-close a superseded PR, or needs guaranteed closure behavior after merge. This skill explicitly closes the superseded PR with gh CLI and verifies final PR states instead of relying on closing keywords.\n---\n\n# Supersede PR\n\n## Overview\n\nUse this skill to handle PR supersession end-to-end.\nDo not rely on `Closes #<number>` to close another PR. GitHub closing keywords close issues, not pull requests.\n\n## Workflow\n\n1. Identify PR numbers and target repo.\n\n- Capture `old_pr` (the superseded PR) and `new_pr` (the replacement PR).\n- Resolve the repo with `gh repo view --json nameWithOwner -q .nameWithOwner` when not provided.\n\n1. Create or update the replacement PR first.\n\n- Open/push the replacement branch.\n- Open the new PR.\n- Include a traceable link in the PR body such as `Supersedes #<old_pr>`.\n\n1. Close the superseded PR explicitly.\n\n- Run:\n\n```bash\nscripts/close_superseded_pr.ts <old_pr> <new_pr>\n```\n\n- This adds a comment (`Superseded by #<new_pr>.`) and closes the old PR.\n\n1. Verify states.\n\n- Confirm the superseded PR is closed:\n\n```bash\ngh pr view <old_pr> --json state,url\n```\n\n- Confirm the replacement PR status/checks:\n\n```bash\ngh pr checks <new_pr>\n```\n\n## Rules\n\n1. Do not use `Closes #<old_pr>` when `<old_pr>` is a pull request.\n\n- Use `Closes/Fixes` only for issues.\n- Use `Supersedes #<old_pr>` or `Refs #<old_pr>` for PR-to-PR linkage.\n\n1. Prefer explicit closure over implied automation.\n\n- Always run the close command when the user asks to supersede a PR.\n- Treat closure as incomplete until `gh pr view <old_pr>` returns `CLOSED`.\n\n## Script\n\nUse the bundled script for deterministic closure:\n\n- `scripts/close_superseded_pr.ts`\n" }, { "path": ".agents/skills/supersede-pr/agents/openai.yaml", "content": "interface:\n display_name: 'Supersede PR'\n short_description: 'Close superseded pull requests safely'\n default_prompt: 'Use $supersede-pr to replace a PR and close the superseded PR safely.'\n" }, { "path": ".agents/skills/supersede-pr/scripts/close_superseded_pr.ts", "content": "#!/usr/bin/env node\nimport { spawnSync } from 'node:child_process'\nimport * as process from 'node:process'\n\ntype ParsedArgs = {\n dryRun: boolean\n newPr: string\n oldPr: string\n repo: string | null\n}\n\nfunction main(): void {\n let parsed = parseArgs(process.argv.slice(2))\n ensureNumericPrNumber(parsed.oldPr, 'old_pr')\n ensureNumericPrNumber(parsed.newPr, 'new_pr')\n\n if (parsed.oldPr === parsed.newPr) {\n fail('old_pr and new_pr must be different.')\n }\n\n let repo =\n parsed.repo ?? ghCapture(['repo', 'view', '--json', 'nameWithOwner', '-q', '.nameWithOwner'])\n let oldState = ghCapture([\n 'pr',\n 'view',\n parsed.oldPr,\n '--repo',\n repo,\n '--json',\n 'state',\n '-q',\n '.state',\n ])\n let newState = ghCapture([\n 'pr',\n 'view',\n parsed.newPr,\n '--repo',\n repo,\n '--json',\n 'state',\n '-q',\n '.state',\n ])\n\n if (newState !== 'OPEN' && newState !== 'MERGED') {\n fail(`Replacement PR #${parsed.newPr} is in state '${newState}'. Expected OPEN or MERGED.`)\n }\n\n if (oldState !== 'OPEN') {\n process.stdout.write(`Superseded PR #${parsed.oldPr} is already ${oldState}. Nothing to do.\\n`)\n return\n }\n\n let comment = `Superseded by #${parsed.newPr}.`\n\n process.stdout.write(`Repo: ${repo}\\n`)\n process.stdout.write(`Closing PR #${parsed.oldPr} with comment: ${comment}\\n`)\n\n if (parsed.dryRun) {\n process.stdout.write(\n `[dry-run] gh pr close \"${parsed.oldPr}\" --repo \"${repo}\" --comment \"${comment}\"\\n`,\n )\n return\n }\n\n ghInherit(['pr', 'close', parsed.oldPr, '--repo', repo, '--comment', comment])\n\n let finalState = ghCapture([\n 'pr',\n 'view',\n parsed.oldPr,\n '--repo',\n repo,\n '--json',\n 'state',\n '-q',\n '.state',\n ])\n if (finalState !== 'CLOSED') {\n fail(`Failed to close PR #${parsed.oldPr}. Final state: ${finalState}`)\n }\n\n process.stdout.write(`Closed PR #${parsed.oldPr} successfully.\\n`)\n}\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n if (argv.includes('-h') || argv.includes('--help')) {\n printUsage()\n process.exit(0)\n }\n\n if (argv.length < 2) {\n printUsage()\n process.exit(1)\n }\n\n let oldPr = argv[0]\n let newPr = argv[1]\n let repo: string | null = null\n let dryRun = false\n let index = 2\n\n while (index < argv.length) {\n let arg = argv[index]\n if (arg === '--repo') {\n let next = argv[index + 1]\n if (!next) {\n fail('--repo requires a value like owner/repo')\n }\n repo = next\n index += 2\n continue\n }\n if (arg === '--dry-run') {\n dryRun = true\n index++\n continue\n }\n fail(`Unknown argument: ${arg}`)\n }\n\n return { dryRun, newPr, oldPr, repo }\n}\n\nfunction printUsage(): void {\n process.stdout.write(`Usage:\n close_superseded_pr.ts <old_pr> <new_pr> [--repo <owner/repo>] [--dry-run]\n\nExamples:\n close_superseded_pr.ts 11085 11087\n close_superseded_pr.ts 11085 11087 --repo remix-run/remix\n close_superseded_pr.ts 11085 11087 --dry-run\n`)\n}\n\nfunction ensureNumericPrNumber(value: string, label: string): void {\n if (!/^[0-9]+$/.test(value)) {\n fail(`${label} must be a numeric pull request number.`)\n }\n}\n\nfunction ghCapture(args: string[]): string {\n let result = spawnSync('gh', args, { encoding: 'utf8' })\n if (result.status !== 0) {\n let stderr = (result.stderr ?? '').trim()\n let details = stderr ? `\\n${stderr}` : ''\n fail(`gh ${args.join(' ')} failed.${details}`)\n }\n return (result.stdout ?? '').trim()\n}\n\nfunction ghInherit(args: string[]): void {\n let result = spawnSync('gh', args, { stdio: 'inherit' })\n if (result.status !== 0) {\n fail(`gh ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}.`)\n }\n}\n\nfunction fail(message: string): never {\n process.stderr.write(`${message}\\n`)\n process.exit(1)\n}\n\nmain()\n" }, { "path": ".agents/skills/supersede-pr/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"allowJs\": false,\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"noEmit\": true,\n \"strict\": true,\n \"target\": \"ESNext\",\n \"verbatimModuleSyntax\": true\n },\n \"include\": [\"scripts/**/*.ts\"]\n}\n" }, { "path": ".agents/skills/update-pr/SKILL.md", "content": "---\nname: update-pr\ndescription: Update an existing GitHub pull request title and description so they accurately describe the pull request as it exists now. Use when the user asks to update, rewrite, refresh, fix, or tighten a PR title/body, or when the PR scope has changed and the metadata needs to be brought back in sync.\n---\n\n# Update PR\n\n## Overview\n\nRewrite pull request metadata as if drafting it from scratch for the current diff. Treat the title and body as a current reviewer-facing summary of the PR, not as commentary about prior versions of the PR.\n\n## Workflow\n\n1. Read the current PR title/body and the current branch diff before drafting.\n2. Identify the PR's current scope, APIs, behavior changes, and reviewer-relevant context.\n3. Rewrite the body from scratch so it describes the PR as it exists now.\n4. Review the title at the same time and update it whenever the body is updated.\n5. Apply the update with `gh pr edit`.\n\n## Rules\n\n- Never write the description as an update to itself. Do not say things like \"this expands the original PR\", \"this PR now also\", or similar process narration unless the user explicitly wants history called out.\n- Always evaluate the title when updating a PR. If the scope or emphasis changed, rewrite the title too.\n- Write in terms of the present PR contents, using concise reviewer-facing language.\n- Keep the structure minimal: one short introductory paragraph plus flat bullets is usually enough.\n- Include usage examples when the PR introduces or materially changes a feature API.\n- Preserve still-relevant issue links or context, but drop stale framing.\n\n## Applying The Update\n\n- Draft the new title and body in a temporary file.\n- Use `gh pr edit <number> --title \"<title>\" --body-file <file>`.\n- Re-read the PR after editing to confirm the final title/body match the intended framing.\n" }, { "path": ".agents/skills/update-pr/agents/openai.yaml", "content": "interface:\n display_name: 'Update PR'\n short_description: 'Refresh an existing pull request title and body.'\n default_prompt: 'Use $update-pr to rewrite this pull request title and description so they accurately describe the PR as it exists now.'\n" }, { "path": ".agents/skills/write-api-docs/SKILL.md", "content": "---\nname: write-api-docs\ndescription: Write or audit public API docs for Remix packages. Use when adding or tightening JSDoc on exported functions, classes, interfaces, type aliases, or option objects.\n---\n\n# Write API Docs\n\n## Overview\n\nUse this skill when documenting public APIs in Remix packages.\n\nThe goal is to document the API users can actually import, not every helper in `src/lib`.\nWork from the package exports outward, add concise JSDoc to the public declarations, and make sure the result passes the repo's ESLint JSDoc rules.\n\n## Workflow\n\n1. Identify the package's public exports.\n2. Find the `src` entry files that back those exports.\n3. Trace those entry files to the declarations they re-export from `src/lib`.\n4. Add or tighten JSDoc on the public declarations only.\n5. Run package typecheck if appropriate and always run `pnpm run lint`.\n\n## How To Identify Public API\n\nThe source of truth is the package's `package.json`.\n\n- Start with `package.json` `exports`.\n- Each public export should map to a file directly under `src/`.\n- Those `src/*.ts` entry files define the public surface by re-exporting symbols from `src/lib`.\n- A declaration in `src/lib` is public only if it is re-exported by one of those public `src/*.ts` entry files.\n\nRules:\n\n- Do not assume everything in `src/lib` is public.\n- Do not document private helpers just because they are exported within `src/lib`.\n- If a declaration is not reachable from a package export, it is internal unless the user explicitly asks otherwise.\n\n## What To Document\n\nFor public API, add JSDoc to:\n\n- exported functions\n- exported classes\n- exported interfaces\n- exported type aliases\n- exported public constants when they are part of the API shape\n\nFor public interfaces:\n\n- add a JSDoc block on the interface itself\n- add a property-level JSDoc block for every property on the interface, even when the name seems obvious\n\nFor public object-shaped type aliases:\n\n- prefer an `interface` when you are introducing a new public object shape\n- if an existing public type alias cannot reasonably become an interface, document the object shape as thoroughly as the syntax allows\n\nFor overloads:\n\n- document the public overload signatures or the exported declaration in a way that makes the callable surface clear to users\n\n## JSDoc Style For This Repo\n\nKeep comments short, factual, and user-facing.\n\n- Describe what the API does, not how the implementation works internally.\n- Prefer one concise summary sentence, then short `@param` / `@returns` docs as needed.\n- Do not put TypeScript types in JSDoc tags. ESLint forbids JSDoc type syntax here because the source of truth is the TypeScript signature.\n- Keep parameter names in JSDoc exactly aligned with the function signature.\n- Use `@returns` for non-void functions and include a real description.\n- For `@param`, include descriptions and do not add a hyphen before the description.\n- Specify `@param` default values in parenthesis at the end of the comment, do not use `@default` tags\n- Include an `@example` code block when it helps to show a use-case or pattern. Skip `@example` for simple getters, trivial constructors, or APIs whose usage is self-evident.\n- Use `{@link API}` to link to related Remix APIs when it adds value. Don't link every related API — use discretion to avoid noise.\n- Use backticks for all other unlinked code references — identifiers, HTTP methods, special values.\n\nGood:\n\n```ts\n/**\n * Creates an {@link AuthProvider} for direct credentials-based authentication.\n *\n * @param options Parsing and verification hooks for submitted credentials.\n * @returns A provider that can be passed to `login()`.\n */\nexport function createCredentialsAuthProvider(...) {}\n```\n\nAvoid:\n\n```ts\n/**\n * @param {CredentialsOptions} options - options\n * @returns {CredentialsProvider}\n */\n```\n\n## ESLint Expectations\n\nThe relevant rules live in [`eslint.config.js`](../../eslint.config.js).\n\nFor `packages/**/*.{ts,tsx}` (excluding tests), ESLint enforces JSDoc on callable declarations such as:\n\n- function declarations\n- function expressions\n- arrow functions\n- class declarations\n- public methods\n\nImportant enforced details:\n\n- `jsdoc/require-param`\n- `jsdoc/require-param-name`\n- `jsdoc/require-param-description`\n- `jsdoc/require-returns`\n- `jsdoc/require-returns-description`\n- `jsdoc/no-types`\n- `jsdoc/check-param-names`\n- `jsdoc/check-types`\n- `jsdoc/check-alignment`\n\nPractical implication:\n\n- if a public function takes parameters, document all of them\n- if a public function returns a value, document the return value\n- do not use JSDoc type annotations\n- keep the block formatted cleanly enough to satisfy alignment checks\n\n## Review Checklist\n\n- Did you start from `package.json` exports instead of guessing from `src/lib`?\n- Are all documented declarations actually reachable from a public `src/*.ts` entry file?\n- Do all public functions and methods have JSDoc with `@param` and `@returns` where required?\n- Do public interfaces and type aliases have a concise doc block explaining what they represent?\n- Does every property on every public interface have its own property-level JSDoc block?\n- Did you avoid documenting internal helpers that are not exported publicly?\n- Did `pnpm run lint` pass?\n" }, { "path": ".agents/skills/write-readme/SKILL.md", "content": "---\nname: write-readme\ndescription: Write or rewrite package README files in the style used by the Remix repository. Use when drafting a new package README, revising an existing README, or reviewing README structure, examples, installation instructions, and section ordering for Remix packages.\n---\n\n# Write Readme\n\n## Overview\n\nDraft README files as concise package documentation for real users, not as marketing copy or API dumps. Mirror the structure used across this repository, keep examples production-oriented, and avoid awkward manual line breaks in prose.\n\n## Workflow\n\n1. Read the package API and at least one or two sibling package READMEs before drafting.\n2. Document the package as it exists today, not the package you wish existed.\n3. Start with a realistic production usage example as soon as the installation section is done.\n4. Cover each major feature with a concrete example.\n5. Finish with internal ecosystem links, external related work, and license info.\n\n## Structure\n\nUse this section order unless there is a strong package-specific reason not to:\n\n1. `# short package-name` (i.e. `fetch-router` instead of `@remix-run/fetch-router`)\n2. Intro: one or two sentences explaining what the package does and why it exists\n3. `## Features`: a flat bullet list of the main highlights\n4. `## Installation`\n5. `## Usage`: a production-like example that shows the package in context\n6. One section per major feature, each with focused examples\n7. `## Related Packages`\n8. `## Related Work`\n9. `## License`\n\n## Rules\n\n- Installation should always start with:\n\n```sh\nnpm i remix\n```\n\n- If the package requires a third-party dependency or peer, include it explicitly in the installation section after `remix`.\n- Usage examples should import from `remix/...`, not `@remix-run/...`.\n- The first example should look like real application code, not the smallest possible snippet.\n- Feature sections should show how to use the package's major capabilities in practice, with one example per capability when useful.\n- Keep prose compact. Do not hard-wrap paragraphs at awkward places in the middle of a sentence just to force a line length.\n- Prefer flat bullets and short paragraphs over long explanatory blocks.\n- `Related Packages` should point to relevant Remix packages in the monorepo.\n- `Related Work` should point to external libraries, specs, standards, or prior art that help readers place the package.\n- `License` should use the standard repo wording and link.\n\n## Checklist\n\n- Does the intro explain the package in one or two sentences?\n- Does the features list surface the package's main value quickly?\n- Does the installation section use `npm i remix`?\n- Does the main usage example show a realistic production scenario?\n- Does each major feature have an example?\n- Does the README end with `Related Packages`, `Related Work`, and `License`?\n- Does the prose read naturally without awkward manual line breaks?\n" }, { "path": ".agents/skills/write-readme/agents/openai.yaml", "content": "interface:\n display_name: 'Write Readme'\n short_description: 'Write Remix package READMEs in the repo style.'\n default_prompt: 'Use $write-readme to draft or rewrite this package README in the style used by the Remix repository.'\n" }, { "path": ".github/workflows/build.yaml", "content": "name: Build\n\non:\n push:\n branches:\n - main\n pull_request:\n branches-ignore:\n - release-v2\n - v2\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n build:\n strategy:\n matrix:\n os: [ubuntu-latest, windows-latest]\n\n runs-on: ${{ matrix.os }}\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Build packages\n run: pnpm build\n" }, { "path": ".github/workflows/check.yaml", "content": "name: Type check, lint, validate change files\n\non:\n push:\n branches:\n - main\n pull_request:\n branches-ignore:\n - release-v2\n - v2\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n lint:\n name: Lint\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - uses: pnpm/action-setup@v4\n name: Install pnpm\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Lint\n run: pnpm lint\n\n typecheck:\n name: Typecheck\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - uses: pnpm/action-setup@v4\n name: Install pnpm\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Typecheck\n run: pnpm typecheck\n\n change-files:\n name: Validate change files\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n\n - name: Check change files\n run: node ./scripts/changes-validate.ts\n" }, { "path": ".github/workflows/data-table-integration.yaml", "content": "name: Data Table Integration Tests\n\non:\n push:\n branches:\n - main\n paths:\n - '.github/workflows/data-table-integration.yaml'\n - 'packages/data-table/**'\n - 'packages/data-table-postgres/**'\n - 'packages/data-table-mysql/**'\n - 'packages/data-table-sqlite/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n pull_request:\n paths:\n - '.github/workflows/data-table-integration.yaml'\n - 'packages/data-table/**'\n - 'packages/data-table-postgres/**'\n - 'packages/data-table-mysql/**'\n - 'packages/data-table-sqlite/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n\njobs:\n unit:\n name: Unit and Build\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run data-table package checks\n run: |\n pnpm --filter @remix-run/data-table run typecheck\n pnpm --filter @remix-run/data-table run test\n pnpm --filter @remix-run/data-table run test:coverage\n pnpm --filter @remix-run/data-table run build\n pnpm --filter @remix-run/data-table-postgres run typecheck\n pnpm --filter @remix-run/data-table-postgres run test\n pnpm --filter @remix-run/data-table-postgres run test:coverage\n pnpm --filter @remix-run/data-table-postgres run build\n pnpm --filter @remix-run/data-table-mysql run typecheck\n pnpm --filter @remix-run/data-table-mysql run test\n pnpm --filter @remix-run/data-table-mysql run test:coverage\n pnpm --filter @remix-run/data-table-mysql run build\n pnpm --filter @remix-run/data-table-sqlite run typecheck\n pnpm --filter @remix-run/data-table-sqlite run test\n pnpm --filter @remix-run/data-table-sqlite run test:coverage\n pnpm --filter @remix-run/data-table-sqlite run build\n\n postgres-integration:\n name: Postgres Integration\n runs-on: ubuntu-latest\n\n services:\n postgres:\n image: postgres:16\n env:\n POSTGRES_USER: postgres\n POSTGRES_PASSWORD: postgres\n POSTGRES_DB: remix\n ports:\n - 5432:5432\n options: >-\n --health-cmd=\"pg_isready -U postgres\"\n --health-interval=10s\n --health-timeout=5s\n --health-retries=5\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run postgres integration tests\n env:\n DATA_TABLE_INTEGRATION: '1'\n DATA_TABLE_POSTGRES_URL: postgres://postgres:postgres@127.0.0.1:5432/remix\n run: node --disable-warning=ExperimentalWarning --test './packages/data-table-postgres/src/lib/adapter.integration.test.ts'\n\n mysql-integration:\n name: MySQL Integration\n runs-on: ubuntu-latest\n\n services:\n mysql:\n image: mysql:8\n env:\n MYSQL_ROOT_PASSWORD: root\n MYSQL_DATABASE: remix\n ports:\n - 3306:3306\n options: >-\n --health-cmd=\"mysqladmin ping -h 127.0.0.1 -uroot -proot\"\n --health-interval=10s\n --health-timeout=5s\n --health-retries=10\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run mysql integration tests\n env:\n DATA_TABLE_INTEGRATION: '1'\n DATA_TABLE_MYSQL_URL: mysql://root:root@127.0.0.1:3306/remix\n run: node --disable-warning=ExperimentalWarning --test './packages/data-table-mysql/src/lib/adapter.integration.test.ts'\n\n sqlite-integration:\n name: SQLite Integration\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Build sqlite native module\n run: pnpm rebuild better-sqlite3\n\n - name: Run sqlite adapter tests\n env:\n DATA_TABLE_INTEGRATION: '1'\n run: node --disable-warning=ExperimentalWarning --test './packages/data-table-sqlite/src/lib/adapter.integration.test.ts'\n" }, { "path": ".github/workflows/file-storage-integration.yaml", "content": "name: File Storage Integration Tests\n\non:\n push:\n branches:\n - main\n paths:\n - '.github/workflows/file-storage-integration.yaml'\n - 'packages/file-storage/**'\n - 'packages/file-storage-s3/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n pull_request:\n paths:\n - '.github/workflows/file-storage-integration.yaml'\n - 'packages/file-storage/**'\n - 'packages/file-storage-s3/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n\njobs:\n unit:\n name: Unit and Build\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run file-storage-s3 package checks\n run: |\n pnpm --filter @remix-run/file-storage-s3 run typecheck\n pnpm --filter @remix-run/file-storage-s3 run test\n pnpm --filter @remix-run/file-storage-s3 run build\n\n s3-integration:\n name: S3 Integration\n runs-on: ubuntu-latest\n\n services:\n localstack:\n image: localstack/localstack:4.4.0\n env:\n SERVICES: s3\n AWS_ACCESS_KEY_ID: test\n AWS_SECRET_ACCESS_KEY: test\n DEFAULT_REGION: us-east-1\n ports:\n - 4566:4566\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Wait for LocalStack\n run: |\n for i in {1..60}; do\n if curl -fsS http://127.0.0.1:4566/_localstack/health > /dev/null; then\n exit 0\n fi\n sleep 1\n done\n echo \"LocalStack did not become ready in time\"\n exit 1\n\n - name: Run S3 integration tests\n env:\n FILE_STORAGE_S3_INTEGRATION: '1'\n FILE_STORAGE_S3_ENDPOINT: http://127.0.0.1:4566\n FILE_STORAGE_S3_BUCKET: remix-file-storage-integration\n FILE_STORAGE_S3_REGION: us-east-1\n FILE_STORAGE_S3_ACCESS_KEY_ID: test\n FILE_STORAGE_S3_SECRET_ACCESS_KEY: test\n FILE_STORAGE_S3_FORCE_PATH_STYLE: '1'\n run: node --disable-warning=ExperimentalWarning --test './packages/file-storage-s3/src/lib/s3.integration.test.ts'\n" }, { "path": ".github/workflows/format.yml", "content": "name: Format\n\non:\n push:\n branches:\n - main\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n format:\n if: \"${{ github.repository == 'remix-run/remix' && !startsWith(github.event.head_commit.message, 'chore: format') }}\"\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n token: ${{ secrets.FORMAT_PAT }}\n fetch-depth: 0\n\n - name: Detect formatting-relevant changes\n id: changes\n run: |\n base=\"${{ github.event.before }}\"\n\n if [ \"$base\" = \"0000000000000000000000000000000000000000\" ]; then\n files=\"$(git ls-files)\"\n else\n files=\"$(git diff --name-only \"$base\" \"$GITHUB_SHA\")\"\n fi\n\n if [ -z \"$files\" ]; then\n echo \"No changed files detected\"\n echo \"should_run=false\" >> \"$GITHUB_OUTPUT\"\n exit 0\n fi\n\n while IFS= read -r file; do\n case \"$file\" in\n .prettierignore|.prettierrc|.prettierrc.json|.prettierrc.yml|.prettierrc.yaml|.prettierrc.js|.prettierrc.cjs|.prettierrc.mjs|*.js|*.jsx|*.cjs|*.mjs|*.ts|*.tsx|*.cts|*.mts|*.json|*.jsonc|*.md|*.mdx|*.yaml|*.yml|*.css|*.scss|*.html)\n echo \"Formatting-relevant change: $file\"\n echo \"should_run=true\" >> \"$GITHUB_OUTPUT\"\n exit 0\n ;;\n esac\n done <<EOF\n $files\n EOF\n\n echo \"No formatting-relevant files changed\"\n echo \"should_run=false\" >> \"$GITHUB_OUTPUT\"\n\n - name: Install pnpm\n if: steps.changes.outputs.should_run == 'true'\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n if: steps.changes.outputs.should_run == 'true'\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n if: steps.changes.outputs.should_run == 'true'\n run: pnpm install --frozen-lockfile\n\n - name: Format\n if: steps.changes.outputs.should_run == 'true'\n run: pnpm format\n\n - name: Commit\n if: steps.changes.outputs.should_run == 'true'\n run: |\n git config --local user.email \"hello@remix.run\"\n git config --local user.name \"Remix Run Bot\"\n\n git add .\n git restore .github/workflows # PAT doesn't have permission to push workflow changes\n if [ -z \"$(git status --porcelain)\" ]; then\n echo \"No formatting changes\"\n exit 0\n fi\n git commit -m \"chore: format\"\n git push\n echo \"Pushed formatting changes https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n" }, { "path": ".github/workflows/generate-remix.yaml", "content": "# Update the `remix` package by auto-generating from the `@remix-run/*` packages in the repo\n# runs on any pushes/PRs to `main` that touch any `package.json` files since that would\n# potentially alter the sub-exports that need to be reflected in the `remix` package.\n\n# Note: Does not currently run on PRs from forked repos.\n\nname: Update Remix package\n\non:\n push:\n branches:\n - 'main'\n paths:\n - 'packages/**/package.json'\n pull_request:\n branches-ignore:\n - release-v2\n - v2\n paths:\n - 'packages/**/package.json'\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n generate-remix:\n if: |\n github.repository == 'remix-run/remix' &&\n (\n github.event_name == 'push' ||\n github.event.pull_request.head.repo.full_name == github.repository\n )\n runs-on: ubuntu-latest\n steps:\n # Normal checkout of the trigger branch on pushes\n - name: Checkout\n if: github.event_name == 'push'\n uses: actions/checkout@v4\n with:\n # Use a PAT because using the default `GITHUB_TOKEN`/`github.token` will not\n # trigger workflow runs, so use a PAT to ensure new commits will run CI checks.\n # See: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow\n token: ${{ secrets.GH_REMIX_PAT }}\n\n # Checkout the PR branch when running on PRs\n - name: Checkout\n if: github.event_name == 'pull_request'\n uses: actions/checkout@v4\n with:\n ref: ${{ github.event.pull_request.head.ref }}\n # Use a PAT because using the default `GITHUB_TOKEN`/`github.token` will not\n # trigger workflow runs, so use a PAT to ensure new commits will run CI checks.\n # See: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow#triggering-a-workflow-from-a-workflow\n token: ${{ secrets.GH_REMIX_PAT }}\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Generate remix package\n run: pnpm run generate-remix\n\n - name: Commit and push changes\n id: commit\n run: |\n if [ -z \"$(git status --porcelain)\" ]; then\n echo \"💿 no updates to the remix package needed\"\n exit 0\n fi\n\n # Check for unintentional changes\n OUTSIDE_CHANGES=$(git status --porcelain | awk '{print $2}' | grep -v \"^packages/remix/\" || true)\n if [ -n \"$OUTSIDE_CHANGES\" ]; then\n echo \"Refusing to commit changes outside of packages/remix/:\"\n echo \"$OUTSIDE_CHANGES\"\n exit 1\n fi\n\n # Re-install to ensure any new remix peerDependencies are reflected\n pnpm install --no-frozen-lockfile\n\n git config --local user.email \"hello@remix.run\"\n git config --local user.name \"Remix Run Bot\"\n git add .\n git commit -a -m \"build: update remix package\"\n git push\n echo \"💿 pushed updates: https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n echo \"new_sha=$(git rev-parse --short HEAD)\" >> $GITHUB_OUTPUT\n\n - name: Comment on PR\n if: github.event_name == 'pull_request' && steps.commit.outputs.new_sha != ''\n env:\n # `GH_TOKEN` is required to use the `gh` CLI to add comments to PRs.\n GH_TOKEN: ${{ secrets.GH_REMIX_PAT }}\n run: gh pr comment ${{ github.event.pull_request.number }} --body \"Changes in this PR resulted in updates to the auto-generated \\`remix\\` package in ${{ steps.commit.outputs.new_sha }}. Please review those changes prior to merging.\"\n" }, { "path": ".github/workflows/preview.yml", "content": "# Create \"installable\" preview branches\n#\n# Commits to `main` push builds to a `preview/main` branch:\n# pnpm install \"remix-run/remix#preview/main&path:packages/remix\"\n#\n# Pull Requests create `preview/pr-{number}` branches:\n# pnpm install \"remix-run/remix#preview/pr-12345&path:packages/remix\"\n#\n# Can also be dispatched manually with base/installable branches to provide\n# `experimental` branches from PRs or otherwise.\n\nname: Preview Build\n\non:\n push:\n branches:\n - main\n workflow_dispatch:\n inputs:\n baseBranch:\n description: Base Branch\n required: true\n installableBranch:\n description: Installable Branch\n required: true\n pull_request:\n types: [opened, synchronize, reopened, closed]\n\nconcurrency:\n # Include `event_name` here because when a pull_request is merged (closed), the\n # `github.ref` goes back to `ref/heads/main` which will conflict with the run on\n # `main` from the merged PR\n group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n preview:\n # Don't run on PRs from forked repos\n if: github.repository == 'remix-run/remix' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)\n runs-on: ubuntu-latest\n steps:\n - name: Checkout (push)\n if: github.event_name == 'push'\n uses: actions/checkout@v4\n\n - name: Checkout (pull_request)\n if: github.event_name == 'pull_request'\n uses: actions/checkout@v4\n with:\n ref: ${{ github.event.pull_request.head.sha }}\n\n - name: Checkout (workflow_dispatch)\n if: github.event_name == 'workflow_dispatch'\n uses: actions/checkout@v4\n with:\n ref: ${{ inputs.baseBranch }}\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Setup git\n run: |\n git config --local user.email \"hello@remix.run\"\n git config --local user.name \"Remix Run Bot\"\n\n # Build and force push over the preview/main branch\n - name: Build/push branch (push)\n if: github.event_name == 'push'\n run: |\n pnpm run setup-installable-branch preview/main\n git push --force --set-upstream origin preview/main\n echo \"💿 pushed installable branch: https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n\n # Build and force push over the PR preview/pr-{number} branch + comment on the PR\n - name: Build/push branch (pull_request)\n if: github.event_name == 'pull_request' && github.event.pull_request.state == 'open'\n env:\n GITHUB_TOKEN: ${{ github.token }}\n run: |\n pnpm run setup-installable-branch preview/pr-${{ github.event.pull_request.number }}\n git push --force --set-upstream origin preview/pr-${{ github.event.pull_request.number }}\n echo \"pushed installable branch: https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n pnpm run pr-preview comment ${{ github.event.pull_request.number }} preview/pr-${{ github.event.pull_request.number }}\n\n # Build and normal push for experimental releases to avoid unintended force\n # pushes over remote branches in case of a branch name collision\n - name: Build/push branch (workflow_dispatch)\n if: github.event_name == 'workflow_dispatch'\n run: |\n pnpm run setup-installable-branch ${{ inputs.installableBranch }}\n git push --set-upstream origin ${{ inputs.installableBranch }}\n echo \"💿 pushed installable branch: https://github.com/$GITHUB_REPOSITORY/commit/$(git rev-parse HEAD)\"\n\n # Cleanup PR preview/pr-{number} branches when the PR is closed\n - name: Cleanup preview branch\n if: github.event_name == 'pull_request' && github.event.pull_request.state == 'closed'\n env:\n GITHUB_TOKEN: ${{ github.token }}\n run: |\n pnpm run pr-preview cleanup ${{ github.event.pull_request.number }} preview/pr-${{ github.event.pull_request.number }}\n" }, { "path": ".github/workflows/publish.yaml", "content": "name: Publish\n\non:\n push:\n branches:\n - main\n\nconcurrency: ${{ github.workflow }}-${{ github.ref }}\n\njobs:\n check:\n name: Check release readiness\n runs-on: ubuntu-latest\n outputs:\n has_change_files: ${{ steps.check.outputs.has_change_files }}\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Check for change files\n id: check\n run: |\n # Look for change files in any package's .changes directory (excluding README.md)\n change_files=$(find packages/*/.changes -name \"*.md\" ! -name \"README.md\" 2>/dev/null)\n if [ -n \"$change_files\" ]; then\n echo \"Change files found (blocking publish):\"\n echo \"$change_files\"\n echo \"has_change_files=true\" >> $GITHUB_OUTPUT\n else\n echo \"No change files found, proceeding to publish.\"\n echo \"has_change_files=false\" >> $GITHUB_OUTPUT\n fi\n\n publish:\n name: Publish any unreleased packages\n needs: check\n if: needs.check.outputs.has_change_files == 'false'\n runs-on: ubuntu-latest\n\n permissions:\n contents: write # Required for creating tags and GitHub releases\n id-token: write # OIDC ID token is used for authentication with npm/jsr\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Get Playwright Version\n id: playwright-version\n run: echo \"version=$(pnpm --filter @remix-run/component exec playwright --version | cut -d ' ' -f2)\" >> $GITHUB_OUTPUT\n\n - name: Cache Playwright Browsers\n uses: actions/cache@v4\n id: cache-browsers\n with:\n path: ~/.cache/ms-playwright\n key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}\n\n - name: Install Playwright Browsers\n if: steps.cache-browsers.outputs.cache-hit != 'true'\n run: pnpm --filter @remix-run/component exec playwright install --with-deps\n\n - name: Run tests\n run: pnpm test\n\n - name: Build packages\n run: pnpm build\n\n - name: Publish to npm and create releases\n run: node ./scripts/publish.ts\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Output tag\n run: echo \"tag=$(git tag --points-at HEAD | grep -e '^remix@3')\" >> $GITHUB_OUTPUT\n\n docs:\n name: Update API Docs\n needs: publish\n runs-on: ubuntu-latest\n steps:\n - name: Trigger remix-api-docs\n uses: actions/github-script@v8\n with:\n github-token: ${{ secrets.REMIX_API_DOCS_PAT }}\n script: |\n await github.rest.repos.createDispatchEvent({\n owner: 'remix-run',\n repo: 'remix-api-docs',\n event_type: 'update-docs',\n client_payload: { tag: '${{ needs.publish.outputs.tag }}' }\n });\n" }, { "path": ".github/workflows/release-pr.yaml", "content": "name: Update \"Release\" PR\n\non:\n push:\n branches:\n - main\n\nconcurrency: ${{ github.workflow }}-${{ github.ref }}\n\njobs:\n update:\n runs-on: ubuntu-latest\n\n permissions:\n contents: write\n pull-requests: write\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n token: ${{ secrets.GH_REMIX_PAT }}\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Update PR\n run: node scripts/release-pr.ts\n env:\n GITHUB_TOKEN: ${{ secrets.GH_REMIX_PAT }}\n" }, { "path": ".github/workflows/session-integration.yaml", "content": "name: Session Integration Tests\n\non:\n push:\n branches:\n - main\n paths:\n - '.github/workflows/session-integration.yaml'\n - 'packages/session/**'\n - 'packages/session-storage-memcache/**'\n - 'packages/session-storage-redis/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n pull_request:\n paths:\n - '.github/workflows/session-integration.yaml'\n - 'packages/session/**'\n - 'packages/session-storage-memcache/**'\n - 'packages/session-storage-redis/**'\n - 'pnpm-workspace.yaml'\n - 'package.json'\n\njobs:\n memcache-integration:\n name: Memcache Integration\n runs-on: ubuntu-latest\n\n services:\n memcached:\n image: memcached:1.6\n ports:\n - 11211:11211\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run memcache integration tests\n env:\n SESSION_MEMCACHE_INTEGRATION: '1'\n SESSION_MEMCACHE_SERVER: 127.0.0.1:11211\n run: node --disable-warning=ExperimentalWarning --test './packages/session-storage-memcache/src/lib/memcache-storage.integration.test.ts'\n\n redis-integration:\n name: Redis Integration\n runs-on: ubuntu-latest\n\n services:\n redis:\n image: redis:7\n ports:\n - 6379:6379\n options: >-\n --health-cmd=\"redis-cli ping || exit 1\"\n --health-interval=10s\n --health-timeout=5s\n --health-retries=5\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Run redis integration tests\n env:\n SESSION_REDIS_INTEGRATION: '1'\n SESSION_REDIS_URL: redis://127.0.0.1:6379\n run: node --disable-warning=ExperimentalWarning --test './packages/session-storage-redis/src/lib/redis-storage.integration.test.ts'\n" }, { "path": ".github/workflows/test.yaml", "content": "name: Test\n\non:\n push:\n branches:\n - main\n pull_request:\n branches-ignore:\n - release-v2\n - v2\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.ref }}\n cancel-in-progress: true\n\njobs:\n test-ubuntu:\n name: test (ubuntu-latest)\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Get Playwright Version\n id: playwright-version\n shell: bash\n run: echo \"version=$(pnpm --filter @remix-run/component exec playwright --version | cut -d ' ' -f2)\" >> $GITHUB_OUTPUT\n\n - name: Cache Playwright Browsers\n uses: actions/cache@v4\n id: cache-browsers\n with:\n path: |\n ~/.cache/ms-playwright\n key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}\n\n - name: Install Playwright Browsers\n if: steps.cache-browsers.outputs.cache-hit != 'true'\n run: pnpm --filter @remix-run/component exec playwright install --with-deps\n\n - name: Run tests\n run: pnpm test\n\n test-windows-pr:\n name: test (windows-latest, changed packages)\n if: github.event_name == 'pull_request'\n runs-on: windows-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Get Playwright Version\n id: playwright-version\n shell: bash\n run: echo \"version=$(pnpm --filter @remix-run/component exec playwright --version | cut -d ' ' -f2)\" >> $GITHUB_OUTPUT\n\n - name: Cache Playwright Browsers\n uses: actions/cache@v4\n id: cache-browsers\n with:\n path: ~/AppData/Local/ms-playwright\n key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}\n\n - name: Install Playwright Browsers\n if: steps.cache-browsers.outputs.cache-hit != 'true'\n run: pnpm --filter @remix-run/component exec playwright install --with-deps\n\n - name: Run changed package tests\n run: node ./scripts/detect-changed-packages.ts origin/${{ github.base_ref }}\n\n test-windows-main:\n name: test (windows-latest)\n if: github.event_name == 'push'\n runs-on: windows-latest\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Install pnpm\n uses: pnpm/action-setup@v4\n\n - name: Install Node.js\n uses: actions/setup-node@v4\n with:\n node-version-file: 'package.json'\n cache: pnpm\n\n - name: Install dependencies\n run: pnpm install --frozen-lockfile\n\n - name: Get Playwright Version\n id: playwright-version\n shell: bash\n run: echo \"version=$(pnpm --filter @remix-run/component exec playwright --version | cut -d ' ' -f2)\" >> $GITHUB_OUTPUT\n\n - name: Cache Playwright Browsers\n uses: actions/cache@v4\n id: cache-browsers\n with:\n path: ~/AppData/Local/ms-playwright\n key: playwright-${{ runner.os }}-${{ steps.playwright-version.outputs.version }}\n\n - name: Install Playwright Browsers\n if: steps.cache-browsers.outputs.cache-hit != 'true'\n run: pnpm --filter @remix-run/component exec playwright install --with-deps\n\n - name: Run tests\n run: pnpm test\n" }, { "path": ".gitignore", "content": "dist/\nnode_modules/\npnpm-publish-summary.json\nreference/\n.tmp/\n/demos/tmp/\n*.db\n*.db-*\n*.sqlite\n*.sqlite-*\n*.sqlite3\n*.sqlite3-*\n\n.env\n\n/reference\n" }, { "path": ".prettierignore", "content": "node_modules/\ndist/\ntmp/\nreference/\n**/*.bundled.*\n**/public/assets/\n**/test/fixtures/\n**/worker-configuration.d.ts\npnpm-lock.yaml\n" }, { "path": ".prettierrc", "content": "printWidth: 100\nsemi: false\nsingleQuote: true\nuseTabs: false\n" }, { "path": ".vscode/settings.json", "content": "{\n \"deno.enablePaths\": [\"./packages/multipart-parser/examples/deno\"],\n \"nodejs-testing.extensions\": [\n {\n \"extensions\": [\"ts\", \"tsx\"],\n \"parameters\": [\"--import\", \"tsx\"]\n }\n ],\n \"typescript.tsdk\": \"./node_modules/typescript/lib\"\n}\n" }, { "path": ".vscode/task.json", "content": "{\n \"version\": \"0.1.0\",\n \"command\": \"./node_modules/.bin/tsc\",\n \"args\": [\"-v\"],\n \"echoCommand\": true\n}\n" }, { "path": "AGENTS.md", "content": "# Remix 3 Development Guide\n\n## Commands\n\n- **Build**: `pnpm run build` (all packages) or `pnpm --filter @remix-run/<package> run build` (single package)\n- **Test**: `pnpm test` (all packages) or `pnpm --filter @remix-run/<package> run test` (single package)\n- **Single test file**: `node --test './packages/<package>/src/**/<filename>.test.ts'`\n- **Typecheck**: `pnpm run typecheck` (all packages) or `pnpm --filter @remix-run/<package> run typecheck`\n- **Lint**: `pnpm run lint` (check) or `pnpm run lint:fix` (auto-fix)\n- **Before finishing work**: Run `pnpm run lint` and resolve any lint errors before reporting completion.\n- **Format**: `pnpm run format` (auto-fix) or `pnpm run format:check` (check only)\n- **Clean**: `pnpm run clean` (git clean -fdX)\n\n## Architecture\n\n- **Monorepo**: pnpm workspace with packages in `packages/` directory\n- **Key packages**: headers, fetch-proxy, fetch-router, file-storage, form-data-parser, lazy-file, multipart-parser, node-fetch-server, route-pattern, tar-parser\n- **Package exports**: All `exports` in `package.json` have a dedicated file in `src` that defines the public API by re-exporting from within `src/lib`\n- **Lib module boundaries**: Files in `src/lib` are implementation files. Do not add barrel-style re-exports or thin pass-through wrapper APIs between `src/lib` files. Re-exporting belongs only in top-level `src` barrel files that map to package exports.\n- **Cross-package boundaries**: Avoid re-exporting APIs/types from other packages. Consumers should import from the owning package directly. Reuse shared concepts from sibling packages internally instead of creating bespoke duplicate implementations.\n- **Documentation imports/install**: In package READMEs, documentation, and pull request code examples, installation instructions should always include `npm i remix`, usage examples should import from `remix` package exports (not `@remix-run/*`), and any required peer dependency should be included in the installation command.\n- **Philosophy**: Web standards-first, runtime-agnostic (Node.js, Bun, Deno, Cloudflare Workers). Use Web Streams API, Uint8Array, Web Crypto API, Blob/File instead of Node.js APIs\n- **Tests run from source** (no build required), using Node.js test runner\n\n## Code Style\n\n- **Imports**: Always use `import type { X }` for types (separate from value imports); use `export type { X }` for type exports; include `.ts` extensions\n- **One-off scripts**: Write one-off scripts in this repo as TypeScript and make them executable natively with modern Node.js (for example, executable `.ts` files)\n- **Node runtime assumption**: Assume a modern Node.js runtime that supports running TypeScript files natively; prefer `node path/to/script.ts` in examples and instructions.\n- **Variables**: Prefer `let` for locals, `const` only at module scope; never use `var`\n- **Functions**: Use regular function declarations/expressions by default. For callback-based APIs (array methods, Promise callbacks, test callbacks, transaction callbacks, etc.), prefer arrow functions over `function` expressions. When an arrow callback only returns a single expression, use a concise body (`value => expression`) instead of braces/`return`\n- **Object methods**: When defining functions in object literals, use shorthand method syntax (`{ method() {} }`) instead of arrow functions (`{ method: () => {} }`)\n- **Classes**: Use native fields (omit `public`), `#private` for private members (no TypeScript accessibility modifiers)\n- **Formatting**: Prettier (printWidth: 100, no semicolons, single quotes, spaces not tabs)\n- **TypeScript**: Strict mode, ESNext target, ES2022 modules, bundler resolution, verbatimModuleSyntax\n- **Generics**: Use descriptive lowercase names for type parameters (e.g., `source`, `method`, `pattern`) instead of single uppercase letters like `T`, `P`, or `K`\n- **Comments**: Only add non-JSDoc comments when the code is doing something surprising or non-obvious\n\n## Test Structure\n\n- **No loops or conditionals in test suites**: Do not use `for` loops or conditional statements (`if`, `switch`, etc.) to generate test cases within `describe()` blocks. This breaks the Node.js test runner's ability to run individual tests via IDE features (like clicking test icons in the sidebar).\n\n## Demos\n\n- All demo servers should use port **44100** for consistency across the monorepo\n- **Accessible navigation**: Always use proper `<a>` elements for navigation links. Never use JavaScript `onclick` handlers on non-interactive elements like `<tr>`, `<div>`, or `<span>` for navigation. Links should be keyboard accessible and work with screen readers.\n- **Clean shutdown**: Demo servers should handle `SIGINT` and `SIGTERM` signals to exit cleanly when Ctrl+C is pressed. Close the server and call `process.exit(0)`.\n\n## Documentation\n\n- API documentation is handled by scripts in the docs/ directory\n- We use `typedoc` to process the source code, and then generate markdown files from the typedoc output\n- Markdown API documentation files be generated via `pnpm run docs` in the docs/ directory\n\n## Changes and Releases\n\n- **Automated releases**: When changes are pushed to `main`, the [release-pr workflow](/.github/workflows/release-pr.yaml) automatically opens/updates a \"Release\" PR. The [publish workflow](/.github/workflows/publish.yaml) runs on every push to `main` and publishes when no change files are present (i.e., after merging the Release PR).\n- **Manual releases**: `pnpm changes:version` updates package.json, CHANGELOG.md, and creates a git commit. Push to `main` and the publish workflow will handle the rest (including tags and GitHub releases).\n- **How publishing works**: The publish workflow checks for change files. If none exist, it runs `pnpm publish --recursive --report-summary`, reads the summary JSON to see what was published, then creates git tags and GitHub releases for each published package.\n- **Test change/release code with preview scripts**: When modifying any change/release code, run `pnpm changes:preview` to test locally. For the release PR script, run `node ./scripts/release-pr.ts --preview`. For the publish script, run `node ./scripts/publish.ts --dry-run` to see what commands would be executed without actually publishing.\n\n## Skills\n\nA skill is a reusable local instruction set stored in a `SKILL.md` file.\n\n### Available skills\n\n- **add-package**: Create or align a package in the Remix monorepo to match existing package conventions. Use when adding a brand new package under packages/, or when fixing an existing package's structure, test setup, TypeScript/build config, code style, and README layout to match the rest of Remix 3. (file: `./.agents/skills/add-package/SKILL.md`)\n- **make-change-file**: Create or update package change files using Remix repo conventions, deterministic naming, and release-note style. (file: `./.agents/skills/make-change-file/SKILL.md`)\n- **make-demo**: Create or revise demos in the Remix repository so they stay focused on Remix packages, strong code hygiene, and production-quality patterns. (file: `./.agents/skills/make-demo/SKILL.md`)\n- **make-pr**: Create GitHub pull requests with clear context, issue/feature bullets, and required usage examples for new or changed APIs. (file: `./.agents/skills/make-pr/SKILL.md`)\n- **publish-placeholder-package**: Publish a minimal npm package at `0.0.0` to reserve the name and enable npm OIDC setup before CI-based publishing. (file: `./.agents/skills/publish-placeholder-package/SKILL.md`)\n- **supersede-pr**: Replace one GitHub PR with another and explicitly close the superseded PR (instead of relying on `Closes #...` keywords). (file: `./.agents/skills/supersede-pr/SKILL.md`)\n- **update-pr**: Rewrite GitHub PR titles and descriptions from scratch so they match the PR as it exists now, and always review the title when updating the body. (file: `./.agents/skills/update-pr/SKILL.md`)\n- **write-api-docs**: Write or audit public API docs for Remix packages. Use when adding or tightening JSDoc on exported functions, classes, interfaces, type aliases, or option objects. (file: `./.agents/skills/write-api-docs/SKILL.md`)\n- **write-readme**: Write or rewrite Remix package READMEs using this repo's structure, installation conventions, production-style examples, and section ordering. (file: `./.agents/skills/write-readme/SKILL.md`)\n" }, { "path": "CONTRIBUTING.md", "content": "Welcome to Remix! We're excited to have you contribute.\n\nThis guide will help you get started.\n\n## Setting Up Your Environment\n\nWe develop Remix using [pnpm](https://pnpm.io) on Node 24.3+.\n\nIf you're using [VS Code](https://code.visualstudio.com/), we recommend installing the [`node:test runner` extension](https://marketplace.visualstudio.com/items?itemName=connor4312.nodejs-testing) for a smooth testing experience.\n\nOnce that's set up, run `pnpm install` to get all the project dependencies.\n\n## Testing\n\nAll tests run directly from source. This makes it easy to use breakpoint debugging when running tests. This also means you should not need to run a build before running the tests.\n\n```sh\n# Run all tests\n$ pnpm test\n# Run the tests for a specific package\n$ pnpm --filter @remix-run/headers run test\n```\n\n## Building\n\nAll packages are built using a combination of tsc and esbuild.\n\n```sh\n# Build all packages\n$ pnpm run build\n# Build a specific package\n$ pnpm --filter @remix-run/headers run build\n```\n\nAll packages are published with TypeScript types along with both ESM and CJS module formats.\n\n## Making Changes\n\nPackages live in the [`packages` directory](https://github.com/remix-run/remix/tree/v3/packages). At a minimum, each package includes:\n\n- `.changes/`: Directory containing change files for the next release\n- `CHANGELOG.md`: A log of what's changed\n- `package.json`: Package metadata and dependencies\n- `README.md`: Information about the package\n- `src/`: The package's source code\n\nWhen you make changes to a package, please make sure you add a few relevant tests and run the whole test suite to make sure everything still works. Then, [add a change file](#adding-a-change-file) describing your changes and [make a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request). We will take a look at it as soon as we can.\n\n### Adding a Change File\n\nWhen making changes to a package, create a markdown file in the package's `.changes/` directory following this naming convention:\n\n```\n[major|minor|patch].short-description.md\n```\n\n- `major` - Breaking changes for v1.x+ packages\n- `minor` - Breaking changes for v0.x packages, new features\n- `patch` - Bug fixes\n\n#### Examples\n\n- `major.change-something.md` - Breaking change for v1.x+ packages\n- `minor.change-something.md` - Breaking change for v0.x packages\n- `minor.add-something.md` - New feature\n- `patch.fix-something.md` - Bug fix\n\n#### Content Format\n\nWrite your change as a bullet point (without the leading `-` or `*`). This content will be added to the CHANGELOG during release.\n\n```markdown\nAdd support for X feature\n\nThis is an optional longer explanation that will be indented\nunder the main bullet point in the CHANGELOG.\n```\n\nFor breaking changes in v0.x packages, any change files that begin with `BREAKING CHANGE: ` will be hoisted to the top of the release notes:\n\n```markdown\nBREAKING CHANGE: Renamed `foo` option to `bar`\n\nMigration: Update your config to use `bar` instead of `foo`.\n```\n\n#### Validation\n\nChange files are automatically validated in CI. You can also validate them locally:\n\n```sh\npnpm changes:validate\n```\n\n## Releases\n\nReleases are automated via the [release-pr workflow](/.github/workflows/release-pr.yaml) and [publish workflow](/.github/workflows/publish.yaml).\n\n1. **You push changes to `main`** with change files in `packages/*/.changes/`\n\n2. **A \"Release\" PR is automatically opened** (or updated if one exists)\n\n The PR contains:\n\n - Updated `package.json` versions\n - Updated `CHANGELOG.md` files\n - Deleted change files\n\n This PR should not be edited manually. If you need to make changes, modify the change files and/or scripts in `main` to trigger an update to the PR.\n\n3. **When you merge the PR**, the publish workflow runs (it runs on every push to `main` and checks for change files). Since the change files have been deleted, it publishes all unpublished packages to npm, then creates git tags and GitHub releases based on what was actually published.\n\n### Manual Versioning\n\nThe \"Release\" PR simply automates the `pnpm changes:version` command. If needed, you can run this command manually. This will update the `package.json` versions, `CHANGELOG.md` files, and delete the change files. It will then commit the result.\n\n```sh\npnpm changes:version\n```\n\nYou can skip committing the changes by using the `--no-commit` flag. This will leave the changes in a staged state for you to review and commit manually. The command will also output the commit message that would have been used.\n\n```sh\npnpm changes:version --no-commit\n```\n\nTags and GitHub releases are created automatically by the publish workflow after successful npm publish.\n\n### Prerelease Mode for `remix`\n\nThe `remix` package supports prerelease mode via an optional `.changes/config.json` file:\n\n```json\n{\n \"prereleaseChannel\": \"alpha\"\n}\n```\n\nThe `prereleaseChannel` field determines the version suffix (e.g. `alpha`, `beta`, `rc`), while prereleases are always published to npm with the `next` tag. This is only supported for `remix` because it's the only package that needs to publish prereleases alongside an existing stable version on npm. All other packages in this monorepo are new and publish directly as `latest`.\n\n#### Bumping `remix` prerelease versions\n\nWhile in prerelease mode, add change files as normal. The prerelease counter increments (e.g. `3.0.0-alpha.1` → `3.0.0-alpha.2`). Changelog entries still get proper \"Major Changes\" / \"Minor Changes\" / \"Patch Changes\" sections, but the bump type is otherwise ignored—only the prerelease counter is bumped.\n\n#### Transitioning between `remix` prerelease channels\n\nTo transition between channels (e.g. `alpha` → `beta`):\n\n1. Update `prereleaseChannel` in `.changes/config.json` to the new channel\n2. Add a change file describing the transition\n\nVersion resets to the new channel (e.g. `3.0.0-alpha.7` → `3.0.0-beta.0`). The bump type is for changelog categorization only—by convention, use `patch`.\n\n#### Graduating `remix` to stable\n\nTo release the stable version:\n\n1. Remove `prereleaseChannel` from `.changes/config.json` (or delete the file)\n2. Add a change file describing the stable release\n\nThe prerelease suffix is stripped (e.g. `3.0.0-rc.7` → `3.0.0`). The bump type is for changelog categorization only—by convention, use `major` for a major release announcement.\n\n## Preview builds\n\nWe maintain installable builds of `main` in a `preview/main` branch as a way for folks to test out the latest `main` branch without needing to publish releases to npm and clutter up the npm registry and version history UI.\n\nThis is managed via the [`preview` workflow](/.github/workflows/preview.yaml) which uses the [`setup-installable-branch.ts`](./scripts/setup-installable-branch.ts) script to build and commit the build and required `package.json` changes to the `preview/main` branch on every new commit to `main`.\n\nThe `preview/main` branch build can be [installed directly](https://pnpm.io/package-sources#install-from-a-git-repository-combining-different-parameters) with `pnpm` (version 9+):\n\n```sh\npnpm install \"remix-run/remix#preview/main&path:packages/remix\"\n\n# Or, just install a single package\npnpm install \"remix-run/remix#preview/main&path:packages/fetch-router\"\n```\n" }, { "path": "LICENSE", "content": "MIT License\n\nCopyright (c) 2025 Shopify Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "README.md", "content": "# Welcome to Remix 3!\n\nThis is the source repository for Remix 3. It is under active development.\n\nWe published [a blog post](https://remix.run/blog/wake-up-remix) earlier this year with some of our thoughts around Remix 3. It explains our philosophy for web development and why we think the time is right for something new. When working on Remix 3, we follow these principles:\n\n1. **Model-First Development**. AI fundamentally shifts the human-computer interaction model for both user experience and developer workflows. Optimize the source code, documentation, tooling, and abstractions for LLMs. Additionally, develop abstractions for applications to use models in the product itself, not just as a tool to develop it.\n2. **Build on Web APIs**. Sharing abstractions across the stack greatly reduces the amount of context switching, both for humans and machines. Build on the foundation of Web APIs and JavaScript because it is the only full stack ecosystem.\n3. **Religiously Runtime**. Designing for bundlers/compilers/typegen (and any pre-runtime static analysis) leads to poor API design that eventually pollutes the entire system. All packages must be designed with no expectation of static analysis and all tests must run without bundling. Because browsers are involved, `--import` loaders for simple transformations like TypeScript and JSX are permissible.\n4. **Avoid Dependencies**. Dependencies lock you into somebody else's roadmap. Choose them wisely, wrap them completely, and expect to replace most of them with our own package eventually. The goal is zero.\n5. **Demand Composition**. Abstractions should be single-purpose and replaceable. A composable abstraction is easy to add and remove from an existing program. Every package must be useful and documented independent of any other context. New features should first be attempted as a new package. If impossible, attempt to break up the existing package to make it more composable. However, tightly coupled modules that almost always change together in both directions should be moved to the same package.\n6. **Distribute Cohesively**. Extremely composable ecosystems are difficult to learn and use. Remix will be distributed as a single `remix` package for both distribution and documentation.\n\n## Goals\n\nAlthough we recommend the `remix` package for ease of use, all packages that make up Remix should be usable standalone as well. This forces us to consider package boundaries and helps us define public interfaces that are portable and interoperable.\n\nEach package in Remix:\n\n- Has a [single responsibility](https://en.wikipedia.org/wiki/Single-responsibility_principle)\n- Prioritizes web standards to ensure maximum interoperability and portability across JavaScript runtimes\n- Augments standards unobtrusively where they are missing or incomplete, minimizing incompatibility risks\n\nThis means Remix code is **portable by default**. Remix packages work seamlessly across [Node.js](https://nodejs.org/), [Bun](https://bun.sh/), [Deno](https://deno.com/), [Cloudflare Workers](https://workers.cloudflare.com/), and other environments.\n\nWe leverage server-side web APIs when they are available:\n\n- [The Web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) instead of `node:stream`\n- [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of Node.js `Buffer`s\n- [The Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) instead of `node:crypto`\n- [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) and [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) instead of some bespoke runtime-specific API\n\nThe benefit is code that's not just reusable, but **future-proof**.\n\n## Packages\n\nWe currently publish the following packages:\n\n- [async-context-middleware](packages/async-context-middleware): Middleware for storing request context in AsyncLocalStorage\n- [component](packages/component): UI components for Remix\n- [compression-middleware](packages/compression-middleware): Middleware for compressing HTTP responses\n- [cop-middleware](packages/cop-middleware): Middleware for tokenless cross-origin protection in Fetch API servers\n- [cors-middleware](packages/cors-middleware): Middleware for handling CORS in Fetch API servers\n- [csrf-middleware](packages/csrf-middleware): Middleware for CSRF protection in Fetch API servers\n- [cookie](packages/cookie): A toolkit for working with cookies in JavaScript\n- [data-schema](packages/data-schema): Tiny, standards-aligned schema validation\n- [data-table](packages/data-table): A typed, relational query toolkit for Remix\n- [data-table-mysql](packages/data-table-mysql): MySQL adapter for remix/data-table\n- [data-table-postgres](packages/data-table-postgres): PostgreSQL adapter for remix/data-table\n- [data-table-sqlite](packages/data-table-sqlite): SQLite adapter for remix/data-table\n- [fetch-proxy](packages/fetch-proxy): An HTTP proxy for the web Fetch API\n- [fetch-router](packages/fetch-router): A minimal, composable router for the web Fetch API\n- [file-storage](packages/file-storage): Key/value storage for JavaScript File objects\n- [file-storage-s3](packages/file-storage-s3): S3 backend for remix/file-storage\n- [form-data-middleware](packages/form-data-middleware): Middleware for parsing FormData from request bodies\n- [form-data-parser](packages/form-data-parser): A request.formData() wrapper with streaming file upload handling\n- [fs](packages/fs): Filesystem utilities using the Web File API\n- [headers](packages/headers): A toolkit for working with HTTP headers in JavaScript\n- [html-template](packages/html-template): HTML template tag with auto-escaping for JavaScript\n- [lazy-file](packages/lazy-file): Lazy, streaming files for JavaScript\n- [logger-middleware](packages/logger-middleware): Middleware for logging HTTP requests and responses\n- [method-override-middleware](packages/method-override-middleware): Middleware for overriding HTTP request methods from form data\n- [mime](packages/mime): Utilities for working with MIME types\n- [multipart-parser](packages/multipart-parser): A fast, efficient parser for multipart streams in any JavaScript environment\n- [node-fetch-server](packages/node-fetch-server): Build servers for Node.js using the web fetch API\n- [remix](packages/remix): Remix Web Framework\n- [response](packages/response): Response helpers for the web Fetch API\n- [route-pattern](packages/route-pattern): Match and generate URLs with strong typing\n- [session](packages/session): Session management for JavaScript\n- [session-middleware](packages/session-middleware): Middleware for managing sessions with cookie-based storage\n- [session-storage-memcache](packages/session-storage-memcache): Memcache session storage for remix/session\n- [session-storage-redis](packages/session-storage-redis): Redis session storage for remix/session\n- [static-middleware](packages/static-middleware): Middleware for serving static files from the filesystem\n- [tar-parser](packages/tar-parser): A fast, efficient parser for tar streams in any JavaScript environment\n\n## Installation\n\nTo try the current Remix alpha, install the `next` dist-tag:\n\n```sh\nnpm install remix@next\n```\n\nIf you want to play around with the bleeding edge, we also build the latest `main` branch into a `preview/main` branch which can be [installed directly](https://pnpm.io/package-sources#install-from-a-git-repository-combining-different-parameters) with `pnpm` (version 9+):\n\n```sh\npnpm install \"remix-run/remix#preview/main&path:packages/remix\"\n\n# Or, just install a single package\npnpm install \"remix-run/remix#preview/main&path:packages/fetch-router\"\n```\n\n## Contributing\n\nWe welcome contributions! If you'd like to contribute, please feel free to open an issue or submit a pull request. See [CONTRIBUTING](https://github.com/remix-run/remix/blob/main/CONTRIBUTING.md) for more information.\n\n## License\n\nSee [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)\n" }, { "path": "cspell.yml", "content": "version: '0.2'\nlanguage: en\nwords:\n - accentunder\n - actiontype\n - activedescendant\n - aftertoggle\n - arcrole\n - Arcrole\n - autocorrect\n - backlink\n - bbox\n - biblioentry\n - biblioref\n - Booleanish\n - braillelabel\n - brailleroledescription\n - closedby\n - closerequest\n - colcount\n - colindex\n - colindextext\n - columnalign\n - columnlines\n - columnspacing\n - columnspan\n - commandfor\n - contenteditable\n - contentinfo\n - controlslist\n - denomalign\n - describedby\n - desync\n - disableremoteplayback\n - displaystyle\n - DOMCSS\n - dropeffect\n - elementtiming\n - enterkeyhint\n - exportparts\n - fetchpriority\n - fixpoint\n - flowto\n - focusin\n - focusout\n - fontstyle\n - fontweight\n - formaction\n - formenctype\n - formmethod\n - formnovalidate\n - formtarget\n - FOUC\n - framespacing\n - glossref\n - haspopup\n - healthcheck\n - horiz\n - hsba\n - inlist\n - inputmode\n - itemprop\n - itemref\n - itemscope\n - itemtype\n - jsxs\n - keybind\n - keyshortcuts\n - keyup\n - labelledby\n - largeop\n - linethickness\n - lquote\n - lspace\n - maction\n - mathbackground\n - mathcolor\n - mathsize\n - mathvariant\n - maxlength\n - maxsize\n - menclose\n - menuitemcheckbox\n - menuitemradio\n - merror\n - mfenced\n - mfrac\n - Microdata\n - minsize\n - Mmulti\n - mmultiscripts\n - movablelimits\n - mpadded\n - mpath\n - mphantom\n - mprescripts\n - mroot\n - mrow\n - mspace\n - msqrt\n - mstyle\n - msub\n - msubsup\n - msup\n - mtable\n - mtext\n - multiselectable\n - munder\n - munderover\n - noteref\n - novalidate\n - numalign\n - outerclick\n - pagebreak\n - pagelist\n - panose\n - playsinline\n - pointerdown\n - pointerenter\n - pointerleave\n - pointermove\n - pointerup\n - popovertarget\n - popovertargetaction\n - posinset\n - pullquote\n - referrerpolicy\n - renderable\n - roledescription\n - roletype\n - rowalign\n - rowcount\n - rowindex\n - rowindextext\n - rowlines\n - rowspacing\n - rowspan\n - rquote\n - rspace\n - scriptlevel\n - scriptminsize\n - scriptsizemultiplier\n - sectionhead\n - setsize\n - Signalish\n - spinbutton\n - statusline\n - stemh\n - stemv\n - subscriptshift\n - Subsup\n - superscriptshift\n - SVGM\n - treegrid\n - treeitems\n - unitless\n - unkeyed\n - valuenow\n - valuetext\n - vdom\n - visibilitychange\n - vnode\n - VNODE\n - vnodes\n - voffset\n - wmode\n - xlink\nignorePaths:\n - node_modules/**\n - dist/**\n - build/**\n - pnpm-lock.yaml\n" }, { "path": "decisions/001-route-pattern-vs-url-pattern.md", "content": "# RoutePattern vs. URLPattern\n\nThe web has a built-in URL matcher called [`URLPattern`](https://developer.mozilla.org/en-US/docs/Web/API/URLPattern). Why don't we use it instead of creating our own thing with [`RoutePattern`](../packages/route-pattern)?\n\n## Main Differences\n\nThere are a number of major differences between `RoutePattern` and `URLPattern`. Here are the main ones:\n\n- **Generating URLs**: `RoutePattern` comes with an \"href builder\" for building URLs from route patterns. This is the logical bookend to \"matching\" or parsing a URL.\n\n- **Easier pathname-only Matching**: `RoutePattern` allows matching only a URL pathname without resorting to the object syntax, or beginning with a leading `/`\n\n```tsx\nlet pattern = new RoutePattern('products/:id') // matches <protocol>://<host>/products/:id\n// vs. URLPattern, requires object syntax and leading slash\nlet pattern = new URLPattern({ pathname: '/products/:id' })\n```\n\n- **Non-exhaustive Search Matching**: `RoutePattern` does not treat the pattern's search string as exhaustive. This allows matching URLs that contain additional query parameters, which is important for allowing traffic that comes from sources where you don't have full control over the search string.\n\n```tsx\nlet pattern = new RoutePattern('?q=remix')\npattern.match('https://remix.run/?q=remix') // match\npattern.match('https://remix.run/?q=remix&utm_source') // also match!\n\nlet pattern = new URLPattern({ search: '?q=remix' })\npattern.exec('https://remix.run/?q=remix') // match\npattern.exec('https://remix.run/?q=remix&utm_source') // null :(\n```\n\n- **More Intuitive Optionals**: `RoutePattern` expresses optionals using parentheses, similar to Rails. These read like English instead of using `?` to indicate optional groups as in regular expressions. It also makes the start and end positions of an optional group immediately obvious.\n\n```tsx\n// An \"optional group\" using URLPattern\nlet pattern = new URLPattern('/books/:id?', 'https://example.com')\npattern.test('https://example.com/books/123') // true\npattern.test('https://example.com/books') // true\n// This behavior is unintuitive. Is the \":id\" optional? Or the \"/:id\"?\n// There's no way to know when you only have a single group modifier character (the `?`)\npattern.test('https://example.com/books/') // false\n\n// An optional using RoutePattern\nlet pattern = new RoutePattern('/books(/:id)')\npattern.test('https://example.com/books/123') // true\npattern.test('https://example.com/books') // true\n// This result is more intuitive because the () surround the optional\n// portion of the pattern, indicating both start and end characters\npattern.test('https://example.com/books/') // false\n```\n\n- **Uniform Param Access**: `RoutePattern` does not support \"unnamed groups\" that must be accessed by index in the match result. Instead, all variables (groups) must have names and are accessed by that name at `match.params[name]`.\n\n- **No RegExp Syntax**: `RoutePattern` does not allow regex syntax. This means route patterns are statically analyzable without parsing RegExp grammar, which makes it easier to provide type safety. Also, the whole point of `RoutePattern` is to provide a syntax that is sufficient for matching URLs without resorting to some other syntax.\n" }, { "path": "decisions/002-branching-and-releasing.md", "content": "# Branching and Releasing in Remix 3\n\nBeginning in Remix 3 the `remix` package is an umbrella package for everything in Remix. This includes a number of \"sub-packages\" that are all published under the `@remix-run/*` scope. The `remix` package re-exports everything from all sub-packages as a transparent pass-thru. This means users only have to install `remix` to get everything we publish, and they can import everything from some `remix/*` export.\n\nWe anticipate the majority of Remix development will happen directly on the `main` branch. `main` should always be publishable. We will publish minor/patch changes from `main` often for both `remix` and any sub-package that needs it.\n\n## Breaking Changes\n\nWhen it comes to breaking changes (that require a major version bump), we have 2 goals:\n\n- Be slow and deliberate about cutting major `remix` releases so we don't stress people out by releasing majors too often\n- Release breaking changes in sub-packages as soon as they are ready so people can play with them\n\nMajor `remix` releases will happen on a predetermined schedule so that users may plan upgrades into their development lifecycle.\n\nBreaking changes will accumulate on a `future` branch. The `future` branch is a preview of what the next major version of Remix will look like. If someone wants to play with the latest stuff, they can build directly from `future`. We don't make any guarantees about the [stability][^stability] of `future`, which is why users must build from source.\n\nWe will publish new majors of sub-packages as soon as they are ready from the `future` branch. When it's time to cut the next major `remix` release, we will merge `future` into `main`. Of course, this means that `main` should be merged into `future` periodically to make this easier.\n\n[^stability]: By \"stable\" we mean \"won't break between releases\". Both `main` and `future` should always pass all tests and be usable, but on `main` we have versions and stability guarantees between them. On `future`, we don't.\n" }, { "path": "demos/bookstore/.gitignore", "content": "public/assets/\ntmp/\ndata/*.sqlite\n" }, { "path": "demos/bookstore/README.md", "content": "# Bookstore Demo\n\nA full-featured e-commerce bookstore demonstrating the most powerful patterns and features of Remix. This demo showcases authentication, shopping cart, admin CRUD operations, file uploads, progressive enhancement, and much more.\n\n## Running the Demo\n\n```bash\ncd demos/bookstore\npnpm install\npnpm start\n```\n\nThen visit http://localhost:44100\n\n### Demo Accounts\n\n- **Admin**: admin@bookstore.com / admin123\n- **Customer**: customer@example.com / password123\n\n## Database and Migrations\n\n- The SQLite file is stored at `data/bookstore.sqlite`\n- Migration files live in `data/migrations`\n- On startup, the app loads migrations from `data/migrations` and runs pending migrations before seeding demo data\n\n## Code Highlights\n\n- [`app/routes.ts`](app/routes.ts) shows declarative route definitions using `route()`, `form()`, and `resources()` helpers. All route URLs are generated with full type safety, so `routes.admin.books.edit.href({ bookId: '123' })` ensures you never have broken links.\n- [`app/router.ts`](app/router.ts) demonstrates how to compose middleware for cross-cutting concerns: static file serving, form data parsing, method override, sessions, and async context. Each middleware is independent and reusable.\n- [`data/migrations/20260228090000_create_bookstore_schema.ts`](data/migrations/20260228090000_create_bookstore_schema.ts) defines the schema using `remix/data-table/migrations`.\n- [`app/middleware/database.ts`](app/middleware/database.ts) stores the bookstore database on request context with `context.set(Database, db)`, and request handlers read it back with `get(Database)` just like they do for `Session` and `FormData`.\n- [`app/middleware/auth.ts`](app/middleware/auth.ts) provides two patterns:\n - **`loadAuth()`** - Optionally loads the current user without requiring authentication\n - **`requireAuth()`** - Redirects to login with a `returnTo` parameter for post-login redirect\n- [`app/middleware/admin.ts`](app/middleware/admin.ts) shows role-based authorization that returns 403 for non-admin users.\n- [`app/utils/context.ts`](app/utils/context.ts) demonstrates sharing data across the request lifecycle without prop drilling. Any code can call `getCurrentUser()` to access the authenticated user set by middleware earlier in the chain.\n- [`app/utils/session.ts`](app/utils/session.ts) configures signed cookies and filesystem-based session storage.\n- [`app/utils/uploads.ts`](app/utils/uploads.ts) handles file uploads with `@remix-run/form-data-middleware`. The upload handler stores files and returns public URLs. [`app/uploads.tsx`](app/uploads.tsx) serves uploaded files with appropriate caching headers.\n- HTML forms only support GET and POST. [`app/components/restful-form.tsx`](app/components/restful-form.tsx) adds a hidden `_method` field for PUT and DELETE, which the `methodOverride()` middleware translates back to the original method.\n- [`app/assets/cart-button.tsx`](app/assets/cart-button.tsx) shows a button that works without JavaScript (full form submission) but upgrades to fetch-based updates when JS is available. Notice how `hydrated()` wraps a component that maintains local state (`updating`) and calls `this.update()` to re-render.\n- [`app/assets/image-carousel.tsx`](app/assets/image-carousel.tsx) demonstrates a similar pattern for an interactive image carousel.\n- [`app/books.tsx`](app/books.tsx) uses `<Frame>` to render book cards that can be loaded independently. The frame URLs point to [`app/fragments.tsx`](app/fragments.tsx), and [`app/utils/frame.tsx`](app/utils/frame.tsx) shows how frames are resolved server-side during initial render.\n- [`app/admin.books.tsx`](app/admin.books.tsx) demonstrates complete CRUD operations with file uploads, using the RESTful routes generated by `resources('books')`.\n" }, { "path": "demos/bookstore/app/account.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { loginAsCustomer, requestWithSession, assertContains } from '../test/helpers.ts'\n\ndescribe('account handlers', () => {\n it('GET /account redirects to login when not authenticated', async () => {\n let response = await router.fetch('https://remix.run/account')\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login?returnTo=%2Faccount')\n })\n\n it('GET /account returns account page when authenticated', async () => {\n let sessionId = await loginAsCustomer(router)\n\n // Now access account page with session\n let request = requestWithSession('https://remix.run/account', sessionId)\n let response = await router.fetch(request)\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, 'My Account')\n assertContains(html, 'Account Information')\n assertContains(html, 'John Doe')\n })\n\n it('GET /account/orders/:orderId shows order for authenticated user', async () => {\n let sessionId = await loginAsCustomer(router)\n\n // Access existing order\n let request = requestWithSession('https://remix.run/account/orders/1001', sessionId)\n let response = await router.fetch(request)\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, 'Order #1001')\n assertContains(html, 'Ash & Smoke')\n })\n\n it('GET /account/orders shows item counts from normalized order items', async () => {\n let sessionId = await loginAsCustomer(router)\n let request = requestWithSession('https://remix.run/account/orders', sessionId)\n let response = await router.fetch(request)\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, '2 item(s)')\n assertContains(html, '1 item(s)')\n })\n})\n" }, { "path": "demos/bookstore/app/account.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport { Database } from 'remix/data-table'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\nimport { Layout } from './layout.tsx'\nimport { requireAuth } from './middleware/auth.ts'\nimport { orders, orderItemsWithBook, users } from './data/schema.ts'\nimport { getCurrentUser } from './utils/context.ts'\nimport { parseId } from './utils/ids.ts'\nimport { render } from './utils/render.ts'\nimport { RestfulForm } from './components/restful-form.tsx'\n\nconst textField = f.field(s.defaulted(s.string(), ''))\nconst accountSettingsSchema = f.object({\n name: textField,\n email: textField,\n password: textField,\n})\n\nexport default {\n middleware: [requireAuth()],\n actions: {\n index() {\n let user = getCurrentUser()\n\n return render(\n <Layout>\n <h1>My Account</h1>\n\n <div class=\"card\">\n <h2>Account Information</h2>\n <p>\n <strong>Name:</strong> {user.name}\n </p>\n <p>\n <strong>Email:</strong> {user.email}\n </p>\n <p>\n <strong>Role:</strong> {user.role}\n </p>\n <p>\n <strong>Member Since:</strong> {new Date(user.created_at).toLocaleDateString()}\n </p>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.account.settings.index.href()} class=\"btn\">\n Edit Settings\n </a>\n </p>\n </div>\n\n <div class=\"card\" mix={[css({ marginTop: '1.5rem' })]}>\n <h2>Quick Links</h2>\n <p>\n <a href={routes.account.orders.index.href()} class=\"btn btn-secondary\">\n View Orders\n </a>\n <a\n href={routes.books.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Browse Books\n </a>\n </p>\n </div>\n </Layout>,\n )\n },\n\n settings: {\n actions: {\n index() {\n let user = getCurrentUser()\n\n return render(\n <Layout>\n <h1>Account Settings</h1>\n\n <div class=\"card\">\n <RestfulForm method=\"PUT\" action={routes.account.settings.update.href()}>\n <div class=\"form-group\">\n <label for=\"name\">Name</label>\n <input type=\"text\" id=\"name\" name=\"name\" value={user.name} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"email\">Email</label>\n <input type=\"email\" id=\"email\" name=\"email\" value={user.email} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"password\">New Password (leave blank to keep current)</label>\n <input\n type=\"password\"\n id=\"password\"\n name=\"password\"\n autoComplete=\"new-password\"\n />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Update Settings\n </button>\n <a\n href={routes.account.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Cancel\n </a>\n </RestfulForm>\n </div>\n </Layout>,\n )\n },\n\n async update({ get }) {\n let db = get(Database)\n let formData = get(FormData)\n let user = getCurrentUser()\n\n let { email, name, password } = s.parse(accountSettingsSchema, formData)\n\n let updateData: any = { name, email }\n if (password) {\n updateData.password = password\n }\n\n await db.update(users, user.id, updateData)\n\n return redirect(routes.account.index.href())\n },\n },\n },\n\n orders: {\n actions: {\n async index({ get }) {\n let db = get(Database)\n let user = getCurrentUser()\n let userOrders = await db.findMany(orders, {\n where: { user_id: user.id },\n orderBy: ['created_at', 'asc'],\n with: { items: orderItemsWithBook },\n })\n\n return render(\n <Layout>\n <h1>My Orders</h1>\n\n <div class=\"card\">\n {userOrders.length > 0 ? (\n <table>\n <thead>\n <tr>\n <th>Order ID</th>\n <th>Date</th>\n <th>Items</th>\n <th>Total</th>\n <th>Status</th>\n <th>Actions</th>\n </tr>\n </thead>\n <tbody>\n {userOrders.map((order) => (\n <tr>\n <td>#{order.id}</td>\n <td>{new Date(order.created_at).toLocaleDateString()}</td>\n <td>{order.items.length} item(s)</td>\n <td>${order.total.toFixed(2)}</td>\n <td>\n <span class=\"badge badge-info\">{order.status}</span>\n </td>\n <td>\n <a\n href={routes.account.orders.show.href({ orderId: order.id })}\n class=\"btn btn-secondary\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n View\n </a>\n </td>\n </tr>\n ))}\n </tbody>\n </table>\n ) : (\n <p>You have no orders yet.</p>\n )}\n </div>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.account.index.href()} class=\"btn btn-secondary\">\n Back to Account\n </a>\n </p>\n </Layout>,\n )\n },\n\n async show({ get, params }) {\n let db = get(Database)\n let user = getCurrentUser()\n let orderId = parseId(params.orderId)\n let order =\n orderId === undefined\n ? undefined\n : await db.find(orders, orderId, {\n with: { items: orderItemsWithBook },\n })\n\n if (!order || order.user_id !== user.id) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Order Not Found</h1>\n <p>\n <a href={routes.account.orders.index.href()} class=\"btn\">\n Back to Orders\n </a>\n </p>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n let shippingAddress = JSON.parse(order.shipping_address_json) as {\n street: string\n city: string\n state: string\n zip: string\n }\n\n return render(\n <Layout>\n <h1>Order #{order.id}</h1>\n\n <div class=\"card\">\n <p>\n <strong>Order Date:</strong> {new Date(order.created_at).toLocaleDateString()}\n </p>\n <p>\n <strong>Status:</strong> <span class=\"badge badge-info\">{order.status}</span>\n </p>\n\n <h2 mix={[css({ marginTop: '2rem' })]}>Items</h2>\n <table mix={[css({ marginTop: '1rem' })]}>\n <thead>\n <tr>\n <th>Book</th>\n <th>Quantity</th>\n <th>Price</th>\n <th>Subtotal</th>\n </tr>\n </thead>\n <tbody>\n {order.items.map((item) => (\n <tr>\n <td>{item.title}</td>\n <td>{item.quantity}</td>\n <td>${item.unit_price.toFixed(2)}</td>\n <td>${(item.unit_price * item.quantity).toFixed(2)}</td>\n </tr>\n ))}\n </tbody>\n <tfoot>\n <tr>\n <td colSpan={3} mix={[css({ textAlign: 'right', fontWeight: 'bold' })]}>\n Total:\n </td>\n <td mix={[css({ fontWeight: 'bold' })]}>${order.total.toFixed(2)}</td>\n </tr>\n </tfoot>\n </table>\n\n <h2 mix={[css({ marginTop: '2rem' })]}>Shipping Address</h2>\n <p>{shippingAddress.street}</p>\n <p>\n {shippingAddress.city}, {shippingAddress.state} {shippingAddress.zip}\n </p>\n </div>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.account.orders.index.href()} class=\"btn btn-secondary\">\n Back to Orders\n </a>\n </p>\n </Layout>,\n )\n },\n },\n },\n },\n} satisfies Controller<typeof routes.account>\n" }, { "path": "demos/bookstore/app/admin.books.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { loginAsAdmin, requestWithSession } from '../test/helpers.ts'\n\ndescribe('admin books handlers', () => {\n it('POST /admin/books creates new book when admin', async () => {\n let sessionId = await loginAsAdmin(router)\n\n // Create new book\n let createRequest = requestWithSession('https://remix.run/admin/books', sessionId, {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/x-www-form-urlencoded',\n },\n body: new URLSearchParams({\n slug: 'test-book',\n title: 'Test Book',\n author: 'Test Author',\n description: 'Test description',\n price: '29.99',\n genre: 'test',\n isbn: '978-0000000000',\n publishedYear: '2024',\n inStock: 'true',\n }),\n })\n let response = await router.fetch(createRequest)\n\n assert.equal(response.status, 302)\n assert.ok(response.headers.get('Location')?.includes('/admin/books'))\n })\n})\n" }, { "path": "demos/bookstore/app/admin.books.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport * as coerce from 'remix/data-schema/coerce'\nimport { Database } from 'remix/data-table'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\nimport { books } from './data/schema.ts'\nimport { Layout } from './layout.tsx'\nimport { parseId } from './utils/ids.ts'\nimport { render } from './utils/render.ts'\nimport { RestfulForm } from './components/restful-form.tsx'\n\nconst textField = f.field(s.defaulted(s.string(), ''))\nconst optionalTextField = f.field(s.optional(s.string()))\nconst priceField = f.field(s.defaulted(s.string(), '0'))\nconst publishedYearField = f.field(s.defaulted(s.string(), '2024'), {\n name: 'publishedYear',\n})\nconst inStockField = f.field(s.defaulted(coerce.boolean(), false), {\n name: 'inStock',\n})\nconst bookSchema = f.object({\n slug: textField,\n title: textField,\n author: textField,\n description: textField,\n price: priceField,\n genre: textField,\n cover: optionalTextField,\n isbn: textField,\n publishedYear: publishedYearField,\n inStock: inStockField,\n})\n\nexport default {\n actions: {\n async index({ get }) {\n let db = get(Database)\n let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })\n\n return render(\n <Layout>\n <h1>Manage Books</h1>\n\n <p mix={[css({ marginBottom: '1rem' })]}>\n <a href={routes.admin.books.new.href()} class=\"btn\">\n Add New Book\n </a>\n <a\n href={routes.admin.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Back to Dashboard\n </a>\n </p>\n\n <div class=\"card\">\n <table>\n <thead>\n <tr>\n <th>Title</th>\n <th>Author</th>\n <th>Genre</th>\n <th>Price</th>\n <th>Stock</th>\n <th>Actions</th>\n </tr>\n </thead>\n <tbody>\n {allBooks.map((book) => (\n <tr>\n <td>{book.title}</td>\n <td>{book.author}</td>\n <td>{book.genre}</td>\n <td>${book.price.toFixed(2)}</td>\n <td>\n <span class={`badge ${book.in_stock ? 'badge-success' : 'badge-warning'}`}>\n {book.in_stock ? 'Yes' : 'No'}\n </span>\n </td>\n <td class=\"actions\">\n <a\n href={routes.admin.books.edit.href({ bookId: book.id })}\n class=\"btn btn-secondary\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n Edit\n </a>\n <RestfulForm\n method=\"DELETE\"\n action={routes.admin.books.destroy.href({ bookId: book.id })}\n mix={[css({ display: 'inline' })]}\n >\n <button\n type=\"submit\"\n class=\"btn btn-danger\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n Delete\n </button>\n </RestfulForm>\n </td>\n </tr>\n ))}\n </tbody>\n </table>\n </div>\n </Layout>,\n )\n },\n\n async show({ get, params }) {\n let db = get(Database)\n let bookId = parseId(params.bookId)\n let book = bookId === undefined ? undefined : await db.find(books, bookId)\n\n if (!book) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Book Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n return render(\n <Layout>\n <h1>Book Details</h1>\n\n <div class=\"card\">\n <p>\n <strong>Title:</strong> {book.title}\n </p>\n <p>\n <strong>Author:</strong> {book.author}\n </p>\n <p>\n <strong>Slug:</strong> {book.slug}\n </p>\n <p>\n <strong>Description:</strong> {book.description}\n </p>\n <p>\n <strong>Price:</strong> ${book.price.toFixed(2)}\n </p>\n <p>\n <strong>Genre:</strong> {book.genre}\n </p>\n <p>\n <strong>ISBN:</strong> {book.isbn}\n </p>\n <p>\n <strong>Published:</strong> {book.published_year}\n </p>\n <p>\n <strong>In Stock:</strong>{' '}\n <span class={`badge ${book.in_stock ? 'badge-success' : 'badge-warning'}`}>\n {book.in_stock ? 'Yes' : 'No'}\n </span>\n </p>\n\n <div mix={[css({ marginTop: '2rem' })]}>\n <a href={routes.admin.books.edit.href({ bookId: book.id })} class=\"btn\">\n Edit\n </a>\n <a\n href={routes.admin.books.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Back to List\n </a>\n </div>\n </div>\n </Layout>,\n )\n },\n\n new() {\n return render(\n <Layout>\n <h1>Add New Book</h1>\n\n <div class=\"card\">\n <form\n method=\"POST\"\n action={routes.admin.books.create.href()}\n encType=\"multipart/form-data\"\n >\n <div class=\"form-group\">\n <label for=\"title\">Title</label>\n <input type=\"text\" id=\"title\" name=\"title\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"author\">Author</label>\n <input type=\"text\" id=\"author\" name=\"author\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"slug\">Slug (URL-friendly name)</label>\n <input type=\"text\" id=\"slug\" name=\"slug\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"description\">Description</label>\n <textarea id=\"description\" name=\"description\" required></textarea>\n </div>\n\n <div class=\"form-group\">\n <label for=\"price\">Price</label>\n <input type=\"number\" id=\"price\" name=\"price\" step=\"0.01\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"genre\">Genre</label>\n <input type=\"text\" id=\"genre\" name=\"genre\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"isbn\">ISBN</label>\n <input type=\"text\" id=\"isbn\" name=\"isbn\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"publishedYear\">Published Year</label>\n <input type=\"number\" id=\"publishedYear\" name=\"publishedYear\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"inStock\">In Stock</label>\n <select id=\"inStock\" name=\"inStock\">\n <option value=\"true\">Yes</option>\n <option value=\"false\">No</option>\n </select>\n </div>\n\n <div class=\"form-group\">\n <label for=\"cover\">Book Cover Image</label>\n <input type=\"file\" id=\"cover\" name=\"cover\" accept=\"image/*\" />\n <small mix={[css({ color: '#666' })]}>\n Optional. Upload a cover image for this book.\n </small>\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Create Book\n </button>\n <a\n href={routes.admin.books.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Cancel\n </a>\n </form>\n </div>\n </Layout>,\n )\n },\n\n async create({ get }) {\n let db = get(Database)\n let formData = get(FormData)\n let { author, cover, description, genre, inStock, isbn, price, publishedYear, slug, title } =\n s.parse(bookSchema, formData)\n\n await db.create(books, {\n slug,\n title,\n author,\n description,\n price: parseFloat(price),\n genre,\n cover_url: cover ?? '/images/placeholder.jpg',\n image_urls: JSON.stringify([]),\n isbn,\n published_year: parseInt(publishedYear, 10),\n in_stock: inStock,\n })\n\n return redirect(routes.admin.books.index.href())\n },\n\n async edit({ get, params }) {\n let db = get(Database)\n let bookId = parseId(params.bookId)\n let book = bookId === undefined ? undefined : await db.find(books, bookId)\n\n if (!book) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Book Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n return render(\n <Layout>\n <h1>Edit Book</h1>\n\n <div class=\"card\">\n <RestfulForm\n method=\"PUT\"\n action={routes.admin.books.update.href({ bookId: book.id })}\n encType=\"multipart/form-data\"\n >\n <div class=\"form-group\">\n <label for=\"title\">Title</label>\n <input type=\"text\" id=\"title\" name=\"title\" value={book.title} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"author\">Author</label>\n <input type=\"text\" id=\"author\" name=\"author\" value={book.author} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"slug\">Slug (URL-friendly name)</label>\n <input type=\"text\" id=\"slug\" name=\"slug\" value={book.slug} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"description\">Description</label>\n <textarea id=\"description\" name=\"description\" required>\n {book.description}\n </textarea>\n </div>\n\n <div class=\"form-group\">\n <label for=\"price\">Price</label>\n <input\n type=\"number\"\n id=\"price\"\n name=\"price\"\n step=\"0.01\"\n value={book.price}\n required\n />\n </div>\n\n <div class=\"form-group\">\n <label for=\"genre\">Genre</label>\n <input type=\"text\" id=\"genre\" name=\"genre\" value={book.genre} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"isbn\">ISBN</label>\n <input type=\"text\" id=\"isbn\" name=\"isbn\" value={book.isbn} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"publishedYear\">Published Year</label>\n <input\n type=\"number\"\n id=\"publishedYear\"\n name=\"publishedYear\"\n value={book.published_year}\n required\n />\n </div>\n\n <div class=\"form-group\">\n <label for=\"inStock\">In Stock</label>\n <select id=\"inStock\" name=\"inStock\">\n <option value=\"true\" selected={book.in_stock}>\n Yes\n </option>\n <option value=\"false\" selected={!book.in_stock}>\n No\n </option>\n </select>\n </div>\n\n <div class=\"form-group\">\n <label for=\"cover\">Book Cover Image</label>\n {book.cover_url !== '/images/placeholder.jpg' && (\n <div mix={[css({ marginBottom: '0.5rem' })]}>\n <img\n src={book.cover_url}\n alt={book.title}\n mix={[css({ maxWidth: '200px', height: 'auto', borderRadius: '4px' })]}\n />\n <p mix={[css({ fontSize: '0.875rem', color: '#666' })]}>Current cover image</p>\n </div>\n )}\n <input type=\"file\" id=\"cover\" name=\"cover\" accept=\"image/*\" />\n <small mix={[css({ color: '#666' })]}>\n Optional. Upload a new cover image to replace the current one.\n </small>\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Update Book\n </button>\n <a\n href={routes.admin.books.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Cancel\n </a>\n </RestfulForm>\n </div>\n </Layout>,\n )\n },\n\n async update({ get, params }) {\n let db = get(Database)\n let formData = get(FormData)\n let bookId = parseId(params.bookId)\n let book = bookId === undefined ? undefined : await db.find(books, bookId)\n if (!book) {\n return new Response('Book not found', { status: 404 })\n }\n\n let { author, cover, description, genre, inStock, isbn, price, publishedYear, slug, title } =\n s.parse(bookSchema, formData)\n\n // The uploadHandler automatically saves the file and returns the URL path\n // If no file was uploaded, keep the existing cover_url\n let cover_url = cover || book.cover_url\n\n await db.update(books, book.id, {\n slug,\n title,\n author,\n description,\n price: parseFloat(price),\n genre,\n cover_url,\n isbn,\n published_year: parseInt(publishedYear, 10),\n in_stock: inStock,\n })\n\n return redirect(routes.admin.books.index.href())\n },\n\n async destroy({ get, params }) {\n let db = get(Database)\n let bookId = parseId(params.bookId)\n let book = bookId === undefined ? undefined : await db.find(books, bookId)\n if (book) {\n await db.delete(books, book.id)\n }\n\n return redirect(routes.admin.books.index.href())\n },\n },\n} satisfies Controller<typeof routes.admin.books>\n" }, { "path": "demos/bookstore/app/admin.orders.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport { Database } from 'remix/data-table'\n\nimport { routes } from './routes.ts'\nimport { orders, orderItemsWithBook } from './data/schema.ts'\nimport { Layout } from './layout.tsx'\nimport { parseId } from './utils/ids.ts'\nimport { render } from './utils/render.ts'\n\nexport default {\n actions: {\n async index({ get }) {\n let db = get(Database)\n let allOrders = await db.findMany(orders, {\n orderBy: ['created_at', 'asc'],\n with: { items: orderItemsWithBook },\n })\n\n return render(\n <Layout>\n <h1>Manage Orders</h1>\n\n <p mix={[css({ marginBottom: '1rem' })]}>\n <a href={routes.admin.index.href()} class=\"btn btn-secondary\">\n Back to Dashboard\n </a>\n </p>\n\n <div class=\"card\">\n <table>\n <thead>\n <tr>\n <th>Order ID</th>\n <th>Date</th>\n <th>Items</th>\n <th>Total</th>\n <th>Status</th>\n <th>Actions</th>\n </tr>\n </thead>\n <tbody>\n {allOrders.map((order) => (\n <tr>\n <td>#{order.id}</td>\n <td>{new Date(order.created_at).toLocaleDateString()}</td>\n <td>{order.items.length} item(s)</td>\n <td>${order.total.toFixed(2)}</td>\n <td>\n <span class=\"badge badge-info\">{order.status}</span>\n </td>\n <td>\n <a\n href={routes.admin.orders.show.href({ orderId: order.id })}\n class=\"btn btn-secondary\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n View\n </a>\n </td>\n </tr>\n ))}\n </tbody>\n </table>\n </div>\n </Layout>,\n )\n },\n\n async show({ get, params }) {\n let db = get(Database)\n let orderId = parseId(params.orderId)\n let order =\n orderId === undefined\n ? undefined\n : await db.find(orders, orderId, {\n with: { items: orderItemsWithBook },\n })\n\n if (!order) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Order Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n let shippingAddress = JSON.parse(order.shipping_address_json) as {\n street: string\n city: string\n state: string\n zip: string\n }\n\n return render(\n <Layout>\n <h1>Order #{order.id}</h1>\n\n <div class=\"card\">\n <p>\n <strong>Order Date:</strong> {new Date(order.created_at).toLocaleDateString()}\n </p>\n <p>\n <strong>User ID:</strong> {order.user_id}\n </p>\n <p>\n <strong>Status:</strong> <span class=\"badge badge-info\">{order.status}</span>\n </p>\n\n <h2 mix={[css({ marginTop: '2rem' })]}>Items</h2>\n <table mix={[css({ marginTop: '1rem' })]}>\n <thead>\n <tr>\n <th>Book</th>\n <th>Quantity</th>\n <th>Price</th>\n <th>Subtotal</th>\n </tr>\n </thead>\n <tbody>\n {order.items.map((item) => (\n <tr>\n <td>{item.title}</td>\n <td>{item.quantity}</td>\n <td>${item.unit_price.toFixed(2)}</td>\n <td>${(item.unit_price * item.quantity).toFixed(2)}</td>\n </tr>\n ))}\n </tbody>\n <tfoot>\n <tr>\n <td colSpan={3} mix={[css({ textAlign: 'right', fontWeight: 'bold' })]}>\n Total:\n </td>\n <td mix={[css({ fontWeight: 'bold' })]}>${order.total.toFixed(2)}</td>\n </tr>\n </tfoot>\n </table>\n\n <h2 mix={[css({ marginTop: '2rem' })]}>Shipping Address</h2>\n <p>{shippingAddress.street}</p>\n <p>\n {shippingAddress.city}, {shippingAddress.state} {shippingAddress.zip}\n </p>\n </div>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.admin.orders.index.href()} class=\"btn btn-secondary\">\n Back to Orders\n </a>\n </p>\n </Layout>,\n )\n },\n },\n} satisfies Controller<typeof routes.admin.orders>\n" }, { "path": "demos/bookstore/app/admin.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { loginAsCustomer, requestWithSession } from '../test/helpers.ts'\n\ndescribe('admin handlers', () => {\n it('GET /admin redirects when not authenticated', async () => {\n let response = await router.fetch('https://remix.run/admin')\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login?returnTo=%2Fadmin')\n })\n\n it('GET /admin returns 403 for non-admin users', async () => {\n let sessionId = await loginAsCustomer(router)\n\n // Try to access admin\n let request = requestWithSession('https://remix.run/admin', sessionId)\n let response = await router.fetch(request)\n\n assert.equal(response.status, 403)\n })\n})\n" }, { "path": "demos/bookstore/app/admin.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\n\nimport { routes } from './routes.ts'\nimport { Layout } from './layout.tsx'\nimport { requireAuth } from './middleware/auth.ts'\nimport { requireAdmin } from './middleware/admin.ts'\nimport { render } from './utils/render.ts'\n\nimport adminBooksController from './admin.books.tsx'\nimport adminOrdersController from './admin.orders.tsx'\nimport adminUsersController from './admin.users.tsx'\n\nexport default {\n middleware: [requireAuth(), requireAdmin()],\n actions: {\n index() {\n return render(\n <Layout>\n <h1>Admin Dashboard</h1>\n\n <div\n mix={[\n css({\n display: 'grid',\n gridTemplateColumns: 'repeat(auto-fit, minmax(300px, 1fr))',\n gap: '1.5rem',\n }),\n ]}\n >\n <div class=\"card\">\n <h2>Manage Books</h2>\n <p>Add, edit, or remove books from the catalog.</p>\n <a\n href={routes.admin.books.index.href()}\n class=\"btn\"\n mix={[css({ marginTop: '1rem' })]}\n >\n View Books\n </a>\n </div>\n\n <div class=\"card\">\n <h2>Manage Users</h2>\n <p>View and manage user accounts.</p>\n <a\n href={routes.admin.users.index.href()}\n class=\"btn\"\n mix={[css({ marginTop: '1rem' })]}\n >\n View Users\n </a>\n </div>\n\n <div class=\"card\">\n <h2>View Orders</h2>\n <p>Monitor and manage customer orders.</p>\n <a\n href={routes.admin.orders.index.href()}\n class=\"btn\"\n mix={[css({ marginTop: '1rem' })]}\n >\n View Orders\n </a>\n </div>\n </div>\n </Layout>,\n )\n },\n\n books: adminBooksController,\n users: adminUsersController,\n orders: adminOrdersController,\n },\n} satisfies Controller<typeof routes.admin>\n" }, { "path": "demos/bookstore/app/admin.users.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport { Database } from 'remix/data-table'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\nimport { users } from './data/schema.ts'\nimport { Layout } from './layout.tsx'\nimport { render } from './utils/render.ts'\nimport { getCurrentUser } from './utils/context.ts'\nimport { parseId } from './utils/ids.ts'\nimport { RestfulForm } from './components/restful-form.tsx'\n\nconst textField = f.field(s.defaulted(s.string(), ''))\nconst roleField = f.field(\n s.defaulted(s.union([s.literal('customer'), s.literal('admin')]), 'customer'),\n)\nconst userSchema = f.object({\n name: textField,\n email: textField,\n role: roleField,\n})\n\nexport default {\n actions: {\n async index({ get }) {\n let db = get(Database)\n let user = getCurrentUser()\n let allUsers = await db.findMany(users, { orderBy: ['id', 'asc'] })\n\n return render(\n <Layout>\n <h1>Manage Users</h1>\n\n <p mix={[css({ marginBottom: '1rem' })]}>\n <a href={routes.admin.index.href()} class=\"btn btn-secondary\">\n Back to Dashboard\n </a>\n </p>\n\n <div class=\"card\">\n <table>\n <thead>\n <tr>\n <th>Name</th>\n <th>Email</th>\n <th>Role</th>\n <th>Created</th>\n <th>Actions</th>\n </tr>\n </thead>\n <tbody>\n {allUsers.map((u) => (\n <tr>\n <td>{u.name}</td>\n <td>{u.email}</td>\n <td>\n <span class={`badge ${u.role === 'admin' ? 'badge-info' : 'badge-success'}`}>\n {u.role}\n </span>\n </td>\n <td>{new Date(u.created_at).toLocaleDateString()}</td>\n <td class=\"actions\">\n <a\n href={routes.admin.users.edit.href({ userId: u.id })}\n class=\"btn btn-secondary\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n Edit\n </a>\n {u.id !== user.id ? (\n <RestfulForm\n method=\"DELETE\"\n action={routes.admin.users.destroy.href({ userId: u.id })}\n mix={[css({ display: 'inline' })]}\n >\n <button\n type=\"submit\"\n class=\"btn btn-danger\"\n mix={[css({ fontSize: '0.875rem', padding: '0.25rem 0.5rem' })]}\n >\n Delete\n </button>\n </RestfulForm>\n ) : null}\n </td>\n </tr>\n ))}\n </tbody>\n </table>\n </div>\n </Layout>,\n )\n },\n\n async show({ get, params }) {\n let db = get(Database)\n let userId = parseId(params.userId)\n let targetUser = userId === undefined ? undefined : await db.find(users, userId)\n\n if (!targetUser) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>User Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n return render(\n <Layout>\n <h1>User Details</h1>\n\n <div class=\"card\">\n <p>\n <strong>Name:</strong> {targetUser.name}\n </p>\n <p>\n <strong>Email:</strong> {targetUser.email}\n </p>\n <p>\n <strong>Role:</strong>{' '}\n <span class={`badge ${targetUser.role === 'admin' ? 'badge-info' : 'badge-success'}`}>\n {targetUser.role}\n </span>\n </p>\n <p>\n <strong>Created:</strong> {new Date(targetUser.created_at).toLocaleDateString()}\n </p>\n\n <div mix={[css({ marginTop: '2rem' })]}>\n <a href={routes.admin.users.edit.href({ userId: targetUser.id })} class=\"btn\">\n Edit\n </a>\n <a\n href={routes.admin.users.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Back to List\n </a>\n </div>\n </div>\n </Layout>,\n )\n },\n\n async edit({ get, params }) {\n let db = get(Database)\n let userId = parseId(params.userId)\n let targetUser = userId === undefined ? undefined : await db.find(users, userId)\n\n if (!targetUser) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>User Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n return render(\n <Layout>\n <h1>Edit User</h1>\n\n <div class=\"card\">\n <RestfulForm\n method=\"PUT\"\n action={routes.admin.users.update.href({ userId: targetUser.id })}\n >\n <div class=\"form-group\">\n <label for=\"name\">Name</label>\n <input type=\"text\" id=\"name\" name=\"name\" value={targetUser.name} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"email\">Email</label>\n <input type=\"email\" id=\"email\" name=\"email\" value={targetUser.email} required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"role\">Role</label>\n <select id=\"role\" name=\"role\">\n <option value=\"customer\" selected={targetUser.role === 'customer'}>\n Customer\n </option>\n <option value=\"admin\" selected={targetUser.role === 'admin'}>\n Admin\n </option>\n </select>\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Update User\n </button>\n <a\n href={routes.admin.users.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Cancel\n </a>\n </RestfulForm>\n </div>\n </Layout>,\n )\n },\n\n async update({ get, params }) {\n let db = get(Database)\n let formData = get(FormData)\n let userId = parseId(params.userId)\n let targetUser = userId === undefined ? undefined : await db.find(users, userId)\n let { email, name, role } = s.parse(userSchema, formData)\n\n if (targetUser) {\n await db.update(users, targetUser.id, {\n name,\n email,\n role,\n })\n }\n\n return redirect(routes.admin.users.index.href())\n },\n\n async destroy({ get, params }) {\n let db = get(Database)\n let userId = parseId(params.userId)\n let targetUser = userId === undefined ? undefined : await db.find(users, userId)\n if (targetUser) {\n await db.delete(users, targetUser.id)\n }\n\n return redirect(routes.admin.users.index.href())\n },\n },\n} satisfies Controller<typeof routes.admin.users>\n" }, { "path": "demos/bookstore/app/assets/cart-button.tsx", "content": "import { type Handle, clientEntry, on } from 'remix/component'\n\nimport { routes } from '../routes.ts'\n\nlet moduleUrl = routes.assets.href({ path: 'cart-button.js#CartButton' })\n\nexport const CartButton = clientEntry(moduleUrl, (handle: Handle) => {\n let pending = false\n\n return ({ inCart, id, slug }: { inCart: boolean; id: string | number; slug: string }) => (\n <button\n type=\"button\"\n mix={[\n on('click', async (_event, signal) => {\n pending = true\n handle.update()\n\n let formData = new FormData()\n formData.set('bookId', String(id))\n formData.set('slug', slug)\n\n await fetch(routes.api.cartToggle.href(), {\n method: 'POST',\n body: formData,\n signal,\n })\n\n await handle.frame.reload()\n await new Promise((resolve) => setTimeout(resolve, 500))\n if (signal.aborted) return\n pending = false\n handle.update()\n }),\n ]}\n class=\"btn\"\n >\n {pending ? 'Saving...' : inCart ? 'Remove from Cart' : 'Add to Cart'}\n </button>\n )\n})\n" }, { "path": "demos/bookstore/app/assets/cart-items.tsx", "content": "import { css, type Handle, clientEntry, on } from 'remix/component'\n\nimport { routes } from '../routes.ts'\n\nlet moduleUrl = routes.assets.href({ path: 'cart-items.js#CartItems' })\n\ntype CartItem = {\n bookId: number\n slug: string\n title: string\n price: number\n quantity: number\n}\n\ntype CartItemsProps = {\n items: CartItem[]\n total: number\n canCheckout: boolean\n}\n\ntype PendingAction = {\n type: 'update' | 'remove'\n bookId: number\n} | null\n\nexport let CartItems = clientEntry(moduleUrl, (handle: Handle) => {\n let pendingAction: PendingAction = null\n\n let submit = async (form: HTMLFormElement, signal: AbortSignal, nextAction: PendingAction) => {\n if (pendingAction) return\n\n pendingAction = nextAction\n handle.update()\n\n try {\n let formData = new FormData(form)\n formData.set('redirect', 'none')\n\n await fetch(form.action, {\n method: 'POST',\n body: formData,\n signal,\n })\n\n if (signal.aborted) return\n\n await handle.frame.reload()\n } finally {\n pendingAction = null\n handle.update()\n }\n }\n\n return ({ items, total, canCheckout }: CartItemsProps) => {\n let isPending = pendingAction !== null\n let totalLabel = isPending ? '---' : `$${total.toFixed(2)}`\n\n return (\n <>\n {isPending ? (\n <p mix={[css({ marginBottom: '1rem', fontSize: '0.9rem', color: '#666' })]}>\n Updating your cart...\n </p>\n ) : null}\n\n <table>\n <thead>\n <tr>\n <th>Book</th>\n <th>Price</th>\n <th>Quantity</th>\n <th>Subtotal</th>\n <th>Actions</th>\n </tr>\n </thead>\n <tbody>\n {items.map((item) => {\n let isUpdating =\n pendingAction?.type === 'update' && pendingAction.bookId === item.bookId\n let isRemoving =\n pendingAction?.type === 'remove' && pendingAction.bookId === item.bookId\n\n return (\n <tr key={item.bookId}>\n <td>\n <a href={routes.books.show.href({ slug: item.slug })}>{item.title}</a>\n </td>\n\n <td>${item.price.toFixed(2)}</td>\n\n <td>\n <form\n method=\"POST\"\n action={routes.cart.api.update.href()}\n mix={[\n on('submit', async (event, signal) => {\n event.preventDefault()\n await submit(event.currentTarget, signal, {\n type: 'update',\n bookId: item.bookId,\n })\n }),\n css({ display: 'inline-flex', gap: '0.5rem', alignItems: 'center' }),\n ]}\n >\n <input type=\"hidden\" name=\"_method\" value=\"PUT\" />\n <input type=\"hidden\" name=\"bookId\" value={item.bookId} />\n\n <input\n type=\"number\"\n name=\"quantity\"\n defaultValue={item.quantity}\n min=\"1\"\n disabled={isPending}\n mix={[css({ width: '70px' })]}\n />\n\n <button\n type=\"submit\"\n disabled={isPending}\n class=\"btn btn-secondary\"\n mix={[\n css({\n fontSize: '0.875rem',\n padding: '0.25rem 0.5rem',\n minWidth: '6.25rem',\n textAlign: 'center',\n }),\n ]}\n >\n {isUpdating ? 'Saving...' : 'Update'}\n </button>\n </form>\n </td>\n\n <td>${(item.price * item.quantity).toFixed(2)}</td>\n\n <td>\n <form\n method=\"POST\"\n action={routes.cart.api.remove.href()}\n mix={[\n on('submit', async (event, signal) => {\n event.preventDefault()\n await submit(event.currentTarget, signal, {\n type: 'remove',\n bookId: item.bookId,\n })\n }),\n css({ display: 'inline' }),\n ]}\n >\n <input type=\"hidden\" name=\"_method\" value=\"DELETE\" />\n <input type=\"hidden\" name=\"bookId\" value={item.bookId} />\n\n <button\n type=\"submit\"\n disabled={isPending}\n class=\"btn btn-danger\"\n mix={[\n css({\n fontSize: '0.875rem',\n padding: '0.25rem 0.5rem',\n minWidth: '7rem',\n textAlign: 'center',\n }),\n ]}\n >\n {isRemoving ? 'Removing...' : 'Remove'}\n </button>\n </form>\n </td>\n </tr>\n )\n })}\n </tbody>\n </table>\n\n <div mix={[css({ marginTop: '2rem', display: 'flex', alignItems: 'center', gap: '1rem' })]}>\n <p\n mix={[css({ margin: 0, fontSize: '1.25rem', fontWeight: 'bold', marginRight: 'auto' })]}\n >\n Total: {totalLabel}\n </p>\n\n <a href={routes.books.index.href()} class=\"btn btn-secondary\">\n Continue Shopping\n </a>\n\n {canCheckout ? (\n <a href={routes.checkout.index.href()} class=\"btn\">\n Proceed to Checkout\n </a>\n ) : (\n <a href={routes.auth.login.index.href()} class=\"btn\">\n Login to Checkout\n </a>\n )}\n </div>\n </>\n )\n }\n})\n" }, { "path": "demos/bookstore/app/assets/entry.tsx", "content": "import { run } from 'remix/component'\n\nlet app = run({\n async loadModule(moduleUrl: string, exportName: string) {\n let mod = await import(moduleUrl)\n let Component = (mod as any)[exportName]\n if (!Component) {\n throw new Error(`Unknown component: ${moduleUrl}#${exportName}`)\n }\n return Component\n },\n async resolveFrame(src, signal) {\n let response = await fetch(src, { headers: { accept: 'text/html' }, signal })\n if (!response.ok) {\n return `<pre>Frame error: ${response.status} ${response.statusText}</pre>`\n }\n // let text = await response.text()\n // console.log(text)\n // return text\n if (response.body) return response.body\n return response.text()\n },\n})\n\napp.ready().catch((error: unknown) => {\n console.error('Frame adoption failed:', error)\n})\n" }, { "path": "demos/bookstore/app/assets/image-carousel.tsx", "content": "import { css, type Handle, clientEntry, on } from 'remix/component'\n\nimport { routes } from '../routes.ts'\n\nexport const ImageCarousel = clientEntry(\n routes.assets.href({ path: 'image-carousel.js#ImageCarousel' }),\n function ImageCarousel(handle: Handle, setup?: { startIndex?: number }) {\n let index = setup?.startIndex ?? 0\n\n let goPrev = (total: number) => {\n if (index <= 0) return\n index = index - 1\n handle.update()\n }\n\n let goNext = (total: number) => {\n if (index >= total - 1) return\n index = index + 1\n handle.update()\n }\n\n return ({ images }: { images: string[] }) => {\n let total = images.length\n if (total === 0) return null\n if (index > total - 1) index = total - 1\n if (index < 0) index = 0\n\n return (\n <div\n mix={[\n css({\n position: 'relative',\n width: '100%',\n height: '100%',\n overflow: 'hidden',\n backgroundColor: '#f5f5f5',\n }),\n ]}\n >\n <div\n mix={[\n css({\n display: 'flex',\n height: '100%',\n width: '100%',\n transition: 'transform 350ms cubic-bezier(0.22, 1, 0.36, 1)',\n willChange: 'transform',\n }),\n ]}\n style={{\n transform: `translateX(-${index * 100}%)`,\n }}\n >\n {images.map((src, i) => (\n <div\n key={src + i}\n mix={[\n css({\n minWidth: '100%',\n height: '100%',\n position: 'relative',\n }),\n ]}\n >\n <img\n src={src}\n alt={`Image ${i + 1} of ${total}`}\n mix={[\n css({\n width: '100%',\n height: '100%',\n objectFit: 'cover',\n display: 'block',\n userSelect: 'none',\n pointerEvents: 'none',\n }),\n ]}\n draggable={false}\n />\n </div>\n ))}\n </div>\n\n <button\n aria-label=\"Previous image\"\n disabled={index === 0}\n mix={[\n on('click', () => goPrev(total)),\n css({\n position: 'absolute',\n top: '50%',\n left: '8px',\n transform: 'translateY(-50%)',\n width: '40px',\n height: '40px',\n display: 'flex',\n alignItems: 'center',\n justifyContent: 'center',\n background: 'transparent',\n color: 'white',\n border: 'none',\n borderRadius: '999px',\n cursor: 'pointer',\n outline: 'none',\n transition: 'background-color 150ms ease, opacity 150ms ease',\n }),\n ]}\n style={{\n opacity: index === 0 ? 0.4 : 0.9,\n }}\n >\n <span mix={[css({ fontSize: '22px', lineHeight: '1' })]}>{'‹'}</span>\n </button>\n\n <button\n aria-label=\"Next image\"\n disabled={index === total - 1}\n mix={[\n on('click', () => goNext(total)),\n css({\n position: 'absolute',\n top: '50%',\n right: '8px',\n transform: 'translateY(-50%)',\n width: '40px',\n height: '40px',\n display: 'flex',\n alignItems: 'center',\n justifyContent: 'center',\n background: 'transparent',\n color: 'white',\n border: 'none',\n borderRadius: '999px',\n cursor: 'pointer',\n outline: 'none',\n transition: 'background-color 150ms ease, opacity 150ms ease',\n }),\n ]}\n style={{\n opacity: index === total - 1 ? 0.4 : 0.9,\n }}\n >\n <span mix={[css({ fontSize: '22px', lineHeight: '1' })]}>{'›'}</span>\n </button>\n </div>\n )\n }\n },\n)\n" }, { "path": "demos/bookstore/app/auth.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { getSessionCookie, assertContains } from '../test/helpers.ts'\n\ndescribe('auth handlers', () => {\n it('POST /login with valid credentials sets session cookie and redirects', async () => {\n let response = await router.fetch('https://remix.run/login', {\n method: 'POST',\n body: new URLSearchParams({\n email: 'admin@bookstore.com',\n password: 'admin123',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/account')\n\n let sessionId = getSessionCookie(response)\n assert.ok(sessionId, 'Expected session cookie to be set')\n })\n\n it('POST /login with invalid credentials redirects back to login with error', async () => {\n let response = await router.fetch('https://remix.run/login', {\n method: 'POST',\n body: new URLSearchParams({\n email: 'wrong@example.com',\n password: 'wrongpassword',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login')\n\n // Follow redirect to see the error message\n let sessionCookie = getSessionCookie(response)\n let followUpResponse = await router.fetch('https://remix.run/login', {\n headers: {\n Cookie: `session=${sessionCookie}`,\n },\n })\n\n let html = await followUpResponse.text()\n assertContains(html, 'Invalid email or password')\n })\n\n it('POST /login does not treat wildcard characters as email matches', async () => {\n let response = await router.fetch('https://remix.run/login', {\n method: 'POST',\n body: new URLSearchParams({\n email: '%@bookstore.com',\n password: 'admin123',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login')\n })\n\n it('flash error message is cleared after being displayed once', async () => {\n // POST invalid credentials to trigger flash message\n let response = await router.fetch('https://remix.run/login', {\n method: 'POST',\n body: new URLSearchParams({\n email: 'wrong@example.com',\n password: 'wrongpassword',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login')\n\n // Follow redirect to see the error message (first request)\n let sessionCookie = getSessionCookie(response)\n let firstFollowUp = await router.fetch('https://remix.run/login', {\n headers: {\n Cookie: `session=${sessionCookie}`,\n },\n })\n\n let firstHtml = await firstFollowUp.text()\n assertContains(firstHtml, 'Invalid email or password')\n\n // Get updated session cookie (session should be updated to clear flash)\n let updatedSessionCookie = getSessionCookie(firstFollowUp) || sessionCookie\n\n // Refresh the page (second request) - error should NOT be shown\n let secondFollowUp = await router.fetch('https://remix.run/login', {\n headers: {\n Cookie: `session=${updatedSessionCookie}`,\n },\n })\n\n let secondHtml = await secondFollowUp.text()\n assert.ok(\n !secondHtml.includes('Invalid email or password'),\n 'Expected flash error to be cleared after first display',\n )\n })\n\n it('POST /register creates new user and sets session', async () => {\n let uniqueEmail = `newuser-${Date.now()}@example.com`\n\n let response = await router.fetch('https://remix.run/register', {\n method: 'POST',\n body: new URLSearchParams({\n name: 'New User',\n email: uniqueEmail,\n password: 'password123',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/account')\n\n let sessionId = getSessionCookie(response)\n assert.ok(sessionId, 'Expected session cookie to be set')\n })\n\n it('accessing protected route redirects to login with returnTo parameter', async () => {\n let response = await router.fetch('https://remix.run/checkout', {\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n let location = response.headers.get('Location')\n assert.ok(location, 'Expected Location header')\n assert.ok(location.startsWith('/login?returnTo='), 'Expected redirect to login with returnTo')\n assert.ok(\n location.includes(encodeURIComponent('/checkout')),\n 'Expected returnTo to contain /checkout',\n )\n })\n\n it('successful login with returnTo redirects to original destination', async () => {\n let response = await router.fetch(\n 'https://remix.run/login?returnTo=' + encodeURIComponent('/checkout'),\n {\n method: 'POST',\n body: new URLSearchParams({\n email: 'customer@example.com',\n password: 'password123',\n }),\n redirect: 'manual',\n },\n )\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/checkout')\n\n let sessionId = getSessionCookie(response)\n assert.ok(sessionId, 'Expected session cookie to be set')\n })\n\n it('failed login with returnTo preserves returnTo parameter', async () => {\n let response = await router.fetch(\n 'https://remix.run/login?returnTo=' + encodeURIComponent('/checkout'),\n {\n method: 'POST',\n body: new URLSearchParams({\n email: 'wrong@example.com',\n password: 'wrongpassword',\n }),\n redirect: 'manual',\n },\n )\n\n assert.equal(response.status, 302)\n let location = response.headers.get('Location')\n assert.ok(location, 'Expected Location header')\n assert.ok(\n location.includes('returnTo=' + encodeURIComponent('/checkout')),\n 'Expected returnTo to be preserved in redirect',\n )\n\n // Follow redirect to verify error message is shown\n let sessionCookie = getSessionCookie(response)\n let followUpResponse = await router.fetch('https://remix.run' + location, {\n headers: {\n Cookie: `session=${sessionCookie}`,\n },\n })\n\n let html = await followUpResponse.text()\n assertContains(html, 'Invalid email or password')\n assertContains(html, 'returnTo=' + encodeURIComponent('/checkout'))\n })\n\n it('POST /reset-password with mismatched passwords redirects back with error', async () => {\n // First, request a password reset to get a token\n let forgotPasswordResponse = await router.fetch('https://remix.run/forgot-password', {\n method: 'POST',\n body: new URLSearchParams({\n email: 'customer@example.com',\n }),\n })\n\n let html = await forgotPasswordResponse.text()\n // Extract token from the reset link in the demo response\n let tokenMatch = html.match(/\\/reset-password\\/([^\"]+)/)\n assert.ok(tokenMatch, 'Expected to find reset token in response')\n let token = tokenMatch[1]\n\n // Try to reset password with mismatched passwords\n let response = await router.fetch(`https://remix.run/reset-password/${token}`, {\n method: 'POST',\n body: new URLSearchParams({\n password: 'newpassword123',\n confirmPassword: 'differentpassword',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), `/reset-password/${token}`)\n\n // Follow redirect to see the error message\n let sessionCookie = getSessionCookie(response)\n let followUpResponse = await router.fetch(`https://remix.run/reset-password/${token}`, {\n headers: {\n Cookie: `session=${sessionCookie}`,\n },\n })\n\n let errorHtml = await followUpResponse.text()\n assertContains(errorHtml, 'Passwords do not match')\n })\n\n it('POST /reset-password with invalid token redirects back with error', async () => {\n let invalidToken = 'invalid-token-12345'\n\n let response = await router.fetch(`https://remix.run/reset-password/${invalidToken}`, {\n method: 'POST',\n body: new URLSearchParams({\n password: 'newpassword123',\n confirmPassword: 'newpassword123',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), `/reset-password/${invalidToken}`)\n\n // Follow redirect to see the error message\n let sessionCookie = getSessionCookie(response)\n let followUpResponse = await router.fetch(`https://remix.run/reset-password/${invalidToken}`, {\n headers: {\n Cookie: `session=${sessionCookie}`,\n },\n })\n\n let errorHtml = await followUpResponse.text()\n assertContains(errorHtml, 'Invalid or expired reset token')\n })\n})\n" }, { "path": "demos/bookstore/app/auth.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport { Database } from 'remix/data-table'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\nimport { passwordResetTokens, users } from './data/schema.ts'\nimport { Document } from './layout.tsx'\nimport { loadAuth } from './middleware/auth.ts'\nimport { render } from './utils/render.ts'\nimport { Session } from './utils/session.ts'\n\nconst textField = f.field(s.defaulted(s.string(), ''))\nconst loginSchema = f.object({\n email: textField,\n password: textField,\n})\nconst registrationSchema = f.object({\n name: textField,\n email: textField,\n password: textField,\n})\nconst forgotPasswordSchema = f.object({\n email: textField,\n})\nconst resetPasswordSchema = f.object({\n password: textField,\n confirmPassword: textField,\n})\n\nexport default {\n middleware: [loadAuth()],\n actions: {\n login: {\n actions: {\n index({ get, url }) {\n let session = get(Session)\n let error = session.get('error')\n let formAction = routes.auth.login.action.href(undefined, {\n returnTo: url.searchParams.get('returnTo') ?? undefined,\n })\n\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <h1>Login</h1>\n\n {typeof error === 'string' ? (\n <div class=\"alert alert-error\" mix={[css({ marginBottom: '1.5rem' })]}>\n {error}\n </div>\n ) : null}\n\n <form method=\"POST\" action={formAction}>\n <div class=\"form-group\">\n <label for=\"email\">Email</label>\n <input type=\"email\" id=\"email\" name=\"email\" required autoComplete=\"email\" />\n </div>\n\n <div class=\"form-group\">\n <label for=\"password\">Password</label>\n <input\n type=\"password\"\n id=\"password\"\n name=\"password\"\n required\n autoComplete=\"current-password\"\n />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Login\n </button>\n </form>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n Don't have an account?{' '}\n <a href={routes.auth.register.index.href()}>Register here</a>\n </p>\n <p>\n <a href={routes.auth.forgotPassword.index.href()}>Forgot password?</a>\n </p>\n\n <div\n mix={[\n css({\n marginTop: '2rem',\n padding: '1rem',\n background: '#f8f9fa',\n borderRadius: '4px',\n }),\n ]}\n >\n <p mix={[css({ fontSize: '0.9rem' })]}>\n <strong>Demo Accounts:</strong>\n </p>\n <p mix={[css({ fontSize: '0.9rem' })]}>Admin: admin@bookstore.com / admin123</p>\n <p mix={[css({ fontSize: '0.9rem' })]}>\n Customer: customer@example.com / password123\n </p>\n </div>\n </div>\n </Document>,\n )\n },\n\n async action({ get, url }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { email, password } = s.parse(loginSchema, formData)\n let returnTo = url.searchParams.get('returnTo') ?? undefined\n let normalizedEmail = normalizeEmail(email)\n\n let user = await db.findOne(users, { where: { email: normalizedEmail } })\n if (!user || user.password !== password) {\n session.flash('error', 'Invalid email or password. Please try again.')\n return redirect(routes.auth.login.index.href(undefined, { returnTo }))\n }\n\n session.regenerateId(true)\n session.set('userId', user.id)\n\n return redirect(returnTo ?? routes.account.index.href())\n },\n },\n },\n\n register: {\n actions: {\n index() {\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <h1>Register</h1>\n <form method=\"POST\" action={routes.auth.register.action.href()}>\n <div class=\"form-group\">\n <label for=\"name\">Name</label>\n <input type=\"text\" id=\"name\" name=\"name\" required autoComplete=\"name\" />\n </div>\n\n <div class=\"form-group\">\n <label for=\"email\">Email</label>\n <input type=\"email\" id=\"email\" name=\"email\" required autoComplete=\"email\" />\n </div>\n\n <div class=\"form-group\">\n <label for=\"password\">Password</label>\n <input\n type=\"password\"\n id=\"password\"\n name=\"password\"\n required\n autoComplete=\"new-password\"\n />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Register\n </button>\n </form>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n Already have an account? <a href={routes.auth.login.index.href()}>Login here</a>\n </p>\n </div>\n </Document>,\n )\n },\n\n async action({ get }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { email, name, password } = s.parse(registrationSchema, formData)\n let normalizedEmail = normalizeEmail(email)\n\n // Check if user already exists\n if (await db.findOne(users, { where: { email: normalizedEmail } })) {\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <div class=\"alert alert-error\">An account with this email already exists.</div>\n <p>\n <a href={routes.auth.register.index.href()} class=\"btn\">\n Back to Register\n </a>\n <a\n href={routes.auth.login.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Login\n </a>\n </p>\n </div>\n </Document>,\n { status: 400 },\n )\n }\n\n let user = await db.create(\n users,\n {\n email: normalizedEmail,\n password,\n name,\n },\n { returnRow: true },\n )\n\n session.set('userId', user.id)\n\n return redirect(routes.account.index.href())\n },\n },\n },\n\n logout({ get }) {\n let session = get(Session)\n session.destroy()\n return redirect(routes.home.href())\n },\n\n forgotPassword: {\n actions: {\n index() {\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <h1>Forgot Password</h1>\n <p>Enter your email address and we'll send you a link to reset your password.</p>\n\n <form method=\"POST\" action={routes.auth.forgotPassword.action.href()}>\n <div class=\"form-group\">\n <label for=\"email\">Email</label>\n <input type=\"email\" id=\"email\" name=\"email\" required autoComplete=\"email\" />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Send Reset Link\n </button>\n </form>\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.auth.login.index.href()}>Back to Login</a>\n </p>\n </div>\n </Document>,\n )\n },\n\n async action({ get }) {\n let db = get(Database)\n let formData = get(FormData)\n let { email } = s.parse(forgotPasswordSchema, formData)\n let normalizedEmail = normalizeEmail(email)\n let user = await db.findOne(users, { where: { email: normalizedEmail } })\n let token = undefined as string | undefined\n\n if (user) {\n token = Math.random().toString(36).substring(2, 15)\n await db.create(passwordResetTokens, {\n token,\n user_id: user.id,\n expires_at: Date.now() + 3600000,\n })\n }\n\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <div class=\"alert alert-success\">Password reset link sent! Check your email.</div>\n\n {token ? (\n <div\n mix={[\n css({\n marginTop: '1rem',\n padding: '1rem',\n background: '#f8f9fa',\n borderRadius: '4px',\n }),\n ]}\n >\n <p mix={[css({ fontSize: '0.9rem' })]}>\n <strong>Demo Mode:</strong> Click the link below to reset your password\n </p>\n <p mix={[css({ marginTop: '0.5rem' })]}>\n <a\n href={routes.auth.resetPassword.index.href({ token })}\n class=\"btn btn-secondary\"\n >\n Reset Password\n </a>\n </p>\n </div>\n ) : null}\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.auth.login.index.href()} class=\"btn\">\n Back to Login\n </a>\n </p>\n </div>\n </Document>,\n )\n },\n },\n },\n\n resetPassword: {\n actions: {\n index({ params, get }) {\n let session = get(Session)\n let token = params.token\n let error = session.get('error')\n\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <h1>Reset Password</h1>\n <p>Enter your new password below.</p>\n\n {typeof error === 'string' ? (\n <div class=\"alert alert-error\" mix={[css({ marginBottom: '1.5rem' })]}>\n {error}\n </div>\n ) : null}\n\n <form method=\"POST\" action={routes.auth.resetPassword.action.href({ token })}>\n <div class=\"form-group\">\n <label for=\"password\">New Password</label>\n <input\n type=\"password\"\n id=\"password\"\n name=\"password\"\n required\n autoComplete=\"new-password\"\n />\n </div>\n\n <div class=\"form-group\">\n <label for=\"confirmPassword\">Confirm Password</label>\n <input\n type=\"password\"\n id=\"confirmPassword\"\n name=\"confirmPassword\"\n required\n autoComplete=\"new-password\"\n />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Reset Password\n </button>\n </form>\n </div>\n </Document>,\n )\n },\n\n async action({ get, params }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { confirmPassword, password } = s.parse(resetPasswordSchema, formData)\n let token = params.token\n\n if (!token) {\n session.flash('error', 'Invalid or expired reset token.')\n return redirect(routes.auth.forgotPassword.index.href())\n }\n\n if (password !== confirmPassword) {\n session.flash('error', 'Passwords do not match.')\n return redirect(routes.auth.resetPassword.index.href({ token }))\n }\n\n let tokenData = await db.find(passwordResetTokens, { token })\n\n if (!tokenData || tokenData.expires_at < Date.now()) {\n session.flash('error', 'Invalid or expired reset token.')\n return redirect(routes.auth.resetPassword.index.href({ token }))\n }\n\n let user = await db.find(users, tokenData.user_id)\n if (!user) {\n session.flash('error', 'Invalid or expired reset token.')\n return redirect(routes.auth.resetPassword.index.href({ token }))\n }\n\n await db.update(users, user.id, { password })\n await db.delete(passwordResetTokens, { token })\n\n return render(\n <Document>\n <div class=\"card\" mix={[css({ maxWidth: '500px', margin: '2rem auto' })]}>\n <div class=\"alert alert-success\">\n Password reset successfully! You can now login with your new password.\n </div>\n <p>\n <a href={routes.auth.login.index.href()} class=\"btn\">\n Login\n </a>\n </p>\n </div>\n </Document>,\n )\n },\n },\n },\n },\n} satisfies Controller<typeof routes.auth>\n\nfunction normalizeEmail(email: string): string {\n return email.trim().toLowerCase()\n}\n" }, { "path": "demos/bookstore/app/books.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { assertContains } from '../test/helpers.ts'\n\ndescribe('books handlers', () => {\n it('GET /books returns list of books', async () => {\n let response = await router.fetch('https://remix.run/books')\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, 'Browse Books')\n assertContains(html, 'Ash & Smoke')\n assertContains(html, 'Heavy Metal Guitar Riffs')\n assertContains(html, 'Three Ways to Change Your Life')\n })\n\n it('GET /books/:slug returns book details', async () => {\n let response = await router.fetch('https://remix.run/books/bbq')\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, 'Ash & Smoke')\n assertContains(html, 'Rusty Char-Broil')\n assertContains(html, 'Add to Cart')\n })\n\n it('GET /books/:slug returns 404 for non-existent book', async () => {\n let response = await router.fetch('https://remix.run/books/does-not-exist')\n\n assert.equal(response.status, 404)\n let html = await response.text()\n assertContains(html, 'Book Not Found')\n })\n})\n" }, { "path": "demos/bookstore/app/books.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { Frame, css } from 'remix/component'\n\nimport { routes } from './routes.ts'\nimport { Database, ilike } from 'remix/data-table'\n\nimport { books } from './data/schema.ts'\nimport { BookCard } from './components/book-card.tsx'\nimport { Layout } from './layout.tsx'\nimport { loadAuth } from './middleware/auth.ts'\nimport { render } from './utils/render.ts'\nimport { getCurrentCart } from './utils/context.ts'\nimport { ImageCarousel } from './assets/image-carousel.tsx'\n\nexport default {\n middleware: [loadAuth()],\n actions: {\n async index({ get }) {\n let db = get(Database)\n let allBooks = await db.findMany(books, { orderBy: ['id', 'asc'] })\n let genres = await db.query(books).select('genre').distinct().orderBy('genre', 'asc').all()\n let cart = getCurrentCart()\n\n return render(\n <Layout>\n <h1>Browse Books</h1>\n\n <div class=\"card\" mix={[css({ marginBottom: '2rem' })]}>\n <form\n action={routes.search.href()}\n method=\"GET\"\n mix={[css({ display: 'flex', gap: '0.5rem' })]}\n >\n <input\n type=\"search\"\n name=\"q\"\n placeholder=\"Search books by title, author, or description...\"\n mix={[css({ flex: 1, padding: '0.5rem' })]}\n />\n <button type=\"submit\" class=\"btn\">\n Search\n </button>\n </form>\n </div>\n\n <div class=\"card\" mix={[css({ marginBottom: '2rem' })]}>\n <h3>Browse by Genre</h3>\n <div\n mix={[css({ display: 'flex', gap: '0.5rem', flexWrap: 'wrap', marginTop: '1rem' })]}\n >\n {genres.map((genreRow) => (\n <a\n href={routes.books.genre.href({ genre: genreRow.genre })}\n class=\"btn btn-secondary\"\n >\n {genreRow.genre}\n </a>\n ))}\n </div>\n </div>\n\n <div class=\"grid\">\n {allBooks.map((book) => {\n let inCart = cart.items.some((item) => item.slug === book.slug)\n return <BookCard book={book} inCart={inCart} />\n })}\n </div>\n </Layout>,\n )\n },\n\n async genre({ get, params }) {\n let db = get(Database)\n let genre = params.genre\n let matchingBooks = await db.findMany(books, {\n where: ilike('genre', genre),\n orderBy: ['id', 'asc'],\n })\n\n if (matchingBooks.length === 0) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Genre Not Found</h1>\n <p>No books found in the \"{genre}\" genre.</p>\n <p mix={[css({ marginTop: '1rem' })]}>\n <a href={routes.books.index.href()} class=\"btn\">\n Browse All Books\n </a>\n </p>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n let cart = getCurrentCart()\n\n return render(\n <Layout>\n <h1>{genre.charAt(0).toUpperCase() + genre.slice(1)} Books</h1>\n <p mix={[css({ margin: '1rem 0' })]}>\n <a href={routes.books.index.href()} class=\"btn btn-secondary\">\n View All Books\n </a>\n </p>\n\n <div class=\"grid\" mix={[css({ marginTop: '2rem' })]}>\n {matchingBooks.map((book) => {\n let inCart = cart.items.some((item) => item.slug === book.slug)\n return <BookCard book={book} inCart={inCart} />\n })}\n </div>\n </Layout>,\n )\n },\n\n async show({ get, params }) {\n let db = get(Database)\n let book = await db.findOne(books, { where: { slug: params.slug } })\n\n if (!book) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Book Not Found</h1>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n let imageUrls = JSON.parse(book.image_urls) as string[]\n\n return render(\n <Layout>\n <div mix={[css({ display: 'grid', gridTemplateColumns: '300px 1fr', gap: '2rem' })]}>\n <div\n mix={[\n css({\n height: '400px',\n borderRadius: '8px',\n boxShadow: '0 4px 8px rgba(0,0,0,0.1)',\n overflow: 'hidden',\n }),\n ]}\n >\n <ImageCarousel images={imageUrls} />\n </div>\n\n <div class=\"card\">\n <h1>{book.title}</h1>\n <p class=\"author\" mix={[css({ fontSize: '1.2rem', margin: '0.5rem 0' })]}>\n by {book.author}\n </p>\n\n <p mix={[css({ margin: '1rem 0' })]}>\n <span class=\"badge badge-info\">{book.genre}</span>\n <span\n class={`badge ${book.in_stock ? 'badge-success' : 'badge-warning'}`}\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n {book.in_stock ? 'In Stock' : 'Out of Stock'}\n </span>\n </p>\n\n <p class=\"price\" mix={[css({ fontSize: '2rem', margin: '1rem 0' })]}>\n ${book.price.toFixed(2)}\n </p>\n\n <p mix={[css({ margin: '1.5rem 0', lineHeight: 1.8 })]}>{book.description}</p>\n\n <div\n mix={[\n css({\n margin: '1.5rem 0',\n padding: '1rem',\n background: '#f8f9fa',\n borderRadius: '4px',\n }),\n ]}\n >\n <p>\n <strong>ISBN:</strong> {book.isbn}\n </p>\n <p>\n <strong>Published:</strong> {book.published_year}\n </p>\n </div>\n\n {book.in_stock ? (\n <div mix={[css({ marginTop: '2rem' })]}>\n <Frame src={routes.fragments.cartButton.href({ bookId: book.id })} />\n </div>\n ) : (\n <p mix={[css({ color: '#e74c3c', fontWeight: 500 })]}>\n This book is currently out of stock.\n </p>\n )}\n\n <p mix={[css({ marginTop: '1.5rem' })]}>\n <a href={routes.books.index.href()} class=\"btn btn-secondary\">\n Back to Books\n </a>\n </p>\n </div>\n </div>\n </Layout>,\n { headers: { 'Cache-Control': 'no-store' } },\n )\n },\n },\n} satisfies Controller<typeof routes.books>\n" }, { "path": "demos/bookstore/app/cart.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport { getSessionCookie, requestWithSession, assertContains } from '../test/helpers.ts'\n\ndescribe('cart handlers', () => {\n it('POST /cart/api/add adds book to cart', async () => {\n let response = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n redirect: 'manual',\n })\n\n assert.equal(response.status, 302)\n assert.ok(response.headers.get('Location')?.includes('/cart'))\n })\n\n it('GET /cart shows cart items', async () => {\n // First, add item to cart to get a session\n let addResponse = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '2',\n slug: 'heavy-metal',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse)\n assert.ok(sessionId)\n\n // Now view cart with session\n let request = requestWithSession('https://remix.run/cart', sessionId)\n let response = await router.fetch(request)\n\n assert.equal(response.status, 200)\n let html = await response.text()\n assertContains(html, 'Shopping Cart')\n assertContains(html, 'Heavy Metal Guitar Riffs')\n })\n\n it('cart persists state across requests with same session', async () => {\n // Add first item\n let addResponse1 = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse1)\n assert.ok(sessionId)\n\n // Add second item with same session\n let addRequest2 = requestWithSession('https://remix.run/cart/api/add', sessionId, {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '3',\n slug: 'three-ways',\n }),\n })\n await router.fetch(addRequest2)\n\n // View cart - should have both items\n let cartRequest = requestWithSession('https://remix.run/cart', sessionId)\n let cartResponse = await router.fetch(cartRequest)\n\n let html = await cartResponse.text()\n assertContains(html, 'Ash & Smoke')\n assertContains(html, 'Three Ways to Change Your Life')\n })\n\n it('GET /fragments/cart-items renders table fragment for cart items', async () => {\n let addResponse = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '2',\n slug: 'heavy-metal',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse)\n assert.ok(sessionId)\n\n let request = requestWithSession('https://remix.run/fragments/cart-items', sessionId)\n let response = await router.fetch(request)\n let html = await response.text()\n\n assert.equal(response.status, 200)\n assertContains(html, '<table>')\n assertContains(html, '<th>Book</th>')\n assertContains(html, 'Heavy Metal Guitar Riffs')\n assertContains(html, 'Update')\n assertContains(html, 'Remove')\n assertContains(html, 'Total:')\n })\n\n it('GET /fragments/cart-items renders totals and actions', async () => {\n let addResponse = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse)\n assert.ok(sessionId)\n\n let request = requestWithSession('https://remix.run/fragments/cart-items', sessionId)\n let response = await router.fetch(request)\n let html = await response.text()\n\n assert.equal(response.status, 200)\n assertContains(html, 'Total:')\n assertContains(html, '$16.99')\n assertContains(html, 'Continue Shopping')\n assertContains(html, 'Login to Checkout')\n })\n\n it('GET /fragments/cart-items renders empty state when cart is empty', async () => {\n let response = await router.fetch('https://remix.run/fragments/cart-items')\n let html = await response.text()\n\n assert.equal(response.status, 200)\n assertContains(html, 'Your cart is empty.')\n assertContains(html, 'Browse Books')\n })\n\n it('PUT /cart/api/update returns 204 when redirect is none', async () => {\n let addResponse = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse)\n assert.ok(sessionId)\n\n let request = requestWithSession('https://remix.run/cart/api/update', sessionId, {\n method: 'PUT',\n body: new URLSearchParams({\n bookId: '1',\n quantity: '2',\n redirect: 'none',\n }),\n })\n let response = await router.fetch(request)\n\n assert.equal(response.status, 204)\n })\n\n it('DELETE /cart/api/remove returns 204 when redirect is none', async () => {\n let addResponse = await router.fetch('https://remix.run/cart/api/add', {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n redirect: 'manual',\n })\n\n let sessionId = getSessionCookie(addResponse)\n assert.ok(sessionId)\n\n let request = requestWithSession('https://remix.run/cart/api/remove', sessionId, {\n method: 'DELETE',\n body: new URLSearchParams({\n bookId: '1',\n redirect: 'none',\n }),\n })\n let response = await router.fetch(request)\n\n assert.equal(response.status, 204)\n })\n})\n" }, { "path": "demos/bookstore/app/cart.tsx", "content": "import type { Controller, RequestContext } from 'remix/fetch-router'\nimport { Frame } from 'remix/component'\nimport { Database } from 'remix/data-table'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\n\nimport { books } from './data/schema.ts'\nimport { addToCart, removeFromCart, updateCartItem } from './data/cart.ts'\nimport { Layout } from './layout.tsx'\nimport { loadAuth } from './middleware/auth.ts'\nimport { getCurrentCart } from './utils/context.ts'\nimport { parseId } from './utils/ids.ts'\nimport { render } from './utils/render.ts'\nimport { Session } from './utils/session.ts'\n\nconst bookIdField = f.field(s.optional(s.string()))\nconst quantityField = f.field(s.defaulted(s.string(), '1'))\nconst redirectField = f.field(s.optional(s.string()))\nconst bookIdSchema = f.object({\n bookId: bookIdField,\n})\nconst cartActionSchema = f.object({\n bookId: bookIdField,\n redirect: redirectField,\n})\nconst cartUpdateSchema = f.object({\n bookId: bookIdField,\n quantity: quantityField,\n redirect: redirectField,\n})\n\nexport default {\n middleware: [loadAuth()],\n actions: {\n index() {\n return render(\n <Layout>\n <h1>Shopping Cart</h1>\n\n <div class=\"card\">\n <Frame name=\"cart\" src={routes.fragments.cartItems.href()} />\n </div>\n </Layout>,\n )\n },\n\n api: {\n actions: {\n async add({ get }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { bookId, redirect: redirectTo } = s.parse(cartActionSchema, formData)\n if (process.env.NODE_ENV !== 'test') {\n // Simulate network latency\n await new Promise((resolve) => setTimeout(resolve, 1000))\n }\n\n let parsedBookId = parseId(bookId)\n let book = parsedBookId === undefined ? undefined : await db.find(books, parsedBookId)\n if (!book) {\n return new Response('Book not found', { status: 404 })\n }\n\n session.set(\n 'cart',\n addToCart(getCurrentCart(), book.id, book.slug, book.title, book.price, 1),\n )\n\n if (redirectTo === 'none') {\n return new Response(null, { status: 204 })\n }\n\n return redirect(routes.cart.index.href())\n },\n\n async update({ get }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { bookId, quantity, redirect: redirectTo } = s.parse(cartUpdateSchema, formData)\n await new Promise((resolve) => setTimeout(resolve, 1000))\n\n let parsedBookId = parseId(bookId)\n let book = parsedBookId === undefined ? undefined : await db.find(books, parsedBookId)\n if (!book) {\n return new Response('Book not found', { status: 404 })\n }\n\n let nextQuantity = parseInt(quantity, 10)\n\n session.set('cart', updateCartItem(getCurrentCart(), book.id, nextQuantity))\n\n if (redirectTo === 'none') {\n return new Response(null, { status: 204 })\n }\n\n return redirect(routes.cart.index.href())\n },\n\n async remove({ get }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { bookId, redirect: redirectTo } = s.parse(cartActionSchema, formData)\n if (process.env.NODE_ENV !== 'test') {\n // Simulate network latency\n await new Promise((resolve) => setTimeout(resolve, 1000))\n }\n\n let parsedBookId = parseId(bookId)\n let book = parsedBookId === undefined ? undefined : await db.find(books, parsedBookId)\n if (!book) {\n return new Response('Book not found', { status: 404 })\n }\n\n session.set('cart', removeFromCart(getCurrentCart(), book.id))\n\n if (redirectTo === 'none') {\n return new Response(null, { status: 204 })\n }\n\n return redirect(routes.cart.index.href())\n },\n },\n },\n },\n} satisfies Controller<typeof routes.cart>\n\nexport async function toggleCart({ get }: RequestContext) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let { bookId } = s.parse(bookIdSchema, formData)\n let parsedBookId = parseId(bookId)\n let book = parsedBookId === undefined ? undefined : await db.find(books, parsedBookId)\n if (!book) {\n return new Response('Book not found', { status: 404 })\n }\n\n let cart = getCurrentCart()\n let inCart = cart.items.some((item) => item.bookId === book.id)\n\n let next = inCart\n ? removeFromCart(cart, book.id)\n : addToCart(cart, book.id, book.slug, book.title, book.price, 1)\n\n session.set('cart', next)\n\n return new Response(null, { status: 204 })\n}\n" }, { "path": "demos/bookstore/app/checkout.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { router } from './router.ts'\nimport {\n assertContains,\n getSessionCookie,\n loginAsCustomer,\n requestWithSession,\n} from '../test/helpers.ts'\n\ndescribe('checkout handlers', () => {\n it('GET /checkout redirects when not authenticated', async () => {\n let response = await router.fetch('https://remix.run/checkout')\n\n assert.equal(response.status, 302)\n assert.equal(response.headers.get('Location'), '/login?returnTo=%2Fcheckout')\n })\n\n it('POST /checkout creates order when authenticated with items in cart', async () => {\n let sessionCookie = await loginAsCustomer(router)\n\n // Add item to cart\n let addRequest = requestWithSession('https://remix.run/cart/api/add', sessionCookie, {\n method: 'POST',\n body: new URLSearchParams({\n bookId: '1',\n slug: 'bbq',\n }),\n })\n let addResponse = await router.fetch(addRequest)\n\n // Get updated session cookie after cart modification\n sessionCookie = getSessionCookie(addResponse) ?? sessionCookie\n\n // Submit checkout\n let checkoutRequest = requestWithSession('https://remix.run/checkout', sessionCookie, {\n method: 'POST',\n body: new URLSearchParams({\n street: '123 Test St',\n city: 'Test City',\n state: 'TS',\n zip: '12345',\n }),\n })\n let checkoutResponse = await router.fetch(checkoutRequest)\n let confirmationUrl = checkoutResponse.headers.get('Location')\n sessionCookie = getSessionCookie(checkoutResponse) ?? sessionCookie\n\n assert.equal(checkoutResponse.status, 302)\n assert.ok(confirmationUrl?.includes('/checkout/'))\n assert.ok(confirmationUrl?.includes('/confirmation'))\n\n let orderId = confirmationUrl?.match(/\\/checkout\\/([^/]+)\\/confirmation/)?.[1]\n assert.ok(orderId)\n\n let orderDetailsRequest = requestWithSession(\n `https://remix.run/account/orders/${orderId}`,\n sessionCookie,\n )\n let orderDetailsResponse = await router.fetch(orderDetailsRequest)\n\n assert.equal(orderDetailsResponse.status, 200)\n let orderDetailsHtml = await orderDetailsResponse.text()\n assertContains(orderDetailsHtml, 'Ash & Smoke')\n })\n})\n" }, { "path": "demos/bookstore/app/checkout.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport * as s from 'remix/data-schema'\nimport * as f from 'remix/data-schema/form-data'\nimport { Database } from 'remix/data-table'\nimport { redirect } from 'remix/response/redirect'\n\nimport { routes } from './routes.ts'\nimport { requireAuth } from './middleware/auth.ts'\nimport { clearCart, getCartTotal } from './data/cart.ts'\nimport { itemsByOrder, orders, orderItemsWithBook } from './data/schema.ts'\nimport { Layout } from './layout.tsx'\nimport { render } from './utils/render.ts'\nimport { getCurrentUser, getCurrentCart } from './utils/context.ts'\nimport { parseId } from './utils/ids.ts'\nimport { Session } from './utils/session.ts'\n\nconst textField = f.field(s.defaulted(s.string(), ''))\nconst shippingAddressSchema = f.object({\n street: textField,\n city: textField,\n state: textField,\n zip: textField,\n})\n\nexport default {\n middleware: [requireAuth()],\n actions: {\n index() {\n let cart = getCurrentCart()\n let total = getCartTotal(cart)\n\n if (cart.items.length === 0) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Checkout</h1>\n <p>Your cart is empty. Add some books before checking out.</p>\n <p mix={[css({ marginTop: '1rem' })]}>\n <a href={routes.books.index.href()} class=\"btn\">\n Browse Books\n </a>\n </p>\n </div>\n </Layout>,\n )\n }\n\n return render(\n <Layout>\n <h1>Checkout</h1>\n\n <div class=\"card\">\n <h2>Order Summary</h2>\n <table mix={[css({ marginTop: '1rem' })]}>\n <thead>\n <tr>\n <th>Book</th>\n <th>Quantity</th>\n <th>Price</th>\n <th>Subtotal</th>\n </tr>\n </thead>\n <tbody>\n {cart.items.map((item) => (\n <tr>\n <td>{item.title}</td>\n <td>{item.quantity}</td>\n <td>${item.price.toFixed(2)}</td>\n <td>${(item.price * item.quantity).toFixed(2)}</td>\n </tr>\n ))}\n </tbody>\n <tfoot>\n <tr>\n <td colSpan={3} mix={[css({ textAlign: 'right', fontWeight: 'bold' })]}>\n Total:\n </td>\n <td mix={[css({ fontWeight: 'bold' })]}>${total.toFixed(2)}</td>\n </tr>\n </tfoot>\n </table>\n </div>\n\n <div class=\"card\" mix={[css({ marginTop: '1.5rem' })]}>\n <h2>Shipping Information</h2>\n <form method=\"POST\" action={routes.checkout.action.href()}>\n <div class=\"form-group\">\n <label for=\"street\">Street Address</label>\n <input type=\"text\" id=\"street\" name=\"street\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"city\">City</label>\n <input type=\"text\" id=\"city\" name=\"city\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"state\">State</label>\n <input type=\"text\" id=\"state\" name=\"state\" required />\n </div>\n\n <div class=\"form-group\">\n <label for=\"zip\">ZIP Code</label>\n <input type=\"text\" id=\"zip\" name=\"zip\" required />\n </div>\n\n <button type=\"submit\" class=\"btn\">\n Place Order\n </button>\n <a\n href={routes.cart.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Back to Cart\n </a>\n </form>\n </div>\n </Layout>,\n )\n },\n\n async action({ get }) {\n let db = get(Database)\n let session = get(Session)\n let formData = get(FormData)\n let user = getCurrentUser()\n let cart = getCurrentCart()\n\n if (cart.items.length === 0) {\n return redirect(routes.cart.index.href())\n }\n\n let shippingAddress = s.parse(shippingAddressSchema, formData)\n\n let total = cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)\n\n let order = await db.transaction(async (tx) => {\n let createdOrder = await tx.create(\n orders,\n {\n user_id: user.id,\n total,\n shipping_address_json: JSON.stringify(shippingAddress),\n },\n { returnRow: true },\n )\n\n await tx.createMany(\n itemsByOrder.targetTable,\n cart.items.map((item) => ({\n order_id: createdOrder.id,\n book_id: item.bookId,\n title: item.title,\n unit_price: item.price,\n quantity: item.quantity,\n })),\n )\n\n let created = await tx.find(orders, createdOrder.id, {\n with: { items: orderItemsWithBook },\n })\n\n if (!created) {\n throw new Error('Failed to load created order')\n }\n\n return created\n })\n\n session.set('cart', clearCart(cart))\n\n return redirect(routes.checkout.confirmation.href({ orderId: order.id }))\n },\n\n async confirmation({ get, params }) {\n let db = get(Database)\n let user = getCurrentUser()\n let orderId = parseId(params.orderId)\n let order =\n orderId === undefined\n ? undefined\n : await db.find(orders, orderId, {\n with: { items: orderItemsWithBook },\n })\n\n if (!order || order.user_id !== user.id) {\n return render(\n <Layout>\n <div class=\"card\">\n <h1>Order Not Found</h1>\n <p>\n <a href={routes.account.orders.index.href()} class=\"btn\">\n View My Orders\n </a>\n </p>\n </div>\n </Layout>,\n { status: 404 },\n )\n }\n\n return render(\n <Layout>\n <div class=\"alert alert-success\">\n <h1 mix={[css({ marginBottom: '0.5rem' })]}>Order Confirmed!</h1>\n <p>Thank you for your purchase. Your order has been placed successfully.</p>\n </div>\n\n <div class=\"card\">\n <h2>Order #{order.id}</h2>\n <p>\n <strong>Order Date:</strong> {new Date(order.created_at).toLocaleDateString()}\n </p>\n <p>\n <strong>Total:</strong> ${order.total.toFixed(2)}\n </p>\n <p>\n <strong>Status:</strong> <span class=\"badge badge-info\">{order.status}</span>\n </p>\n\n <p mix={[css({ marginTop: '2rem' })]}>\n We'll send you a confirmation email shortly. You can track your order status in your\n account.\n </p>\n\n <div mix={[css({ marginTop: '2rem' })]}>\n <a href={routes.account.orders.show.href({ orderId: order.id })} class=\"btn\">\n View Order Details\n </a>\n <a\n href={routes.books.index.href()}\n class=\"btn btn-secondary\"\n mix={[css({ marginLeft: '0.5rem' })]}\n >\n Continue Shopping\n </a>\n </div>\n </div>\n </Layout>,\n )\n },\n },\n} satisfies Controller<typeof routes.checkout>\n" }, { "path": "demos/bookstore/app/components/book-card.tsx", "content": "import { routes } from '../routes.ts'\nimport type { Book } from '../data/schema.ts'\nimport { Frame, css } from 'remix/component'\n\nexport interface BookCardProps {\n book: Book\n inCart: boolean\n}\n\nexport function BookCard() {\n return ({ book }: BookCardProps) => (\n <div class=\"book-card\">\n <img src={book.cover_url} alt={book.title} />\n <div class=\"book-card-body\">\n <h3>{book.title}</h3>\n <p class=\"author\">by {book.author}</p>\n <p class=\"price\">${book.price.toFixed(2)}</p>\n <div mix={[css({ display: 'flex', gap: '0.5rem', alignItems: 'center' })]}>\n <a href={routes.books.show.href({ slug: book.slug })} class=\"btn\">\n View Details\n </a>\n\n <Frame src={routes.fragments.cartButton.href({ bookId: book.id })} />\n </div>\n </div>\n </div>\n )\n}\n" }, { "path": "demos/bookstore/app/components/restful-form.tsx", "content": "import type { Props, RemixNode } from 'remix/component'\n\nexport interface RestfulFormProps extends Props<'form'> {\n /**\n * The name of the hidden <input> field that contains the method override value.\n * Default is `_method`.\n */\n methodOverrideField?: string\n}\n\n/**\n * A wrapper around the `<form>` element that supports RESTful API methods like `PUT` and `DELETE`.\n *\n * When the method is not `GET` or `POST`, a hidden <input> field is added to the form with a\n * \"method override\" value that instructs the server to use the specified method when routing\n * the request.\n */\nexport function RestfulForm() {\n return ({ method = 'GET', methodOverrideField = '_method', ...props }: RestfulFormProps) => {\n let upperMethod = method.toUpperCase()\n\n if (upperMethod === 'GET') {\n return <form method=\"GET\" {...props} />\n }\n\n return (\n <form method=\"POST\" {...props}>\n {upperMethod !== 'POST' && (\n <input type=\"hidden\" name={methodOverrideField} value={upperMethod} />\n )}\n {props.children}\n </form>\n )\n }\n}\n" }, { "path": "demos/bookstore/app/data/cart.ts", "content": "export interface CartItem {\n bookId: number\n slug: string\n title: string\n price: number\n quantity: number\n}\n\nexport interface Cart {\n items: CartItem[]\n}\n\nexport function isCart(value: unknown): value is Cart {\n return (\n typeof value === 'object' && value !== null && 'items' in value && Array.isArray(value.items)\n )\n}\n\nexport function getCart(value: unknown): Cart {\n return isCart(value) ? value : { items: [] }\n}\n\nexport function addToCart(\n cart: Cart,\n bookId: number,\n slug: string,\n title: string,\n price: number,\n quantity: number = 1,\n): Cart {\n let existingItem = cart.items.find((item) => item.bookId === bookId)\n if (existingItem) {\n existingItem.quantity += quantity\n } else {\n cart.items.push({ bookId, slug, title, price, quantity })\n }\n\n return cart\n}\n\nexport function updateCartItem(cart: Cart, bookId: number, quantity: number): Cart | undefined {\n let item = cart.items.find((item) => item.bookId === bookId)\n\n if (!item) return undefined\n\n if (quantity <= 0) {\n cart.items = cart.items.filter((item) => item.bookId !== bookId)\n } else {\n item.quantity = quantity\n }\n\n return cart\n}\n\nexport function removeFromCart(cart: Cart, bookId: number): Cart {\n cart.items = cart.items.filter((item) => item.bookId !== bookId)\n return cart\n}\n\nexport function clearCart(cart: Cart): Cart {\n return { items: [] }\n}\n\nexport function getCartTotal(cart: Cart): number {\n return cart.items.reduce((sum, item) => sum + item.price * item.quantity, 0)\n}\n" }, { "path": "demos/bookstore/app/data/schema.ts", "content": "import { belongsTo, column as c, table, hasMany } from 'remix/data-table'\nimport type { TableRow, TableRowWith } from 'remix/data-table'\n\nexport const books = table({\n name: 'books',\n columns: {\n id: c.integer(),\n slug: c.text(),\n title: c.text(),\n author: c.text(),\n description: c.text(),\n price: c.decimal(10, 2),\n genre: c.text(),\n image_urls: c.text(),\n cover_url: c.text(),\n isbn: c.text(),\n published_year: c.integer(),\n in_stock: c.boolean(),\n },\n beforeWrite({ value }) {\n let next = { ...value }\n\n if (typeof next.slug === 'string') {\n next.slug = normalizeSlug(next.slug)\n }\n\n if (typeof next.title === 'string') {\n next.title = normalizeText(next.title)\n }\n\n if (typeof next.author === 'string') {\n next.author = normalizeText(next.author)\n }\n\n if (typeof next.description === 'string') {\n next.description = normalizeText(next.description)\n }\n\n if (typeof next.genre === 'string') {\n next.genre = normalizeText(next.genre)\n }\n\n if (typeof next.isbn === 'string') {\n next.isbn = normalizeText(next.isbn)\n }\n\n if (typeof next.cover_url === 'string' && next.cover_url.trim() === '') {\n next.cover_url = '/images/placeholder.jpg'\n }\n\n return { value: next }\n },\n validate({ operation, value }) {\n let issues: Array<{ message: string; path?: Array<string | number> }> = []\n let slug = typeof value.slug === 'string' ? normalizeSlug(value.slug) : undefined\n let title = typeof value.title === 'string' ? normalizeText(value.title) : undefined\n\n if (operation === 'create' && !slug) {\n issues.push({ message: 'Book slug is required.', path: ['slug'] })\n }\n\n if (slug !== undefined && slug.length === 0) {\n issues.push({ message: 'Book slug is required.', path: ['slug'] })\n }\n\n if (operation === 'create' && !title) {\n issues.push({ message: 'Book title is required.', path: ['title'] })\n }\n\n if (title !== undefined && title.length === 0) {\n issues.push({ message: 'Book title is required.', path: ['title'] })\n }\n\n if (typeof value.price === 'number' && (!Number.isFinite(value.price) || value.price < 0)) {\n issues.push({ message: 'Price must be a non-negative number.', path: ['price'] })\n }\n\n if (\n typeof value.published_year === 'number' &&\n (!Number.isInteger(value.published_year) || value.published_year < 0)\n ) {\n issues.push({\n message: 'Published year must be a valid positive integer.',\n path: ['published_year'],\n })\n }\n\n return issues.length > 0 ? { issues } : { value }\n },\n afterRead({ value }) {\n if (typeof value.cover_url !== 'string' || value.cover_url.trim() !== '') {\n return { value }\n }\n\n return {\n value: {\n ...value,\n cover_url: '/images/placeholder.jpg',\n },\n }\n },\n})\n\nexport const users = table({\n name: 'users',\n columns: {\n id: c.integer(),\n email: c.text(),\n password: c.text(),\n name: c.text(),\n role: c.enum(['customer', 'admin']),\n created_at: c.integer(),\n },\n beforeWrite({ operation, value }) {\n let next = { ...value }\n\n if (typeof next.name === 'string') {\n next.name = normalizeText(next.name)\n }\n\n if (typeof next.email === 'string') {\n next.email = normalizeEmail(next.email)\n }\n\n if (typeof next.password === 'string') {\n next.password = next.password.trim()\n }\n\n if (operation === 'create' && next.role === undefined) {\n next.role = 'customer'\n }\n\n if (operation === 'create' && next.created_at === undefined) {\n next.created_at = Date.now()\n }\n\n return { value: next }\n },\n validate({ operation, value }) {\n let issues: Array<{ message: string; path?: Array<string | number> }> = []\n let email = typeof value.email === 'string' ? normalizeEmail(value.email) : undefined\n let name = typeof value.name === 'string' ? normalizeText(value.name) : undefined\n\n if (operation === 'create' && !name) {\n issues.push({ message: 'Name is required.', path: ['name'] })\n }\n\n if (name !== undefined && name.length === 0) {\n issues.push({ message: 'Name is required.', path: ['name'] })\n }\n\n if (operation === 'create' && !email) {\n issues.push({ message: 'Email is required.', path: ['email'] })\n }\n\n if (email !== undefined && !isValidEmail(email)) {\n issues.push({ message: 'Email address is invalid.', path: ['email'] })\n }\n\n if (\n (operation === 'create' && typeof value.password !== 'string') ||\n (typeof value.password === 'string' && value.password.length < 8)\n ) {\n issues.push({\n message: 'Password must be at least 8 characters long.',\n path: ['password'],\n })\n }\n\n return issues.length > 0 ? { issues } : { value }\n },\n afterRead({ value }) {\n if (typeof value.email !== 'string' || typeof value.name !== 'string') {\n return { value }\n }\n\n let email = normalizeEmail(value.email)\n let name = normalizeText(value.name)\n\n if (email === value.email && name === value.name) {\n return { value }\n }\n\n return {\n value: {\n ...value,\n email,\n name,\n },\n }\n },\n})\n\nexport const orders = table({\n name: 'orders',\n columns: {\n id: c.integer(),\n user_id: c.integer(),\n total: c.decimal(10, 2),\n status: c.enum(['pending', 'processing', 'shipped', 'delivered']),\n shipping_address_json: c.text(),\n created_at: c.integer(),\n },\n beforeWrite({ operation, value }) {\n let next = { ...value }\n\n if (operation === 'create' && next.status === undefined) {\n next.status = 'pending'\n }\n\n if (operation === 'create' && next.created_at === undefined) {\n next.created_at = Date.now()\n }\n\n return { value: next }\n },\n validate({ value }) {\n let issues: Array<{ message: string; path?: Array<string | number> }> = []\n\n if (typeof value.total === 'number' && (!Number.isFinite(value.total) || value.total < 0)) {\n issues.push({ message: 'Order total must be a non-negative number.', path: ['total'] })\n }\n\n if (\n typeof value.shipping_address_json === 'string' &&\n !isJsonObject(value.shipping_address_json)\n ) {\n issues.push({\n message: 'Shipping address must be a valid JSON object string.',\n path: ['shipping_address_json'],\n })\n }\n\n return issues.length > 0 ? { issues } : { value }\n },\n})\n\nexport const orderItems = table({\n name: 'order_items',\n primaryKey: ['order_id', 'book_id'],\n columns: {\n order_id: c.integer(),\n book_id: c.integer(),\n title: c.text(),\n unit_price: c.decimal(10, 2),\n quantity: c.integer(),\n },\n beforeWrite({ value }) {\n let next = { ...value }\n\n if (typeof next.title === 'string') {\n next.title = normalizeText(next.title)\n }\n\n return { value: next }\n },\n validate({ value }) {\n let issues: Array<{ message: string; path?: Array<string | number> }> = []\n\n if (\n typeof value.quantity === 'number' &&\n (!Number.isInteger(value.quantity) || value.quantity < 1)\n ) {\n issues.push({ message: 'Quantity must be an integer greater than 0.', path: ['quantity'] })\n }\n\n if (\n typeof value.unit_price === 'number' &&\n (!Number.isFinite(value.unit_price) || value.unit_price < 0)\n ) {\n issues.push({\n message: 'Unit price must be a non-negative number.',\n path: ['unit_price'],\n })\n }\n\n return issues.length > 0 ? { issues } : { value }\n },\n})\n\nexport const itemsByOrder = hasMany(orders, orderItems)\nexport const bookForOrderItem = belongsTo(orderItems, books)\nexport const orderItemsWithBook = itemsByOrder\n .orderBy('book_id', 'asc')\n .with({ book: bookForOrderItem })\n\nexport const passwordResetTokens = table({\n name: 'password_reset_tokens',\n primaryKey: ['token'],\n columns: {\n token: c.text(),\n user_id: c.integer(),\n expires_at: c.integer(),\n },\n})\n\nexport type Book = TableRow<typeof books>\nexport type User = TableRow<typeof users>\nexport type Order = TableRowWith<typeof orders, { items: OrderItem[] }>\nexport type OrderItem = TableRowWith<\n typeof itemsByOrder.targetTable,\n { book: TableRow<typeof bookForOrderItem.targetTable> | null }\n>\n\nfunction normalizeEmail(email: string): string {\n return email.trim().toLowerCase()\n}\n\nfunction normalizeText(value: string): string {\n return value.trim()\n}\n\nfunction normalizeSlug(value: string): string {\n return value\n .trim()\n .toLowerCase()\n .replace(/[^a-z0-9\\s-]/g, '')\n .replace(/\\s+/g, '-')\n .replace(/-+/g, '-')\n}\n\nfunction isValidEmail(email: string): boolean {\n return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email)\n}\n\nfunction isJsonObject(value: string): boolean {\n try {\n let parsed = JSON.parse(value)\n return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)\n } catch {\n return false\n }\n}\n" }, { "path": "demos/bookstore/app/data/setup.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\nimport { fileURLToPath } from 'node:url'\nimport { sql } from 'remix/data-table'\nimport { loadMigrations } from 'remix/data-table/migrations/node'\n\nimport { db, initializeBookstoreDatabase } from './setup.ts'\n\nfunction getRows(result: { rows?: Record<string, unknown>[] }): Record<string, unknown>[] {\n return result.rows ?? []\n}\n\nfunction readRowString(row: Record<string, unknown>, key: string): string {\n let value = row[key]\n\n if (typeof value !== 'string') {\n throw new Error('Expected string row value for key \"' + key + '\"')\n }\n\n return value\n}\n\nfunction readRowCount(row: Record<string, unknown>, key: string): number {\n let value = row[key]\n\n if (typeof value === 'number') {\n return value\n }\n\n if (typeof value === 'bigint') {\n return Number(value)\n }\n\n if (typeof value === 'string') {\n return Number(value)\n }\n\n throw new Error('Expected numeric row value for key \"' + key + '\"')\n}\n\ndescribe('bookstore database setup', () => {\n it('applies migrations and materializes expected schema artifacts', async () => {\n await initializeBookstoreDatabase()\n\n let migrationsPath = fileURLToPath(new URL('../../data/migrations/', import.meta.url))\n let migrations = await loadMigrations(migrationsPath)\n\n let journalResult = await db.exec(\n sql`select id, name from data_table_migrations order by id asc`,\n )\n let journalRows = getRows(journalResult)\n let journalIds = journalRows.map((row) => readRowString(row, 'id'))\n let migrationIds = migrations.map((migration) => migration.id)\n\n assert.equal(journalRows.length, migrations.length)\n assert.deepEqual(journalIds, migrationIds)\n\n assert.equal(await db.adapter.hasTable({ name: 'books' }), true)\n assert.equal(await db.adapter.hasTable({ name: 'users' }), true)\n assert.equal(await db.adapter.hasTable({ name: 'orders' }), true)\n assert.equal(await db.adapter.hasTable({ name: 'order_items' }), true)\n assert.equal(await db.adapter.hasTable({ name: 'password_reset_tokens' }), true)\n\n assert.equal(await db.adapter.hasColumn({ name: 'books' }, 'slug'), true)\n assert.equal(await db.adapter.hasColumn({ name: 'users' }, 'email'), true)\n assert.equal(await db.adapter.hasColumn({ name: 'orders' }, 'user_id'), true)\n\n let ordersIndex = await db.exec(\n sql`select name from sqlite_master where type = 'index' and name = 'orders_user_id_idx'`,\n )\n let orderItemsOrderIndex = await db.exec(\n sql`select name from sqlite_master where type = 'index' and name = 'order_items_order_id_idx'`,\n )\n\n assert.equal(getRows(ordersIndex).length, 1)\n assert.equal(getRows(orderItemsOrderIndex).length, 1)\n })\n\n it('does not duplicate migration journal entries when initialized more than once', async () => {\n await initializeBookstoreDatabase()\n\n let before = await db.exec(sql`select count(*) as count from data_table_migrations`)\n let beforeRows = getRows(before)\n assert.ok(beforeRows.length > 0)\n let beforeCount = readRowCount(beforeRows[0], 'count')\n\n await initializeBookstoreDatabase()\n\n let after = await db.exec(sql`select count(*) as count from data_table_migrations`)\n let afterRows = getRows(after)\n assert.ok(afterRows.length > 0)\n let afterCount = readRowCount(afterRows[0], 'count')\n\n assert.equal(afterCount, beforeCount)\n })\n})\n" }, { "path": "demos/bookstore/app/data/setup.ts", "content": "import * as fs from 'node:fs'\nimport { fileURLToPath } from 'node:url'\nimport BetterSqlite3 from 'better-sqlite3'\nimport { createDatabase } from 'remix/data-table'\nimport { createMigrationRunner } from 'remix/data-table/migrations'\nimport { loadMigrations } from 'remix/data-table/migrations/node'\nimport { createSqliteDatabaseAdapter } from 'remix/data-table-sqlite'\n\nimport { books, orderItems, orders, users } from './schema.ts'\n\nlet dataDirectoryUrl = new URL('../../data/', import.meta.url)\nlet migrationsDirectoryPath = fileURLToPath(new URL('migrations/', dataDirectoryUrl))\nlet databaseFilePath = getDatabaseFilePath()\n\nfs.mkdirSync(fileURLToPath(dataDirectoryUrl), { recursive: true })\n\nif (process.env.NODE_ENV === 'test' && fs.existsSync(databaseFilePath)) {\n fs.unlinkSync(databaseFilePath)\n}\n\nlet sqlite = new BetterSqlite3(databaseFilePath)\nsqlite.pragma('foreign_keys = ON')\nlet adapter = createSqliteDatabaseAdapter(sqlite)\n\nexport let db = createDatabase(adapter)\n\nlet initializePromise: Promise<void> | null = null\n\nexport async function initializeBookstoreDatabase(): Promise<void> {\n if (!initializePromise) {\n initializePromise = initialize()\n }\n\n await initializePromise\n}\n\nasync function initialize(): Promise<void> {\n let migrations = await loadMigrations(migrationsDirectoryPath)\n let migrationRunner = createMigrationRunner(adapter, migrations)\n await migrationRunner.up()\n\n let booksCount = await db.count(books)\n if (booksCount === 0) {\n await db.createMany(books, [\n {\n id: 1,\n slug: 'bbq',\n title: 'Ash & Smoke',\n author: 'Rusty Char-Broil',\n description: 'The perfect gift for the BBQ enthusiast in your life!',\n price: 16.99,\n genre: 'cookbook',\n image_urls: JSON.stringify(['/images/bbq-1.png', '/images/bbq-2.png', '/images/bbq-3.png']),\n cover_url: '/images/bbq-1.png',\n isbn: '978-0525559474',\n published_year: 2020,\n in_stock: true,\n },\n {\n id: 2,\n slug: 'heavy-metal',\n title: 'Heavy Metal Guitar Riffs',\n author: 'Axe Master Krush',\n description: 'The ultimate guide to heavy metal guitar riffs!',\n price: 27.0,\n genre: 'music',\n image_urls: JSON.stringify([\n '/images/heavy-metal-1.png',\n '/images/heavy-metal-2.png',\n '/images/heavy-metal-3.png',\n ]),\n cover_url: '/images/heavy-metal-1.png',\n isbn: '978-0735211292',\n published_year: 2018,\n in_stock: true,\n },\n {\n id: 3,\n slug: 'three-ways',\n title: 'Three Ways to Change Your Life',\n author: 'Wisdom Sage',\n description: 'Life-changing strategies for modern living and personal growth.',\n price: 28.99,\n genre: 'self-help',\n image_urls: JSON.stringify([\n '/images/three-ways-1.png',\n '/images/three-ways-2.png',\n '/images/three-ways-3.png',\n ]),\n cover_url: '/images/three-ways-1.png',\n isbn: '978-0061120084',\n published_year: 2021,\n in_stock: false,\n },\n ])\n }\n\n let usersCount = await db.count(users)\n if (usersCount === 0) {\n await db.createMany(users, [\n {\n id: 1,\n email: 'admin@bookstore.com',\n password: 'admin123',\n name: 'Admin User',\n role: 'admin',\n created_at: new Date('2024-01-15').getTime(),\n },\n {\n id: 2,\n email: 'customer@example.com',\n password: 'password123',\n name: 'John Doe',\n role: 'customer',\n created_at: new Date('2024-03-01').getTime(),\n },\n ])\n }\n\n let ordersCount = await db.count(orders)\n if (ordersCount === 0) {\n await db.createMany(orders, [\n {\n id: 1001,\n user_id: 2,\n total: 45.98,\n status: 'delivered',\n shipping_address_json: JSON.stringify({\n street: '123 Main St',\n city: 'Boston',\n state: 'MA',\n zip: '02101',\n }),\n created_at: new Date('2024-09-15').getTime(),\n },\n {\n id: 1002,\n user_id: 2,\n total: 54.0,\n status: 'shipped',\n shipping_address_json: JSON.stringify({\n street: '123 Main St',\n city: 'Boston',\n state: 'MA',\n zip: '02101',\n }),\n created_at: new Date('2024-10-01').getTime(),\n },\n ])\n }\n\n let orderItemsCount = await db.count(orderItems)\n if (orderItemsCount === 0) {\n await db.createMany(orderItems, [\n {\n order_id: 1001,\n book_id: 1,\n title: 'Ash & Smoke',\n unit_price: 16.99,\n quantity: 1,\n },\n {\n order_id: 1001,\n book_id: 3,\n title: 'Three Ways to Change Your Life',\n unit_price: 28.99,\n quantity: 1,\n },\n {\n order_id: 1002,\n book_id: 2,\n title: 'Heavy Metal Guitar Riffs',\n unit_price: 27.0,\n quantity: 2,\n },\n ])\n }\n}\n\nfunction getDatabaseFilePath(): string {\n let fileName =\n process.env.NODE_ENV === 'test'\n ? `bookstore.test.${process.pid}.${Date.now()}.sqlite`\n : 'bookstore.sqlite'\n\n return fileURLToPath(new URL(fileName, dataDirectoryUrl))\n}\n" }, { "path": "demos/bookstore/app/fragments.tsx", "content": "import type { Controller } from 'remix/fetch-router'\nimport { css } from 'remix/component'\nimport { Database } from 'remix/data-table'\nimport type { routes } from './routes.ts'\nimport { CartButton } from './assets/cart-button.tsx'\nimport { CartItems } from './assets/cart-items.tsx'\nimport { getCartTotal } from './data/cart.ts'\nimport { books } from './data/schema.ts'\nimport { loadAuth } from './middleware/auth.ts'\nimport { getCurrentCart, getCurrentUserSafely } from './utils/context.ts'\nimport { parseId } from './utils/ids.ts'\nimport { renderFragment } from './utils/render.ts'\nimport { routes as appRoutes } from './routes.ts'\n\nexport default {\n middleware: [loadAuth()],\n actions: {\n async cartButton({ get, params }) {\n let db = get(Database)\n let bookId = parseId(params.bookId)\n let book = bookId === undefined ? undefined : await db.find(books, bookId)\n\n if (!book) {\n return renderFragment(<p>Book not found</p>, { status: 404 })\n }\n\n let cart = getCurrentCart()\n let inCart = cart.items.some((item) => item.bookId === book.id)\n\n return renderFragment(<CartButton inCart={inCart} id={book.id} slug={book.slug} />)\n },\n\n cartItems() {\n let cart = getCurrentCart()\n let total = getCartTotal(cart)\n let user = getCurrentUserSafely()\n\n if (cart.items.length === 0) {\n return renderFragment(\n <div mix={[css({ marginTop: '2rem' })]}>\n <p>Your cart is empty.</p>\n <p mix={[css({ marginTop: '1rem' })]}>\n <a href={appRoutes.books.index.href()} class=\"btn\">\n Browse Books\n </a>\n </p>\n </div>,\n )\n }\n\n return renderFragment(<CartItems items={cart.items} total={total} canCheckout={!!user} />)\n },\n },\n} satisfies Controller<typeof routes.fragments>\n" }, { "path": "demos/bookstore/app/layout.tsx", "content": "import type { RemixNode } from 'remix/component'\n\nimport { routes } from './routes.ts'\nimport { getCurrentUserSafely } from './utils/context.ts'\n\nexport function Document() {\n return ({ title = 'Bookstore', children }: { title?: string; children?: RemixNode }) => (\n <html lang=\"en\">\n <head>\n <meta charSet=\"UTF-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>{title}\n \n \n\n" }, { "path": "packages/component/bench/frameworks/preact/index.tsx", "content": "import { useState, useCallback } from 'preact/hooks'\nimport {\n get1000Rows,\n get10000Rows,\n remove,\n sortRows,\n swapRows,\n updatedEvery10thRow,\n buildData,\n} from '../shared.ts'\nimport type { Benchmark, Row } from '../shared.ts'\nimport { render } from 'preact'\nimport { act } from 'preact/test-utils'\n\nexport const name = 'preact'\n\n// Stateful Metric Card Component\nfunction MetricCard({\n id,\n label,\n value,\n change,\n}: {\n id: number\n label: string\n value: string\n change: string\n}) {\n let [selected, setSelected] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n return (\n setSelected(!selected)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n transform: hovered && !selected ? 'translateY(-2px)' : 'translateY(0)',\n transition: 'all 0.2s',\n padding: '20px',\n border: '1px solid #ddd',\n borderRadius: '8px',\n cursor: 'pointer',\n boxShadow: selected ? '0 4px 8px rgba(0,0,0,0.1)' : '0 2px 4px rgba(0,0,0,0.05)',\n }}\n >\n
{label}
\n
{value}
\n
\n {change}\n
\n \n )\n}\n\n// Stateful Chart Bar Component\nfunction ChartBar({ value, index }: { value: number; index: number }) {\n let [hovered, setHovered] = useState(false)\n\n return (\n {}}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n />\n )\n}\n\n// Stateful Activity Item Component\nfunction ActivityItem({\n id,\n title,\n time,\n icon,\n}: {\n id: number\n title: string\n time: string\n icon: string\n}) {\n let [read, setRead] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n return (\n setRead(!read)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n padding: '12px',\n borderBottom: '1px solid #eee',\n cursor: 'pointer',\n backgroundColor: hovered ? '#f5f5f5' : read ? 'rgba(245, 245, 245, 0.6)' : '#fff',\n display: 'flex',\n alignItems: 'center',\n gap: '12px',\n }}\n >\n \n {icon}\n \n
\n
{title}
\n
{time}
\n
\n \n )\n}\n\n// Stateful Dropdown Menu Component\nfunction DropdownMenu({ rowId }: { rowId: number }) {\n let [open, setOpen] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n let actions = ['View Details', 'Edit', 'Duplicate', 'Archive', 'Delete']\n\n return (\n
\n {\n e.stopPropagation()\n setOpen(!open)\n }}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n style={{\n padding: '4px 8px',\n fontSize: '12px',\n backgroundColor: hovered ? '#286090' : '#337ab7',\n }}\n >\n ⋮\n \n {open && (\n setOpen(false)}\n >\n {actions.map((action, idx) => (\n {\n e.stopPropagation()\n setOpen(false)\n }}\n onMouseEnter={(e: any) => {\n e.currentTarget.style.backgroundColor = '#f5f5f5'\n }}\n onMouseLeave={(e: any) => {\n e.currentTarget.style.backgroundColor = '#fff'\n }}\n style={{\n padding: '8px 12px',\n cursor: 'pointer',\n borderBottom: idx < actions.length - 1 ? '1px solid #eee' : 'none',\n }}\n >\n {action}\n
\n ))}\n \n )}\n \n )\n}\n\n// Stateful Dashboard Table Row Component\nfunction DashboardTableRow({ row }: { row: Row }) {\n let [hovered, setHovered] = useState(false)\n let [selected, setSelected] = useState(false)\n\n return (\n setSelected(!selected)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n cursor: 'pointer',\n }}\n >\n {row.id}\n {row.label}\n \n Active\n \n \n ${(row.id * 10.5).toFixed(2)}\n \n \n \n \n \n )\n}\n\n// Stateful Search Input Component\nfunction SearchInput() {\n let [value, setValue] = useState('')\n let [focused, setFocused] = useState(false)\n\n return (\n setValue(e.target.value)}\n onFocus={() => setFocused(true)}\n onBlur={() => setFocused(false)}\n style={{\n padding: '8px 12px',\n border: `1px solid ${focused ? '#337ab7' : '#ddd'}`,\n borderRadius: '4px',\n fontSize: '14px',\n width: '300px',\n outline: focused ? '2px solid #337ab7' : 'none',\n outlineOffset: '2px',\n }}\n />\n )\n}\n\n// Stateful Form Widgets Component\nfunction FormWidgets() {\n let [selectValue, setSelectValue] = useState('option1')\n let [checkboxValues, setCheckboxValues] = useState>(new Set())\n let [radioValue, setRadioValue] = useState('radio1')\n let [toggleValue, setToggleValue] = useState(false)\n let [progressValue, setProgressValue] = useState(45)\n\n return (\n
\n

Settings

\n
\n \n setSelectValue(e.target.value)}\n onFocus={(e: any) => {\n e.currentTarget.style.borderColor = '#337ab7'\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.borderColor = '#ddd'\n e.currentTarget.style.outline = 'none'\n }}\n style={{\n padding: '6px 12px',\n border: '1px solid #ddd',\n borderRadius: '4px',\n fontSize: '14px',\n width: '100%',\n }}\n >\n \n \n \n \n \n
\n {['Checkbox 1', 'Checkbox 2', 'Checkbox 3'].map((label, idx) => (\n \n {\n let next = new Set(checkboxValues)\n if (e.target.checked) {\n next.add(`checkbox-${idx}`)\n } else {\n next.delete(`checkbox-${idx}`)\n }\n setCheckboxValues(next)\n }}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n />\n \n
\n ))}\n
\n {['Radio 1', 'Radio 2', 'Radio 3'].map((label, idx) => (\n \n ))}\n
\n
\n \n \n setToggleValue(e.target.checked)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n style={{ opacity: 0, width: 0, height: 0 }}\n />\n \n \n \n \n
\n
\n \n \n \n {progressValue}%\n
\n \n \n \n )\n}\n\nfunction Dashboard({ onSwitchToTable }: { onSwitchToTable: () => void }) {\n let [dashboardRows, setDashboardRows] = useState(() => buildData(300))\n\n let sortDashboardAsc = () => {\n setDashboardRows((current) => sortRows(current, true))\n }\n\n let sortDashboardDesc = () => {\n setDashboardRows((current) => sortRows(current, false))\n }\n let chartData = [65, 45, 78, 52, 89, 34, 67, 91, 43, 56, 72, 38, 55, 82, 47, 63, 71, 39, 58, 84]\n let activities = Array.from({ length: 50 }, (_, i) => ({\n id: i + 1,\n title: `Activity ${i + 1}: ${['Order placed', 'Payment received', 'Shipment created', 'Customer registered', 'Product updated'][i % 5]}`,\n time: `${i + 1} ${i === 0 ? 'minute' : 'minutes'} ago`,\n icon: ['O', 'P', 'S', 'C', 'U'][i % 5],\n }))\n\n return (\n
\n \n

Dashboard

\n {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n >\n Switch to Table\n \n
\n\n
\n
\n \n \n \n \n
\n
\n\n \n \n

Sales Performance

\n \n {chartData.map((value, index) => (\n \n ))}\n \n \n\n \n

Recent Activity

\n \n {activities.map((activity) => (\n \n ))}\n \n \n \n\n
\n \n
\n

Dashboard Items

\n \n Sort ↑\n \n \n Sort ↓\n \n
\n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n {dashboardRows.map((row) => (\n \n ))}\n \n
\n ID\n \n Label\n \n Status\n \n Value\n \n Actions\n
\n \n \n\n \n \n )\n}\n\nfunction App() {\n let [rows, setRows] = useState([])\n let [selected, setSelected] = useState(null)\n let [view, setView] = useState<'table' | 'dashboard'>('table')\n\n let run = () => {\n setRows(get1000Rows())\n setSelected(null)\n }\n\n let runLots = () => {\n setRows(get10000Rows())\n setSelected(null)\n }\n\n let add = () => {\n setRows((current) => [...current, ...get1000Rows()])\n }\n\n let update = () => {\n setRows((current) => updatedEvery10thRow(current))\n }\n\n let clear = () => {\n setRows([])\n setSelected(null)\n }\n\n let swap = () => {\n setRows((current) => swapRows(current))\n }\n\n let removeRow = (id: number) => {\n setRows((current) => remove(current, id))\n }\n\n let sortAsc = () => {\n setRows((current) => sortRows(current, true))\n }\n\n let sortDesc = () => {\n setRows((current) => sortRows(current, false))\n }\n\n let switchToDashboard = () => {\n setView('dashboard')\n }\n\n let switchToTable = () => {\n setView('table')\n }\n\n if (view === 'dashboard') {\n return \n }\n\n return (\n
\n
\n
\n
\n

Preact

\n
\n
\n
\n
\n \n
\n
\n \n Create 10,000 rows\n \n
\n
\n \n
\n
\n \n Update every 10th row\n \n
\n
\n \n
\n
\n \n Swap Rows\n \n
\n
\n \n Sort Ascending\n \n
\n
\n \n Sort Descending\n \n
\n
\n \n Switch to Dashboard\n \n
\n
\n
\n
\n
\n \n \n {rows.map((row) => {\n let rowId = row.id\n return (\n \n \n \n \n \n )\n })}\n \n
{rowId}\n {\n event.preventDefault()\n setSelected(rowId)\n }}\n >\n {row.label}\n \n \n {\n event.preventDefault()\n removeRow(rowId)\n }}\n >\n \n \n \n
\n \n
\n )\n}\n\nlet el = document.getElementById('app')!\nrender(, el)\n" }, { "path": "packages/component/bench/frameworks/preact/package.json", "content": "{\n \"name\": \"component-benchmark-preact\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build:prod\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm\",\n \"build\": \"esbuild index.tsx --bundle --outfile=dist/index.js --format=esm\",\n \"dev\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm --watch\"\n },\n \"dependencies\": {\n \"esbuild\": \"^0.27.1\",\n \"preact\": \"^10.28.0\"\n }\n}\n" }, { "path": "packages/component/bench/frameworks/preact/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\",\n \"jsxImportSource\": \"preact\"\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/bench/frameworks/preact-signals/index.html", "content": "\n\n \n \n Preact Signals Benchmark\n \n \n \n
\n \n \n\n" }, { "path": "packages/component/bench/frameworks/preact-signals/index.tsx", "content": "import { signal, batch, useComputed, type Signal } from '@preact/signals'\nimport { For } from '@preact/signals/utils'\nimport { render } from 'preact'\nimport { buildData as buildPlainData, sortRows as sortPlainRows, get1000Rows } from '../shared.ts'\nimport type { Benchmark, Row as PlainRow } from '../shared.ts'\n\nexport const name = 'preact-signals'\n\ntype Row = { id: number; label: Signal }\n\nfunction buildSignalData(count: number): Row[] {\n let plainData = buildPlainData(count)\n return plainData.map((row) => ({\n id: row.id,\n label: signal(row.label),\n }))\n}\n\n// Top-level signals for state\nlet data = signal([])\nlet selected = signal(null)\nlet view = signal<'table' | 'dashboard'>('table')\n\nlet run = () => {\n data.value = buildSignalData(1000)\n selected.value = null\n}\n\nlet runLots = () => {\n data.value = buildSignalData(10000)\n selected.value = null\n}\n\nlet add = () => {\n data.value = data.value.concat(buildSignalData(1000))\n}\n\nlet update = () => {\n batch(() => {\n for (let i = 0, d = data.value, len = d.length; i < len; i += 10) {\n d[i].label.value = d[i].label.value + ' !!!'\n }\n })\n}\n\nlet clear = () => {\n data.value = []\n selected.value = null\n}\n\nlet swap = () => {\n let d = data.value.slice()\n if (d.length > 998) {\n let tmp = d[1]\n d[1] = d[998]\n d[998] = tmp\n data.value = d\n }\n}\n\nlet removeRow = (id: number) => {\n let idx = data.value.findIndex((d) => d.id === id)\n data.value = [...data.value.slice(0, idx), ...data.value.slice(idx + 1)]\n}\n\nlet selectRow = (id: number) => {\n selected.value = id\n}\n\nlet sortAsc = () => {\n // Convert signal rows to plain rows, sort, then convert back\n let plainRows: PlainRow[] = data.value.map((row) => ({\n id: row.id,\n label: row.label.value,\n }))\n let sorted = sortPlainRows(plainRows, true)\n // Rebuild signal rows maintaining the same signal instances where possible\n let sortedSignalRows: Row[] = sorted.map((plainRow) => {\n let existing = data.value.find((r) => r.id === plainRow.id)\n if (existing && existing.label.value === plainRow.label) {\n return existing\n }\n return { id: plainRow.id, label: signal(plainRow.label) }\n })\n data.value = sortedSignalRows\n}\n\nlet sortDesc = () => {\n // Convert signal rows to plain rows, sort, then convert back\n let plainRows: PlainRow[] = data.value.map((row) => ({\n id: row.id,\n label: row.label.value,\n }))\n let sorted = sortPlainRows(plainRows, false)\n // Rebuild signal rows maintaining the same signal instances where possible\n let sortedSignalRows: Row[] = sorted.map((plainRow) => {\n let existing = data.value.find((r) => r.id === plainRow.id)\n if (existing && existing.label.value === plainRow.label) {\n return existing\n }\n return { id: plainRow.id, label: signal(plainRow.label) }\n })\n data.value = sortedSignalRows\n}\n\nlet switchToDashboard = () => {\n view.value = 'dashboard'\n}\n\nlet switchToTable = () => {\n view.value = 'table'\n}\n\n// Stateful Metric Card Component\nfunction MetricCard({\n id,\n label,\n value,\n change,\n}: {\n id: number\n label: string\n value: string\n change: string\n}) {\n let selected = signal(false)\n let hovered = signal(false)\n\n return (\n (selected.value = !selected.value)}\n onMouseEnter={() => (hovered.value = true)}\n onMouseLeave={() => (hovered.value = false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n style={{\n backgroundColor: hovered.value ? '#f5f5f5' : '#fff',\n transform: hovered.value && !selected.value ? 'translateY(-2px)' : 'translateY(0)',\n transition: 'all 0.2s',\n padding: '20px',\n border: '1px solid #ddd',\n borderRadius: '8px',\n cursor: 'pointer',\n boxShadow: selected.value ? '0 4px 8px rgba(0,0,0,0.1)' : '0 2px 4px rgba(0,0,0,0.05)',\n }}\n >\n
{label}
\n
{value}
\n
\n {change}\n
\n \n )\n}\n\n// Stateful Chart Bar Component\nfunction ChartBar({ value, index }: { value: number; index: number }) {\n let hovered = signal(false)\n\n return (\n {}}\n onMouseEnter={() => (hovered.value = true)}\n onMouseLeave={() => (hovered.value = false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n />\n )\n}\n\n// Stateful Activity Item Component\nfunction ActivityItem({\n id,\n title,\n time,\n icon,\n}: {\n id: number\n title: string\n time: string\n icon: string\n}) {\n let read = signal(false)\n let hovered = signal(false)\n\n return (\n (read.value = !read.value)}\n onMouseEnter={() => (hovered.value = true)}\n onMouseLeave={() => (hovered.value = false)}\n style={{\n padding: '12px',\n borderBottom: '1px solid #eee',\n cursor: 'pointer',\n backgroundColor: hovered.value\n ? '#f5f5f5'\n : read.value\n ? 'rgba(245, 245, 245, 0.6)'\n : '#fff',\n display: 'flex',\n alignItems: 'center',\n gap: '12px',\n }}\n >\n \n {icon}\n \n
\n
{title}
\n
{time}
\n
\n \n )\n}\n\n// Stateful Dropdown Menu Component\nfunction DropdownMenu({ rowId }: { rowId: number }) {\n let open = signal(false)\n let hovered = signal(false)\n\n let actions = ['View Details', 'Edit', 'Duplicate', 'Archive', 'Delete']\n\n return (\n
\n {\n e.stopPropagation()\n open.value = !open.value\n }}\n onMouseEnter={() => (hovered.value = true)}\n onMouseLeave={() => (hovered.value = false)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n style={{\n padding: '4px 8px',\n fontSize: '12px',\n backgroundColor: hovered.value ? '#286090' : '#337ab7',\n }}\n >\n ⋮\n \n {open.value && (\n (open.value = false)}\n >\n {actions.map((action, idx) => (\n {\n e.stopPropagation()\n open.value = false\n }}\n onMouseEnter={(e: any) => {\n e.currentTarget.style.backgroundColor = '#f5f5f5'\n }}\n onMouseLeave={(e: any) => {\n e.currentTarget.style.backgroundColor = '#fff'\n }}\n style={{\n padding: '8px 12px',\n cursor: 'pointer',\n borderBottom: idx < actions.length - 1 ? '1px solid #eee' : 'none',\n }}\n >\n {action}\n
\n ))}\n \n )}\n \n )\n}\n\n// Stateful Dashboard Table Row Component\nfunction DashboardTableRow({ row }: { row: PlainRow }) {\n let hovered = signal(false)\n let selected = signal(false)\n\n return (\n (selected.value = !selected.value)}\n onMouseEnter={() => (hovered.value = true)}\n onMouseLeave={() => (hovered.value = false)}\n style={{\n backgroundColor: hovered.value ? '#f5f5f5' : '#fff',\n cursor: 'pointer',\n }}\n >\n {row.id}\n {row.label}\n \n Active\n \n \n ${(row.id * 10.5).toFixed(2)}\n \n \n \n \n \n )\n}\n\n// Stateful Search Input Component\nfunction SearchInput() {\n let value = signal('')\n let focused = signal(false)\n\n return (\n (value.value = e.target.value)}\n onFocus={() => (focused.value = true)}\n onBlur={() => (focused.value = false)}\n style={{\n padding: '8px 12px',\n border: `1px solid ${focused.value ? '#337ab7' : '#ddd'}`,\n borderRadius: '4px',\n fontSize: '14px',\n width: '300px',\n outline: focused.value ? '2px solid #337ab7' : 'none',\n outlineOffset: '2px',\n }}\n />\n )\n}\n\n// Stateful Form Widgets Component\nfunction FormWidgets() {\n let selectValue = signal('option1')\n let checkboxValues = signal>(new Set())\n let radioValue = signal('radio1')\n let toggleValue = signal(false)\n let progressValue = signal(45)\n\n return (\n
\n

Settings

\n
\n \n (selectValue.value = e.target.value)}\n onFocus={(e: any) => {\n e.currentTarget.style.borderColor = '#337ab7'\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.borderColor = '#ddd'\n e.currentTarget.style.outline = 'none'\n }}\n style={{\n padding: '6px 12px',\n border: '1px solid #ddd',\n borderRadius: '4px',\n fontSize: '14px',\n width: '100%',\n }}\n >\n \n \n \n \n \n
\n {['Checkbox 1', 'Checkbox 2', 'Checkbox 3'].map((label, idx) => (\n \n {\n let next = new Set(checkboxValues.value)\n if (e.target.checked) {\n next.add(`checkbox-${idx}`)\n } else {\n next.delete(`checkbox-${idx}`)\n }\n checkboxValues.value = next\n }}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n />\n \n
\n ))}\n
\n {['Radio 1', 'Radio 2', 'Radio 3'].map((label, idx) => (\n \n ))}\n
\n
\n \n \n (toggleValue.value = e.target.checked)}\n onFocus={(e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n style={{ opacity: 0, width: 0, height: 0 }}\n />\n \n \n \n \n
\n
\n \n \n \n {progressValue.value}%\n
\n \n \n \n )\n}\n\nfunction Row({ id, label }: { id: number; label: Signal }) {\n let rowClass = useComputed(() => (selected.value === id ? 'danger' : ''))\n return (\n \n {id}\n \n {\n event.preventDefault()\n selectRow(id)\n }}\n >\n {label}\n \n \n \n {\n event.preventDefault()\n removeRow(id)\n }}\n >\n \n \n \n \n \n )\n}\n\nfunction Dashboard({ onSwitchToTable }: { onSwitchToTable: () => void }) {\n let dashboardRows = signal(buildPlainData(300))\n\n let sortDashboardAsc = () => {\n dashboardRows.value = sortPlainRows(dashboardRows.value, true)\n }\n\n let sortDashboardDesc = () => {\n dashboardRows.value = sortPlainRows(dashboardRows.value, false)\n }\n let chartData = [65, 45, 78, 52, 89, 34, 67, 91, 43, 56, 72, 38, 55, 82, 47, 63, 71, 39, 58, 84]\n let activities = Array.from({ length: 50 }, (_, i) => ({\n id: i + 1,\n title: `Activity ${i + 1}: ${['Order placed', 'Payment received', 'Shipment created', 'Customer registered', 'Product updated'][i % 5]}`,\n time: `${i + 1} ${i === 0 ? 'minute' : 'minutes'} ago`,\n icon: ['O', 'P', 'S', 'C', 'U'][i % 5],\n }))\n\n return (\n
\n \n

Dashboard

\n {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e: any) => {\n e.currentTarget.style.outline = ''\n }}\n >\n Switch to Table\n \n
\n\n
\n
\n \n \n \n \n
\n
\n\n \n \n

Sales Performance

\n \n {chartData.map((value, index) => (\n \n ))}\n \n \n\n \n

Recent Activity

\n \n {activities.map((activity) => (\n \n ))}\n \n \n \n\n
\n \n
\n

Dashboard Items

\n \n Sort ↑\n \n \n Sort ↓\n \n
\n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n {dashboardRows.value.map((row) => (\n \n ))}\n \n
\n ID\n \n Label\n \n Status\n \n Value\n \n Actions\n
\n \n \n\n \n \n )\n}\n\nfunction App() {\n let currentView = view.value\n\n if (currentView === 'dashboard') {\n return \n }\n\n return (\n
\n
\n
\n
\n

Preact Signals

\n
\n
\n
\n
\n \n
\n
\n \n Create 10,000 rows\n \n
\n
\n \n
\n
\n \n Update every 10th row\n \n
\n
\n \n
\n
\n \n Swap Rows\n \n
\n
\n \n Sort Ascending\n \n
\n
\n \n Sort Descending\n \n
\n
\n \n Switch to Dashboard\n \n
\n
\n
\n
\n
\n \n \n {(row) => }\n \n
\n \n
\n )\n}\n\nlet el = document.getElementById('app')!\nrender(, el)\n" }, { "path": "packages/component/bench/frameworks/preact-signals/package.json", "content": "{\n \"name\": \"component-benchmark-preact-signals\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm\",\n \"dev\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm --watch\"\n },\n \"dependencies\": {\n \"@preact/signals\": \"^2.0.4\",\n \"esbuild\": \"^0.27.1\",\n \"preact\": \"^10.28.0\"\n }\n}\n" }, { "path": "packages/component/bench/frameworks/preact-signals/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\",\n \"jsxImportSource\": \"preact\"\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/bench/frameworks/react/index.html", "content": "\n\n \n \n React Benchmark\n \n \n \n
\n \n \n\n" }, { "path": "packages/component/bench/frameworks/react/index.tsx", "content": "import { useState } from 'react'\nimport {\n get1000Rows,\n get10000Rows,\n remove,\n sortRows,\n swapRows,\n updatedEvery10thRow,\n buildData,\n} from '../shared.ts'\nimport type { Benchmark, Row } from '../shared.ts'\nimport { createRoot, type Root } from 'react-dom/client'\nimport { flushSync } from 'react-dom'\n\nexport const name = 'react'\n\n// Stateful Metric Card Component\nfunction MetricCard({\n id,\n label,\n value,\n change,\n}: {\n id: number\n label: string\n value: string\n change: string\n}) {\n let [selected, setSelected] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n return (\n setSelected(!selected)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n transform: hovered && !selected ? 'translateY(-2px)' : 'translateY(0)',\n transition: 'all 0.2s',\n padding: '20px',\n border: '1px solid #ddd',\n borderRadius: '8px',\n cursor: 'pointer',\n boxShadow: selected ? '0 4px 8px rgba(0,0,0,0.1)' : '0 2px 4px rgba(0,0,0,0.05)',\n }}\n >\n
{label}
\n
{value}
\n
\n {change}\n
\n \n )\n}\n\n// Stateful Chart Bar Component\nfunction ChartBar({ value, index }: { value: number; index: number }) {\n let [hovered, setHovered] = useState(false)\n\n return (\n {}}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n />\n )\n}\n\n// Stateful Activity Item Component\nfunction ActivityItem({\n id,\n title,\n time,\n icon,\n}: {\n id: number\n title: string\n time: string\n icon: string\n}) {\n let [read, setRead] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n return (\n setRead(!read)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n padding: '12px',\n borderBottom: '1px solid #eee',\n cursor: 'pointer',\n backgroundColor: hovered ? '#f5f5f5' : read ? 'rgba(245, 245, 245, 0.6)' : '#fff',\n display: 'flex',\n alignItems: 'center',\n gap: '12px',\n }}\n >\n \n {icon}\n \n
\n
{title}
\n
{time}
\n
\n \n )\n}\n\n// Stateful Dropdown Menu Component\nfunction DropdownMenu({ rowId }: { rowId: number }) {\n let [open, setOpen] = useState(false)\n let [hovered, setHovered] = useState(false)\n\n let actions = ['View Details', 'Edit', 'Duplicate', 'Archive', 'Delete']\n\n return (\n
\n {\n e.stopPropagation()\n setOpen(!open)\n }}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n style={{\n padding: '4px 8px',\n fontSize: '12px',\n backgroundColor: hovered ? '#286090' : '#337ab7',\n }}\n >\n ⋮\n \n {open && (\n setOpen(false)}\n >\n {actions.map((action, idx) => (\n {\n e.stopPropagation()\n setOpen(false)\n }}\n onMouseEnter={(e) => {\n e.currentTarget.style.backgroundColor = '#f5f5f5'\n }}\n onMouseLeave={(e) => {\n e.currentTarget.style.backgroundColor = '#fff'\n }}\n style={{\n padding: '8px 12px',\n cursor: 'pointer',\n borderBottom: idx < actions.length - 1 ? '1px solid #eee' : 'none',\n }}\n >\n {action}\n
\n ))}\n \n )}\n \n )\n}\n\n// Stateful Dashboard Table Row Component\nfunction DashboardTableRow({ row }: { row: Row }) {\n let [hovered, setHovered] = useState(false)\n let [selected, setSelected] = useState(false)\n\n return (\n setSelected(!selected)}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n cursor: 'pointer',\n }}\n >\n {row.id}\n {row.label}\n \n Active\n \n \n ${(row.id * 10.5).toFixed(2)}\n \n \n \n \n \n )\n}\n\n// Stateful Search Input Component\nfunction SearchInput() {\n let [value, setValue] = useState('')\n let [focused, setFocused] = useState(false)\n\n return (\n setValue(e.target.value)}\n onFocus={() => setFocused(true)}\n onBlur={() => setFocused(false)}\n style={{\n padding: '8px 12px',\n border: `1px solid ${focused ? '#337ab7' : '#ddd'}`,\n borderRadius: '4px',\n fontSize: '14px',\n width: '300px',\n outline: focused ? '2px solid #337ab7' : 'none',\n outlineOffset: '2px',\n }}\n />\n )\n}\n\n// Stateful Form Widgets Component\nfunction FormWidgets() {\n let [selectValue, setSelectValue] = useState('option1')\n let [checkboxValues, setCheckboxValues] = useState>(new Set())\n let [radioValue, setRadioValue] = useState('radio1')\n let [toggleValue, setToggleValue] = useState(false)\n let [progressValue, setProgressValue] = useState(45)\n\n return (\n
\n

Settings

\n
\n \n setSelectValue(e.target.value)}\n onFocus={(e) => {\n e.currentTarget.style.borderColor = '#337ab7'\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.borderColor = '#ddd'\n e.currentTarget.style.outline = 'none'\n }}\n style={{\n padding: '6px 12px',\n border: '1px solid #ddd',\n borderRadius: '4px',\n fontSize: '14px',\n width: '100%',\n }}\n >\n \n \n \n \n \n
\n {['Checkbox 1', 'Checkbox 2', 'Checkbox 3'].map((label, idx) => (\n \n {\n let next = new Set(checkboxValues)\n if (e.target.checked) {\n next.add(`checkbox-${idx}`)\n } else {\n next.delete(`checkbox-${idx}`)\n }\n setCheckboxValues(next)\n }}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n />\n \n
\n ))}\n
\n {['Radio 1', 'Radio 2', 'Radio 3'].map((label, idx) => (\n \n ))}\n
\n
\n \n \n setToggleValue(e.target.checked)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n style={{ opacity: 0, width: 0, height: 0 }}\n />\n \n \n \n \n
\n
\n \n \n \n {progressValue}%\n
\n \n \n \n )\n}\n\nfunction Dashboard({ onSwitchToTable }: { onSwitchToTable: () => void }) {\n let [dashboardRows, setDashboardRows] = useState(() => buildData(300))\n\n let sortDashboardAsc = () => {\n setDashboardRows((current) => sortRows(current, true))\n }\n\n let sortDashboardDesc = () => {\n setDashboardRows((current) => sortRows(current, false))\n }\n let chartData = [65, 45, 78, 52, 89, 34, 67, 91, 43, 56, 72, 38, 55, 82, 47, 63, 71, 39, 58, 84]\n let activities = Array.from({ length: 50 }, (_, i) => ({\n id: i + 1,\n title: `Activity ${i + 1}: ${['Order placed', 'Payment received', 'Shipment created', 'Customer registered', 'Product updated'][i % 5]}`,\n time: `${i + 1} ${i === 0 ? 'minute' : 'minutes'} ago`,\n icon: ['O', 'P', 'S', 'C', 'U'][i % 5],\n }))\n\n return (\n
\n \n

Dashboard

\n {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n >\n Switch to Table\n \n
\n\n
\n
\n \n \n \n \n
\n
\n\n \n \n

Sales Performance

\n \n {chartData.map((value, index) => (\n \n ))}\n \n \n\n \n

Recent Activity

\n \n {activities.map((activity) => (\n \n ))}\n \n \n \n\n
\n \n
\n

Dashboard Items

\n \n Sort ↑\n \n \n Sort ↓\n \n
\n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n {dashboardRows.map((row) => (\n \n ))}\n \n
\n ID\n \n Label\n \n Status\n \n Value\n \n Actions\n
\n \n \n\n \n \n )\n}\n\nfunction App() {\n let [rows, setRows] = useState([])\n let [selected, setSelected] = useState(null)\n let [view, setView] = useState<'table' | 'dashboard'>('table')\n\n let run = () => {\n setRows(get1000Rows())\n setSelected(null)\n }\n\n let runLots = () => {\n setRows(get10000Rows())\n setSelected(null)\n }\n\n let add = () => {\n setRows((current) => [...current, ...get1000Rows()])\n }\n\n let update = () => {\n setRows((current) => updatedEvery10thRow(current))\n }\n\n let clear = () => {\n setRows([])\n setSelected(null)\n }\n\n let swap = () => {\n setRows((current) => swapRows(current))\n }\n\n let removeRow = (id: number) => {\n setRows((current) => remove(current, id))\n }\n\n let sortAsc = () => {\n setRows((current) => sortRows(current, true))\n }\n\n let sortDesc = () => {\n setRows((current) => sortRows(current, false))\n }\n\n let switchToDashboard = () => {\n setView('dashboard')\n }\n\n let switchToTable = () => {\n setView('table')\n }\n\n if (view === 'dashboard') {\n return \n }\n\n return (\n
\n
\n
\n
\n

React

\n
\n
\n
\n
\n \n
\n
\n \n Create 10,000 rows\n \n
\n
\n \n
\n
\n \n Update every 10th row\n \n
\n
\n \n Clear\n \n
\n
\n \n Swap Rows\n \n
\n
\n \n Sort Ascending\n \n
\n
\n \n Sort Descending\n \n
\n
\n \n Switch to Dashboard\n \n
\n
\n
\n
\n
\n \n \n {rows.map((row) => {\n let rowId = row.id\n return (\n \n \n \n \n \n )\n })}\n \n
{rowId}\n {\n event.preventDefault()\n setSelected(rowId)\n }}\n >\n {row.label}\n \n \n {\n event.preventDefault()\n removeRow(rowId)\n }}\n >\n \n \n \n
\n \n
\n )\n}\n\nlet el = document.getElementById('app')!\nlet root = createRoot(el)\nroot.render()\n" }, { "path": "packages/component/bench/frameworks/react/package.json", "content": "{\n \"name\": \"component-benchmark-remix\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm\",\n \"dev\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm --watch\"\n },\n \"dependencies\": {\n \"esbuild\": \"^0.27.1\",\n \"react\": \"^19.2.1\",\n \"react-dom\": \"^19.2.1\"\n },\n \"devDependencies\": {\n \"@types/react\": \"^19.2.7\",\n \"@types/react-dom\": \"^19.2.3\"\n }\n}\n" }, { "path": "packages/component/bench/frameworks/react/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\"\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/bench/frameworks/remix/index.html", "content": "\n\n \n \n Remix Benchmark\n \n \n \n
\n \n \n\n" }, { "path": "packages/component/bench/frameworks/remix/index.tsx", "content": "import {\n get1000Rows,\n get10000Rows,\n remove,\n sortRows,\n swapRows,\n updatedEvery10thRow,\n buildData,\n} from '../shared.ts'\nimport type { Benchmark, Row } from '../shared.ts'\nimport { createRoot, on } from '@remix-run/component'\nimport type { Handle } from '@remix-run/component'\n\nexport const name = 'remix'\n\nfunction Button() {\n return ({ id, text, fn }: { id: string; text: string; fn: () => void }) => (\n
\n \n
\n )\n}\n\n// Stateful Metric Card Component\nfunction MetricCard(handle: Handle) {\n let selected = false\n let hovered = false\n\n return ({\n id,\n label,\n value,\n change,\n }: {\n id: number\n label: string\n value: string\n change: string\n }) => (\n {\n selected = !selected\n handle.update()\n }),\n on('mouseenter', () => {\n hovered = true\n handle.update()\n }),\n on('mouseleave', () => {\n hovered = false\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.outline = ''\n }),\n ]}\n tabIndex={0}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n transform: hovered && !selected ? 'translateY(-2px)' : 'translateY(0)',\n transition: 'all 0.2s',\n padding: '20px',\n border: '1px solid #ddd',\n borderRadius: '8px',\n cursor: 'pointer',\n boxShadow: selected ? '0 4px 8px rgba(0,0,0,0.1)' : '0 2px 4px rgba(0,0,0,0.05)',\n }}\n >\n
{label}
\n
{value}
\n
\n {change}\n
\n \n )\n}\n\n// Stateful Chart Bar Component\nfunction ChartBar(handle: Handle) {\n let hovered = false\n\n return ({ value, index }: { value: number; index: number }) => (\n {}),\n on('mouseenter', () => {\n hovered = true\n handle.update()\n }),\n on('mouseleave', () => {\n hovered = false\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.outline = ''\n }),\n ]}\n style={{\n height: `${value}%`,\n backgroundColor: hovered ? '#286090' : '#337ab7',\n width: '30px',\n margin: '0 2px',\n cursor: 'pointer',\n transition: 'all 0.2s',\n opacity: hovered ? 0.9 : 1,\n transform: hovered ? 'scaleY(1.1)' : 'scaleY(1)',\n }}\n tabIndex={0}\n />\n )\n}\n\n// Stateful Activity Item Component\nfunction ActivityItem(handle: Handle) {\n let read = false\n let hovered = false\n\n return ({ id, title, time, icon }: { id: number; title: string; time: string; icon: string }) => (\n {\n read = !read\n handle.update()\n }),\n on('mouseenter', () => {\n hovered = true\n handle.update()\n }),\n on('mouseleave', () => {\n hovered = false\n handle.update()\n }),\n ]}\n style={{\n padding: '12px',\n borderBottom: '1px solid #eee',\n cursor: 'pointer',\n backgroundColor: hovered ? '#f5f5f5' : read ? 'rgba(245, 245, 245, 0.6)' : '#fff',\n display: 'flex',\n alignItems: 'center',\n gap: '12px',\n }}\n >\n \n {icon}\n \n
\n
{title}
\n
{time}
\n
\n \n )\n}\n\n// Stateful Dropdown Menu Component\nfunction DropdownMenu(handle: Handle) {\n let open = false\n let hovered = false\n\n let actions = ['View Details', 'Edit', 'Duplicate', 'Archive', 'Delete']\n\n return ({ rowId }: { rowId: number }) => (\n
\n {\n e.stopPropagation()\n open = !open\n handle.update()\n }),\n on('mouseenter', () => {\n hovered = true\n handle.update()\n }),\n on('mouseleave', () => {\n hovered = false\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.outline = ''\n }),\n ]}\n style={{\n padding: '4px 8px',\n fontSize: '12px',\n backgroundColor: hovered ? '#286090' : '#337ab7',\n }}\n >\n ⋮\n \n {open && (\n {\n open = false\n handle.update()\n }),\n ]}\n >\n {actions.map((action, idx) => (\n {\n e.stopPropagation()\n open = false\n handle.update()\n }),\n on('mouseenter', (e: any) => {\n e.currentTarget.style.backgroundColor = '#f5f5f5'\n }),\n on('mouseleave', (e: any) => {\n e.currentTarget.style.backgroundColor = '#fff'\n }),\n ]}\n style={{\n padding: '8px 12px',\n cursor: 'pointer',\n borderBottom: idx < actions.length - 1 ? '1px solid #eee' : 'none',\n }}\n >\n {action}\n
\n ))}\n \n )}\n \n )\n}\n\n// Stateful Dashboard Table Row Component\nfunction DashboardTableRow(handle: Handle) {\n let hovered = false\n let selected = false\n\n return ({ row }: { row: Row }) => (\n {\n selected = !selected\n handle.update()\n }),\n on('mouseenter', () => {\n hovered = true\n handle.update()\n }),\n on('mouseleave', () => {\n hovered = false\n handle.update()\n }),\n ]}\n style={{\n backgroundColor: hovered ? '#f5f5f5' : '#fff',\n cursor: 'pointer',\n }}\n >\n {row.id}\n {row.label}\n \n Active\n \n \n ${(row.id * 10.5).toFixed(2)}\n \n \n \n \n \n )\n}\n\n// Stateful Search Input Component\nfunction SearchInput(handle: Handle) {\n let value = ''\n let focused = false\n\n return () => (\n {\n value = e.target.value\n handle.update()\n }),\n on('focus', () => {\n focused = true\n handle.update()\n }),\n on('blur', () => {\n focused = false\n handle.update()\n }),\n ]}\n style={{\n padding: '8px 12px',\n border: `1px solid ${focused ? '#337ab7' : '#ddd'}`,\n borderRadius: '4px',\n fontSize: '14px',\n width: '300px',\n outline: focused ? '2px solid #337ab7' : 'none',\n outlineOffset: '2px',\n }}\n />\n )\n}\n\n// Stateful Form Widgets Component\nfunction FormWidgets(handle: Handle) {\n let selectValue = 'option1'\n let checkboxValues = new Set()\n let radioValue = 'radio1'\n let toggleValue = false\n let progressValue = 45\n\n return () => (\n
\n

Settings

\n
\n \n {\n selectValue = e.target.value\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.borderColor = '#337ab7'\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.borderColor = '#ddd'\n e.currentTarget.style.outline = 'none'\n }),\n ]}\n style={{\n padding: '6px 12px',\n border: '1px solid #ddd',\n borderRadius: '4px',\n fontSize: '14px',\n width: '100%',\n }}\n >\n \n \n \n \n \n
\n {['Checkbox 1', 'Checkbox 2', 'Checkbox 3'].map((label, idx) => (\n \n {\n if (e.target.checked) {\n checkboxValues.add(`checkbox-${idx}`)\n } else {\n checkboxValues.delete(`checkbox-${idx}`)\n }\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.outline = ''\n }),\n ]}\n />\n \n
\n ))}\n
\n {['Radio 1', 'Radio 2', 'Radio 3'].map((label, idx) => (\n \n ))}\n
\n
\n \n \n {\n toggleValue = e.target.checked\n handle.update()\n }),\n on('focus', (e: any) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }),\n on('blur', (e: any) => {\n e.currentTarget.style.outline = ''\n }),\n ]}\n style={{ opacity: 0, width: 0, height: 0 }}\n />\n \n \n \n \n
\n
\n \n \n \n {progressValue}%\n
\n \n \n \n )\n}\n\nfunction Dashboard(handle: Handle) {\n let dashboardRows = buildData(300)\n\n let sortDashboardAsc = () => {\n dashboardRows = sortRows(dashboardRows, true)\n handle.update()\n }\n\n let sortDashboardDesc = () => {\n dashboardRows = sortRows(dashboardRows, false)\n handle.update()\n }\n let chartData = [65, 45, 78, 52, 89, 34, 67, 91, 43, 56, 72, 38, 55, 82, 47, 63, 71, 39, 58, 84]\n let activities = Array.from({ length: 50 }, (_, i) => ({\n id: i + 1,\n title: `Activity ${i + 1}: ${['Order placed', 'Payment received', 'Shipment created', 'Customer registered', 'Product updated'][i % 5]}`,\n time: `${i + 1} ${i === 0 ? 'minute' : 'minutes'} ago`,\n icon: ['O', 'P', 'S', 'C', 'U'][i % 5],\n }))\n\n return ({ onSwitchToTable }: { onSwitchToTable: () => void }) => (\n
\n \n

Dashboard

\n \n Switch to Table\n \n
\n\n
\n
\n \n \n \n \n
\n
\n\n \n \n

Sales Performance

\n \n {chartData.map((value, index) => (\n \n ))}\n \n \n\n \n

Recent Activity

\n \n {activities.map((activity) => (\n \n ))}\n \n \n \n\n
\n \n
\n

Dashboard Items

\n \n Sort ↑\n \n \n Sort ↓\n \n
\n \n
\n \n \n \n \n \n \n \n \n \n \n \n \n {dashboardRows.map((row) => (\n \n ))}\n \n
\n ID\n \n Label\n \n Status\n \n Value\n \n Actions\n
\n \n \n\n \n \n )\n}\n\nfunction App(handle: Handle) {\n let rows: Row[] = []\n let selected: number | null = null\n let view: 'table' | 'dashboard' = 'table'\n\n let setRows = (newRows: Row[]) => {\n rows = newRows\n handle.update()\n }\n\n let setSelected = (newSelected: number | null) => {\n selected = newSelected\n handle.update()\n }\n\n let switchToDashboard = () => {\n view = 'dashboard'\n handle.update()\n }\n\n let switchToTable = () => {\n view = 'table'\n handle.update()\n }\n\n return () => {\n if (view === 'dashboard') {\n return \n }\n\n return (\n
\n
\n
\n
\n

Remix

\n
\n
\n
\n {\n rows = get1000Rows()\n selected = null\n handle.update()\n }}\n />\n {\n rows = get10000Rows()\n selected = null\n handle.update()\n }}\n />\n {\n setRows([...rows, ...get1000Rows()])\n }}\n />\n {\n setRows(updatedEvery10thRow(rows))\n }}\n />\n {\n rows = []\n selected = null\n handle.update()\n }}\n />\n {\n setRows(swapRows(rows))\n }}\n />\n {\n setRows(sortRows(rows, true))\n }}\n />\n {\n setRows(sortRows(rows, false))\n }}\n />\n
\n
\n
\n
\n \n \n {rows.map((row) => {\n let rowId = row.id\n return (\n \n \n \n \n \n )\n })}\n \n
{rowId}\n {\n setSelected(rowId)\n }),\n ]}\n >\n {row.label}\n \n \n {\n setRows(remove(rows, rowId))\n }),\n ]}\n >\n \n \n \n
\n \n
\n )\n }\n}\n\nlet el = document.getElementById('app')!\nlet root = createRoot(el)\nroot.render()\n" }, { "path": "packages/component/bench/frameworks/remix/package.json", "content": "{\n \"name\": \"component-benchmark-remix\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build:prod\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm\",\n \"build\": \"esbuild index.tsx --bundle --outfile=dist/index.js --format=esm\",\n \"dev\": \"esbuild index.tsx --bundle --minify --outfile=dist/index.js --format=esm --watch\"\n },\n \"dependencies\": {\n \"@remix-run/component\": \"workspace:^\",\n \"esbuild\": \"^0.27.1\"\n }\n}\n" }, { "path": "packages/component/bench/frameworks/remix/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\",\n \"jsxImportSource\": \"@remix-run/component\"\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/bench/frameworks/shared.ts", "content": "export interface Benchmark {\n run(): void\n teardown(): void\n}\n\nexport interface Framework {\n name: string\n insert: () => Benchmark\n // swap: Benchmark\n // update: Benchmark\n // replace: Benchmark\n}\n\nexport type Row = { id: number; label: string }\n\nlet idCounter = 1\n\nconst A = [\n 'pretty',\n 'large',\n 'big',\n 'small',\n 'tall',\n 'short',\n 'long',\n 'handsome',\n 'plain',\n 'quaint',\n 'clean',\n 'elegant',\n 'easy',\n 'angry',\n 'crazy',\n 'helpful',\n 'mushy',\n 'odd',\n 'unsightly',\n 'adorable',\n 'important',\n 'inexpensive',\n 'cheap',\n 'expensive',\n 'fancy',\n ],\n C = [\n 'red',\n 'yellow',\n 'blue',\n 'green',\n 'pink',\n 'brown',\n 'purple',\n 'brown',\n 'white',\n 'black',\n 'orange',\n ],\n N = [\n 'table',\n 'chair',\n 'house',\n 'bbq',\n 'desk',\n 'car',\n 'pony',\n 'cookie',\n 'sandwich',\n 'burger',\n 'pizza',\n 'mouse',\n 'keyboard',\n ]\n\nexport function buildData(count: number) {\n let data = new Array(count)\n\n for (let i = 0; i < count; i++) {\n // Use deterministic selection based on index to ensure same data every time\n data[i] = {\n id: idCounter++,\n label: `${A[i % A.length]} ${C[i % C.length]} ${N[i % N.length]}`,\n }\n }\n\n return data\n}\n\nexport function get1000Rows(): Row[] {\n return buildData(1000)\n}\n\nexport function get10000Rows(): Row[] {\n return buildData(10000)\n}\n\nexport function updatedEvery10thRow(data: Row[]): Row[] {\n let newData = data.slice(0)\n for (let i = 0, d = data, len = d.length; i < len; i += 10) {\n newData[i] = { id: data[i].id, label: data[i].label + ' !!!' }\n }\n return newData\n}\n\nexport function swapRows(data: Row[]): Row[] {\n let d = data.slice()\n if (d.length > 998) {\n let tmp = d[1]\n d[1] = d[998]\n d[998] = tmp\n }\n return d\n}\n\nexport function remove(data: Row[], id: number): Row[] {\n return data.filter((d) => d.id !== id)\n}\n\nexport function sortRows(data: Row[], ascending: boolean = true): Row[] {\n let sorted = data.slice().sort((a, b) => {\n if (ascending) {\n return a.label.localeCompare(b.label)\n } else {\n return b.label.localeCompare(a.label)\n }\n })\n return sorted\n}\n" }, { "path": "packages/component/bench/frameworks/solid/build.js", "content": "import { build, context } from 'esbuild'\nimport { solidPlugin } from 'esbuild-plugin-solid'\n\nlet isProduction = process.env.NODE_ENV === 'production'\nlet isWatch = process.argv.includes('--watch')\n\nlet buildOptions = {\n entryPoints: ['index.tsx'],\n bundle: true,\n outfile: 'dist/index.js',\n format: 'esm',\n plugins: [solidPlugin()],\n minify: isProduction,\n}\n\nif (isWatch) {\n let ctx = await context(buildOptions)\n await ctx.watch()\n console.log('Watching...')\n} else {\n await build(buildOptions)\n console.log('Build complete')\n}\n" }, { "path": "packages/component/bench/frameworks/solid/index.html", "content": "\n\n \n \n SolidJS Benchmark\n \n \n \n
\n \n \n\n" }, { "path": "packages/component/bench/frameworks/solid/index.tsx", "content": "import { createSignal, createSelector, For } from 'solid-js'\nimport { render } from 'solid-js/web'\nimport {\n get1000Rows,\n get10000Rows,\n remove,\n sortRows,\n swapRows,\n updatedEvery10thRow,\n buildData,\n} from '../shared.ts'\nimport type { Benchmark, Row } from '../shared.ts'\n\nexport const name = 'solid'\n\n// Stateful Metric Card Component\nfunction MetricCard(props: { id: number; label: string; value: string; change: string }) {\n let [selected, setSelected] = createSignal(false)\n let [hovered, setHovered] = createSignal(false)\n\n return (\n setSelected(!selected())}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n style={{\n 'background-color': hovered() ? '#f5f5f5' : '#fff',\n transform: hovered() && !selected() ? 'translateY(-2px)' : 'translateY(0)',\n transition: 'all 0.2s',\n padding: '20px',\n border: '1px solid #ddd',\n 'border-radius': '8px',\n cursor: 'pointer',\n 'box-shadow': selected() ? '0 4px 8px rgba(0,0,0,0.1)' : '0 2px 4px rgba(0,0,0,0.05)',\n }}\n >\n
\n {props.label}\n
\n
\n {props.value}\n
\n \n {props.change}\n \n \n )\n}\n\n// Stateful Chart Bar Component\nfunction ChartBar(props: { value: number; index: number }) {\n let [hovered, setHovered] = createSignal(false)\n\n return (\n {}}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n tabIndex={0}\n />\n )\n}\n\n// Stateful Activity Item Component\nfunction ActivityItem(props: { id: number; title: string; time: string; icon: string }) {\n let [read, setRead] = createSignal(false)\n let [hovered, setHovered] = createSignal(false)\n\n return (\n setRead(!read())}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n padding: '12px',\n 'border-bottom': '1px solid #eee',\n cursor: 'pointer',\n 'background-color': hovered() ? '#f5f5f5' : read() ? 'rgba(245, 245, 245, 0.6)' : '#fff',\n display: 'flex',\n 'align-items': 'center',\n gap: '12px',\n }}\n >\n \n {props.icon}\n \n
\n
{props.title}
\n
{props.time}
\n
\n \n )\n}\n\n// Stateful Dropdown Menu Component\nfunction DropdownMenu(props: { rowId: number }) {\n let [open, setOpen] = createSignal(false)\n let [hovered, setHovered] = createSignal(false)\n\n let actions = ['View Details', 'Edit', 'Duplicate', 'Archive', 'Delete']\n\n return (\n
\n {\n e.stopPropagation()\n setOpen(!open())\n }}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n style={{\n padding: '4px 8px',\n 'font-size': '12px',\n 'background-color': hovered() ? '#286090' : '#337ab7',\n }}\n >\n ⋮\n \n {open() && (\n setOpen(false)}\n >\n \n {(action, idx) => (\n {\n e.stopPropagation()\n setOpen(false)\n }}\n onMouseEnter={(e) => {\n e.currentTarget.style.backgroundColor = '#f5f5f5'\n }}\n onMouseLeave={(e) => {\n e.currentTarget.style.backgroundColor = '#fff'\n }}\n style={{\n padding: '8px 12px',\n cursor: 'pointer',\n 'border-bottom': idx() < actions.length - 1 ? '1px solid #eee' : 'none',\n }}\n >\n {action}\n
\n )}\n \n \n )}\n \n )\n}\n\n// Stateful Dashboard Table Row Component\nfunction DashboardTableRow(props: { row: Row }) {\n let [hovered, setHovered] = createSignal(false)\n let [selected, setSelected] = createSignal(false)\n\n return (\n setSelected(!selected())}\n onMouseEnter={() => setHovered(true)}\n onMouseLeave={() => setHovered(false)}\n style={{\n 'background-color': hovered() ? '#f5f5f5' : '#fff',\n cursor: 'pointer',\n }}\n >\n {props.row.id}\n {props.row.label}\n \n Active\n \n \n ${(props.row.id * 10.5).toFixed(2)}\n \n \n \n \n \n )\n}\n\n// Stateful Search Input Component\nfunction SearchInput() {\n let [value, setValue] = createSignal('')\n let [focused, setFocused] = createSignal(false)\n\n return (\n setValue(e.currentTarget.value)}\n onFocus={() => setFocused(true)}\n onBlur={() => setFocused(false)}\n style={{\n padding: '8px 12px',\n border: `1px solid ${focused() ? '#337ab7' : '#ddd'}`,\n 'border-radius': '4px',\n 'font-size': '14px',\n width: '300px',\n outline: focused() ? '2px solid #337ab7' : 'none',\n 'outline-offset': '2px',\n }}\n />\n )\n}\n\n// Stateful Form Widgets Component\nfunction FormWidgets() {\n let [selectValue, setSelectValue] = createSignal('option1')\n let [checkboxValues, setCheckboxValues] = createSignal>(new Set())\n let [radioValue, setRadioValue] = createSignal('radio1')\n let [toggleValue, setToggleValue] = createSignal(false)\n let [progressValue, setProgressValue] = createSignal(45)\n\n let checkboxLabels = ['Checkbox 1', 'Checkbox 2', 'Checkbox 3']\n let radioLabels = ['Radio 1', 'Radio 2', 'Radio 3']\n\n return (\n
\n

Settings

\n
\n \n setSelectValue(e.currentTarget.value)}\n onFocus={(e) => {\n e.currentTarget.style.borderColor = '#337ab7'\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.borderColor = '#ddd'\n e.currentTarget.style.outline = 'none'\n }}\n style={{\n padding: '6px 12px',\n border: '1px solid #ddd',\n 'border-radius': '4px',\n 'font-size': '14px',\n width: '100%',\n }}\n >\n \n \n \n \n \n
\n \n {(label, idx) => (\n \n {\n let next = new Set(checkboxValues())\n if (e.target.checked) {\n next.add(`checkbox-${idx()}`)\n } else {\n next.delete(`checkbox-${idx()}`)\n }\n setCheckboxValues(next)\n }}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #337ab7'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n />\n \n
\n )}\n \n
\n \n {(label, idx) => (\n \n )}\n \n
\n
\n \n \n setToggleValue(e.target.checked)}\n onFocus={(e) => {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n style={{ opacity: 0, width: 0, height: 0 }}\n />\n \n \n \n \n
\n
\n \n \n \n {progressValue()}%\n
\n \n \n \n )\n}\n\nfunction Dashboard(props: { onSwitchToTable: () => void }) {\n let [dashboardRows, setDashboardRows] = createSignal(buildData(300))\n\n let sortDashboardAsc = () => {\n setDashboardRows((current) => sortRows(current, true))\n }\n\n let sortDashboardDesc = () => {\n setDashboardRows((current) => sortRows(current, false))\n }\n let chartData = [65, 45, 78, 52, 89, 34, 67, 91, 43, 56, 72, 38, 55, 82, 47, 63, 71, 39, 58, 84]\n let activities = Array.from({ length: 50 }, (_, i) => ({\n id: i + 1,\n title: `Activity ${i + 1}: ${['Order placed', 'Payment received', 'Shipment created', 'Customer registered', 'Product updated'][i % 5]}`,\n time: `${i + 1} ${i === 0 ? 'minute' : 'minutes'} ago`,\n icon: ['O', 'P', 'S', 'C', 'U'][i % 5],\n }))\n\n return (\n
\n \n

Dashboard

\n {\n e.currentTarget.style.outline = '2px solid #222'\n e.currentTarget.style.outlineOffset = '2px'\n }}\n onBlur={(e) => {\n e.currentTarget.style.outline = ''\n }}\n >\n Switch to Table\n \n
\n\n
\n
\n \n \n \n \n
\n
\n\n \n \n

Sales Performance

\n \n \n {(value, index) => }\n \n \n \n\n \n

Recent Activity

\n \n {(activity) => }\n \n \n \n\n
\n \n
\n

Dashboard Items

\n \n Sort ↑\n \n \n Sort ↓\n \n
\n \n
\n \n \n \n \n \n ID\n \n \n Label\n \n \n Status\n \n \n Value\n \n \n Actions\n \n \n \n \n {(row) => }\n \n
\n \n \n\n \n \n )\n}\n\nfunction App() {\n let [rows, setRows] = createSignal([])\n let [selected, setSelected] = createSignal(null)\n let [view, setView] = createSignal<'table' | 'dashboard'>('table')\n\n let run = () => {\n setRows(get1000Rows())\n setSelected(null)\n }\n\n let runLots = () => {\n setRows(get10000Rows())\n setSelected(null)\n }\n\n let add = () => {\n setRows((current) => [...current, ...get1000Rows()])\n }\n\n let update = () => {\n setRows((current) => updatedEvery10thRow(current))\n }\n\n let clear = () => {\n setRows([])\n setSelected(null)\n }\n\n let swap = () => {\n setRows((current) => swapRows(current))\n }\n\n let removeRow = (id: number) => {\n setRows((current) => remove(current, id))\n }\n\n let sortAsc = () => {\n setRows((current) => sortRows(current, true))\n }\n\n let sortDesc = () => {\n setRows((current) => sortRows(current, false))\n }\n\n let switchToDashboard = () => {\n setView('dashboard')\n }\n\n let switchToTable = () => {\n setView('table')\n }\n\n let isSelected = createSelector(selected)\n\n return (\n <>\n {view() === 'dashboard' ? (\n \n ) : (\n
\n
\n
\n
\n

SolidJS

\n
\n
\n
\n
\n \n
\n
\n \n Create 10,000 rows\n \n
\n
\n \n
\n
\n \n Update every 10th row\n \n
\n
\n \n Clear\n \n
\n
\n \n Swap Rows\n \n
\n
\n \n Sort Ascending\n \n
\n
\n \n Sort Descending\n \n
\n
\n \n Switch to Dashboard\n \n
\n
\n
\n
\n
\n \n \n \n {(row) => {\n let rowId = row.id\n return (\n \n \n \n \n \n )\n }}\n \n \n
{rowId}\n {\n event.preventDefault()\n setSelected(rowId)\n }}\n >\n {row.label}\n \n \n {\n event.preventDefault()\n removeRow(rowId)\n }}\n >\n \n \n \n
\n \n
\n )}\n \n )\n}\n\nlet el = document.getElementById('app')!\nrender(() => , el)\n" }, { "path": "packages/component/bench/frameworks/solid/package.json", "content": "{\n \"name\": \"component-benchmark-solid\",\n \"private\": true,\n \"type\": \"module\",\n \"scripts\": {\n \"build:prod\": \"NODE_ENV=production node build.js\",\n \"build\": \"node build.js\",\n \"dev\": \"node build.js --watch\"\n },\n \"dependencies\": {\n \"esbuild\": \"^0.27.1\",\n \"solid-js\": \"^1.9.3\"\n },\n \"devDependencies\": {\n \"@types/node\": \"catalog:\",\n \"esbuild-plugin-solid\": \"^0.6.0\"\n }\n}\n" }, { "path": "packages/component/bench/frameworks/solid/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"preserve\",\n \"jsxImportSource\": \"solid-js\"\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/bench/frameworks/styles.css", "content": "body {\n margin: 0;\n padding: 10px 0 0 0;\n overflow-y: scroll;\n font-family:\n system-ui,\n -apple-system,\n BlinkMacSystemFont,\n sans-serif;\n background: #ffffff;\n}\n\n* {\n box-sizing: border-box;\n}\n\n.container {\n max-width: 960px;\n margin: 0 auto;\n padding: 0 15px 40px;\n}\n\n.row {\n display: flex;\n flex-wrap: wrap;\n margin-left: -5px;\n margin-right: -5px;\n}\n\n.col-md-6,\n.col-sm-6 {\n padding-left: 5px;\n padding-right: 5px;\n}\n\n@media (min-width: 768px) {\n .col-md-6 {\n width: 50%;\n }\n}\n\n@media (min-width: 576px) {\n .col-sm-6 {\n width: 50%;\n }\n}\n\n.jumbotron {\n padding: 10px 20px;\n margin-bottom: 20px;\n background-color: #eeeeee;\n border-radius: 6px;\n}\n\n.jumbotron .row h1 {\n margin: 0;\n font-size: 40px;\n font-weight: 500;\n}\n\n.smallpad {\n padding: 5px;\n}\n\n.btn {\n display: inline-block;\n margin-bottom: 0;\n font-weight: 400;\n text-align: center;\n white-space: nowrap;\n vertical-align: middle;\n background-image: none;\n border: 1px solid transparent;\n padding: 6px 12px;\n font-size: 14px;\n line-height: 1.42857143;\n border-radius: 4px;\n user-select: none;\n}\n\n.btn:focus-visible {\n outline: 2px solid #222;\n outline-offset: 2px;\n}\n\n.btn-primary {\n color: #fff;\n background-color: #337ab7;\n border-color: #2e6da4;\n}\n\n.btn-primary:hover {\n background-color: #286090;\n border-color: #204d74;\n}\n\n.btn-block {\n display: block;\n width: 100%;\n}\n\ntable {\n width: 100%;\n border-collapse: collapse;\n margin-bottom: 20px;\n /* contain: strict; */\n}\n\ntr {\n /* contain-intrinsic-size: auto 36px;\n content-visibility: auto; */\n}\n\n.table > tbody > tr > td {\n padding: 8px;\n border-top: 1px solid #dddddd;\n white-space: nowrap;\n}\n\n.table-hover > tbody > tr:hover {\n background-color: #f5f5f5;\n}\n\n.table-striped > tbody > tr:nth-child(odd) {\n background-color: #f9f9f9;\n}\n\n.table > tbody > tr.danger > td {\n background-color: #f2dede;\n}\n\n.test-data a {\n display: block;\n color: #337ab7;\n text-decoration: none;\n cursor: pointer;\n}\n\n.test-data a:hover {\n text-decoration: underline;\n}\n\n.glyphicon {\n position: relative;\n display: inline-block;\n}\n\n.glyphicon-remove::before {\n content: '×';\n font-size: 16px;\n line-height: 1;\n}\n\n.preloadicon {\n position: absolute;\n top: -20px;\n left: -20px;\n}\n" }, { "path": "packages/component/bench/package.json", "content": "{\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@remix-run/fetch-router\": \"workspace:*\",\n \"@remix-run/node-fetch-server\": \"workspace:*\",\n \"@remix-run/static-middleware\": \"workspace:*\"\n },\n \"devDependencies\": {\n \"@types/node\": \"catalog:\",\n \"playwright\": \"^1.49.1\",\n \"tsx\": \"catalog:\"\n },\n \"scripts\": {\n \"start\": \"tsx server.ts\",\n \"dev\": \"tsx watch server.ts\",\n \"build-frameworks\": \"pnpm --filter \\\"component-benchmark-*\\\" run build\",\n \"bench\": \"tsx runner.ts\"\n }\n}\n" }, { "path": "packages/component/bench/runner.ts", "content": "import { spawn, type ChildProcess } from 'node:child_process'\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\nimport { parseArgs } from 'node:util'\n\nimport { chromium, type Browser, type Page } from 'playwright'\n\nconst PORT = 44100\nconst BASE_URL = `http://localhost:${PORT}`\nconst REMIX_RESULTS_FILE = path.join(import.meta.dirname, '.remix-prev-results.json')\nconst LAST_ARGS_FILE = path.join(import.meta.dirname, '.last-args.json')\n\ninterface SavedArgs {\n cpu: string\n runs: string\n warmups: string\n headless: boolean\n table: boolean\n profile: boolean\n allocProfile: boolean\n framework: string[]\n benchmark: string[]\n}\n\nfunction saveArgs(args: SavedArgs): void {\n fs.writeFileSync(LAST_ARGS_FILE, JSON.stringify(args, null, 2))\n}\n\nfunction loadLastArgs(): SavedArgs | null {\n try {\n if (fs.existsSync(LAST_ARGS_FILE)) {\n return JSON.parse(fs.readFileSync(LAST_ARGS_FILE, 'utf-8'))\n }\n } catch {\n // Ignore errors\n }\n return null\n}\n\n// Check for 'repeat' command\nlet isRepeat = process.argv[2] === 'repeat'\n\n// Parse command line arguments\nlet { values: args } = parseArgs({\n options: {\n cpu: { type: 'string', default: '4' },\n runs: { type: 'string', default: '5' },\n warmups: { type: 'string', default: '2' },\n headless: { type: 'boolean', default: false },\n table: { type: 'boolean', default: false },\n profile: { type: 'boolean', default: false },\n 'alloc-profile': { type: 'boolean', default: false },\n framework: {\n type: 'string',\n multiple: true,\n short: 'f',\n // default: ['remix', 'preact'],\n },\n benchmark: { type: 'string', multiple: true, short: 'b' },\n },\n allowPositionals: true,\n})\n\n// If repeating, load saved args\nif (isRepeat) {\n let savedArgs = loadLastArgs()\n if (savedArgs) {\n args = { ...args, ...savedArgs }\n if ('allocProfile' in savedArgs) {\n args['alloc-profile'] = savedArgs.allocProfile\n }\n console.log('Repeating with saved options:', savedArgs)\n } else {\n console.error('No previous run found. Run a benchmark first.')\n process.exit(1)\n }\n} else {\n // Save current args for repeat\n saveArgs({\n cpu: args.cpu!,\n runs: args.runs!,\n warmups: args.warmups!,\n headless: args.headless!,\n table: args.table!,\n profile: args.profile!,\n allocProfile: args['alloc-profile']!,\n framework: args.framework || [],\n benchmark: args.benchmark || [],\n })\n}\n\nlet cpuThrottling = parseInt(args.cpu!, 10)\nlet benchmarkRuns = parseInt(args.runs!, 10)\nlet warmupRuns = parseInt(args.warmups!, 10)\nlet headless = args.headless!\nlet useTable = args.table!\nlet showProfile = args.profile!\nlet showAllocProfile = args['alloc-profile']!\nlet frameworkFilter = args.framework || []\nlet benchmarkFilter = args.benchmark || []\n\ninterface FunctionProfile {\n name: string\n time: number\n percentage: number\n}\n\ninterface AllocationProfile {\n name: string\n bytes: number\n percentage: number\n}\n\ninterface TimingResult {\n scripting: number\n total: number\n profile?: FunctionProfile[]\n allocProfile?: AllocationProfile[]\n}\n\ninterface BenchmarkResult {\n framework: string\n operation: string\n scripting: { times: number[]; mean: number; median: number; min: number; max: number }\n total: { times: number[]; mean: number; median: number; min: number; max: number }\n}\n\ninterface Operation {\n name: string\n setup?: (page: Page) => Promise\n action: (page: Page) => Promise\n teardown?: (page: Page) => Promise\n}\n\nconst EVENT_TIMING_TIMEOUT_MS = 5000\n\n// Click an element and measure time until next paint using Event Timing API\n// Also captures Chrome DevTools Profiler data for detailed function-level analysis\nasync function clickAndMeasure(\n page: Page,\n selector: string,\n operationName?: string,\n): Promise {\n // Set up the observer before clicking (using string to avoid tsx transformation issues)\n await page.evaluate(`\n window.__benchResult = null;\n window.__benchObserver = new PerformanceObserver(function(list) {\n var entries = list.getEntries();\n for (var i = 0; i < entries.length; i++) {\n var entry = entries[i];\n if (entry.entryType === 'event' && entry.name === 'click') {\n window.__benchResult = {\n scripting: entry.processingEnd - entry.processingStart,\n total: entry.duration\n };\n window.__benchObserver.disconnect();\n return;\n }\n }\n });\n window.__benchObserver.observe({ type: 'event', buffered: false, durationThreshold: 0 });\n `)\n\n // Start Chrome DevTools Profiler\n let cdp = await page.context().newCDPSession(page)\n if (showProfile) {\n await cdp.send('Profiler.enable')\n await cdp.send('Profiler.start')\n }\n if (showAllocProfile) {\n await cdp.send('HeapProfiler.enable')\n await cdp.send('HeapProfiler.startSampling', {\n samplingInterval: 32768,\n includeObjectsCollectedByMajorGC: true,\n includeObjectsCollectedByMinorGC: true,\n })\n }\n\n // Use Playwright's click which fires real pointer events\n await page.click(selector)\n\n let timing: TimingResult\n let cpuProfileResult: any\n let allocProfileResult: any\n try {\n let operationLabel = operationName ?? 'unknown'\n timing = (await page.evaluate(`\n new Promise(function(resolve, reject) {\n var timeoutMs = ${EVENT_TIMING_TIMEOUT_MS}\n var selector = ${JSON.stringify(selector)}\n var operationName = ${JSON.stringify(operationLabel)}\n var timeoutId = setTimeout(function() {\n if (window.__benchObserver) {\n window.__benchObserver.disconnect()\n }\n reject(new Error(\n 'Timed out waiting for Event Timing click entry after ' +\n timeoutMs +\n 'ms (selector=\"' +\n selector +\n '\", operation=\"' +\n operationName +\n '\")'\n ))\n }, timeoutMs)\n\n function check() {\n if (window.__benchResult !== null) {\n clearTimeout(timeoutId)\n resolve(window.__benchResult)\n return\n }\n requestAnimationFrame(check)\n }\n\n requestAnimationFrame(check)\n })\n `)) as TimingResult\n } finally {\n if (showProfile) {\n cpuProfileResult = await cdp.send('Profiler.stop').catch(() => null)\n await cdp.send('Profiler.disable').catch(() => undefined)\n }\n if (showAllocProfile) {\n allocProfileResult = await cdp.send('HeapProfiler.stopSampling').catch(() => null)\n await cdp.send('HeapProfiler.disable').catch(() => undefined)\n }\n }\n\n // Process profiling data\n let profileData: FunctionProfile[] | undefined\n if (showProfile && cpuProfileResult && cpuProfileResult.profile) {\n let profile = cpuProfileResult.profile as any\n let nodes = profile.nodes || []\n let samples = profile.samples || []\n let timeDeltas = profile.timeDeltas || []\n\n // Calculate self time for each function\n let functionTimes = new Map()\n let functionNames = new Map()\n\n // Build function name map\n for (let node of nodes) {\n let name = node.callFrame?.functionName || node.callFrame?.url || 'unknown'\n if (name.includes('node_modules')) continue // Skip node_modules\n functionNames.set(node.id, name)\n }\n\n // Calculate time spent in each function (self time = time when this function is on top of stack)\n let totalTime = 0\n for (let i = 0; i < samples.length; i++) {\n let sampleId = samples[i]\n let delta = timeDeltas[i] || 0\n totalTime += delta\n\n // Self time is when this function is the top of the stack\n let current = functionTimes.get(sampleId) || 0\n functionTimes.set(sampleId, current + delta)\n }\n\n // Sort by self time and get top 30\n profileData = Array.from(functionTimes.entries())\n .map(([id, time]) => ({\n name: functionNames.get(id) || 'unknown',\n time: time / 1000, // Convert to ms\n percentage: totalTime > 0 ? (time / totalTime) * 100 : 0,\n }))\n .filter((item) => !item.name.includes('node_modules'))\n .sort((a, b) => b.time - a.time)\n .slice(0, 30)\n }\n\n let allocProfileData: AllocationProfile[] | undefined\n if (showAllocProfile && allocProfileResult && allocProfileResult.profile) {\n allocProfileData = buildAllocationProfile(allocProfileResult.profile as any)\n }\n\n return { ...timing, profile: profileData, allocProfile: allocProfileData }\n}\n\n// Wait for the main thread to be idle (no pending tasks)\nasync function waitForIdle(page: Page): Promise {\n await page.evaluate(`\n new Promise(function(resolve) {\n // First wait for paint to complete\n requestAnimationFrame(function() {\n requestAnimationFrame(function() {\n // Then wait for the main thread to be idle\n requestIdleCallback(function() {\n // Double-check with another idle callback to ensure cleanup is done\n requestIdleCallback(resolve, { timeout: 100 });\n }, { timeout: 100 });\n });\n });\n })\n `)\n}\n\n// Click without measuring (for setup/teardown)\nasync function click(page: Page, selector: string): Promise {\n await page.click(selector)\n // Wait for paint and idle to complete before continuing\n await waitForIdle(page)\n}\n\n// Clear all rows\nasync function clear(page: Page): Promise {\n await click(page, '#clear')\n}\n\n// Create 1000 rows\nasync function create1k(page: Page): Promise {\n await click(page, '#run')\n}\n\n// Define all benchmark operations\nconst operations: Operation[] = [\n {\n name: 'create1k',\n setup: clear,\n action: (page) => clickAndMeasure(page, '#run', 'create1k'),\n },\n // {\n // name: 'create10k',\n // setup: clear,\n // action: (page) => clickAndMeasure(page, '#runlots', 'create10k'),\n // },\n {\n name: 'append1k',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#add', 'append1k'),\n teardown: clear,\n },\n {\n name: 'update',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#update', 'update'),\n teardown: clear,\n },\n {\n name: 'clear',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#clear', 'clear'),\n },\n {\n name: 'swapRows',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#swaprows', 'swapRows'),\n teardown: clear,\n },\n {\n name: 'selectRow',\n setup: create1k,\n action: (page) => clickAndMeasure(page, 'tbody tr:first-child td.col-md-4 a', 'selectRow'),\n teardown: clear,\n },\n {\n name: 'removeRow',\n setup: create1k,\n action: (page) => clickAndMeasure(page, 'tbody tr:first-child td.col-md-1 a', 'removeRow'),\n teardown: clear,\n },\n {\n name: 'replace1k',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#run', 'replace1k'),\n teardown: clear,\n },\n {\n name: 'sortAsc',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#sortasc', 'sortAsc'),\n teardown: clear,\n },\n {\n name: 'sortDesc',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#sortdesc', 'sortDesc'),\n teardown: clear,\n },\n {\n name: 'switchToDashboard',\n setup: create1k,\n action: (page) => clickAndMeasure(page, '#switchToDashboard', 'switchToDashboard'),\n teardown: async (page) => {\n await click(page, '#switchToTable')\n await clear(page)\n },\n },\n {\n name: 'renderDashboard',\n setup: clear,\n action: (page) => clickAndMeasure(page, '#switchToDashboard', 'renderDashboard'),\n teardown: async (page) => {\n await click(page, '#switchToTable')\n await clear(page)\n },\n },\n {\n name: 'teardownDashboard',\n setup: async (page) => {\n await clear(page)\n await click(page, '#switchToDashboard')\n },\n action: (page) => clickAndMeasure(page, '#switchToTable', 'teardownDashboard'),\n teardown: clear,\n },\n {\n name: 'sortDashboardAsc',\n setup: async (page) => {\n await clear(page)\n await click(page, '#switchToDashboard')\n },\n action: (page) => clickAndMeasure(page, '#sortDashboardAsc', 'sortDashboardAsc'),\n teardown: async (page) => {\n await click(page, '#switchToTable')\n await clear(page)\n },\n },\n {\n name: 'sortDashboardDesc',\n setup: async (page) => {\n await clear(page)\n await click(page, '#switchToDashboard')\n },\n action: (page) => clickAndMeasure(page, '#sortDashboardDesc', 'sortDashboardDesc'),\n teardown: async (page) => {\n await click(page, '#switchToTable')\n await clear(page)\n },\n },\n]\n\n// Start the benchmark server\nfunction startServer(): Promise {\n return new Promise((resolve, reject) => {\n let server = spawn('tsx', ['server.ts'], {\n cwd: import.meta.dirname,\n stdio: ['ignore', 'pipe', 'pipe'],\n })\n\n let started = false\n\n server.stdout?.on('data', (data: Buffer) => {\n let output = data.toString()\n if (output.includes('Benchmark server running') && !started) {\n started = true\n resolve(server)\n }\n })\n\n server.stderr?.on('data', (data: Buffer) => {\n if (!started) {\n reject(new Error(`Server error: ${data.toString()}`))\n }\n })\n\n server.on('error', reject)\n\n // Timeout if server doesn't start\n setTimeout(() => {\n if (!started) {\n server.kill()\n reject(new Error('Server failed to start within timeout'))\n }\n }, 10000)\n })\n}\n\n// Stop the server\nfunction stopServer(server: ChildProcess): Promise {\n return new Promise((resolve) => {\n server.on('close', () => resolve())\n server.kill('SIGTERM')\n })\n}\n\n// Get list of frameworks\nfunction getFrameworks(): string[] {\n let frameworksDir = path.join(import.meta.dirname, 'frameworks')\n let entries = fs.readdirSync(frameworksDir, { withFileTypes: true })\n return entries\n .filter((entry) => entry.isDirectory())\n .map((entry) => entry.name)\n .sort()\n}\n\n// Save remix results to file for comparison with next run\nfunction saveRemixResults(results: BenchmarkResult[]): void {\n let remixResults = results.filter((r) => r.framework === 'remix')\n if (remixResults.length > 0) {\n fs.writeFileSync(REMIX_RESULTS_FILE, JSON.stringify(remixResults, null, 2))\n }\n}\n\n// Load previous remix results if they exist\nfunction loadPreviousRemixResults(): BenchmarkResult[] {\n try {\n if (fs.existsSync(REMIX_RESULTS_FILE)) {\n let data = fs.readFileSync(REMIX_RESULTS_FILE, 'utf-8')\n let results: BenchmarkResult[] = JSON.parse(data)\n // Rename framework to \"remix (prev)\"\n return results.map((r) => ({ ...r, framework: 'remix (prev)' }))\n }\n } catch {\n // Ignore errors loading previous results\n }\n return []\n}\n\n// Run a single operation and measure time\nasync function measureOperation(page: Page, operation: Operation): Promise {\n // Run setup if defined\n if (operation.setup) {\n await operation.setup(page)\n }\n\n // Wait for idle before measuring to ensure no pending work from setup\n await waitForIdle(page)\n\n // Measure the action (returns timing from Event Timing API)\n let timing = await operation.action(page)\n\n // Run teardown if defined\n if (operation.teardown) {\n await operation.teardown(page)\n }\n\n // Wait for idle after teardown to ensure cleanup is complete before next operation\n await waitForIdle(page)\n\n return timing\n}\n\n// Calculate statistics for an array of numbers\nfunction calcStats(times: number[]) {\n let sorted = [...times].sort((a, b) => a - b)\n return {\n times,\n mean: times.reduce((a, b) => a + b, 0) / times.length,\n median: sorted[Math.floor(sorted.length / 2)],\n min: sorted[0],\n max: sorted[sorted.length - 1],\n }\n}\n\n// Aggregate profiling data and calculate medians\nfunction aggregateProfiles(\n profiles: FunctionProfile[][],\n operationName: string,\n): FunctionProfile[] | null {\n if (profiles.length === 0) return null\n\n // Collect all function names across all runs\n let functionMap = new Map()\n for (let profile of profiles) {\n for (let func of profile) {\n if (!functionMap.has(func.name)) {\n functionMap.set(func.name, [])\n }\n functionMap.get(func.name)!.push(func.time)\n }\n }\n\n // Calculate median time for each function\n // Also calculate average percentage across runs\n let aggregated: FunctionProfile[] = []\n for (let [name, times] of functionMap.entries()) {\n let sorted = [...times].sort((a, b) => a - b)\n let median = sorted[Math.floor(sorted.length / 2)]\n\n // Calculate average percentage across all runs\n let percentages: number[] = []\n for (let profile of profiles) {\n let func = profile.find((f) => f.name === name)\n if (func) {\n percentages.push(func.percentage)\n }\n }\n let avgPercentage =\n percentages.length > 0 ? percentages.reduce((a, b) => a + b, 0) / percentages.length : 0\n\n aggregated.push({\n name,\n time: median,\n percentage: avgPercentage,\n })\n }\n\n // Sort by median time and return top 30\n return aggregated.sort((a, b) => b.time - a.time).slice(0, 30)\n}\n\nfunction aggregateAllocationProfiles(profiles: AllocationProfile[][]): AllocationProfile[] | null {\n if (profiles.length === 0) return null\n\n let functionMap = new Map()\n for (let profile of profiles) {\n for (let func of profile) {\n if (!functionMap.has(func.name)) {\n functionMap.set(func.name, [])\n }\n functionMap.get(func.name)!.push(func.bytes)\n }\n }\n\n let aggregated: AllocationProfile[] = []\n for (let [name, bytes] of functionMap.entries()) {\n let sorted = [...bytes].sort((a, b) => a - b)\n let median = sorted[Math.floor(sorted.length / 2)]\n\n let percentages: number[] = []\n for (let profile of profiles) {\n let func = profile.find((f) => f.name === name)\n if (func) {\n percentages.push(func.percentage)\n }\n }\n let avgPercentage =\n percentages.length > 0 ? percentages.reduce((a, b) => a + b, 0) / percentages.length : 0\n\n aggregated.push({\n name,\n bytes: median,\n percentage: avgPercentage,\n })\n }\n\n return aggregated.sort((a, b) => b.bytes - a.bytes).slice(0, 30)\n}\n\n// Print profiling table\nfunction printProfileTable(profile: FunctionProfile[], operationName: string): void {\n if (profile.length === 0) return\n\n console.log(`\\n${operationName}`)\n console.log('📊 Top functions by self time (median):')\n console.log('═'.repeat(90))\n console.log(`${'Function'.padEnd(70)} ${'Time (ms)'.padStart(10)} ${'%'.padStart(8)}`)\n console.log('─'.repeat(90))\n for (let item of profile) {\n let name = item.name.length > 68 ? '...' + item.name.slice(-65) : item.name\n console.log(\n `${name.padEnd(70)} ${item.time.toFixed(2).padStart(10)} ${item.percentage.toFixed(1).padStart(7)}%`,\n )\n }\n console.log('═'.repeat(90))\n}\n\nfunction printAllocationProfileTable(profile: AllocationProfile[], operationName: string): void {\n if (profile.length === 0) return\n\n console.log(`\\n${operationName}`)\n console.log('🧠 Top functions by allocated heap (median):')\n console.log('═'.repeat(100))\n console.log(\n `${'Function'.padEnd(68)} ${'Bytes'.padStart(14)} ${'KB'.padStart(10)} ${'%'.padStart(8)}`,\n )\n console.log('─'.repeat(100))\n for (let item of profile) {\n let name = item.name.length > 66 ? '...' + item.name.slice(-63) : item.name\n let kb = item.bytes / 1024\n console.log(\n `${name.padEnd(68)} ${item.bytes.toFixed(0).padStart(14)} ${kb.toFixed(2).padStart(10)} ${item.percentage.toFixed(1).padStart(7)}%`,\n )\n }\n console.log('═'.repeat(100))\n}\n\n// Run benchmark for a single framework\nasync function benchmarkFramework(\n page: Page,\n framework: string,\n): Promise<{\n results: BenchmarkResult[]\n profiles: Map\n allocProfiles: Map\n}> {\n let results: BenchmarkResult[] = []\n let profiles = new Map()\n let allocProfiles = new Map()\n\n let url = `${BASE_URL}/${framework}/index.html`\n\n // Filter operations if benchmark filter is specified\n let filteredOperations =\n benchmarkFilter.length > 0\n ? operations.filter((op) => benchmarkFilter.some((filter) => op.name.includes(filter)))\n : operations\n\n for (let operation of filteredOperations) {\n let scriptingTimes: number[] = []\n let totalTimes: number[] = []\n let runProfiles: FunctionProfile[][] = []\n let runAllocProfiles: AllocationProfile[][] = []\n\n // Reload page before each operation to reset all JS state (idCounter, etc.)\n await page.goto(url)\n await page.waitForSelector('#run')\n\n // Warmup runs (not recorded)\n for (let i = 0; i < warmupRuns; i++) {\n await measureOperation(page, operation)\n }\n\n // Benchmark runs\n for (let i = 0; i < benchmarkRuns; i++) {\n let timing = await measureOperation(page, operation)\n scriptingTimes.push(timing.scripting)\n totalTimes.push(timing.total)\n if (showProfile && timing.profile) {\n runProfiles.push(timing.profile)\n }\n if (showAllocProfile && timing.allocProfile) {\n runAllocProfiles.push(timing.allocProfile)\n }\n }\n\n results.push({\n framework,\n operation: operation.name,\n scripting: calcStats(scriptingTimes),\n total: calcStats(totalTimes),\n })\n\n if (showProfile && runProfiles.length > 0) {\n profiles.set(operation.name, runProfiles)\n }\n if (showAllocProfile && runAllocProfiles.length > 0) {\n allocProfiles.set(operation.name, runAllocProfiles)\n }\n\n process.stdout.write('.')\n }\n\n return { results, profiles, allocProfiles }\n}\n\n// ANSI color codes\nconst RESET = '\\x1b[0m'\nconst RED = '\\x1b[31m'\nconst GREEN = '\\x1b[32m'\nconst YELLOW = '\\x1b[33m'\nconst WHITE = '\\x1b[97m'\nconst BG_GRAY = '\\x1b[48;5;240m'\nconst BOLD = '\\x1b[1m'\nconst DIM = '\\x1b[2m'\n\n// Print combined bar graph with scripting (yellow) and total bars\nfunction printBarGraph(allResults: BenchmarkResult[]): void {\n let operationNames = [...new Set(allResults.map((r) => r.operation))]\n let frameworks = [...new Set(allResults.map((r) => r.framework))]\n let hasRemix = frameworks.includes('remix')\n\n // Put remix first if it exists\n if (hasRemix) {\n frameworks = ['remix', ...frameworks.filter((f) => f !== 'remix')]\n }\n\n // Get terminal width (default to 100, max 120)\n let termWidth = Math.min(process.stdout.columns || 100, 120)\n\n // Find max framework name length for label padding\n let maxNameLen = Math.max(...frameworks.map((f) => f.length))\n let labelWidth = maxNameLen + 4 // \" name: \"\n\n // Reserve space for label + bar + \" scripting_value \" + \" total_value (ratio)\"\n let suffixWidth = 25\n let barMaxWidth = termWidth - labelWidth - suffixWidth\n\n // Calculate global max value across all operations (use total since it's always >= scripting)\n let globalMax = Math.max(...allResults.map((r) => r.total.median))\n\n for (let opName of operationNames) {\n console.log(`${DIM}${opName}${RESET}`)\n\n let remixResult = hasRemix\n ? allResults.find((r) => r.framework === 'remix' && r.operation === opName)\n : null\n let remixTotal = remixResult ? remixResult.total.median : null\n\n for (let fw of frameworks) {\n let result = allResults.find((r) => r.framework === fw && r.operation === opName)\n let scriptingValue = result ? result.scripting.median : 0\n let totalValue = result ? result.total.median : 0\n let scriptingRounded = Math.round(scriptingValue * 10) / 10\n let totalRounded = Math.round(totalValue * 10) / 10\n\n // Calculate bar lengths (scaled to global max)\n let scriptingBarLen = Math.round((scriptingValue / globalMax) * barMaxWidth)\n let totalBarLen = Math.round((totalValue / globalMax) * barMaxWidth)\n let remainingBarLen = totalBarLen - scriptingBarLen\n\n // Build the scripting bar (yellow)\n let scriptingBar = '█'.repeat(scriptingBarLen)\n // Build the remaining bar (default color, total - scripting)\n let remainingBar = '█'.repeat(Math.max(0, remainingBarLen))\n\n // Scripting value with gray background and white text (fixed width for alignment)\n let scriptingText = ` ${String(scriptingRounded).padStart(5)} `\n\n // Build total suffix with ratio\n let totalSuffix = String(totalRounded)\n if (fw !== 'remix' && remixTotal !== null && remixTotal > 0) {\n let ratio = Math.round((totalValue / remixTotal) * 10) / 10\n let color = ratio < 1 ? RED : ratio > 1 ? GREEN : ''\n totalSuffix += ` ${color}(${ratio}x)${color ? RESET : ''}`\n }\n\n // Print single combined line: label + yellow bars + scripting value (gray bg) + remaining bars + total\n let label = (' ' + fw + ':').padEnd(labelWidth)\n console.log(\n `${label}${YELLOW}${scriptingBar}${RESET}${BG_GRAY}${WHITE}${scriptingText}${RESET}${remainingBar} ${totalSuffix}`,\n )\n }\n console.log('')\n }\n}\n\n// Print results as two tables (scripting and total)\nfunction printTable(allResults: BenchmarkResult[]): void {\n let operationNames = [...new Set(allResults.map((r) => r.operation))]\n let frameworks = [...new Set(allResults.map((r) => r.framework))]\n\n // Put remix first if it exists\n if (frameworks.includes('remix')) {\n frameworks = ['remix', ...frameworks.filter((f) => f !== 'remix')]\n }\n\n // Build scripting table with flags for slow operations\n let scriptingData: Record> = {}\n for (let opName of operationNames) {\n let remixResult = allResults.find((r) => r.framework === 'remix' && r.operation === opName)\n let remixValue = remixResult ? remixResult.scripting.median : 0\n let otherValues = frameworks\n .filter((fw) => fw !== 'remix')\n .map((fw) => {\n let result = allResults.find((r) => r.framework === fw && r.operation === opName)\n return result ? result.scripting.median : 0\n })\n .filter((v) => v > 0)\n\n // Check if remix is significantly slower (2x longer than fastest other)\n let isSlow = false\n if (remixValue && otherValues.length > 0) {\n let fastestOther = Math.min(...otherValues)\n isSlow = remixValue > fastestOther * 2.0\n }\n\n let displayName = isSlow ? `${opName} 🚩` : opName\n scriptingData[displayName] = {}\n for (let fw of frameworks) {\n let result = allResults.find((r) => r.framework === fw && r.operation === opName)\n scriptingData[displayName][fw] = result ? Math.round(result.scripting.median * 10) / 10 : 0\n }\n }\n\n // Build total table with flags for slow operations\n let totalData: Record> = {}\n for (let opName of operationNames) {\n let remixResult = allResults.find((r) => r.framework === 'remix' && r.operation === opName)\n let remixValue = remixResult ? remixResult.total.median : 0\n let otherValues = frameworks\n .filter((fw) => fw !== 'remix')\n .map((fw) => {\n let result = allResults.find((r) => r.framework === fw && r.operation === opName)\n return result ? result.total.median : 0\n })\n .filter((v) => v > 0)\n\n // Check if remix is significantly slower (>20% slower than fastest other)\n let isSlow = false\n if (remixValue && otherValues.length > 0) {\n let fastestOther = Math.min(...otherValues)\n isSlow = remixValue > fastestOther * 1.2\n }\n\n let displayName = isSlow ? `${opName} 🚩` : opName\n totalData[displayName] = {}\n for (let fw of frameworks) {\n let result = allResults.find((r) => r.framework === fw && r.operation === opName)\n totalData[displayName][fw] = result ? Math.round(result.total.median * 10) / 10 : 0\n }\n }\n\n console.log('Scripting Time (ms):')\n console.table(scriptingData)\n console.log('')\n console.log('Total Time (ms):')\n console.table(totalData)\n}\n\n// Print results as bar graphs or tables\nfunction printResults(allResults: BenchmarkResult[]): void {\n if (useTable) {\n printTable(allResults)\n } else {\n printBarGraph(allResults)\n }\n}\n\n// Main benchmark runner\nasync function main(): Promise {\n let server: ChildProcess | null = null\n let browser: Browser | null = null\n\n try {\n console.log('Starting benchmark server...')\n server = await startServer()\n\n console.log('Launching browser...')\n browser = await chromium.launch({ headless })\n let page = await browser.newPage()\n\n // Enable CPU throttling via CDP\n let client = await page.context().newCDPSession(page)\n await client.send('Emulation.setCPUThrottlingRate', { rate: cpuThrottling })\n\n let allFrameworks = getFrameworks()\n let frameworks = allFrameworks\n\n // Filter frameworks if specified\n if (frameworkFilter.length > 0) {\n let invalidFrameworks = frameworkFilter.filter((f) => !allFrameworks.includes(f))\n if (invalidFrameworks.length > 0) {\n console.error(`Error: Invalid framework(s): ${invalidFrameworks.join(', ')}`)\n console.error(`Available frameworks: ${allFrameworks.join(', ')}`)\n process.exit(1)\n }\n frameworks = frameworkFilter\n }\n\n let allResults: BenchmarkResult[] = []\n let allProfiles = new Map()\n let allAllocProfiles = new Map()\n\n // Load previous remix results if remix is being benchmarked\n let hasRemix = frameworks.includes('remix')\n let previousRemixResults: BenchmarkResult[] = []\n if (hasRemix) {\n previousRemixResults = loadPreviousRemixResults()\n if (previousRemixResults.length > 0) {\n console.log('Loaded previous remix results for comparison')\n }\n }\n\n console.log(`Benchmarking ${frameworks.length} frameworks: ${frameworks.join(', ')}`)\n console.log(`${warmupRuns} warmup runs, ${benchmarkRuns} benchmark runs per operation`)\n console.log(`CPU throttling: ${cpuThrottling}x`)\n console.log('')\n\n for (let framework of frameworks) {\n process.stdout.write(` ${framework}: `)\n let { results, profiles, allocProfiles } = await benchmarkFramework(page, framework)\n allResults.push(...results)\n // Store profiles keyed by framework-operation name\n for (let [operationName, runProfiles] of profiles.entries()) {\n let key = `${framework}-${operationName}`\n allProfiles.set(key, runProfiles)\n }\n for (let [operationName, runAllocProfiles] of allocProfiles.entries()) {\n let key = `${framework}-${operationName}`\n allAllocProfiles.set(key, runAllocProfiles)\n }\n console.log(' done')\n }\n\n // Save current remix results for next run\n if (hasRemix) {\n saveRemixResults(allResults)\n }\n\n // Add previous remix results to display only when remix is the only framework\n // (When comparing against other frameworks, we don't need to show previous remix)\n if (previousRemixResults.length > 0 && frameworks.length === 1) {\n allResults.push(...previousRemixResults)\n }\n\n // Print aggregated profiling tables first\n if (showProfile && allProfiles.size > 0) {\n for (let [key, runProfiles] of allProfiles.entries()) {\n let aggregated = aggregateProfiles(runProfiles, key)\n if (aggregated) {\n printProfileTable(aggregated, key)\n }\n }\n }\n if (showAllocProfile && allAllocProfiles.size > 0) {\n for (let [key, runAllocProfiles] of allAllocProfiles.entries()) {\n let aggregated = aggregateAllocationProfiles(runAllocProfiles)\n if (aggregated) {\n printAllocationProfileTable(aggregated, key)\n }\n }\n }\n\n // Print benchmark results after profiles\n printResults(allResults)\n\n console.log('Benchmark complete!')\n } finally {\n console.log('Cleaning up...')\n if (browser) {\n await browser.close()\n }\n if (server) {\n await stopServer(server)\n }\n }\n}\n\nmain().catch((error) => {\n console.error('Benchmark failed:', error)\n process.exit(1)\n})\n\nfunction buildAllocationProfile(rawProfile: any): AllocationProfile[] {\n let bytesByName = new Map()\n let totalBytes = 0\n\n function walk(node: any) {\n if (!node || typeof node !== 'object') return\n\n let selfSize = Number(node.selfSize || 0)\n let name =\n node.callFrame?.functionName || node.callFrame?.url || node.callFrame?.scriptId || 'unknown'\n if (!name.includes('node_modules')) {\n let current = bytesByName.get(name) || 0\n bytesByName.set(name, current + selfSize)\n totalBytes += selfSize\n }\n\n let children = Array.isArray(node.children) ? node.children : []\n for (let child of children) {\n walk(child)\n }\n }\n\n walk(rawProfile.head)\n\n return Array.from(bytesByName.entries())\n .map(([name, bytes]) => ({\n name,\n bytes,\n percentage: totalBytes > 0 ? (bytes / totalBytes) * 100 : 0,\n }))\n .sort((a, b) => b.bytes - a.bytes)\n .slice(0, 30)\n}\n" }, { "path": "packages/component/bench/server.ts", "content": "import * as fs from 'node:fs'\nimport * as http from 'node:http'\nimport * as path from 'node:path'\n\nimport { createRouter } from '@remix-run/fetch-router'\nimport { route } from '@remix-run/fetch-router/routes'\nimport { createRequestListener } from '@remix-run/node-fetch-server'\nimport { staticFiles } from '@remix-run/static-middleware'\n\nlet frameworksDir = path.resolve(import.meta.dirname, 'frameworks')\n\nlet routes = route({\n index: '/',\n})\n\nlet router = createRouter({\n middleware: [staticFiles('./frameworks')],\n})\n\nlet html = String.raw\n\nrouter.get(routes.index, () => {\n let entries = fs.readdirSync(frameworksDir, { withFileTypes: true })\n let frameworks = entries\n .filter((entry) => entry.isDirectory())\n .map((entry) => entry.name)\n .sort()\n\n let links = frameworks\n .map((name) => `
  • ${name}
    • `)\n .join('')\n\n return new Response(\n html`\n \n \n Benchmarks\n \n \n \n

    Benchmarks

    \n
      \n ${links}\n
    \n \n `,\n { headers: { 'Content-Type': 'text/html' } },\n )\n})\n\nlet server = http.createServer(\n createRequestListener(async (request) => {\n return await router.fetch(request)\n }),\n)\n\nserver.listen(44100, () => {\n console.log('Benchmark server running at http://localhost:44100')\n})\n\nfunction shutdown() {\n server.close(() => {\n process.exit(0)\n })\n}\n\nprocess.on('SIGINT', shutdown)\nprocess.on('SIGTERM', shutdown)\n" }, { "path": "packages/component/bench/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"types\": [\"node\"]\n },\n \"exclude\": [\"frameworks\", \"dist\"]\n}\n" }, { "path": "packages/component/demos/.gitignore", "content": "*.bundled.*" }, { "path": "packages/component/demos/animation/aspect-ratio.tsx", "content": "import { type Handle } from 'remix/component'\nimport { css, on, spring } from 'remix/component'\n\nexport function AspectRatio(handle: Handle) {\n let aspectRatio = 1\n let width = 100\n\n return () => (\n \n \n \n \n
    \n \n Ratio\n {\n let value = event.currentTarget.value\n\n setTimeout(() => {\n if (signal.aborted) return\n aspectRatio = parseFloat(value)\n handle.update()\n }, 200)\n }),\n ]}\n />\n \n {aspectRatio.toFixed(1)}\n \n \n \n Width\n {\n let value = event.currentTarget.value\n\n setTimeout(() => {\n if (signal.aborted) return\n width = parseFloat(value)\n handle.update()\n }, 200)\n }),\n ]}\n />\n \n {width}\n \n \n
    \n \n )\n}\n\nlet rangeInputCss = {\n flex: 1,\n accentColor: '#8df0cc',\n cursor: 'pointer',\n} as const\n" }, { "path": "packages/component/demos/animation/bouncy-switch.tsx", "content": "import { type Handle } from 'remix/component'\nimport { css, on, spring } from 'remix/component'\n\nlet bounceEasing = `linear(0, 0.258 12%, 0.424 18.3%, 0.633 24.4%, 0.999 33.3%, 0.783 39.8%, 0.733 42.5%, 0.716 45.1%, 0.731 47.6%, 0.777 50.2%, 0.999 57.7%, 0.906 61.7%, 0.883 63.5%, 0.876 65.2%, 0.901 68.7%, 0.999 74.5%, 0.964 77.4%, 0.953 80.1%, 0.961 82.6%, 1 88.2%, 0.99 91.9%, 1)`\n\nexport function BouncySwitch(handle: Handle) {\n let isOn = true\n\n return () => (\n {\n isOn = !isOn\n handle.update()\n }),\n ]}\n >\n \n \n )\n}\n" }, { "path": "packages/component/demos/animation/color-interpolation.tsx", "content": "import { css } from 'remix/component'\n\n/*\n * A comparison of color interpolation methods.\n *\n * The \"dimming effect\" in browser animations happens because sRGB is\n * gamma-encoded, so linear interpolation passes through desaturated colors.\n *\n * The OKLCH box uses the @property hack: register a custom property as ,\n * animate it 0→1, then use color-mix(in oklch, ...) with that number.\n */\nexport function ColorInterpolation() {\n return () => (\n
    \n \n\n
    \n \n
    sRGB
    \n
    \n\n
    \n \n
    OKLCH
    \n
    \n
    \n )\n}\n" }, { "path": "packages/component/demos/animation/cube.tsx", "content": "import type { Handle } from 'remix/component'\nimport { css, ref } from 'remix/component'\n\nexport function Cube(handle: Handle) {\n let cube: HTMLDivElement\n\n function animate(t: number) {\n if (handle.signal.aborted) return\n\n let rotate = Math.sin(t / 10000) * 200\n let y = (1 + Math.sin(t / 1000)) * -25\n cube.style.transform = `translateY(${y}px) rotateX(${rotate}deg) rotateY(${rotate}deg)`\n\n requestAnimationFrame(animate)\n }\n\n return () => (\n \n {\n cube = node\n requestAnimationFrame(animate)\n }),\n css({\n width: '100px',\n height: '100px',\n position: 'relative',\n transformStyle: 'preserve-3d',\n }),\n ]}\n >\n \n \n \n \n \n \n \n \n )\n}\n" }, { "path": "packages/component/demos/animation/default-animate.tsx", "content": "import { animateEntrance, animateLayout, css, on, type Handle } from 'remix/component'\n\nlet nextId = 1\nfunction createItem() {\n return { id: nextId++, label: `Item ${nextId - 1}` }\n}\n\nexport function DefaultAnimate(handle: Handle) {\n let items = [createItem(), createItem()]\n\n return () => (\n \n
    \n {\n items.unshift(createItem())\n handle.update()\n }),\n ]}\n >\n Add\n \n {\n // Shuffle the array\n for (let i = items.length - 1; i > 0; i--) {\n let j = Math.floor(Math.random() * (i + 1))\n ;[items[i], items[j]] = [items[j], items[i]]\n }\n handle.update()\n }),\n ]}\n >\n Shuffle\n \n
    \n {items.map((item) => (\n \n {item.label}\n {\n items = items.filter((i) => i.id !== item.id)\n handle.update()\n }),\n ]}\n >\n \n \n \n \n \n ))}\n \n )\n}\n" }, { "path": "packages/component/demos/animation/enter.tsx", "content": "import { animateEntrance, css, spring } from 'remix/component'\n\nexport function EnterAnimation() {\n return () => (\n \n )\n}\n" }, { "path": "packages/component/demos/animation/entry.tsx", "content": "import { createRoot, css, on, type Handle, type RemixNode } from 'remix/component'\nimport { DefaultAnimate } from './default-animate.tsx'\nimport { EnterAnimation } from './enter.tsx'\nimport { ExitAnimation } from './exit.tsx'\nimport { Press } from './press.tsx'\nimport { HTMLContent } from './html-content.tsx'\nimport { Keyframes } from './keyframes.tsx'\nimport { InterruptibleKeyframes } from './interruptible-keyframes.tsx'\nimport { RollingSquare } from './rolling-square.tsx'\nimport { Rotate } from './rotate.tsx'\nimport { TransitionOptions } from './transition-options.tsx'\nimport { Cube } from './cube.tsx'\nimport { SharedLayout } from './shared-layout.tsx'\nimport { AspectRatio } from './aspect-ratio.tsx'\nimport { BouncySwitch } from './bouncy-switch.tsx'\nimport { ColorInterpolation } from './color-interpolation.tsx'\nimport { FlipToggle } from './flip-toggle.tsx'\nimport { Reordering } from './reordering.tsx'\nimport { MultiStateBadge } from './multi-state-badge.tsx'\nimport { HoldToConfirm } from './hold-to-confirm.tsx'\nimport { MaterialRipple } from './material-ripple.tsx'\n\nfunction Tile(handle: Handle) {\n let remountKey = 0\n\n return ({ title, children, notes }: { title: string; children: RemixNode; notes?: string }) => (\n \n {\n remountKey++\n handle.update()\n }),\n ]}\n title=\"Replay animation\"\n >\n \n \n \n \n \n

    {title}

    \n \n {children}\n \n {notes && (\n \n {notes}\n

    \n )}\n \n )\n}\n\ncreateRoot(document.body).render(\n <>\n

    Animations

    \n

    \n Most animations are adapted from Motion. Thank you for\n your work Matt Perry!\n

    \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n ,\n)\n" }, { "path": "packages/component/demos/animation/exit.tsx", "content": "import type { Handle } from 'remix/component'\nimport { animateEntrance, animateExit, css, on, spring } from 'remix/component'\n\nexport function ExitAnimation(handle: Handle) {\n let isVisible = true\n\n let shouldAnimate = false\n handle.queueTask(() => {\n shouldAnimate = true\n })\n\n return () => (\n \n {isVisible && (\n \n )}\n {\n isVisible = !isVisible\n handle.update()\n }),\n ]}\n >\n {isVisible ? 'Hide' : 'Show'}\n \n \n )\n}\n" }, { "path": "packages/component/demos/animation/flip-toggle.tsx", "content": "import { animateLayout, css, on, type Handle } from 'remix/component'\n\nexport function FlipToggle(handle: Handle) {\n let isOn = false\n\n return () => (\n {\n isOn = !isOn\n handle.update()\n }),\n ]}\n style={{\n // The actual layout property that changes\n justifyContent: isOn ? 'flex-start' : 'flex-end',\n }}\n >\n \n \n )\n}\n" }, { "path": "packages/component/demos/animation/hold-to-confirm.tsx", "content": "import {\n animateEntrance,\n animateExit,\n createMixin,\n css,\n on,\n pressEvents,\n spring,\n type Handle,\n} from 'remix/component'\n\n// Demo\nlet buttonExitAnimation = {\n opacity: 0,\n transform: 'scale(1.15)',\n duration: 100,\n easing: 'ease-in',\n}\n\nlet confirmationEnterAnimation = {\n opacity: 0,\n transform: 'scale(0.9)',\n duration: 200,\n easing: 'ease-out',\n}\n\nexport function HoldToConfirm(handle: Handle) {\n let confirmed = false\n\n return () => (\n *': { gridArea: '1 / 1' },\n }),\n ]}\n >\n {!confirmed && (\n {\n confirmed = true\n handle.update()\n }}\n />\n )}\n {confirmed && (\n {\n confirmed = false\n handle.update()\n }}\n />\n )}\n \n )\n}\n\nfunction HoldButton(handle: Handle) {\n let confirming = false\n\n return (props: { onConfirm: () => void }) => (\n {\n confirming = true\n handle.update()\n }),\n on(confirmPress.cancel, () => {\n if (!confirming) return\n confirming = false\n handle.update()\n }),\n on(confirmPress.end, () => {\n props.onConfirm()\n }),\n ]}\n >\n \n\n \n \n Hold to Delete\n \n \n )\n}\n\nfunction Confirmation() {\n return (props: { onReset: () => void }) => (\n \n \n \n Deleted\n \n\n \n Reset Demo\n \n \n )\n}\n\nfunction TrashIcon() {\n return () => (\n \n \n \n \n )\n}\n\nfunction CheckIcon() {\n return () => (\n \n \n \n )\n}\n\nconst PRESS_CONFIRM_TIME = 2000\nlet pressConfirmStartEventType = 'demo:press-confirm-start' as const\nlet pressConfirmCancelEventType = 'demo:press-confirm-cancel' as const\nlet pressConfirmEndEventType = 'demo:press-confirm-end' as const\n\ndeclare global {\n interface HTMLElementEventMap {\n [pressConfirmStartEventType]: Event\n [pressConfirmCancelEventType]: Event\n [pressConfirmEndEventType]: Event\n }\n}\n\nlet baseConfirmPress = createMixin((handle) => {\n let timer = 0\n\n let clearTimer = () => {\n if (timer) {\n clearTimeout(timer)\n timer = 0\n }\n }\n\n handle.addEventListener('remove', clearTimer)\n\n return (props) => (\n {\n let target = event.currentTarget\n clearTimer()\n target.dispatchEvent(new Event(pressConfirmStartEventType, { bubbles: true }))\n timer = window.setTimeout(() => {\n target.dispatchEvent(new Event(pressConfirmEndEventType, { bubbles: true }))\n }, PRESS_CONFIRM_TIME)\n }),\n on(pressEvents.up, (event) => {\n clearTimer()\n event.currentTarget.dispatchEvent(\n new Event(pressConfirmCancelEventType, { bubbles: true }),\n )\n }),\n on(pressEvents.cancel, (event) => {\n clearTimer()\n event.currentTarget.dispatchEvent(\n new Event(pressConfirmCancelEventType, { bubbles: true }),\n )\n }),\n ]}\n />\n )\n})\n\ntype ConfirmPressMixin = typeof baseConfirmPress & {\n readonly start: typeof pressConfirmStartEventType\n readonly cancel: typeof pressConfirmCancelEventType\n readonly end: typeof pressConfirmEndEventType\n}\n\nlet confirmPress: ConfirmPressMixin = Object.assign(baseConfirmPress, {\n start: pressConfirmStartEventType,\n cancel: pressConfirmCancelEventType,\n end: pressConfirmEndEventType,\n})\n" }, { "path": "packages/component/demos/animation/html-content.tsx", "content": "import type { Handle } from 'remix/component'\nimport { css, spring } from 'remix/component'\n\nexport function HTMLContent(handle: Handle) {\n let count = 0\n let from = 0\n let to = 100\n\n let counter = spring({ duration: 3000, bounce: 0 })\n\n function animate() {\n if (handle.signal.aborted) return\n\n let { value: t, done } = counter.next()\n if (done) return\n\n count = Math.round(from + (to - from) * t)\n handle.update()\n requestAnimationFrame(animate)\n }\n\n handle.queueTask(() => {\n requestAnimationFrame(animate)\n })\n\n return () => (\n \n {count}\n \n )\n}\n" }, { "path": "packages/component/demos/animation/index.html", "content": "\n\n \n Animation\n \n \n \n \n \n\n" }, { "path": "packages/component/demos/animation/interruptible-keyframes.tsx", "content": "import type { Handle } from 'remix/component'\nimport { css, on, ref } from 'remix/component'\n\nexport function InterruptibleKeyframes(handle: Handle) {\n let box: HTMLDivElement\n let currentAnimation: Animation | null = null\n\n function getCurrentScale(): number {\n let matrix = new DOMMatrix(getComputedStyle(box).transform)\n return matrix.a\n }\n\n function interruptAnimation() {\n if (currentAnimation) {\n currentAnimation.commitStyles()\n currentAnimation.cancel()\n currentAnimation = null\n }\n }\n\n return () => (\n (box = node)),\n css({\n width: 100,\n height: 100,\n backgroundColor: '#0cdcf7',\n borderRadius: 5,\n }),\n on('pointerenter', () => {\n interruptAnimation()\n let startScale = getCurrentScale()\n\n currentAnimation = box.animate(\n [\n { transform: `scale(${startScale})`, offset: 0, easing: 'ease-in-out' },\n { transform: 'scale(1.1)', offset: 0.6, easing: 'ease-out' },\n { transform: 'scale(1.6)', offset: 1 },\n ],\n {\n duration: 500,\n fill: 'forwards',\n },\n )\n }),\n on('pointerleave', () => {\n interruptAnimation()\n let startScale = getCurrentScale()\n\n currentAnimation = box.animate(\n [{ transform: `scale(${startScale})` }, { transform: 'scale(1)' }],\n {\n duration: 300,\n easing: 'ease-out',\n fill: 'forwards',\n },\n )\n }),\n ]}\n />\n )\n}\n" }, { "path": "packages/component/demos/animation/keyframes.tsx", "content": "import { css } from 'remix/component'\n\nexport function Keyframes() {\n return () => (\n
    \n \n
    \n )\n}\n" }, { "path": "packages/component/demos/animation/material-ripple.tsx", "content": "import type { Handle } from 'remix/component'\nimport { animateEntrance, animateExit, css, on, pressEvents, ref } from 'remix/component'\n\ntype Ripple = {\n id: number\n x: number\n y: number\n size: number\n}\n\nexport function MaterialRipple(handle: Handle) {\n let ripples: Ripple[] = []\n let idCounter = 0\n let buttonEl: HTMLButtonElement | null = null\n\n function createRipple(originX: number, originY: number) {\n if (!buttonEl) return\n\n let rect = buttonEl.getBoundingClientRect()\n let localX = originX - rect.left\n let localY = originY - rect.top\n let dx = Math.max(localX, rect.width - localX)\n let dy = Math.max(localY, rect.height - localY)\n let radius = Math.sqrt(dx * dx + dy * dy)\n let size = radius * 2\n\n let id = ++idCounter\n ripples = [...ripples, { id, x: localX, y: localY, size }]\n handle.update()\n }\n\n function removeAllRipples() {\n if (ripples.length > 0) {\n ripples = []\n handle.update()\n }\n }\n\n return () => (\n {\n buttonEl = el\n }),\n css({\n position: 'relative',\n display: 'inline-flex',\n alignItems: 'center',\n justifyContent: 'center',\n padding: '10px 20px',\n borderRadius: 4,\n textTransform: 'uppercase',\n backgroundColor: 'transparent',\n color: '#7c3aed',\n border: '1px solid #7c3aed',\n userSelect: 'none',\n cursor: 'pointer',\n overflow: 'hidden',\n letterSpacing: '0.2px',\n WebkitTapHighlightColor: 'transparent',\n transition: 'border-color 200ms linear, background-color 200ms linear',\n '&:hover': {\n borderColor: '#6d28d9',\n backgroundColor: '#7c3aed20',\n },\n '&:focus-visible': {\n outline: '2px solid #7c3aed80',\n outlineOffset: 2,\n },\n }),\n pressEvents(),\n on(pressEvents.down, (event) => {\n if (!buttonEl) return\n let rect = buttonEl.getBoundingClientRect()\n let x = event.clientX || rect.left + rect.width / 2\n let y = event.clientY || rect.top + rect.height / 2\n createRipple(x, y)\n }),\n on(pressEvents.up, removeAllRipples),\n on(pressEvents.cancel, removeAllRipples),\n ]}\n >\n Click me\n \n {ripples.map((ripple) => (\n // Outer span: handles exit (fade out)\n \n {/* Inner span: handles enter (scale) so it doesn't get reversed when removed */}\n \n \n ))}\n \n \n )\n}\n" }, { "path": "packages/component/demos/animation/mixin-presence-list.tsx", "content": "import type { Handle } from 'remix/component'\nimport { animateEntrance, animateExit, css, on } from 'remix/component'\n\nlet nextId = 1\nfunction createItem() {\n return { id: nextId++, label: `Row ${nextId - 1}` }\n}\n\nexport function MixinPresenceList(handle: Handle) {\n let items = [createItem(), createItem(), createItem()]\n\n return () => (\n \n
    \n {\n items.unshift(createItem())\n handle.update()\n }),\n ]}\n >\n Add\n \n {\n items = items.slice(0, Math.max(0, items.length - 1))\n handle.update()\n }),\n ]}\n >\n Remove\n \n
    \n {items.map((item) => (\n \n {item.label}\n {\n items = items.filter((entry) => entry.id !== item.id)\n handle.update()\n }),\n ]}\n >\n ×\n \n \n ))}\n \n )\n}\n" }, { "path": "packages/component/demos/animation/mixin-reclaim.tsx", "content": "import type { Handle } from 'remix/component'\nimport { animateEntrance, animateExit, css, on } from 'remix/component'\n\nexport function MixinReclaim(handle: Handle) {\n let visible = true\n let interruptTimer: number | undefined\n\n function clearInterruptTimer() {\n if (interruptTimer === undefined) return\n window.clearTimeout(interruptTimer)\n interruptTimer = undefined\n }\n\n function scheduleInterrupt() {\n clearInterruptTimer()\n visible = false\n handle.update()\n interruptTimer = window.setTimeout(() => {\n visible = true\n handle.update()\n interruptTimer = undefined\n }, 140)\n }\n\n return () => (\n
    \n
    \n {\n clearInterruptTimer()\n visible = true\n handle.update()\n }),\n ]}\n >\n Show\n \n \n Interrupt\n \n
    \n\n {\n clearInterruptTimer()\n visible = false\n handle.update()\n }),\n ]}\n >\n Hide\n \n\n
    \n {visible && (\n \n Reclaim Me Mid-Exit\n
    \n )}\n
    \n \n )\n}\n" }, { "path": "packages/component/demos/animation/multi-state-badge.tsx", "content": "import type { Handle } from 'remix/component'\nimport { animateEntrance, animateExit, css, on, ref } from 'remix/component'\nimport { spring } from '../../src/lib/spring.ts'\n\nconst STATES = {\n idle: 'Start',\n processing: 'Processing',\n success: 'Done',\n error: 'Something went wrong',\n} as const\n\ntype State = keyof typeof STATES\n\nfunction getNextState(state: State): State {\n let states = Object.keys(STATES) as State[]\n let nextIndex = (states.indexOf(state) + 1) % states.length\n return states[nextIndex]\n}\n\nconst ICON_SIZE = 20\nconst STROKE_WIDTH = 1.5\nconst VIEW_BOX_SIZE = 24\n\nlet iconEnterAnimation = {\n transform: 'translateY(-40px) scale(0.5)',\n filter: 'blur(6px)',\n duration: 150,\n easing: 'ease-out',\n}\n\nlet iconExitAnimation = {\n transform: 'translateY(40px) scale(0.5)',\n filter: 'blur(6px)',\n duration: 150,\n easing: 'ease-in',\n}\n\nexport function MultiStateBadge(handle: Handle) {\n let state: State = 'idle'\n\n return () => (\n \n {\n state = getNextState(state)\n handle.update()\n }),\n ]}\n >\n \n \n \n )\n}\n\nfunction Badge(handle: Handle) {\n let badgeEl: HTMLDivElement\n let prevState: State | null = null\n\n return (props: { state: State }) => {\n // Trigger shake/scale animations on state change\n if (prevState !== null && prevState !== props.state) {\n handle.queueTask(() => {\n if (props.state === 'error') {\n badgeEl.animate(\n {\n transform: [\n 'translateX(0)',\n 'translateX(-6px)',\n 'translateX(6px)',\n 'translateX(-6px)',\n 'translateX(0)',\n ],\n },\n { duration: 300, easing: 'ease-in-out', delay: 100 },\n )\n } else if (props.state === 'success') {\n badgeEl.animate(\n { transform: ['scale(1)', 'scale(1.2)', 'scale(1)'] },\n { duration: 300, easing: 'ease-in-out' },\n )\n }\n })\n }\n prevState = props.state\n\n return (\n (badgeEl = node)),\n css({\n backgroundColor: '#e2e8f0',\n color: '#0f1115',\n display: 'flex',\n overflow: 'hidden',\n alignItems: 'center',\n justifyContent: 'center',\n padding: '12px 20px',\n fontSize: 16,\n borderRadius: 999,\n willChange: 'transform, filter',\n transition: `gap ${spring('snappy')}`,\n }),\n ]}\n style={{ gap: props.state === 'idle' ? '0px' : '8px' }}\n >\n \n \n ))}\n \n\n {/* Instructions */}\n \n Click to move target • Drag the blue circle and release to see velocity-based spring\n \n \n )\n}\n\ncreateRoot(document.body).render()\n" }, { "path": "packages/component/demos/spring/index.html", "content": "\n\n \n Spring Animation\n \n \n \n \n\n" }, { "path": "packages/component/demos/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\", \"DOM.AsyncIterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"types\": [\"node\", \"dom-navigation\"],\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true,\n \"skipLibCheck\": true,\n \"jsx\": \"react-jsx\",\n \"jsxImportSource\": \"remix/component\",\n \"paths\": {\n \"*\": [\"./*\"],\n \"remix/component/jsx-runtime\": [\"../../remix/src/component/jsx-runtime.ts\"],\n \"remix/component/jsx-dev-runtime\": [\"../../remix/src/component/jsx-dev-runtime.ts\"]\n }\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/component/docs/components.md", "content": "# Components\n\nAll components follow a consistent two-phase structure.\n\n## Component Structure\n\n1. **Setup Phase** - Runs once when the component is first created\n2. **Render Phase** - Runs on initial render and every update afterward\n\n```tsx\nfunction MyComponent(handle: Handle, setup: SetupType) {\n // Setup phase: runs once\n let state = initializeState(setup)\n\n // Return render function: runs on every update\n return (props: Props) => {\n return
    {/* render content */}
    \n }\n}\n```\n\n## Runtime Behavior\n\nWhen a component is rendered:\n\n1. **First Render**:\n\n - The component function is called with `handle` and the `setup` prop\n - The returned render function is stored\n - The render function is called with regular props\n - Any tasks queued via `handle.queueTask()` are executed after rendering\n\n2. **Subsequent Updates**:\n\n - Only the render function is called\n - Setup phase is skipped, setup closure persists for the lifetime of the component instance\n - Props are passed to the render function\n - The `setup` prop is stripped from props\n - Tasks queued during the update are executed after rendering\n\n3. **Component Removal**:\n - `handle.signal` is aborted\n - All event listeners registered via `addEventListeners()` are automatically cleaned up\n - Any queued tasks are executed with an aborted signal\n\n## Setup vs Props\n\nThe `setup` prop is special—it's only available in the setup phase and is automatically excluded from props. This prevents accidental stale captures:\n\n```tsx\nfunction Counter(handle: Handle, setup: number) {\n // setup prop (e.g., initialCount) only available here\n let count = setup\n\n return (props: { label: string }) => {\n // props only receives { label } - setup is excluded\n return (\n
    \n {props.label}: {count}\n
    \n )\n }\n}\n\n// Usage\nlet element = \n```\n\n## Basic Rendering\n\nThe simplest component just returns JSX:\n\n```tsx\nfunction Greeting() {\n return (props: { name: string }) =>
    Hello, {props.name}!
    \n}\n\nlet el = \n```\n\n## Prop Passing\n\nProps flow from parent to child through JSX attributes:\n\n```tsx\nfunction Parent() {\n return () => \n}\n\nfunction Child() {\n return (props: { message: string; count: number }) => (\n
    \n

    {props.message}

    \n

    Count: {props.count}

    \n
    \n )\n}\n```\n\n## Stateful Updates\n\nState is managed with plain JavaScript variables. Call `handle.update()` to trigger a re-render:\n\n```tsx\nfunction Counter(handle: Handle) {\n let count = 0\n\n return () => (\n
    \n Count: {count}\n {\n count++\n handle.update()\n }),\n ]}\n >\n Increment\n \n
    \n )\n}\n```\n\n## See Also\n\n- [Handle API](./handle.md) - Complete handle API reference\n- [Patterns](./patterns.md) - State management best practices\n" }, { "path": "packages/component/docs/composition.md", "content": "# Composition\n\nBuilding component trees with props, children, refs, and keys.\n\n## Props\n\nProps flow from parent to child through JSX attributes:\n\n```tsx\nfunction Parent() {\n return () => \n}\n\nfunction Child() {\n return (props: { message: string; count: number }) => (\n
    \n

    {props.message}

    \n

    Count: {props.count}

    \n
    \n )\n}\n```\n\n## Children\n\nComponents can compose other components via `children`:\n\n```tsx\nfunction Layout() {\n return (props: { children: RemixNode }) => (\n
    \n
    My App
    \n
    {props.children}
    \n
    © 2024
    \n
    \n )\n}\n\nfunction App() {\n return () => (\n \n

    Welcome

    \n

    Content goes here

    \n     \n )\n}\n```\n\n## Ref Mixin\n\nUse the `ref(...)` mixin to get a reference to the DOM node after it's rendered. This is useful for DOM operations like focusing elements, scrolling, measuring dimensions, or setting up observers.\n\n```tsx\nfunction Form(handle: Handle) {\n let inputRef: HTMLInputElement\n\n return () => (\n
    \n (inputRef = node))]} />\n {\n // Focus the input from elsewhere in the form\n inputRef.focus()\n }),\n ]}\n >\n Focus Input\n \n \n )\n}\n```\n\nThe `ref` callback receives an `AbortSignal` as its second parameter, which is aborted when the element is removed from the DOM. Use this for cleanup operations:\n\n```tsx\nfunction ResizeTracker(handle: Handle) {\n let dimensions = { width: 0, height: 0 }\n\n return () => (\n {\n // Set up ResizeObserver\n let observer = new ResizeObserver((entries) => {\n let entry = entries[0]\n if (entry) {\n dimensions.width = Math.round(entry.contentRect.width)\n dimensions.height = Math.round(entry.contentRect.height)\n handle.update()\n }\n })\n observer.observe(node)\n\n // Clean up when element is removed\n signal.addEventListener('abort', () => {\n observer.disconnect()\n })\n }),\n ]}\n >\n Size: {dimensions.width} x {dimensions.height}\n \n )\n}\n```\n\nThe `ref` callback is called only once when the element is first rendered, not on every update.\n\n## Key Prop\n\nUse the `key` prop to uniquely identify elements in lists. Keys enable efficient diffing and preserve DOM nodes and component state when lists are reordered, filtered, or updated.\n\n```tsx\nfunction TodoList(handle: Handle) {\n let todos = [\n { id: '1', text: 'Buy milk' },\n { id: '2', text: 'Walk dog' },\n { id: '3', text: 'Write code' },\n ]\n\n return () => (\n
      \n {todos.map((todo) => (\n
    • {todo.text}
      • \n ))}\n
    \n )\n}\n```\n\nWhen you reorder, add, or remove items, keys ensure:\n\n- **DOM nodes are reused** - Elements with matching keys are moved, not recreated\n- **Component state is preserved** - Component instances persist across reorders\n- **Focus and selection are maintained** - Input focus stays with the same element\n- **Input values are preserved** - Form values remain with their elements\n\n```tsx\nfunction ReorderableList(handle: Handle) {\n let items = [\n { id: 'a', label: 'Item A' },\n { id: 'b', label: 'Item B' },\n { id: 'c', label: 'Item C' },\n ]\n\n function reverse() {\n items = [...items].reverse()\n handle.update()\n }\n\n return () => (\n
    \n \n {items.map((item) => (\n
    \n \n
    \n ))}\n
    \n )\n}\n```\n\nEven when the list order changes, each input maintains its value and focus state because the `key` prop identifies which DOM node corresponds to which item.\n\nKeys can be any type (string, number, bigint, object, symbol), but should be stable and unique within the list:\n\n```tsx\n// Good: stable, unique IDs\n{\n items.map((item) => )\n}\n\n// Good: index can work if list never reorders\n{\n items.map((item, index) => )\n}\n\n// Bad: don't use random values or values that change\n{\n items.map((item) => )\n}\n```\n\n## See Also\n\n- [Context](./context.md) - Indirect composition without prop drilling\n" }, { "path": "packages/component/docs/context.md", "content": "# Context\n\nContext enables components to communicate without direct prop passing.\n\n## Basic Context\n\nUse `handle.context.set()` to provide values and `handle.context.get()` to consume them:\n\n```tsx\nfunction ThemeProvider(handle: Handle<{ theme: 'light' | 'dark' }>) {\n let theme: 'light' | 'dark' = 'light'\n\n handle.context.set({ theme })\n\n return (props: { children: RemixNode }) => (\n
    \n {\n theme = theme === 'light' ? 'dark' : 'light'\n handle.context.set({ theme })\n handle.update()\n }),\n ]}\n >\n Toggle Theme\n \n {props.children}\n
    \n )\n}\n\nfunction ThemedContent(handle: Handle) {\n let { theme } = handle.context.get(ThemeProvider)\n\n return () => (\n
    \n Current theme: {theme}\n
    \n )\n}\n```\n\n**Important:** `handle.context.set()` does not cause any updates—it simply stores a value. If you want the component tree to update when context changes, you must call `handle.update()` after setting the context (as shown above).\n\n## TypedEventTarget for Granular Updates\n\nFor better performance, use `TypedEventTarget` to avoid updating the entire subtree. This allows descendants to subscribe to specific changes rather than re-rendering on every parent update:\n\n```tsx\nimport { TypedEventTarget } from 'remix/component'\n\nclass Theme extends TypedEventTarget<{ change: Event }> {\n #value: 'light' | 'dark' = 'light'\n\n get value() {\n return this.#value\n }\n\n setValue(value: 'light' | 'dark') {\n this.#value = value\n this.dispatchEvent(new Event('change'))\n }\n}\n\nfunction ThemeProvider(handle: Handle) {\n let theme = new Theme()\n handle.context.set(theme)\n\n return (props: { children: RemixNode }) => (\n
    \n {\n // No update needed - consumers subscribe to changes\n theme.setValue(theme.value === 'light' ? 'dark' : 'light')\n }),\n ]}\n >\n Toggle Theme\n \n {props.children}\n
    \n )\n}\n\nfunction ThemedContent(handle: Handle) {\n let theme = handle.context.get(ThemeProvider)\n\n // Subscribe to granular updates\n addEventListeners(theme, handle.signal, {\n change() {\n handle.update()\n },\n })\n\n return () => (\n
    \n Current theme: {theme.value}\n
    \n )\n}\n```\n\nBenefits of this pattern:\n\n- **No unnecessary re-renders**: Only components that subscribe to changes are updated\n- **Decoupled updates**: The provider doesn't need to call `handle.update()` when context changes\n- **Type-safe events**: `TypedEventTarget` ensures event handlers receive the correct event types\n\n## Context with Multiple Values\n\nProvide multiple related values through context:\n\n```tsx\nclass AppContext extends TypedEventTarget<{ userChange: Event; settingsChange: Event }> {\n #user: User | null = null\n #settings: Settings = defaultSettings\n\n get user() {\n return this.#user\n }\n\n get settings() {\n return this.#settings\n }\n\n setUser(user: User | null) {\n this.#user = user\n this.dispatchEvent(new Event('userChange'))\n }\n\n setSettings(settings: Settings) {\n this.#settings = settings\n this.dispatchEvent(new Event('settingsChange'))\n }\n}\n\nfunction AppProvider(handle: Handle) {\n let context = new AppContext()\n handle.context.set(context)\n\n return (props: { children: RemixNode }) => props.children\n}\n\n// Components can subscribe to only the events they care about\nfunction UserDisplay(handle: Handle) {\n let context = handle.context.get(AppProvider)\n\n addEventListeners(context, handle.signal, {\n userChange() {\n handle.update()\n },\n })\n\n return () =>
    {context.user?.name ?? 'Not logged in'}
    \n}\n```\n\n## See Also\n\n- [Handle API](./handle.md) - `handle.context` reference\n- [Events](./events.md) - `addEventListeners()` for subscribing to EventTargets\n" }, { "path": "packages/component/docs/events.md", "content": "# Events\n\nEvent handling with the `on()` mixin and signal-based interruption management.\n\n## Basic Event Handling\n\nUse the `on()` mixin to attach event listeners to elements:\n\n```tsx\nfunction Button(handle: Handle) {\n let count = 0\n\n return () => (\n {\n count++\n handle.update()\n }),\n ]}\n >\n Clicked {count} times\n \n )\n}\n```\n\n## Event Handler Signature\n\nEvent handlers receive the event object and an optional `AbortSignal`:\n\n```tsx\nmix={[on('click', (event) => {\n // event is the DOM event\n event.preventDefault()\n }), on('input', async (event, signal) => {\n // signal is aborted when handler is re-entered or component removed\n let response = await fetch('/api', { signal })\n })]}\n```\n\n## Signals in Event Handlers\n\nEvent handlers receive an `AbortSignal` that's automatically aborted when:\n\n- The handler is re-entered (user triggers another event before the previous one completes)\n- The component is removed from the tree\n\nThis prevents race conditions when users create events faster than async work completes:\n\n```tsx\nfunction SearchInput(handle: Handle) {\n let results: string[] = []\n let loading = false\n\n return () => (\n
    \n {\n let query = event.currentTarget.value\n loading = true\n handle.update()\n\n // Passing signal automatically aborts previous requests\n let response = await fetch(`/search?q=${query}`, { signal })\n let data = await response.json()\n // Manual check for APIs that don't accept a signal\n if (signal.aborted) return\n\n results = data.results\n loading = false\n handle.update()\n }),\n ]}\n />\n {loading &&
    Loading...
    }\n {!loading && results.length > 0 && (\n
      \n {results.map((result, i) => (\n
    • {result}
      • \n ))}\n
    \n )}\n
    \n )\n}\n```\n\nThe signal ensures only the latest search request completes, preventing stale results from overwriting newer ones.\n\n## Multiple Event Types\n\nHandle multiple events on the same element:\n\n```tsx\nfunction InteractiveBox(handle: Handle) {\n let state = 'idle'\n\n return () => (\n {\n state = 'hovered'\n handle.update()\n }),\n on('mouseleave', () => {\n state = 'idle'\n handle.update()\n }),\n on('click', () => {\n state = 'clicked'\n handle.update()\n }),\n ]}\n >\n State: {state}\n \n )\n}\n```\n\n## Form Events\n\nCommon form event patterns:\n\n```tsx\nfunction Form(handle: Handle) {\n return () => (\n {\n event.preventDefault()\n let formData = new FormData(event.currentTarget)\n // Process form data\n }),\n ]}\n >\n {\n // Validate on blur\n let value = event.currentTarget.value\n if (!value.includes('@')) {\n event.currentTarget.setCustomValidity('Invalid email')\n }\n }),\n on('input', (event) => {\n // Clear validation on input\n event.currentTarget.setCustomValidity('')\n }),\n ]}\n />\n \n \n )\n}\n```\n\n## Keyboard Events\n\nHandle keyboard interactions:\n\n```tsx\nfunction KeyboardNav(handle: Handle) {\n let selectedIndex = 0\n let items = ['Apple', 'Banana', 'Cherry']\n\n return () => (\n {\n switch (event.key) {\n case 'ArrowDown':\n event.preventDefault()\n selectedIndex = Math.min(selectedIndex + 1, items.length - 1)\n handle.update()\n break\n case 'ArrowUp':\n event.preventDefault()\n selectedIndex = Math.max(selectedIndex - 1, 0)\n handle.update()\n break\n }\n }),\n ]}\n >\n {items.map((item, i) => (\n
  • \n {item}\n
    • \n ))}\n \n )\n}\n```\n\n## Global Event Listeners\n\nUse `addEventListeners()` for global event targets with automatic cleanup:\n\n```tsx\nfunction WindowResizeTracker(handle: Handle) {\n let width = window.innerWidth\n let height = window.innerHeight\n\n // Set up global listeners once in setup\n addEventListeners(window, handle.signal, {\n resize() {\n width = window.innerWidth\n height = window.innerHeight\n handle.update()\n },\n })\n\n return () => (\n
    \n Window size: {width} x {height}\n
    \n )\n}\n```\n\n```tsx\nfunction KeyboardTracker(handle: Handle) {\n let keys: string[] = []\n\n addEventListeners(document, handle.signal, {\n keydown(event) {\n keys.push(event.key)\n handle.update()\n },\n })\n\n return () =>
    Keys: {keys.join(', ')}
    \n}\n```\n\n## Best Practices\n\n### Prefer Press Events Over Click\n\nFor interactive elements, prefer `press` events over `click`. Press events provide better cross-device behavior:\n\n- Fire on both mouse and touch interactions\n- Handle keyboard activation (Enter/Space) automatically\n- Prevent ghost clicks on touch devices\n- Support press-and-hold patterns\n\n```tsx\n// ❌ Avoid: click doesn't handle all interaction modes well\n\n\n// ✅ Prefer: press handles mouse, touch, and keyboard uniformly\n\n```\n\nUse `click` only when you specifically need mouse-click behavior (e.g., detecting right-clicks or modifier keys).\n\n### Do Work in Event Handlers\n\nDo as much work as possible in event handlers. Use the event handler scope for transient state:\n\n```tsx\n// ✅ Good: Do work in handler, only store what renders need\nfunction SearchResults(handle: Handle) {\n let results: string[] = [] // Needed for rendering\n let loading = false // Needed for rendering loading state\n\n return () => (\n
    \n {\n let query = event.currentTarget.value\n // Do work in handler scope\n loading = true\n handle.update()\n\n let response = await fetch(`/search?q=${query}`, { signal })\n let data = await response.json()\n if (signal.aborted) return\n\n // Only store what's needed for rendering\n results = data.results\n loading = false\n handle.update()\n }),\n ]}\n />\n {loading &&
    Loading...
    }\n {results.map((result, i) => (\n
    {result}
    \n ))}\n
    \n )\n}\n```\n\n### Always Check signal.aborted\n\nFor async work, always check the signal or pass it to APIs that support it:\n\n```tsx\nmix={[on('click', async (event, signal) => {\n // Option 1: Pass signal to fetch\n let response = await fetch('/api', { signal })\n\n // Option 2: Manual check after await\n let data = await someAsyncOperation()\n if (signal.aborted) return\n\n // Safe to update state\n handle.update()\n })]}\n```\n\n## See Also\n\n- [Handle API](./handle.md) - `addEventListeners()` for global listeners\n- [Patterns](./patterns.md) - Data loading and async patterns\n" }, { "path": "packages/component/docs/frames.md", "content": "# Frames\n\nA `` renders server content into the page. Frames can stream in after the initial HTML, nest inside other frames, contain client entries, and be reloaded from the client without a full page navigation.\n\n## Basic usage\n\n```tsx\nimport { Frame } from 'remix/component'\n\nfunction App() {\n return () => (\n
    \n

    Dashboard

    \n Loading sidebar...
    } />\n \n \n )\n}\n```\n\n### Props\n\n- **`src`** (required) - The URL to fetch the frame content from.\n- **`fallback`** (optional) - Content to show while the frame is loading. When provided, the frame streams non-blocking (the initial page renders immediately with the fallback, and the real content arrives later). Without a fallback, the frame blocks rendering until its content resolves.\n- **`name`** (optional) - Registers the frame for lookup via `handle.frames.get(name)` from client entries.\n\n## Blocking vs non-blocking\n\nThe presence of a `fallback` prop determines streaming behavior:\n\n**Blocking** (no fallback): The server waits for the frame content before sending the initial HTML chunk. Use this for content that must be visible immediately.\n\n```tsx\n\n```\n\n**Non-blocking** (with fallback): The fallback renders in the initial chunk. The real content streams in later and replaces the fallback. Use this for content that can load progressively.\n\n```tsx\nLoading...} />\n```\n\n## Resolving frame content\n\nOn the server, `renderToStream` calls your `resolveFrame` function to get the HTML for each frame:\n\n```tsx\nimport { renderToStream } from 'remix/component/server'\n\nlet stream = renderToStream(, {\n frameSrc: request.url,\n async resolveFrame(src, _target, context) {\n let res = await fetch(new URL(src, context?.currentFrameSrc ?? request.url))\n return res.body // or res.text() for a string\n },\n})\n```\n\n`resolveFrame` can return:\n\n- A string of HTML\n- A `ReadableStream`\n- A promise of either\n\nFrame content is itself rendered with `renderToStream`, so frames can contain other frames and client entries. The hydration data from nested frames is merged into the parent response automatically.\n\nWhen a server frame response is itself rendered with `renderToStream()`, pass `frameSrc` for that frame's URL and forward `topFrameSrc` from `resolveFrame()` if you want nested SSR components to keep seeing the outer document URL through `handle.frames.top.src`.\n\n## Reloading frames\n\nClient entries inside a frame can trigger a reload via `handle.frame.reload()`:\n\n```tsx\nimport { clientEntry, on, type Handle } from 'remix/component'\n\nexport let RefreshButton = clientEntry(\n '/assets/refresh.js#RefreshButton',\n function RefreshButton(handle: Handle) {\n return () => (\n {\n handle.frame.reload()\n }),\n ]}\n >\n Refresh\n \n )\n },\n)\n```\n\nYou can also reload adjacent named frames:\n\n```tsx\n\n\n\n```\n\n```tsx\nfunction CartRow(handle: Handle) {\n return () => (\n {\n await handle.frames.get('cart-summary')?.reload()\n await handle.frames.get('cart-empty')?.reload()\n await handle.frame.reload()\n }),\n ]}\n >\n Save\n \n )\n}\n```\n\n`handle.frames.get(name)` returns `undefined` when no named frame is mounted.\n\nWhen a frame reloads:\n\n1. The frame's `src` is re-fetched via `resolveFrame` on the client.\n2. The new HTML is parsed and diffed against the current frame content.\n3. Matching DOM nodes are updated in place. New nodes are inserted, removed nodes are cleaned up.\n4. Client entries inside the frame receive updated props from the server while preserving their local component state.\n\nThis means a counter inside a reloading frame keeps its count, but sees any new props the server sends.\n\n## Nested frames\n\nFrames can nest. Each frame owns its own region of the DOM and hydrates its client entries independently:\n\n```tsx\nfunction App() {\n return () => (\n
    \n Loading outer...
    } />\n \n )\n}\n\n// /outer response:\nfunction OuterFrame() {\n return () => (\n
    \n

    Outer

    \n Loading inner...
    } />\n \n )\n}\n```\n\nNested frames stream independently. The outer frame can resolve and render while the inner frame is still loading.\n\nDuring SSR, `handle.frame.src` should point at the frame currently being rendered, while `handle.frames.top.src` should stay fixed at the outer document URL. Use `renderToStream({ frameSrc, topFrameSrc })` inside nested `resolveFrame()` handlers to preserve that distinction.\n\n## Client-resolved frames\n\nOn the client, `run` accepts an optional `resolveFrame` implementation:\n\n```tsx\nlet app = run({\n loadModule: ...,\n async resolveFrame(src, signal, target) {\n let headers = new Headers({ accept: 'text/html' })\n if (target) headers.set('x-remix-target', target)\n let response = await fetch(src, { headers, signal })\n return response.body ?? (await response.text())\n },\n})\n```\n\nThis is used both for initial hydration of pending frames and for `handle.frame.reload()` calls. If omitted, frames resolve to `

    resolve frame unimplemented

    `. Because this function defines the trust boundary for frame HTML, only return content from sources you trust.\n\n## Frame lifecycle\n\n1. **Server render** - Frame content is resolved via `resolveFrame` and serialized into the HTML stream. Frame metadata is stored in the `rmx-data` script.\n2. **Client boot** - `run` discovers frame boundaries, hydrates client entries inside them, and sets up observers for any pending (non-blocking) frames still streaming.\n3. **Reload** - `handle.frame.reload()` re-fetches the frame's `src`, diffs the new content into the DOM, and re-hydrates any client entries with updated props.\n4. **Dispose** - When a frame is removed (e.g., parent re-render), its client entries are cleaned up and sub-frames are disposed recursively.\n\n## See Also\n\n- [Server Rendering](./server-rendering.md) - Streaming HTML with `renderToStream`\n- [Hydration](./hydration.md) - Client entries and the `run` function\n" }, { "path": "packages/component/docs/getting-started.md", "content": "# Getting Started\n\nCreate interactive UIs with Remix Component using a two-phase component model: setup runs once, render runs on every update.\n\n## Client-Only Root\n\nTo start using Remix Component on the client, create a root and render your top-level component:\n\n```tsx\nimport { createRoot } from 'remix/component'\nimport type { Handle } from 'remix/component'\n\nfunction App(handle: Handle) {\n return () => (\n
    \n

    Hello, World!

    \n
    \n )\n}\n\n// Create a root attached to a DOM element\nlet container = document.getElementById('app')!\nlet root = createRoot(container)\n\n// Render your app\nroot.render()\n```\n\nThe `createRoot` function takes a DOM element (or `document.body`) and returns a root object with a `render` method. You can call `render` multiple times to update the app:\n\n```tsx\nfunction App(handle: Handle) {\n let count = 0\n\n return () => (\n
    \n

    Count: {count}

    \n {\n count++\n handle.update()\n }),\n ]}\n >\n Increment\n \n
    \n )\n}\n\nlet root = createRoot(document.body)\nroot.render()\n```\n\n## Root Methods\n\nThe root object provides several methods:\n\n- **`render(node)`** - Renders a component tree into the root container\n- **`flush()`** - Synchronously flushes all pending updates and tasks\n- **`dispose()`** - Removes the component tree and cleans up\n\n```tsx\nlet root = createRoot(document.body)\n\n// Render initial app\nroot.render()\n\n// Flush any pending updates synchronously\nroot.flush()\n\n// Later, remove the app\nroot.dispose()\n```\n\n## Server-Rendered App\n\nFor a server-rendered app, define your page as a component, render it with `renderToStream`, and hydrate client entries on the client:\n\n### Server\n\n```tsx\nimport { renderToStream } from 'remix/component/server'\nimport { Frame } from 'remix/component'\nimport { Counter } from './assets/counter.tsx'\n\nfunction App() {\n return () => (\n \n \n My App\n `\n}\n\nfunction escapeScriptJson(json: string): string {\n // Avoid prematurely closing the script tag when serialized data contains \"\".\n return json.replace(/): string {\n let parts: string[] = []\n\n for (let [key, value] of Object.entries(style)) {\n if (value == null) continue\n if (typeof value === 'boolean') continue\n if (typeof value === 'number' && !Number.isFinite(value)) continue\n\n // Convert camelCase to kebab-case\n let cssKey = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`)\n\n // Add px to numeric values where appropriate\n let shouldAppendPx =\n typeof value === 'number' &&\n value !== 0 &&\n !NUMERIC_CSS_PROPS.has(cssKey) &&\n !cssKey.startsWith('--')\n\n let cssValue = shouldAppendPx\n ? `${value}px`\n : Array.isArray(value)\n ? value.join(', ')\n : String(value)\n\n parts.push(`${cssKey}: ${cssValue};`)\n }\n\n return parts.join(' ')\n}\n\n// Frame styles work end-to-end when frame handlers use their own `renderToStream`:\n// the handler's `finalizeHtml` emits `')\n })\n\n it('places styles in head when no html root', async () => {\n let stream = renderToStream(
    No HTML root
    )\n let html = await drain(stream)\n\n // Style should be in a head element\n expect(html).toMatch(/^\n \n \n
    \n

    Index of ${pathname}

    \n \n \n \n \n \n \n \n \n \n ${tableRows}\n \n
    NameSizeType
    \n
    \n \n \n `)\n}\n\nasync function calculateDirectorySize(dirPath: string): Promise {\n let totalSize = 0\n\n try {\n let dirents = await fsp.readdir(dirPath, { withFileTypes: true })\n\n for (let dirent of dirents) {\n let fullPath = path.join(dirPath, dirent.name)\n\n try {\n if (dirent.isDirectory()) {\n totalSize += await calculateDirectorySize(fullPath)\n } else if (dirent.isFile()) {\n let stats = await fsp.stat(fullPath)\n totalSize += stats.size\n }\n } catch {\n // Skip files/folders we can't access\n }\n }\n } catch {\n // If we can't read the directory, return 0\n }\n\n return totalSize\n}\n\nfunction formatFileSize(bytes: number): string {\n if (bytes === 0) return '0 B'\n let units = ['B', 'kB', 'MB', 'GB', 'TB']\n let i = Math.floor(Math.log(bytes) / Math.log(1024))\n let size = bytes / Math.pow(1024, i)\n return size.toFixed(i === 0 ? 0 : 1) + ' ' + units[i]\n}\n" }, { "path": "packages/static-middleware/src/lib/static.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport * as fs from 'node:fs'\nimport * as os from 'node:os'\nimport * as path from 'node:path'\nimport { describe, it, beforeEach, afterEach } from 'node:test'\n\nimport { createRouter } from '@remix-run/fetch-router'\nimport { formData } from '@remix-run/form-data-middleware'\nimport { methodOverride } from '@remix-run/method-override-middleware'\n\nimport { staticFiles } from './static.ts'\n\ndescribe('staticFiles middleware', () => {\n let tmpDir: string\n beforeEach(() => {\n tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'static-middleware-test-'))\n })\n\n afterEach(() => {\n fs.rmSync(tmpDir, { recursive: true, force: true })\n })\n\n function createTestFile(filename: string, content: string, date?: Date) {\n let filePath = path.join(tmpDir, filename)\n let dir = path.dirname(filePath)\n\n if (!fs.existsSync(dir)) {\n fs.mkdirSync(dir, { recursive: true })\n }\n\n fs.writeFileSync(filePath, content)\n\n if (date) {\n fs.utimesSync(filePath, date, date)\n }\n\n return filePath\n }\n\n describe('basic functionality', () => {\n it('serves a file', async () => {\n createTestFile('test.txt', 'Hello, World!')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Content-Type'), 'text/plain; charset=utf-8')\n })\n\n it('serves a file with HEAD request', async () => {\n createTestFile('test.txt', 'Hello, World!')\n\n let router = createRouter()\n router.head('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt', { method: 'HEAD' })\n\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '')\n assert.equal(response.headers.get('Content-Type'), 'text/plain; charset=utf-8')\n })\n\n it('serves files from nested directories', async () => {\n createTestFile('dir/subdir/file.txt', 'Nested file')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/dir/subdir/file.txt')\n\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Nested file')\n })\n\n it('falls through to handler for non-existent file', async () => {\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Custom Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/nonexistent.txt')\n\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Custom Fallback Handler')\n })\n\n it('falls through to handler when requesting a directory', async () => {\n let dirPath = path.join(tmpDir, 'subdir')\n fs.mkdirSync(dirPath)\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir')\n\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Fallback Handler')\n })\n })\n\n it('supports etag by default', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n let etag = response.headers.get('ETag')\n assert.ok(etag)\n assert.equal(etag, 'W/\"13-1735689600000\"')\n\n let response2 = await router.fetch('https://remix.run/test.txt', {\n headers: { 'If-None-Match': etag },\n })\n assert.equal(response2.status, 304)\n assert.equal(await response2.text(), '')\n })\n\n it('does not send etag if etag is disabled', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { etag: false })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('ETag'), null)\n })\n\n it('supports last-modified by default', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Last-Modified'), lastModified.toUTCString())\n })\n\n it('does not send last-modified if lastModified is disabled', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { lastModified: false })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Last-Modified'), null)\n })\n\n it('does not support accept-ranges by default for compressible files', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Accept-Ranges'), null)\n\n let response2 = await router.fetch('https://remix.run/test.txt', {\n headers: { Range: 'bytes=0-4' },\n })\n assert.equal(response2.status, 200)\n assert.equal(await response2.text(), 'Hello, World!')\n })\n\n it('supports range requests when acceptRanges is explicitly enabled', async () => {\n let lastModified = new Date('2025-01-01')\n createTestFile('test.txt', 'Hello, World!', lastModified)\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { acceptRanges: true })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Accept-Ranges'), 'bytes')\n\n let response2 = await router.fetch('https://remix.run/test.txt', {\n headers: { Range: 'bytes=0-4' },\n })\n assert.equal(response2.status, 206)\n assert.equal(await response2.text(), 'Hello')\n assert.equal(response2.headers.get('Content-Range'), 'bytes 0-4/13')\n assert.equal(response2.headers.get('Content-Length'), '5')\n assert.equal(response2.headers.get('Accept-Ranges'), 'bytes')\n })\n\n it('supports range requests with acceptRanges function', async () => {\n createTestFile('test.txt', 'Hello, World!')\n createTestFile('video.dat', 'fake video data')\n let router = createRouter()\n router.get('/*', {\n middleware: [\n staticFiles(tmpDir, {\n acceptRanges: (file) => file.type.startsWith('video/'),\n }),\n ],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n // test.txt should not have ranges (text/plain doesn't match video/* filter)\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Accept-Ranges'), null)\n\n let response2 = await router.fetch('https://remix.run/test.txt', {\n headers: { Range: 'bytes=0-4' },\n })\n assert.equal(response2.status, 200)\n assert.equal(await response2.text(), 'Hello, World!')\n })\n\n it('supports cache-control', async () => {\n createTestFile('test.txt', 'Hello, World!')\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { cacheControl: 'public, max-age=3600' })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt')\n assert.equal(response.headers.get('Cache-Control'), 'public, max-age=3600')\n })\n\n it('works with multiple static middleware instances', async () => {\n createTestFile('assets/style.css', 'body {}')\n createTestFile('images/logo.png', 'PNG data')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response1 = await router.fetch('https://remix.run/assets/style.css')\n assert.equal(response1.status, 200)\n assert.equal(await response1.text(), 'body {}')\n\n let response2 = await router.fetch('https://remix.run/images/logo.png')\n assert.equal(response2.status, 200)\n assert.equal(await response2.text(), 'PNG data')\n })\n\n it('works as fallback middleware', async () => {\n createTestFile('index.html', '

    Fallback Handler

    ')\n\n let router = createRouter()\n router.get('/api/users', () => new Response('Users API'))\n router.get('*path', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response1 = await router.fetch('https://remix.run/api/users')\n assert.equal(await response1.text(), 'Users API')\n\n let response2 = await router.fetch('https://remix.run/index.html')\n assert.equal(await response2.text(), '

    Fallback Handler

    ')\n })\n\n for (let method of ['POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'] as const) {\n it(`ignores ${method} requests`, async () => {\n createTestFile('test.txt', 'Hello, World!')\n\n let router = createRouter()\n router.route(method, '/*path', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/test.txt', { method })\n\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Fallback Handler')\n })\n }\n\n it('prevents path traversal with .. in pathname', async () => {\n createTestFile('secret.txt', 'Secret content')\n\n let publicDirName = 'public'\n createTestFile(`${publicDirName}/allowed.txt`, 'Allowed content')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(path.join(tmpDir, publicDirName))],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let allowedResponse = await router.fetch('https://remix.run/allowed.txt')\n assert.equal(allowedResponse.status, 200)\n assert.equal(await allowedResponse.text(), 'Allowed content')\n\n let traversalResponse = await router.fetch('https://remix.run/../secret.txt')\n assert.equal(traversalResponse.status, 404)\n })\n\n it('does not support absolute paths in the URL', async () => {\n let parentDir = path.dirname(tmpDir)\n let secretFileName = 'secret-outside-root.txt'\n let secretPath = path.join(parentDir, secretFileName)\n fs.writeFileSync(secretPath, 'Secret content')\n\n let router = createRouter()\n router.get('*path', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n try {\n let response = await router.fetch(`https://remix.run/${secretPath}`)\n assert.equal(response.status, 404)\n } finally {\n fs.unlinkSync(secretPath)\n }\n })\n\n describe('filter option', () => {\n it('filters files based on custom filter function', async () => {\n createTestFile('index.html', '

    Home

    ')\n createTestFile('secret.txt', 'Secret')\n createTestFile('public.txt', 'Public')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [\n staticFiles(tmpDir, {\n filter: (path) => !path.includes('secret'),\n }),\n ],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let secretResponse = await router.fetch('https://remix.run/secret.txt')\n assert.equal(secretResponse.status, 404)\n assert.equal(await secretResponse.text(), 'Fallback Handler')\n\n let publicResponse = await router.fetch('https://remix.run/public.txt')\n assert.equal(publicResponse.status, 200)\n assert.equal(await publicResponse.text(), 'Public')\n })\n })\n\n describe('index option', () => {\n it('serves default index.html when requesting a directory', async () => {\n createTestFile('subdir/index.html', '

    Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Index Page

    ')\n assert.equal(response.headers.get('Content-Type'), 'text/html; charset=utf-8')\n })\n\n it('serves default index.html when requesting a directory without trailing slash', async () => {\n createTestFile('subdir/index.html', '

    Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Index Page

    ')\n assert.equal(response.headers.get('Content-Type'), 'text/html; charset=utf-8')\n })\n\n it('serves default index.htm when index.html does not exist', async () => {\n createTestFile('subdir/index.htm', '

    HTM Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    HTM Index Page

    ')\n assert.equal(response.headers.get('Content-Type'), 'text/html; charset=utf-8')\n })\n\n it('prefers index.html over index.htm when both exist', async () => {\n createTestFile('subdir/index.html', '

    HTML Index

    ')\n createTestFile('subdir/index.htm', '

    HTM Index

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    HTML Index

    ')\n })\n\n it('falls through when directory has no index file', async () => {\n let dirPath = path.join(tmpDir, 'subdir')\n fs.mkdirSync(dirPath)\n createTestFile('subdir/other.txt', 'Not an index file')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Fallback Handler')\n })\n\n it('serves custom index file when specified', async () => {\n createTestFile('subdir/default.html', '

    Custom Default Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { index: ['default.html'] })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Custom Default Page

    ')\n })\n\n it('tries custom index files in order', async () => {\n createTestFile('subdir/home.html', '

    Home Page

    ')\n createTestFile('subdir/default.html', '

    Default Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { index: ['index.html', 'home.html', 'default.html'] })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Home Page

    ')\n })\n\n it('serves root directory index file', async () => {\n createTestFile('index.html', '

    Root Index

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Root Index

    ')\n })\n\n it('supports empty index array to disable index file serving', async () => {\n createTestFile('subdir/index.html', '

    Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { index: [] })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Fallback Handler')\n })\n\n it('supports index: false to disable index file serving', async () => {\n createTestFile('subdir/index.html', '

    Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { index: false })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 404)\n assert.equal(await response.text(), 'Fallback Handler')\n })\n\n it('supports index: true to use default index files', async () => {\n createTestFile('subdir/index.html', '

    Index Page

    ')\n\n let router = createRouter()\n router.get('/*', {\n middleware: [staticFiles(tmpDir, { index: true })],\n action() {\n return new Response('Fallback Handler', { status: 404 })\n },\n })\n\n let response = await router.fetch('https://remix.run/subdir/')\n assert.equal(response.status, 200)\n assert.equal(await response.text(), '

    Index Page

    ')\n })\n })\n\n describe('works with method-override middleware', () => {\n it('ignores overridden POST requests', async () => {\n createTestFile('test.txt', 'Hello, World!')\n\n let router = createRouter({\n middleware: [formData(), methodOverride()],\n })\n router.post('/*path', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('POST handler called', { status: 200 })\n },\n })\n\n let formDataPayload = new FormData()\n formDataPayload.append('_method', 'POST')\n formDataPayload.append('name', 'test')\n\n let response = await router.fetch('https://remix.run/test.txt', {\n method: 'POST',\n body: formDataPayload,\n })\n\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'POST handler called')\n })\n\n it('serves files with overridden GET requests', async () => {\n createTestFile('test.txt', 'Hello, World!')\n\n let router = createRouter({\n middleware: [formData(), methodOverride()],\n })\n router.get('/*path', {\n middleware: [staticFiles(tmpDir)],\n action() {\n return new Response('GET handler fallback', { status: 404 })\n },\n })\n\n let formDataPayload = new FormData()\n formDataPayload.append('_method', 'GET')\n\n let response = await router.fetch('https://remix.run/test.txt', {\n method: 'POST',\n body: formDataPayload,\n })\n\n assert.equal(response.status, 200)\n assert.equal(await response.text(), 'Hello, World!')\n assert.equal(response.headers.get('Content-Type'), 'text/plain; charset=utf-8')\n })\n })\n})\n" }, { "path": "packages/static-middleware/src/lib/static.ts", "content": "import * as path from 'node:path'\nimport * as fsp from 'node:fs/promises'\nimport { openLazyFile } from '@remix-run/fs'\nimport type { Middleware } from '@remix-run/fetch-router'\nimport { createFileResponse as sendFile, type FileResponseOptions } from '@remix-run/response/file'\n\nimport { generateDirectoryListing } from './directory-listing.ts'\n\n/**\n * Function that determines if HTTP Range requests should be supported for a given file.\n *\n * @param file The File object being served\n * @returns true if range requests should be supported\n */\nexport type AcceptRangesFunction = (file: File) => boolean\n\n/**\n * Options for the {@link staticFiles} middleware in addition to {@link FileResponseOptions}.\n */\nexport interface StaticFilesOptions extends Omit {\n /**\n * Filter function to determine which files should be served.\n *\n * @param path The relative path being requested\n * @returns Whether to serve the file\n */\n filter?: (path: string) => boolean\n\n /**\n * Whether to support HTTP Range requests for partial content.\n *\n * Can be a boolean or a function that receives the file.\n * When enabled, includes Accept-Ranges header and handles Range requests\n * with 206 Partial Content responses.\n *\n * Defaults to enabling ranges only for non-compressible MIME types,\n * as defined by `isCompressibleMimeType()` from `@remix-run/mime`.\n *\n * Note: Range requests and compression are mutually exclusive. When\n * `Accept-Ranges: bytes` is present in the response headers, the compression\n * middleware will not compress the response. This is why the default behavior\n * enables ranges only for non-compressible types.\n *\n * @example\n * // Force range request support for all files\n * acceptRanges: true\n *\n * @example\n * // Enable ranges for videos only\n * acceptRanges: (file) => file.type.startsWith('video/')\n */\n acceptRanges?: boolean | AcceptRangesFunction\n\n /**\n * Files to try and serve as the index file when the request path targets a directory.\n *\n * - `true`: Use default index files `['index.html', 'index.htm']`\n * - `false`: Disable index file serving\n * - `string[]`: Custom list of index files to try in order\n *\n * @default true\n */\n index?: boolean | string[]\n /**\n * Whether to return an HTML page listing the files in a directory when the request path\n * targets a directory. If both this and `index` are set, `index` takes precedence.\n *\n * @default false\n */\n listFiles?: boolean\n}\n\n/**\n * Creates a middleware that serves static files from the filesystem.\n *\n * Uses the URL pathname to resolve files, removing the leading slash to make it a relative path.\n * The middleware always falls through to the handler if the file is not found or an error occurs.\n *\n * @param root The root directory to serve files from (absolute or relative to cwd)\n * @param options Configuration for file responses\n * @returns The static files middleware\n */\nexport function staticFiles(root: string, options: StaticFilesOptions = {}): Middleware {\n // Ensure root is an absolute path\n root = path.resolve(root)\n\n let { acceptRanges, filter, index: indexOption, listFiles, ...fileOptions } = options\n\n // Normalize index option\n let index: string[]\n if (indexOption === false) {\n index = []\n } else if (indexOption === true || indexOption === undefined) {\n index = ['index.html', 'index.htm']\n } else {\n index = indexOption\n }\n\n return async (context, next) => {\n if (context.method !== 'GET' && context.method !== 'HEAD') {\n return next()\n }\n\n let relativePath = context.url.pathname.replace(/^\\/+/, '')\n\n if (filter && !filter(relativePath)) {\n return next()\n }\n\n let targetPath = path.join(root, relativePath)\n let filePath: string | undefined\n\n try {\n let stats = await fsp.stat(targetPath)\n\n if (stats.isFile()) {\n filePath = targetPath\n } else if (stats.isDirectory()) {\n // Try each index file in turn\n for (let indexFile of index) {\n let indexPath = path.join(targetPath, indexFile)\n try {\n let indexStats = await fsp.stat(indexPath)\n if (indexStats.isFile()) {\n filePath = indexPath\n break\n }\n } catch {\n // Index file doesn't exist, continue to next\n }\n }\n\n // If no index file found and listFiles is enabled, show directory listing\n if (!filePath && listFiles) {\n return generateDirectoryListing(targetPath, context.url.pathname)\n }\n }\n } catch {\n // Path doesn't exist or isn't accessible, fall through\n }\n\n if (filePath) {\n let fileName = path.relative(root, filePath)\n let lazyFile = openLazyFile(filePath, { name: fileName })\n\n let finalFileOptions: FileResponseOptions = { ...fileOptions }\n\n // If acceptRanges is a function, evaluate it with the lazyFile\n // Otherwise, pass it directly to sendFile\n if (typeof acceptRanges === 'function') {\n finalFileOptions.acceptRanges = acceptRanges(lazyFile)\n } else if (acceptRanges !== undefined) {\n finalFileOptions.acceptRanges = acceptRanges\n }\n\n return sendFile(lazyFile, context.request, finalFileOptions)\n }\n\n return next()\n }\n}\n" }, { "path": "packages/static-middleware/tsconfig.build.json", "content": "{\n \"extends\": \"./tsconfig.json\",\n \"compilerOptions\": {\n \"declaration\": true,\n \"declarationMap\": true,\n \"outDir\": \"./dist\"\n },\n \"include\": [\"global.d.ts\", \"src\"],\n \"exclude\": [\"src/**/*.test.ts\", \"dist\"]\n}\n" }, { "path": "packages/static-middleware/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "packages/tar-parser/.changes/README.md", "content": "# Changes Directory\n\nSee the [Contributing Guide](../../../CONTRIBUTING.md#adding-a-change-file) for documentation on how to add change files.\n" }, { "path": "packages/tar-parser/CHANGELOG.md", "content": "# `tar-parser` CHANGELOG\n\nThis is the changelog for [`tar-parser`](https://github.com/remix-run/remix/tree/main/packages/tar-parser). It follows [semantic versioning](https://semver.org/).\n\n## v0.7.0 (2025-11-20)\n\n- Update dev dependencies to use `@remix-run/fs` instead of `@remix-run/lazy-file/fs`.\n\n## v0.6.0 (2025-11-04)\n\n- Build using `tsc` instead of `esbuild`. This means modules in the `dist` directory now mirror the layout of modules in the `src` directory.\n\n## v0.5.0 (2025-10-22)\n\n- BREAKING CHANGE: Removed CommonJS build. This package is now ESM-only. If you need to use this package in a CommonJS project, you will need to use dynamic `import()`.\n\n## v0.4.0 (2025-07-24)\n\n- Renamed package from `@mjackson/tar-parser` to `@remix-run/tar-parser`\n\n## v0.3.0 (2025-06-06)\n\n- Add `/src` to npm package, so \"go to definition\" goes to the actual source\n- Use one set of types for all built files, instead of separate types for ESM and CJS\n- Build using esbuild directly instead of tsup\n\n## v0.2.2 (2025-02-04)\n\n- Add `Promise` to `TarEntryHandler` return type\n\n## v0.2.1 (2025-01-24)\n\n- Add support for environments that do not support `ReadableStream.prototype[Symbol.asyncIterator]` (i.e. Safari), see #46\n\n## v0.2.0 (2025-01-07)\n\n- Fix a bug that hangs the process when trying to read zero-length entries.\n\n## v0.1.0 (2024-12-06)\n\n- Initial release\n" }, { "path": "packages/tar-parser/LICENSE", "content": "MIT License\n\nCopyright (c) 2025 Shopify Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n" }, { "path": "packages/tar-parser/README.md", "content": "# tar-parser\n\nStreaming [tar archive]() parsing for JavaScript. `tar-parser` handles POSIX/GNU/PAX archives incrementally so large tar files can be processed without buffering the full payload.\n\n## Features\n\n- **Universal Runtime** - Runs anywhere JavaScript runs\n- **Web Streams** - Built on the standard [web Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API), so it's composable with `fetch()` streams\n- **Format Support** - Supports POSIX, GNU, and PAX tar formats\n- **Memory Efficient** - Does not buffer anything in normal usage\n- **Zero Dependencies** - No external dependencies\n\n## Installation\n\n```sh\nnpm i remix\n```\n\n## Usage\n\nThe main parser interface is the `parseTar(archive, handler)` function:\n\n```ts\nimport { parseTar } from 'remix/tar-parser'\n\nlet response = await fetch('https://github.com/remix-run/remix/archive/refs/heads/main.tar.gz')\n\nawait parseTar(response.body.pipeThrough(new DecompressionStream('gzip')), (entry) => {\n console.log(entry.name, entry.size)\n})\n```\n\nIf you're parsing an archive with filename encodings other than UTF-8, use the `filenameEncoding` option:\n\n```ts\nlet response = await fetch(/* ... */)\n\nawait parseTar(response.body, { filenameEncoding: 'latin1' }, (entry) => {\n console.log(entry.name, entry.size)\n})\n```\n\n## Benchmark\n\n`tar-parser` performs on par with other popular tar parsing libraries on Node.js.\n\n```\n> @remix-run/tar-parser@0.0.0 bench /Users/michael/Projects/remix-the-web/packages/tar-parser\n> node ./bench/runner.ts\n\nPlatform: Darwin (24.0.0)\nCPU: Apple M1 Pro\nDate: 12/6/2024, 11:00:55 AM\nNode.js v22.8.0\n┌────────────┬────────────────────┐\n│ (index) │ lodash npm package │\n├────────────┼────────────────────┤\n│ tar-parser │ '6.23 ms ± 0.58' │\n│ tar-stream │ '6.72 ms ± 2.24' │\n│ node-tar │ '6.49 ms ± 0.44' │\n└────────────┴────────────────────┘\n```\n\n## Related Packages\n\n- [`multipart-parser`](https://github.com/remix-run/remix/tree/main/packages/multipart-parser) - Fast, streaming multipart parser for JavaScript\n\n## Credits\n\n`tar-parser` is based on the excellent [tar-stream package](https://www.npmjs.com/package/tar-stream) (MIT license) and adopts the same core parsing algorithm, utility functions, and many test cases.\n\n## License\n\nSee [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)\n" }, { "path": "packages/tar-parser/bench/package.json", "content": "{\n \"name\": \"tar-parser-bench\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@remix-run/fs\": \"workspace:^\",\n \"@remix-run/tar-parser\": \"workspace:^\",\n \"gunzip-maybe\": \"^1.4.2\",\n \"tar\": \"^7.4.3\",\n \"tar-stream\": \"^3.1.7\"\n },\n \"devDependencies\": {\n \"@types/gunzip-maybe\": \"^1.4.2\",\n \"@types/tar\": \"^6.1.13\",\n \"@types/tar-stream\": \"^3.1.3\"\n }\n}\n" }, { "path": "packages/tar-parser/bench/parsers/node-tar.ts", "content": "import * as fs from 'node:fs'\nimport * as tar from 'tar'\n\nexport async function parse(filename: string): Promise {\n let stream = fs.createReadStream(filename)\n\n let start = performance.now()\n\n await new Promise((resolve, reject) => {\n stream\n .pipe(tar.t())\n .on('entry', (entry) => {\n entry.resume()\n })\n .on('finish', () => {\n resolve()\n })\n })\n\n return performance.now() - start\n}\n" }, { "path": "packages/tar-parser/bench/parsers/tar-parser.ts", "content": "import { parseTar } from '@remix-run/tar-parser'\nimport { openLazyFile } from '@remix-run/fs'\n\nexport async function parse(filename: string): Promise {\n let stream = openLazyFile(filename).stream().pipeThrough(new DecompressionStream('gzip'))\n\n let start = performance.now()\n\n await parseTar(stream, (_entry) => {\n // Do nothing\n })\n\n return performance.now() - start\n}\n" }, { "path": "packages/tar-parser/bench/parsers/tar-stream.ts", "content": "import * as fs from 'node:fs'\nimport gunzip from 'gunzip-maybe'\nimport tar from 'tar-stream'\n\nexport async function parse(filename: string): Promise {\n let stream = fs.createReadStream(filename).pipe(gunzip())\n\n let start = performance.now()\n\n await new Promise((resolve, reject) => {\n let extract = tar.extract()\n\n extract.on('error', reject)\n\n extract.on('entry', function (_header, stream, next) {\n stream.on('end', function () {\n next() // ready for next entry\n })\n\n stream.resume() // just auto drain the stream\n })\n\n extract.on('finish', function () {\n resolve()\n })\n\n stream.pipe(extract)\n })\n\n return performance.now() - start\n}\n" }, { "path": "packages/tar-parser/bench/runner.ts", "content": "import * as os from 'node:os'\nimport * as process from 'node:process'\n\nimport { fixtures } from '../test/utils.ts'\n\nimport * as nodeTar from './parsers/node-tar.ts'\nimport * as tarParser from './parsers/tar-parser.ts'\nimport * as tarStream from './parsers/tar-stream.ts'\n\nconst benchmarks = [{ name: 'lodash npm package', filename: fixtures.lodashNpmPackage }]\n\ninterface Parser {\n parse(filename: string): Promise\n}\n\nasync function runParserBenchmarks(\n parser: Parser,\n times = 1000,\n): Promise {\n let results: BenchmarkResults[string] = {}\n\n for (let benchmark of benchmarks) {\n let measurements: number[] = []\n for (let i = 0; i < times; ++i) {\n measurements.push(await parser.parse(benchmark.filename))\n }\n\n results[benchmark.name] = getMeanAndStdDev(measurements)\n }\n\n return results\n}\n\nfunction getMeanAndStdDev(measurements: number[]): string {\n let mean = measurements.reduce((a, b) => a + b, 0) / measurements.length\n let variance = measurements.reduce((a, b) => a + (b - mean) ** 2, 0) / measurements.length\n let stdDev = Math.sqrt(variance)\n return mean.toFixed(2) + ' ms ± ' + stdDev.toFixed(2)\n}\n\ninterface BenchmarkResults {\n [parserName: string]: {\n [benchmarkName: string]: string\n }\n}\n\nasync function runBenchmarks(parserName?: string): Promise {\n let results: BenchmarkResults = {}\n\n if (parserName === 'tar-parser' || parserName === undefined) {\n results['tar-parser'] = await runParserBenchmarks(tarParser)\n }\n if (parserName === 'tar-stream' || parserName === undefined) {\n results['tar-stream'] = await runParserBenchmarks(tarStream)\n }\n if (parserName === 'node-tar' || parserName === undefined) {\n results['node-tar'] = await runParserBenchmarks(nodeTar)\n }\n\n return results\n}\n\nfunction printResults(results: BenchmarkResults) {\n console.log(`Platform: ${os.type()} (${os.release()})`)\n console.log(`CPU: ${os.cpus()[0].model}`)\n console.log(`Date: ${new Date().toLocaleString()}`)\n console.log(`Node.js ${process.version}`)\n\n console.table(results)\n}\n\nrunBenchmarks(process.argv[2]).then(printResults, (error) => {\n console.error(error)\n process.exit(1)\n})\n" }, { "path": "packages/tar-parser/package.json", "content": "{\n \"name\": \"@remix-run/tar-parser\",\n \"version\": \"0.7.0\",\n \"description\": \"A fast, efficient parser for tar streams in any JavaScript environment\",\n \"author\": \"Michael Jackson \",\n \"license\": \"MIT\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"git+https://github.com/remix-run/remix.git\",\n \"directory\": \"packages/tar-parser\"\n },\n \"homepage\": \"https://github.com/remix-run/remix/tree/main/packages/tar-parser#readme\",\n \"files\": [\n \"LICENSE\",\n \"README.md\",\n \"dist\",\n \"src\",\n \"!src/**/*.test.ts\"\n ],\n \"type\": \"module\",\n \"exports\": {\n \".\": \"./src/index.ts\",\n \"./package.json\": \"./package.json\"\n },\n \"publishConfig\": {\n \"exports\": {\n \".\": {\n \"types\": \"./dist/index.d.ts\",\n \"default\": \"./dist/index.js\"\n },\n \"./package.json\": \"./package.json\"\n }\n },\n \"devDependencies\": {\n \"@remix-run/fs\": \"workspace:*\",\n \"@types/node\": \"catalog:\",\n \"@typescript/native-preview\": \"catalog:\"\n },\n \"scripts\": {\n \"bench\": \"node ./bench/runner.ts\",\n \"build\": \"tsgo -p tsconfig.build.json\",\n \"clean\": \"git clean -fdX\",\n \"prepublishOnly\": \"pnpm run build\",\n \"test\": \"node --test\",\n \"typecheck\": \"tsgo --noEmit\"\n },\n \"keywords\": [\n \"tar\",\n \"archive\",\n \"parser\",\n \"stream\"\n ]\n}\n" }, { "path": "packages/tar-parser/src/globals.ts", "content": "// This file provides global type augmentation for ReadableStream async iteration.\n// See https://github.com/DefinitelyTyped/DefinitelyTyped/discussions/62651\n\ndeclare global {\n interface ReadableStream {\n values(options?: { preventCancel?: boolean }): AsyncIterableIterator\n [Symbol.asyncIterator](): AsyncIterableIterator\n }\n}\n\nexport {}\n" }, { "path": "packages/tar-parser/src/index.ts", "content": "import './globals.ts'\n\nexport {\n TarParseError,\n type TarHeader,\n type ParseTarHeaderOptions,\n parseTarHeader,\n type ParseTarOptions,\n parseTar,\n type TarParserOptions,\n TarParser,\n TarEntry,\n} from './lib/tar.ts'\n" }, { "path": "packages/tar-parser/src/lib/read-stream.ts", "content": "// We need this little helper for environments that do not support\n// ReadableStream.prototype[Symbol.asyncIterator] yet. See #46\nexport async function* readStream(stream: ReadableStream): AsyncIterable {\n let reader = stream.getReader()\n\n while (true) {\n let result = await reader.read()\n if (result.done) break\n yield result.value\n }\n}\n" }, { "path": "packages/tar-parser/src/lib/tar.test.ts", "content": "import * as assert from 'node:assert/strict'\nimport { describe, it } from 'node:test'\n\nimport { fixtures, readFixture } from '../../test/utils.ts'\n\nimport { type TarHeader, parseTar } from './tar.ts'\n\nasync function bufferBytes(stream: ReadableStream): Promise> {\n let chunks: Uint8Array[] = []\n let length = 0\n\n for await (let chunk of stream) {\n chunks.push(chunk)\n length += chunk.byteLength\n }\n\n let result = new Uint8Array(length)\n let offset = 0\n\n for (let chunk of chunks) {\n result.set(chunk, offset)\n offset += chunk.byteLength\n }\n\n return result\n}\n\nasync function bufferString(\n stream: ReadableStream,\n encoding = 'utf-8',\n): Promise {\n let decoder = new TextDecoder(encoding)\n let string = ''\n\n for await (let chunk of stream) {\n string += decoder.decode(chunk, { stream: true })\n }\n\n string += decoder.decode()\n\n return string\n}\n\nasync function computeHash(\n buffer: Uint8Array,\n algorithm = 'SHA-256',\n): Promise {\n let digest = await crypto.subtle.digest(algorithm, buffer)\n return Array.from(new Uint8Array(digest))\n .map((byte) => byte.toString(16).padStart(2, '0'))\n .join('')\n .slice(0, 8)\n}\n\ndescribe('TarParser', () => {\n it('parses express-4.21.1.tgz', async () => {\n let entries: Record = {}\n await parseTar(readFixture(fixtures.expressNpmPackage), async (entry) => {\n let hash = await computeHash(await bufferBytes(entry.body))\n entries[entry.name] = hash\n })\n\n assert.deepEqual(entries, {\n 'package/LICENSE': '95a57628',\n 'package/lib/application.js': '5901b32f',\n 'package/lib/express.js': '2f25585c',\n 'package/index.js': '4d2f5afc',\n 'package/lib/router/index.js': '19c5ca9b',\n 'package/lib/middleware/init.js': '48c1d12f',\n 'package/lib/router/layer.js': 'c90709dc',\n 'package/lib/middleware/query.js': '6edce396',\n 'package/lib/request.js': '64ac1075',\n 'package/lib/response.js': '4b5c338c',\n 'package/lib/router/route.js': '86db1235',\n 'package/lib/utils.js': '9035c6d9',\n 'package/lib/view.js': 'ec627880',\n 'package/package.json': '774eaac2',\n 'package/History.md': 'ca257313',\n 'package/Readme.md': '016f344e',\n })\n })\n\n it('parses fetch-proxy-0.1.0.tar.gz', async () => {\n let count = 0\n await parseTar(readFixture(fixtures.fetchProxyGithubArchive), async (entry) => {\n // Drain the body stream to avoid memory accumulation\n for await (let _ of entry.body) {\n }\n count++\n })\n\n assert.equal(count, 192)\n })\n\n it('parses lodash-4.17.21.tgz', async () => {\n let count = 0\n await parseTar(readFixture(fixtures.lodashNpmPackage), async (entry) => {\n // Drain the body stream to avoid memory accumulation\n for await (let _ of entry.body) {\n }\n count++\n })\n\n assert.equal(count, 1054)\n })\n\n it('parses npm-11.0.0.tgz', async () => {\n let count = 0\n await parseTar(readFixture(fixtures.npmNpmPackage), async (entry) => {\n // Drain the body stream to avoid memory accumulation\n for await (let _ of entry.body) {\n }\n count++\n })\n\n assert.equal(count, 2368)\n })\n})\n\ndescribe('tar-stream test cases', () => {\n it('parses one-file.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.oneFile), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'test.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 12,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'hello world\\n',\n ],\n ])\n })\n\n it('parses multi-file.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.multiFile), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'file-1.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 12,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'i am file-1\\n',\n ],\n [\n {\n name: 'file-2.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 12,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'i am file-2\\n',\n ],\n ])\n })\n\n it('parses pax.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.pax), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'pax.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 12,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: {\n path: 'pax.txt',\n special: 'sauce',\n },\n },\n 'hello world\\n',\n ],\n ])\n })\n\n it('parses types.tar', async () => {\n let headers: TarHeader[] = []\n await parseTar(readFixture(fixtures.types), async (entry) => {\n headers.push(entry.header)\n })\n\n assert.deepEqual(headers, [\n {\n name: 'directory',\n mode: 0o755,\n uid: 501,\n gid: 20,\n size: 0,\n mtime: 1387580181,\n type: 'directory',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n {\n name: 'directory-link',\n mode: 0o755,\n uid: 501,\n gid: 20,\n size: 0,\n mtime: 1387580181,\n type: 'symlink',\n linkname: 'directory',\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n ])\n })\n\n it('parses long-name.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.longName), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'my/file/is/longer/than/100/characters/and/should/use/the/prefix/header/foobarbaz/foobarbaz/foobarbaz/foobarbaz/foobarbaz/foobarbaz/filename.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 16,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'hello long name\\n',\n ],\n ])\n })\n\n it('parses unicode-bsd.tar', async () => {\n let headers: TarHeader[] = []\n await parseTar(readFixture(fixtures.unicodeBsd), async (entry) => {\n headers.push(entry.header)\n })\n\n assert.deepEqual(headers, [\n {\n name: 'høllø.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 4,\n mtime: 1387588646,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: {\n 'SCHILY.dev': '16777217',\n 'SCHILY.ino': '3599143',\n 'SCHILY.nlink': '1',\n atime: '1387589077',\n ctime: '1387588646',\n path: 'høllø.txt',\n },\n },\n ])\n })\n\n it('parses unicode.tar', async () => {\n let headers: TarHeader[] = []\n await parseTar(readFixture(fixtures.unicode), async (entry) => {\n headers.push(entry.header)\n })\n\n assert.deepEqual(headers, [\n {\n name: 'høstål.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 8,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: { path: 'høstål.txt' },\n },\n ])\n })\n\n it('parses name-is-100.tar', async () => {\n let entries: [number, string][] = []\n await parseTar(readFixture(fixtures.nameIs100), async (entry) => {\n entries.push([entry.header.name.length, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [[100, 'hello\\n']])\n })\n\n it('parses space.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.space), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.equal(entries.length, 4)\n })\n\n it('parses gnu-long-path.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.gnuLongPath), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.equal(entries.length, 1)\n })\n\n it('parses base-256-uid-gid.tar', async () => {\n let headers: TarHeader[] = []\n await parseTar(readFixture(fixtures.base256UidGid), async (entry) => {\n headers.push(entry.header)\n })\n\n assert.equal(headers.length, 1)\n assert.equal(headers[0].uid, 116435139)\n assert.equal(headers[0].gid, 1876110778)\n })\n\n it('parses base-256-size.tar', async () => {\n let headers: TarHeader[] = []\n await parseTar(readFixture(fixtures.base256Size), async (entry) => {\n headers.push(entry.header)\n })\n\n assert.deepEqual(headers, [\n {\n name: 'test.txt',\n mode: 0o644,\n uid: 501,\n gid: 20,\n size: 12,\n mtime: 1387580181,\n type: 'file',\n linkname: null,\n uname: 'maf',\n gname: 'staff',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n ])\n })\n\n it('parses latin1.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.latin1), { filenameEncoding: 'latin1' }, async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: \"En français, s'il vous plaît?.txt\",\n mode: 0o644,\n uid: 0,\n gid: 0,\n size: 14,\n mtime: 1495941034,\n type: 'file',\n linkname: null,\n uname: 'root',\n gname: 'root',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'Hello, world!\\n',\n ],\n ])\n })\n\n it('throws when parsing incomplete.tar', async () => {\n await assert.rejects(\n async () => {\n await parseTar(readFixture(fixtures.incomplete), () => {})\n },\n {\n name: 'TarParseError',\n message: 'Unexpected end of archive',\n },\n )\n })\n\n it('parses gnu.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.gnu), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'test.txt',\n mode: 0o644,\n uid: 12345,\n gid: 67890,\n size: 14,\n mtime: 1559239869,\n type: 'file',\n linkname: null,\n uname: 'myuser',\n gname: 'mygroup',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'Hello, world!\\n',\n ],\n ])\n })\n\n it('parses gnu-incremental.tar', async () => {\n let entries: [TarHeader, string][] = []\n await parseTar(readFixture(fixtures.gnuIncremental), async (entry) => {\n entries.push([entry.header, await bufferString(entry.body)])\n })\n\n assert.deepEqual(entries, [\n [\n {\n name: 'test.txt',\n mode: 0o644,\n uid: 12345,\n gid: 67890,\n size: 14,\n mtime: 1559239869,\n type: 'file',\n linkname: null,\n uname: 'myuser',\n gname: 'mygroup',\n devmajor: 0,\n devminor: 0,\n pax: null,\n },\n 'Hello, world!\\n',\n ],\n ])\n })\n})\n" }, { "path": "packages/tar-parser/src/lib/tar.ts", "content": "import { readStream } from './read-stream.ts'\nimport {\n buffersEqual,\n concatChunks,\n computeChecksum,\n decodeLongPath,\n decodePax,\n getOctal,\n getString,\n overflow,\n} from './utils.ts'\n\nconst TarBlockSize = 512\n\n/**\n * An error thrown when parsing a tar archive fails.\n */\nexport class TarParseError extends Error {\n /**\n * @param message The error message\n */\n constructor(message: string) {\n super(message)\n this.name = 'TarParseError'\n }\n}\n\n/**\n * The parsed header of a tar entry.\n */\nexport interface TarHeader {\n /**\n * Entry path stored in the archive.\n */\n name: string\n\n /**\n * File mode parsed from the header, or `null` when unavailable.\n */\n mode: number | null\n\n /**\n * Numeric user ID parsed from the header, or `null` when unavailable.\n */\n uid: number | null\n\n /**\n * Numeric group ID parsed from the header, or `null` when unavailable.\n */\n gid: number | null\n\n /**\n * Entry size in bytes.\n */\n size: number\n\n /**\n * Last modification time parsed from the header, or `null` when unavailable.\n */\n mtime: number | null\n\n /**\n * Normalized entry type such as `file` or `directory`.\n */\n type: string\n\n /**\n * Linked path target for link entries, or `null` when not present.\n */\n linkname: string | null\n\n /**\n * User name parsed from the header.\n */\n uname: string\n\n /**\n * Group name parsed from the header.\n */\n gname: string\n\n /**\n * Major device number for device entries, or `null` when unavailable.\n */\n devmajor: number | null\n\n /**\n * Minor device number for device entries, or `null` when unavailable.\n */\n devminor: number | null\n\n /**\n * Decoded PAX metadata attached to the entry, or `null` when none is present.\n */\n pax: Record | null\n}\n\nconst TarFileTypes: Record = {\n '0': 'file',\n '1': 'link',\n '2': 'symlink',\n '3': 'character-device',\n '4': 'block-device',\n '5': 'directory',\n '6': 'fifo',\n '7': 'contiguous-file',\n '27': 'gnu-long-link-path',\n '28': 'gnu-long-path',\n '30': 'gnu-long-path',\n '55': 'pax-global-header',\n '72': 'pax-header',\n}\n\nconst ZeroOffset = '0'.charCodeAt(0)\nconst UstarMagic = new Uint8Array([0x75, 0x73, 0x74, 0x61, 0x72, 0x00]) // \"ustar\\0\"\nconst UstarVersion = new Uint8Array([ZeroOffset, ZeroOffset]) // \"00\"\nconst GnuMagic = new Uint8Array([0x75, 0x73, 0x74, 0x61, 0x72, 0x20]) // \"ustar \"\nconst GnuVersion = new Uint8Array([0x20, 0x00]) // \" \\0\"\n\n/**\n * Options for parsing tar headers.\n */\nexport interface ParseTarHeaderOptions {\n /**\n * Set `false` to disallow unknown header formats.\n *\n * @default true\n */\n allowUnknownFormat?: boolean\n /**\n * The label (encoding) for filenames.\n *\n * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings)\n *\n * @default 'utf-8'\n */\n filenameEncoding?: string\n}\n\n/**\n * Parses a tar header block.\n *\n * @param block The tar header block\n * @param options Options that control how the header is parsed\n * @returns The parsed tar header\n */\nexport function parseTarHeader(block: Uint8Array, options?: ParseTarHeaderOptions): TarHeader {\n if (block.length !== TarBlockSize) {\n throw new TarParseError('Invalid tar header size')\n }\n\n let allowUnknownFormat = options?.allowUnknownFormat ?? true\n let filenameEncoding = options?.filenameEncoding ?? 'utf-8'\n\n // Tar header format\n // Offset Size Field\n // 0 100 Filename\n // 100 8 File mode (octal)\n // 108 8 Owner's numeric user ID (octal)\n // 116 8 Group's numeric user ID (octal)\n // 124 12 File size in bytes (octal)\n // 136 12 Last modification time (octal)\n // 148 8 Checksum for header block (octal)\n // 156 1 Type flag\n // 157 100 Name of linked file\n // 257 6 Magic string \"ustar\\0\" or \"ustar \"\n // 263 2 Version \"00\" or \" \\0\"\n // 265 32 Owner username\n // 297 32 Owner groupname\n // 329 8 Device major number (octal)\n // 337 8 Device minor number (octal)\n // 345 155 Filename prefix (ustar only)\n\n let checksum = getOctal(block, 148, 8)\n if (checksum !== computeChecksum(block)) {\n throw new TarParseError(\n 'Invalid tar header. Maybe the tar is corrupted or needs to be gunzipped?',\n )\n }\n\n let typeFlag = block[156] === 0 ? 0 : block[156] - ZeroOffset\n let header: TarHeader = {\n name: getString(block, 0, 100, filenameEncoding),\n mode: getOctal(block, 100, 8),\n uid: getOctal(block, 108, 8),\n gid: getOctal(block, 116, 8),\n size: getOctal(block, 124, 12) ?? 0,\n mtime: getOctal(block, 136, 12),\n type: TarFileTypes[typeFlag] ?? 'unknown',\n linkname: block[157] === 0 ? null : getString(block, 157, 100, filenameEncoding),\n uname: getString(block, 265, 32),\n gname: getString(block, 297, 32),\n devmajor: getOctal(block, 329, 8),\n devminor: getOctal(block, 337, 8),\n pax: null,\n }\n\n let magic = block.subarray(257, 263)\n let version = block.subarray(263, 265)\n if (buffersEqual(magic, UstarMagic) && buffersEqual(version, UstarVersion)) {\n // UStar (posix) format\n if (block[345] !== 0) {\n let prefix = getString(block, 345, 155)\n header.name = prefix + '/' + header.name\n }\n } else if (buffersEqual(magic, GnuMagic) && buffersEqual(version, GnuVersion)) {\n // GNU format\n } else if (!allowUnknownFormat) {\n throw new TarParseError('Invalid tar header, unknown format')\n }\n\n return header\n}\n\ntype TarArchiveSource =\n | ReadableStream\n | Uint8Array\n | Iterable\n | AsyncIterable\n\ntype TarEntryHandler = (entry: TarEntry) => void | Promise\n\n/**\n * Options for parsing a tar archive.\n */\nexport type ParseTarOptions = ParseTarHeaderOptions\n\n/**\n * Parse a tar archive and call the given handler for each entry it contains.\n *\n * ```ts\n * import { parseTar } from 'remix/tar-parser';\n *\n * await parseTar(archive, (entry) => {\n * console.log(entry.name);\n * });\n * ```\n *\n * @param archive The tar archive source data\n * @param handler A function to call for each entry in the archive\n * @returns A promise that resolves when the parse is finished\n */\nexport async function parseTar(archive: TarArchiveSource, handler: TarEntryHandler): Promise\nexport async function parseTar(\n archive: TarArchiveSource,\n options: ParseTarOptions,\n handler: TarEntryHandler,\n): Promise\nexport async function parseTar(\n archive: TarArchiveSource,\n options: ParseTarOptions | TarEntryHandler,\n handler?: TarEntryHandler,\n): Promise {\n let opts: ParseTarOptions | undefined\n if (typeof options === 'function') {\n handler = options\n } else {\n opts = options\n }\n\n let parser = new TarParser(opts)\n await parser.parse(archive, handler!)\n}\n\n/**\n * Options for configuring a {@link TarParser}.\n */\nexport type TarParserOptions = ParseTarHeaderOptions\n\n/**\n * A parser for tar archives.\n */\nexport class TarParser {\n #buffer: Uint8Array | null = null\n #missing = 0\n #header: TarHeader | null = null\n #bodyController: ReadableStreamDefaultController | null = null\n #longHeader = false\n #gnuLongPath: string | null = null\n #gnuLongLinkPath: string | null = null\n #paxGlobal: Record | null = null\n #pax: Record | null = null\n\n #options?: TarParserOptions\n\n /**\n * @param options Options that control how the tar archive is parsed\n */\n constructor(options?: TarParserOptions) {\n this.#options = options\n }\n\n /**\n * Parse a stream/buffer tar archive and call the given handler for each entry it contains.\n * Resolves when the parse is finished and all handlers resolve.\n *\n * @param archive The tar archive source data\n * @param handler A function to call for each entry in the archive\n * @returns A promise that resolves when the parse is finished\n */\n async parse(archive: TarArchiveSource, handler: TarEntryHandler): Promise {\n this.#reset()\n\n let results: unknown[] = []\n\n function handleEntry(entry: TarEntry): void {\n results.push(handler(entry))\n }\n\n if (archive instanceof ReadableStream) {\n for await (let chunk of readStream(archive)) {\n this.#write(chunk, handleEntry)\n }\n } else if (isAsyncIterable(archive)) {\n for await (let chunk of archive) {\n this.#write(chunk, handleEntry)\n }\n } else if (archive instanceof Uint8Array) {\n this.#write(archive, handleEntry)\n } else if (isIterable(archive)) {\n for (let chunk of archive) {\n this.#write(chunk, handleEntry)\n }\n } else {\n throw new TypeError('Cannot parse tar archive; expected a stream or buffer')\n }\n\n if (this.#missing !== 0) {\n throw new TarParseError('Unexpected end of archive')\n }\n\n await Promise.all(results)\n }\n\n #reset(): void {\n this.#buffer = null\n this.#missing = 0\n this.#header = null\n this.#bodyController = null\n this.#longHeader = false\n this.#gnuLongPath = null\n this.#gnuLongLinkPath = null\n this.#paxGlobal = null\n this.#pax = null\n }\n\n #write(chunk: Uint8Array, handler: TarEntryHandler): void {\n if (this.#buffer !== null) {\n this.#buffer = concatChunks(this.#buffer, chunk)\n } else {\n this.#buffer = chunk\n }\n\n while (this.#buffer !== null && this.#buffer.length > 0) {\n if (this.#missing > 0) {\n if (this.#bodyController !== null) {\n this.#parseBody()\n continue\n }\n\n if (this.#longHeader) {\n if (this.#missing > this.#buffer.length) break\n this.#parseLongHeader()\n continue\n }\n\n if (this.#missing >= this.#buffer.length) {\n this.#missing -= this.#buffer.length\n this.#buffer = null\n break\n }\n\n this.#buffer = this.#buffer.subarray(this.#missing)\n this.#missing = 0\n }\n\n if (this.#buffer.length < TarBlockSize) break\n this.#parseHeader(handler)\n }\n }\n\n #parseHeader(handler: TarEntryHandler): void {\n let block = this.#read(TarBlockSize)\n\n if (isZeroBlock(block)) {\n this.#header = null\n return\n }\n\n this.#header = parseTarHeader(block, this.#options)\n\n switch (this.#header.type) {\n case 'gnu-long-path':\n case 'gnu-long-link-path':\n case 'pax-global-header':\n case 'pax-header':\n this.#longHeader = true\n this.#missing = this.#header.size\n return\n }\n\n if (this.#gnuLongPath) {\n this.#header.name = this.#gnuLongPath\n this.#gnuLongPath = null\n }\n\n if (this.#gnuLongLinkPath) {\n this.#header.linkname = this.#gnuLongLinkPath\n this.#gnuLongLinkPath = null\n }\n\n if (this.#pax) {\n if (this.#pax.path) this.#header.name = this.#pax.path\n if (this.#pax.linkpath) this.#header.linkname = this.#pax.linkpath\n if (this.#pax.size) this.#header.size = parseInt(this.#pax.size, 10)\n this.#header.pax = this.#pax\n this.#pax = null\n }\n\n if (this.#header.size === 0 || this.#header.type === 'directory') {\n let emptyBody = new ReadableStream({\n start(controller) {\n controller.close()\n },\n })\n\n handler(new TarEntry(this.#header, emptyBody))\n this.#bodyController = null\n this.#missing = 0\n return\n }\n\n let body = new ReadableStream({\n start: (controller) => {\n this.#bodyController = controller\n },\n })\n\n handler(new TarEntry(this.#header, body))\n\n this.#missing = this.#header.size\n }\n\n #parseLongHeader(): void {\n this.#longHeader = false\n\n let buffer = this.#read(this.#header!.size)\n\n switch (this.#header!.type) {\n case 'gnu-long-path':\n this.#gnuLongPath = decodeLongPath(buffer)\n break\n case 'gnu-long-link-path':\n this.#gnuLongLinkPath = decodeLongPath(buffer)\n break\n case 'pax-global-header':\n this.#paxGlobal = decodePax(buffer)\n break\n case 'pax-header':\n this.#pax =\n this.#paxGlobal !== null\n ? Object.assign({}, this.#paxGlobal, decodePax(buffer))\n : decodePax(buffer)\n break\n }\n\n this.#missing = overflow(this.#header!.size)\n }\n\n #parseBody(): void {\n if (this.#missing >= this.#buffer!.length) {\n this.#bodyController!.enqueue(this.#buffer!)\n this.#missing -= this.#buffer!.length\n this.#buffer = null\n } else {\n this.#bodyController!.enqueue(this.#read(this.#missing))\n this.#bodyController!.close()\n this.#bodyController = null\n this.#missing = overflow(this.#header!.size)\n }\n }\n\n #read(size: number): Uint8Array {\n let result = this.#buffer!.subarray(0, size)\n this.#buffer = this.#buffer!.subarray(size)\n return result\n }\n}\n\nfunction isIterable(value: unknown): value is Iterable {\n return typeof value === 'object' && value != null && Symbol.iterator in value\n}\n\nfunction isAsyncIterable(value: unknown): value is AsyncIterable {\n return typeof value === 'object' && value != null && Symbol.asyncIterator in value\n}\n\nfunction isZeroBlock(buffer: Uint8Array): boolean {\n return buffer.every((byte) => byte === 0)\n}\n\n/**\n * An entry in a tar archive.\n */\nexport class TarEntry {\n #header: TarHeader\n #body: ReadableStream\n #bodyUsed = false\n\n /**\n * @param header The header info for this entry\n * @param body The entry's content as a stream\n */\n constructor(header: TarHeader, body: ReadableStream) {\n this.#header = header\n this.#body = body\n }\n\n /**\n * The content of this entry as an [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer).\n *\n * @returns A promise that resolves to an `ArrayBuffer`\n */\n async arrayBuffer(): Promise {\n return (await this.bytes()).buffer as ArrayBuffer\n }\n\n /**\n * The content of this entry as a `ReadableStream`.\n */\n get body(): ReadableStream {\n return this.#body\n }\n\n /**\n * Whether the body of this entry has been consumed.\n */\n get bodyUsed(): boolean {\n return this.#bodyUsed\n }\n\n /**\n * The content of this entry buffered into a single typed array.\n *\n * @returns A promise that resolves to a `Uint8Array`\n */\n async bytes(): Promise {\n if (this.#bodyUsed) {\n throw new Error('Body is already consumed or is being consumed')\n }\n\n this.#bodyUsed = true\n\n let result = new Uint8Array(this.size)\n let offset = 0\n for await (let chunk of readStream(this.#body)) {\n result.set(chunk, offset)\n offset += chunk.length\n }\n\n return result\n }\n\n /**\n * The raw header info associated with this entry.\n */\n get header(): TarHeader {\n return this.#header\n }\n\n /**\n * The name of this entry.\n */\n get name(): string {\n return this.header.name\n }\n\n /**\n * The size of this entry in bytes.\n */\n get size(): number {\n return this.header.size\n }\n\n /**\n * The content of this entry as a string.\n *\n * Note: Do not use this for binary data, use `await entry.bytes()` or stream `entry.body` directly instead.\n *\n * @returns A promise that resolves to the entry's content as a string\n */\n async text(): Promise {\n return new TextDecoder().decode(await this.bytes())\n }\n}\n" }, { "path": "packages/tar-parser/src/lib/utils.ts", "content": "export function buffersEqual(a: Uint8Array, b: Uint8Array): boolean {\n if (a.length !== b.length) return false\n for (let i = 0; i < a.length; i++) {\n if (a[i] !== b[i]) return false\n }\n return true\n}\n\nexport function concatChunks(a: Uint8Array, b: Uint8Array): Uint8Array {\n let result = new Uint8Array(a.length + b.length)\n result.set(a)\n result.set(b, a.length)\n return result\n}\n\nexport function computeChecksum(block: Uint8Array): number {\n let sum = 8 * 32\n for (let i = 0; i < 148; i++) sum += block[i]\n for (let i = 156; i < 512; i++) sum += block[i]\n return sum\n}\n\nexport function decodeLongPath(buffer: Uint8Array): string {\n return Utf8Decoder.decode(buffer)\n}\n\nexport function decodePax(buffer: Uint8Array): Record {\n let pax: Record = {}\n\n while (buffer.length) {\n let i = 0\n while (i < buffer.length && buffer[i] !== 32) i++\n\n let len = parseInt(Utf8Decoder.decode(buffer.subarray(0, i)), 10)\n if (!len) break\n\n let val = Utf8Decoder.decode(buffer.subarray(i + 1, len - 1))\n let eq = val.indexOf('=')\n if (eq === -1) break\n\n pax[val.slice(0, eq)] = val.slice(eq + 1)\n\n buffer = buffer.subarray(len)\n }\n\n return pax\n}\n\nexport function indexOf(buffer: Uint8Array, value: number, offset: number, end: number): number {\n for (; offset < end; offset++) {\n if (buffer[offset] === value) return offset\n }\n return end\n}\n\nexport function getString(buffer: Uint8Array, offset: number, size: number, label = 'utf-8') {\n return new TextDecoder(label).decode(\n buffer.subarray(offset, indexOf(buffer, 0, offset, offset + size)),\n )\n}\n\nconst Utf8Decoder = new TextDecoder()\n\nexport function getOctal(buffer: Uint8Array, offset: number, size: number) {\n let value = buffer.subarray(offset, offset + size)\n offset = 0\n\n if (value[offset] & 0x80) return parse256(value)\n\n // Older versions of tar can prefix with spaces\n while (offset < value.length && value[offset] === 32) offset++\n let end = clamp(indexOf(value, 32, offset, value.length), value.length, value.length)\n while (offset < end && value[offset] === 0) offset++\n if (end === offset) return 0\n\n return parseInt(Utf8Decoder.decode(value.subarray(offset, end)), 8)\n}\n\nfunction clamp(index: number, len: number, defaultValue: number): number {\n if (typeof index !== 'number') return defaultValue\n index = ~~index // Coerce to integer.\n if (index >= len) return len\n if (index >= 0) return index\n index += len\n if (index >= 0) return index\n return 0\n}\n\n/* Copied from the tar-stream repo who copied it from the node-tar repo.\n */\nfunction parse256(buf: Uint8Array): number | null {\n // first byte MUST be either 80 or FF\n // 80 for positive, FF for 2's comp\n let positive\n if (buf[0] === 0x80) positive = true\n else if (buf[0] === 0xff) positive = false\n else return null\n\n // build up a base-256 tuple from the least sig to the highest\n let tuple = []\n let i\n for (i = buf.length - 1; i > 0; i--) {\n let byte = buf[i]\n if (positive) tuple.push(byte)\n else tuple.push(0xff - byte)\n }\n\n let sum = 0\n let len = tuple.length\n for (i = 0; i < len; i++) {\n sum += tuple[i] * Math.pow(256, i)\n }\n\n return positive ? sum : -1 * sum\n}\n\nexport function overflow(size: number): number {\n size &= 511\n return size && 512 - size\n}\n" }, { "path": "packages/tar-parser/test/utils.ts", "content": "import * as path from 'node:path'\nimport { fileURLToPath } from 'node:url'\nimport { openLazyFile } from '@remix-run/fs'\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url))\nconst fixturesDir = path.resolve(__dirname, 'fixtures')\n\nexport const fixtures = {\n base256Size: path.resolve(fixturesDir, 'base-256-size.tar'),\n base256UidGid: path.resolve(fixturesDir, 'base-256-uid-gid.tar'),\n expressNpmPackage: path.resolve(fixturesDir, 'express-4.21.1.tgz'),\n fetchProxyGithubArchive: path.resolve(fixturesDir, 'fetch-proxy-0.1.0.tar.gz'),\n gnuIncremental: path.resolve(fixturesDir, 'gnu-incremental.tar'),\n gnuLongPath: path.resolve(fixturesDir, 'gnu-long-path.tar'),\n gnu: path.resolve(fixturesDir, 'gnu.tar'),\n incomplete: path.resolve(fixturesDir, 'incomplete.tar'),\n latin1: path.resolve(fixturesDir, 'latin1.tar'),\n lodashNpmPackage: path.resolve(fixturesDir, 'lodash-4.17.21.tgz'),\n longName: path.resolve(fixturesDir, 'long-name.tar'),\n multiFile: path.resolve(fixturesDir, 'multi-file.tar'),\n npmNpmPackage: path.resolve(fixturesDir, 'npm-11.0.0.tgz'),\n nameIs100: path.resolve(fixturesDir, 'name-is-100.tar'),\n oneFile: path.resolve(fixturesDir, 'one-file.tar'),\n pax: path.resolve(fixturesDir, 'pax.tar'),\n space: path.resolve(fixturesDir, 'space.tar'),\n types: path.resolve(fixturesDir, 'types.tar'),\n unicodeBsd: path.resolve(fixturesDir, 'unicode-bsd.tar'),\n unicode: path.resolve(fixturesDir, 'unicode.tar'),\n}\n\nexport function readFixture(filename: string): ReadableStream {\n let stream = openLazyFile(filename).stream()\n return filename.endsWith('.tar.gz') || filename.endsWith('.tgz')\n ? stream.pipeThrough(new DecompressionStream('gzip'))\n : stream\n}\n" }, { "path": "packages/tar-parser/tsconfig.build.json", "content": "{\n \"extends\": \"./tsconfig.json\",\n \"compilerOptions\": {\n \"declaration\": true,\n \"declarationMap\": true,\n \"outDir\": \"./dist\"\n },\n \"include\": [\"src\"],\n \"exclude\": [\"src/**/*.test.ts\", \"dist\"]\n}\n" }, { "path": "packages/tar-parser/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"strict\": true,\n \"lib\": [\"ES2024\", \"DOM\", \"DOM.Iterable\"],\n \"module\": \"ES2022\",\n \"moduleResolution\": \"Bundler\",\n \"target\": \"ESNext\",\n \"allowImportingTsExtensions\": true,\n \"rewriteRelativeImportExtensions\": true,\n \"verbatimModuleSyntax\": true\n },\n \"exclude\": [\"bench\", \"dist\"]\n}\n" }, { "path": "pnpm-workspace.yaml", "content": "catalog:\n '@types/node': ^24.6.0\n '@typescript/native-preview': 7.0.0-dev.20251125.1\n playwright: ^1.53.1\n tsx: ^4.20.6\n typescript: ^5.9.3\n\npackages:\n - demos/*\n - docs\n - packages/*\n - packages/fetch-router/demos/*\n - packages/form-data-parser/demos/*\n - packages/component/demos\n - packages/component/bench\n - packages/component/bench/frameworks/*\n - packages/lazy-file/scripts\n - packages/multipart-parser/bench\n - packages/multipart-parser/demos/*\n - packages/node-fetch-server/bench\n - packages/node-fetch-server/demos/*\n - packages/route-pattern/bench\n - packages/static-middleware/demos/*\n - packages/tar-parser/bench\n - scripts\n\nshellEmulator: true\n" }, { "path": "scripts/changes-preview.ts", "content": "import {\n parseAllChangeFiles,\n formatValidationErrors,\n generateChangelogContent,\n generateCommitMessage,\n} from './utils/changes.ts'\nimport { colors, colorize } from './utils/color.ts'\n\n/**\n * Main preview function\n */\nfunction main() {\n let result = parseAllChangeFiles()\n\n if (!result.valid) {\n console.error(colorize('Validation failed', colors.red) + '\\n')\n console.error(formatValidationErrors(result.errors))\n console.error()\n process.exit(1)\n }\n\n let { releases } = result\n\n if (releases.length === 0) {\n console.log('No packages have changes to release.\\n')\n process.exit(0)\n }\n\n console.log(colorize('CHANGES', colors.lightBlue))\n console.log()\n console.log(`${releases.length} package${releases.length === 1 ? '' : 's'} with changes:\\n`)\n\n for (let release of releases) {\n console.log(\n ` • ${release.packageName}: ${release.currentVersion} → ${release.nextVersion} (${release.bump} bump)`,\n )\n for (let change of release.changes) {\n console.log(` - ${change.file}`)\n }\n console.log()\n }\n\n console.log(colorize('CHANGELOG PREVIEW', colors.lightBlue))\n console.log()\n\n for (let release of releases) {\n console.log(colorize(`${release.packageDirName}/CHANGELOG.md:`, colors.gray))\n console.log()\n console.log(generateChangelogContent(release))\n }\n\n console.log(colorize('COMMIT MESSAGE', colors.lightBlue))\n console.log()\n console.log(generateCommitMessage(releases))\n console.log()\n\n console.log(colorize('VERSION COMMAND', colors.lightBlue))\n console.log()\n console.log('pnpm changes:version')\n console.log()\n}\n\nmain()\n" }, { "path": "scripts/changes-validate.ts", "content": "import * as fs from 'node:fs'\nimport { parseAllChangeFiles, formatValidationErrors } from './utils/changes.ts'\nimport { colors, colorize } from './utils/color.ts'\nimport { getAllPackageDirNames, getPackageFile } from './utils/packages.ts'\n\nfunction getMissingChangelogPackageDirNames(): string[] {\n let packageDirNames = getAllPackageDirNames()\n let missing: string[] = []\n\n for (let packageDirName of packageDirNames) {\n let changelogPath = getPackageFile(packageDirName, 'CHANGELOG.md')\n if (!fs.existsSync(changelogPath)) {\n missing.push(packageDirName)\n }\n }\n\n return missing\n}\n\n/**\n * Validates all change files in the repository\n * Exits with code 1 if any validation errors are found\n */\nfunction main() {\n let hasErrors = false\n\n // Validate all packages have changelogs\n console.log('Validating package changelogs...\\n')\n let missingChangelogPackageDirNames = getMissingChangelogPackageDirNames()\n\n if (missingChangelogPackageDirNames.length > 0) {\n hasErrors = true\n console.error(colorize('Missing changelogs', colors.red) + '\\n')\n for (let packageDirName of missingChangelogPackageDirNames) {\n console.error(`📦 ${packageDirName}: Missing CHANGELOG.md file`)\n }\n console.error()\n }\n\n // Validate change files\n console.log('Validating change files...\\n')\n let result = parseAllChangeFiles()\n\n if (!result.valid) {\n hasErrors = true\n console.error(colorize('Invalid change files', colors.red) + '\\n')\n console.error(formatValidationErrors(result.errors))\n console.error()\n } else {\n console.log(colorize('All change files are valid!', colors.lightGreen) + '\\n')\n }\n\n if (hasErrors) {\n process.exit(1)\n }\n}\n\nmain()\n" }, { "path": "scripts/changes-version.ts", "content": "/**\n * Updates package.json versions, CHANGELOG.md files, and creates a release commit.\n *\n * Usage:\n * pnpm changes:version [--no-commit]\n *\n * Options:\n * --no-commit Only update files, don't commit (for manual review)\n */\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\nimport {\n parseAllChangeFiles,\n formatValidationErrors,\n generateChangelogContent,\n generateCommitMessage,\n} from './utils/changes.ts'\nimport { colors, colorize } from './utils/color.ts'\nimport { getPackageFile, getPackagePath } from './utils/packages.ts'\nimport { readJson, writeJson, readFile, writeFile } from './utils/fs.ts'\nimport { logAndExec } from './utils/process.ts'\n\n/**\n * Updates package.json version\n */\nfunction updatePackageJson(packageDirName: string, newVersion: string) {\n let packageJsonPath = getPackageFile(packageDirName, 'package.json')\n let packageJson = readJson(packageJsonPath)\n packageJson.version = newVersion\n writeJson(packageJsonPath, packageJson)\n console.log(` ✓ Updated package.json to ${newVersion}`)\n}\n\n/**\n * Updates CHANGELOG.md with new content\n */\nfunction updateChangelog(packageDirName: string, newContent: string) {\n let changelogPath = getPackageFile(packageDirName, 'CHANGELOG.md')\n let existingChangelog = readFile(changelogPath)\n\n let lines = existingChangelog.split('\\n')\n\n // Find the first ## version entry\n let firstVersionIndex = lines.findIndex((line) => line.startsWith('## '))\n\n let updatedChangelog: string\n if (firstVersionIndex !== -1) {\n // Insert before the first version entry\n lines.splice(firstVersionIndex, 0, newContent)\n updatedChangelog = lines.join('\\n')\n } else {\n // No version entries yet - append to the end\n updatedChangelog = existingChangelog.trimEnd() + '\\n\\n' + newContent + '\\n'\n }\n\n writeFile(changelogPath, updatedChangelog)\n console.log(` ✓ Updated CHANGELOG.md`)\n}\n\n/**\n * Deletes all change files (except README.md)\n */\nfunction deleteChangeFiles(packageDirName: string) {\n let changesDir = path.join(getPackagePath(packageDirName), '.changes')\n let files = fs.readdirSync(changesDir)\n let changeFiles = files.filter((file) => file !== 'README.md' && file.endsWith('.md'))\n\n for (let file of changeFiles) {\n let filePath = path.join(changesDir, file)\n fs.unlinkSync(filePath)\n }\n\n console.log(` ✓ Deleted ${changeFiles.length} change file${changeFiles.length === 1 ? '' : 's'}`)\n}\n\n/**\n * Main version function\n */\nfunction main() {\n let skipCommit = process.argv.includes('--no-commit')\n\n console.log('Validating change files...\\n')\n\n let result = parseAllChangeFiles()\n\n if (!result.valid) {\n console.error(colorize('Validation failed', colors.red) + '\\n')\n console.error(formatValidationErrors(result.errors))\n console.error()\n process.exit(1)\n }\n\n let { releases } = result\n\n if (releases.length === 0) {\n console.log('No packages have changes to release.\\n')\n process.exit(0)\n }\n\n console.log(colorize('Validation passed!', colors.lightGreen) + '\\n')\n console.log('═'.repeat(80))\n console.log(colorize(skipCommit ? 'UPDATING VERSION' : 'PREPARING RELEASE', colors.lightBlue))\n console.log('═'.repeat(80))\n console.log()\n\n // Process each package\n for (let release of releases) {\n console.log(\n colorize(`${release.packageName}:`, colors.gray) +\n ` ${release.currentVersion} → ${release.nextVersion}`,\n )\n\n // Update package.json\n updatePackageJson(release.packageDirName, release.nextVersion)\n\n // Update CHANGELOG.md\n let changelogContent = generateChangelogContent(release)\n updateChangelog(release.packageDirName, changelogContent)\n\n // Delete change files\n deleteChangeFiles(release.packageDirName)\n\n console.log()\n }\n\n if (skipCommit) {\n // Success message for --no-commit\n console.log('═'.repeat(80))\n console.log(colorize('VERSION UPDATED', colors.lightGreen))\n console.log('═'.repeat(80))\n console.log()\n console.log('Files have been updated. Review the changes, then manually commit:')\n console.log()\n console.log('```sh')\n let commitMessage = generateCommitMessage(releases)\n console.log(`git add .`)\n console.log()\n console.log(`git commit -m \"${commitMessage}\"`)\n console.log('```')\n console.log()\n } else {\n // Stage all changes\n console.log('Staging changes...')\n logAndExec('git add .')\n console.log()\n\n // Create commit\n let commitMessage = generateCommitMessage(releases)\n console.log('Creating commit...')\n logAndExec(`git commit -m \"${commitMessage}\"`)\n console.log()\n\n // Success message (skip in CI since the workflow handles the rest)\n if (!process.env.CI) {\n console.log('═'.repeat(80))\n console.log('✅ RELEASE PREPARED')\n console.log('═'.repeat(80))\n console.log()\n console.log('Release commit has been created locally.')\n console.log()\n console.log('To publish, push and the publish workflow will handle the rest:')\n console.log()\n console.log(' git push')\n console.log()\n }\n }\n}\n\nmain()\n" }, { "path": "scripts/detect-changed-packages.ts", "content": "import * as cp from 'node:child_process'\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\n\ntype PackageInfo = {\n dirName: string\n name: string\n dependencies: string[]\n}\n\ntype CliOptions = {\n baseRef: string\n headRef: string\n listOnly: boolean\n}\n\nfunction main() {\n let options = parseArgs(process.argv.slice(2))\n let packageInfos = getPackageInfos()\n let changedPackages = getChangedPackageNames(options.baseRef, options.headRef, packageInfos)\n let selectedPackages = getSelectedPackageNames(changedPackages, packageInfos)\n\n if (options.listOnly) {\n console.log(JSON.stringify(selectedPackages, null, 2))\n return\n }\n\n if (selectedPackages.length === 0) {\n console.log(\n `No package changes detected between ${options.baseRef} and ${options.headRef}. Skipping package tests.`,\n )\n return\n }\n\n console.log(\n `Running tests for packages changed between ${options.baseRef} and ${options.headRef}:`,\n )\n for (let packageName of selectedPackages) {\n console.log(`- ${packageName}`)\n }\n console.log()\n\n let args = selectedPackages.flatMap((packageName) => ['--filter', packageName])\n args.push('run', 'test')\n\n let result = cp.spawnSync('pnpm', args, {\n stdio: 'inherit',\n shell: process.platform === 'win32',\n })\n\n if (result.status !== 0) {\n process.exit(result.status ?? 1)\n }\n}\n\nfunction parseArgs(args: string[]): CliOptions {\n let baseRef = ''\n let headRef = 'HEAD'\n let listOnly = false\n\n for (let arg of args) {\n if (arg === '--list') {\n listOnly = true\n continue\n }\n\n if (baseRef === '') {\n baseRef = arg\n continue\n }\n\n if (headRef === 'HEAD') {\n headRef = arg\n continue\n }\n\n throw new Error(`Unexpected argument: ${arg}`)\n }\n\n if (baseRef === '') {\n throw new Error(\n 'Usage: node ./scripts/detect-changed-packages.ts [head-ref] [--list]',\n )\n }\n\n return { baseRef, headRef, listOnly }\n}\n\nfunction getPackageInfos(): PackageInfo[] {\n let packagesDir = path.join(process.cwd(), 'packages')\n let infos: PackageInfo[] = []\n\n for (let dirName of fs.readdirSync(packagesDir)) {\n let packageJsonPath = path.join(packagesDir, dirName, 'package.json')\n if (!fs.existsSync(packageJsonPath)) {\n continue\n }\n\n let packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as {\n name?: string\n dependencies?: Record\n devDependencies?: Record\n optionalDependencies?: Record\n peerDependencies?: Record\n }\n\n if (typeof packageJson.name !== 'string') {\n continue\n }\n\n let dependencyNames = new Set()\n\n for (let field of [\n packageJson.dependencies,\n packageJson.devDependencies,\n packageJson.optionalDependencies,\n packageJson.peerDependencies,\n ]) {\n for (let dependencyName of Object.keys(field ?? {})) {\n dependencyNames.add(dependencyName)\n }\n }\n\n infos.push({\n dirName,\n name: packageJson.name,\n dependencies: [...dependencyNames],\n })\n }\n\n return infos\n}\n\nfunction getChangedPackageNames(\n baseRef: string,\n headRef: string,\n packageInfos: PackageInfo[],\n): Set {\n let diffOutput = cp.execFileSync(\n 'git',\n ['diff', '--name-only', `${baseRef}...${headRef}`, '--', 'packages/*'],\n { encoding: 'utf8' },\n )\n\n let dirNameToPackageName = new Map(packageInfos.map((info) => [info.dirName, info.name]))\n let changedPackages = new Set()\n\n for (let file of diffOutput.split('\\n')) {\n if (!file.startsWith('packages/')) {\n continue\n }\n\n let [, dirName] = file.split('/', 3)\n let packageName = dirNameToPackageName.get(dirName)\n if (packageName != null) {\n changedPackages.add(packageName)\n }\n }\n\n return changedPackages\n}\n\nfunction getSelectedPackageNames(\n changedPackages: Set,\n packageInfos: PackageInfo[],\n): string[] {\n if (changedPackages.size === 0) {\n return []\n }\n\n let knownPackageNames = new Set(packageInfos.map((info) => info.name))\n let reverseDependencies = new Map>()\n\n for (let info of packageInfos) {\n reverseDependencies.set(info.name, new Set())\n }\n\n for (let info of packageInfos) {\n for (let dependencyName of info.dependencies) {\n if (!knownPackageNames.has(dependencyName)) {\n continue\n }\n\n reverseDependencies.get(dependencyName)?.add(info.name)\n }\n }\n\n let selectedPackages = new Set(changedPackages)\n let queue = [...changedPackages]\n\n while (queue.length > 0) {\n let packageName = queue.shift()\n if (packageName == null) {\n continue\n }\n\n for (let dependentName of reverseDependencies.get(packageName) ?? []) {\n if (selectedPackages.has(dependentName)) {\n continue\n }\n\n selectedPackages.add(dependentName)\n queue.push(dependentName)\n }\n }\n\n return packageInfos\n .map((info) => info.name)\n .filter((packageName) => selectedPackages.has(packageName))\n}\n\nmain()\n" }, { "path": "scripts/generate-remix.ts", "content": "/**\n * Auto-generates the remix umbrella package by:\n * 1. Scanning all @remix-run/* packages in packages/ directory\n * 2. Creating source files that re-export from each package and sub-export\n * 3. Generating exports configuration in package.json\n * 4. Setting up dependencies for all referenced packages\n *\n * Run: node docs/generate-remix.ts\n */\n\nimport fs from 'node:fs/promises'\nimport path from 'node:path'\nimport url from 'node:url'\nimport * as semver from 'semver'\nimport { logAndExec } from './utils/process.ts'\n\nlet __dirname = path.dirname(url.fileURLToPath(import.meta.url))\nlet packagesDir = path.resolve(__dirname, '../packages')\nlet remixDir = path.join(packagesDir, 'remix')\nlet remixChangesDir = path.join(remixDir, '.changes')\nlet remixPackageJsonPath = path.join(remixDir, 'package.json')\n\nconst SOURCE_FOLDER = 'src'\n\ntype RemixRunPackage = {\n name: string\n version: string\n exports: ExportEntry[]\n}\n\ntype ExportEntry = {\n // The source file path relative to src: `headers.ts`, `headers/cookie-storage.ts`\n sourceFile: string\n // The export path in package.json exports: `./headers`, `./headers/cookie-storage`1\n exportPath: string\n // The package/sub-export to re-export from: `@remix-run/headers`, `@remix-run/headers/cookie-storage`\n reExportFrom: string\n}\n\nlet { remixRunPackages, allExports } = await getRemixRunPackages()\nlet remixPackageJson = JSON.parse(await fs.readFile(remixPackageJsonPath, 'utf-8'))\n\n// Track existing exports for comparison\nlet existingExports = new Set(\n Object.keys(remixPackageJson.exports || {}).filter(\n (key) => key !== '.' && key !== './package.json',\n ),\n)\n\n// Update remixPackageJson in place and output to disk\nawait updateRemixPackage()\n\n// Generate change files\nawait outputExportsChangeFiles(remixPackageJson.exports)\n\n// Implementations\nasync function getRemixRunPackages() {\n console.log('Scanning packages...')\n\n // Get all packages except remix itself\n let packageDirNames = (await fs.readdir(packagesDir, { withFileTypes: true }))\n .filter((dirent) => dirent.isDirectory() && dirent.name !== 'remix')\n .map((dirent) => dirent.name)\n\n let remixRunPackages: RemixRunPackage[] = []\n\n // Scan each package for its exports\n for (let packageDirName of packageDirNames) {\n let packageJsonPath = path.join(packagesDir, packageDirName, 'package.json')\n let packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf-8'))\n let packageName = packageJson.name as string\n\n // Skip if not a @remix-run package\n if (!packageName.startsWith('@remix-run/')) {\n continue\n }\n\n let remixRunPackage: RemixRunPackage = {\n name: packageName,\n version: packageJson.version,\n exports: [],\n }\n remixRunPackages.push(remixRunPackage)\n\n let shortName = packageName.replace('@remix-run/', '')\n\n // Get all exports except package.json\n let packageExports = packageJson.exports\n if (packageExports && typeof packageExports === 'object') {\n for (let [exportPath, _] of Object.entries(packageExports)) {\n if (exportPath === './package.json') continue\n\n if (exportPath === '.') {\n // Main export\n remixRunPackage.exports.push({\n sourceFile: `${shortName}.ts`,\n exportPath: `./${shortName}`,\n reExportFrom: packageName,\n })\n } else {\n // Sub-export (e.g., \"./cookie-storage\")\n let subExport = exportPath.replace('./', '')\n remixRunPackage.exports.push({\n sourceFile: `${shortName}/${subExport}.ts`,\n exportPath: `./${shortName}/${subExport}`,\n reExportFrom: `${packageName}/${subExport}`,\n })\n }\n }\n }\n }\n\n // Sort exports by export path for consistent ordering\n let allExports = remixRunPackages.flatMap((pkg) => pkg.exports)\n allExports.sort((a, b) => a.exportPath.localeCompare(b.exportPath))\n\n console.log(\n `Found ${remixRunPackages.length} @remix-run packages with a total of ${allExports.length} exports.`,\n )\n\n return { remixRunPackages, allExports }\n}\n\nasync function updateRemixPackage() {\n // Ensure we have a passing linter before generating code\n logAndExec(`npx eslint packages/remix/ --max-warnings=0`)\n\n // Clear existing source files\n let sourceFolderPath = path.join(remixDir, SOURCE_FOLDER)\n await fs.rm(sourceFolderPath, { recursive: true, force: true })\n await fs.mkdir(sourceFolderPath, { recursive: true })\n\n // Generate fresh source files\n console.log('Generating Remix source files...')\n for (let entry of allExports) {\n let sourceFilePath = path.join(remixDir, SOURCE_FOLDER, entry.sourceFile)\n // Create subdirectory if needed\n let sourceFileDir = path.dirname(sourceFilePath)\n await fs.mkdir(sourceFileDir, { recursive: true })\n let content = [\n `// IMPORTANT: This file is auto-generated, please do not edit manually.`,\n `export * from '${entry.reExportFrom}'\\n`,\n ].join('\\n')\n await fs.writeFile(sourceFilePath, content, 'utf-8')\n }\n\n // Run linter against generated code with --fix\n logAndExec(`npx eslint packages/remix/ --max-warnings=0 --fix`)\n\n // Update package.json\n console.log('Updating Remix package.json...')\n remixPackageJson.exports = {}\n remixPackageJson.publishConfig.exports = {}\n\n for (let entry of allExports) {\n let exportPath = path.join(SOURCE_FOLDER, entry.sourceFile)\n remixPackageJson.exports[entry.exportPath] = `./${exportPath}`\n\n let distFile = path.join(entry.sourceFile.replace(/\\.ts$/, ''))\n remixPackageJson.publishConfig.exports[entry.exportPath] = {\n types: `./dist/${distFile}.d.ts`,\n default: `./dist/${distFile}.js`,\n }\n }\n\n remixPackageJson.exports['./package.json'] = './package.json'\n remixPackageJson.publishConfig.exports['./package.json'] = './package.json'\n\n for (let packageInfo of remixRunPackages) {\n remixPackageJson.dependencies[packageInfo.name] = 'workspace:^'\n }\n\n await fs.writeFile(\n remixPackageJsonPath,\n JSON.stringify(remixPackageJson, null, 2) + '\\n',\n 'utf-8',\n )\n}\n\n// Build exports change summary\nasync function outputExportsChangeFiles(exportsConfig: Record) {\n let newExportsSet = new Set(\n Object.keys(exportsConfig).filter((key) => key !== '.' && key !== './package.json'),\n )\n let addedExports = Array.from(newExportsSet).filter((key) => !existingExports.has(key))\n let removedExports = Array.from(existingExports).filter((key) => !newExportsSet.has(key))\n\n if (addedExports.length === 0 && removedExports.length === 0) {\n return\n }\n\n let semverType = removedExports.length > 0 ? 'major' : 'minor'\n let changeFileBaseName = 'remix.update-exports.md'\n let changeFile = path.join(remixChangesDir, `${semverType}.${changeFileBaseName}`)\n let alternateSemverType = semverType === 'major' ? 'minor' : 'major'\n let alternateChangeFile = path.join(\n remixChangesDir,\n `${alternateSemverType}.${changeFileBaseName}`,\n )\n let legacyChangeFilePattern = /^(major|minor)\\.remix\\.update-exports-\\d+\\.md$/\n let changes = ''\n\n // Remove any old timestamped exports change files from prior runs.\n for (let fileName of await fs.readdir(remixChangesDir)) {\n if (!legacyChangeFilePattern.test(fileName)) {\n continue\n }\n await fs.unlink(path.join(remixChangesDir, fileName))\n }\n\n // Remove the alternate semver deterministic file if present so we only keep one.\n try {\n await fs.unlink(alternateChangeFile)\n } catch (e) {\n if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {\n throw e\n }\n }\n\n if (removedExports.length > 0) {\n console.log()\n console.log('Removed package.json exports:')\n changes += 'Removed `package.json` `exports`:\\n'\n for (let exportPath of removedExports) {\n exportPath = exportPath.replace('./', '')\n let exportName = `remix/${exportPath}`\n console.log(` - ${exportName}`)\n changes += ` - \\`${exportName}\\`\\n`\n\n // Remove re-export file\n let srcFile = path.join(remixDir, SOURCE_FOLDER, exportPath + '.ts')\n try {\n await fs.unlink(srcFile)\n } catch (e) {\n if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {\n throw e\n }\n }\n }\n }\n\n if (addedExports.length > 0) {\n console.log()\n console.log('Added package.json exports:')\n changes += 'Added `package.json` `exports`:\\n'\n for (let exportPath of addedExports) {\n let entry = allExports.find((e) => e.exportPath === exportPath)\n exportPath = `remix/${exportPath.replace('./', '')}`\n if (entry) {\n console.log(` - ${exportPath} → ${entry.reExportFrom}`)\n changes += ` - \\`${exportPath}\\` to re-export APIs from \\`${entry.reExportFrom}\\`\\n`\n }\n }\n }\n\n await fs.writeFile(changeFile, changes, 'utf-8')\n console.log()\n console.log('Created exports change file:')\n console.log(` - ${path.relative(process.cwd(), changeFile)}`)\n}\n" }, { "path": "scripts/package.json", "content": "{\n \"name\": \"remix-the-scripts\",\n \"private\": true,\n \"type\": \"module\",\n \"dependencies\": {\n \"@octokit/request\": \"^9.1.3\",\n \"@types/node\": \"catalog:\",\n \"@types/semver\": \"^7.5.8\",\n \"semver\": \"^7.6.3\"\n },\n \"scripts\": {\n \"test\": \"node --test\",\n \"typecheck\": \"tsgo --noEmit\"\n }\n}\n" }, { "path": "scripts/pr-preview.ts", "content": "/**\n * PR Preview Script\n *\n * This script manages preview builds for pull requests by:\n * - Creating comments on PRs with installation instructions for preview builds\n * - Cleaning up preview branches when PRs are merged or closed\n *\n * Commands:\n * - `comment `: Adds a comment to the specified PR with instructions\n * to install the preview build. Updates any existing preview comments.\n * - `cleanup `: Deletes the preview branch from the remote repository\n * and adds a cleanup notification comment to the PR.\n *\n * Usage: `node pr-preview.ts `\n */\n\nimport { parseArgs } from 'node:util'\n\nimport { createPrComment, deletePrComment, getPrComments, updatePrComment } from './utils/github.ts'\nimport { logAndExec } from './utils/process.ts'\n\nconst STICKY_MARKER = ''\nconst CLEANUP_MARKER = ''\n\nlet { positionals } = parseArgs({\n allowPositionals: true,\n strict: true,\n})\n\nif (positionals.length !== 3) {\n printUsage()\n process.exit(1)\n}\n\nlet [command, prNumberString, branch] = positionals\nlet prNumber = parseInt(prNumberString, 10)\nif (isNaN(prNumber) || prNumber <= 0) {\n printUsage()\n throw new Error(`Invalid PR number: ${prNumberString}`)\n}\n\nlet commands: Record Promise> = {\n comment,\n cleanup,\n}\n\nif (commands[command]) {\n await commands[command]()\n} else {\n printUsage()\n throw new Error(`Unknown command: ${command}`)\n}\n\nfunction printUsage() {\n console.error('Usage: node pr-preview.ts ')\n console.error(' comment - Add preview comment to PR')\n console.error(' cleanup - Delete branch from origin')\n}\n\nasync function comment() {\n let commentBody = `\\\n${STICKY_MARKER}\n### Preview Build Available\n\nA preview build has been created for this PR. You can install it using:\n\n\\`\\`\\`sh\npnpm install \"remix-run/remix#${branch}&path:packages/remix\"\n\\`\\`\\`\n\nThis preview build will be updated automatically as you push new commits.`\n\n // Get existing comments\n let comments = await getPrComments(prNumber)\n\n // Only add a comment if one doesn't already exist\n let stickyComment = comments.find((comment) => comment.body?.includes(STICKY_MARKER))\n if (stickyComment) {\n console.log('Updating preview comment on PR')\n await updatePrComment(stickyComment.id, commentBody)\n } else {\n console.log('Adding preview comment to PR')\n await createPrComment(prNumber, commentBody)\n }\n\n // Delete cleanup comment if it exists\n let cleanupComment = comments.find((comment) => comment.body?.includes(CLEANUP_MARKER))\n if (cleanupComment) {\n console.log('Deleting existing cleanup comment')\n await deletePrComment(cleanupComment.id)\n }\n}\n\nasync function cleanup() {\n console.log(`Deleted branch: ${branch}`)\n await logAndExec(`git push --delete origin ${branch}`)\n\n let commentBody = `\\\n${CLEANUP_MARKER}\nThe preview branch \\`${branch}\\` has been deleted now that this PR is merged/closed.`\n\n console.log('Adding cleanup comment to PR')\n await createPrComment(prNumber, commentBody)\n}\n" }, { "path": "scripts/publish.ts", "content": "/**\n * Publishes packages to npm and creates tags/releases for what was published.\n *\n * This script uses pnpm publish with --report-summary, reads the summary file,\n * and creates Git tags + GitHub releases. When the remix package is in prerelease\n * mode (has .changes/config.json with prereleaseChannel), it publishes in two phases:\n * all other packages as \"latest\", then remix with the \"next\" tag.\n *\n * This script is designed for CI use. For previewing releases, use `pnpm changes:preview`.\n *\n * Usage:\n * node scripts/publish.ts [--skip-ci-check] [--dry-run]\n *\n * Options:\n * --skip-ci-check Bypass the CI environment check\n * --dry-run Show what would be published without actually publishing.\n * Queries npm to determine unpublished packages and previews\n * what the GitHub releases would look like.\n */\nimport * as cp from 'node:child_process'\nimport * as fs from 'node:fs'\nimport * as path from 'node:path'\n\nimport {\n findVersionIntroductionCommit,\n getLocalTagTarget,\n getRemoteTagTarget,\n tagExists,\n} from './utils/git.ts'\nimport { createRelease, releaseExists } from './utils/github.ts'\nimport { getRootDir, logAndExec } from './utils/process.ts'\nimport { readChangesConfig, getChangelogEntry } from './utils/changes.ts'\nimport {\n getAllPackageDirNames,\n getPackageFile,\n getGitTag,\n packageNameToDirectoryName,\n getPackageShortName,\n} from './utils/packages.ts'\nimport { readJson, fileExists } from './utils/fs.ts'\n\nlet rootDir = getRootDir()\n\nlet args = process.argv.slice(2)\nlet skipCiCheck = args.includes('--skip-ci-check')\nlet dryRun = args.includes('--dry-run')\n\ninterface PublishedPackage {\n packageName: string\n version: string\n tag: string\n}\n\ninterface PublishSummary {\n publishedPackages: Array<{\n name: string\n version: string\n }>\n}\n\ninterface LocalPackage {\n dirName: string\n npmName: string\n localVersion: string\n}\n\ninterface TagPlan {\n pkg: PublishedPackage\n targetCommit: string\n}\n\n/**\n * Read published packages from pnpm's publish summary file.\n * See https://pnpm.io/cli/publish#--report-summary\n */\nfunction readPublishSummary(): PublishedPackage[] {\n let summaryPath = path.join(rootDir, 'pnpm-publish-summary.json')\n\n if (!fs.existsSync(summaryPath)) {\n throw new Error(\n `pnpm-publish-summary.json not found. This is unexpected after a successful publish.`,\n )\n }\n\n let summary: PublishSummary = JSON.parse(fs.readFileSync(summaryPath, 'utf-8'))\n\n return summary.publishedPackages.map((pkg) => ({\n packageName: pkg.name,\n version: pkg.version,\n tag: getGitTag(pkg.name, pkg.version),\n }))\n}\n\n/**\n * Get local package metadata from the workspace.\n */\nfunction getLocalPackages(): LocalPackage[] {\n let packageDirNames = getAllPackageDirNames()\n let localPackages: LocalPackage[] = []\n\n for (let packageDirName of packageDirNames) {\n let packageJsonPath = getPackageFile(packageDirName, 'package.json')\n\n // Skip directories without a package.json\n if (!fileExists(packageJsonPath)) {\n continue\n }\n\n let packageJson = readJson(packageJsonPath)\n localPackages.push({\n dirName: packageDirName,\n npmName: packageJson.name as string,\n localVersion: packageJson.version as string,\n })\n }\n\n return localPackages\n}\n\n/**\n * Check if a specific version of a package is published on npm.\n */\nasync function isVersionPublished(packageName: string, version: string): Promise {\n return new Promise((resolve) => {\n cp.exec(\n `npm view ${packageName}@${version} version`,\n { encoding: 'utf-8' },\n (_error, stdout) => {\n // If we get output that matches the version, it exists\n resolve(stdout.trim() === version)\n },\n )\n })\n}\n\n/**\n * Get all packages that have versions not yet published to npm.\n */\nasync function getUnpublishedPackages(): Promise {\n let localPackages = getLocalPackages()\n\n // Query npm for all packages in parallel\n let npmResults = await Promise.all(\n localPackages.map(async (pkg) => ({\n pkg,\n isPublished: await isVersionPublished(pkg.npmName, pkg.localVersion),\n })),\n )\n\n // Filter to unpublished packages\n let unpublished: PublishedPackage[] = []\n for (let { pkg, isPublished } of npmResults) {\n if (!isPublished) {\n unpublished.push({\n packageName: pkg.npmName,\n version: pkg.localVersion,\n tag: getGitTag(pkg.npmName, pkg.localVersion),\n })\n }\n }\n\n return unpublished\n}\n\n/**\n * Find package versions that are already published to npm but missing git tags.\n * This enables release recovery after partial publish failures.\n */\nasync function getPublishedPackagesMissingTags(): Promise {\n let localPackages = getLocalPackages()\n\n let npmResults = await Promise.all(\n localPackages.map(async (pkg) => ({\n pkg,\n isPublished: await isVersionPublished(pkg.npmName, pkg.localVersion),\n })),\n )\n\n let missingTags: PublishedPackage[] = []\n for (let { pkg, isPublished } of npmResults) {\n if (!isPublished) {\n continue\n }\n\n let tag = getGitTag(pkg.npmName, pkg.localVersion)\n if (!tagExists(tag)) {\n missingTags.push({\n packageName: pkg.npmName,\n version: pkg.localVersion,\n tag,\n })\n }\n }\n\n return missingTags\n}\n\n/**\n * Find package versions that are already published and tagged but missing GitHub releases.\n * This enables release recovery after tags were pushed successfully.\n */\nasync function getPublishedPackagesMissingReleases(): Promise {\n let localPackages = getLocalPackages()\n\n let npmResults = await Promise.all(\n localPackages.map(async (pkg) => ({\n pkg,\n isPublished: await isVersionPublished(pkg.npmName, pkg.localVersion),\n })),\n )\n\n let missingReleases: PublishedPackage[] = []\n for (let { pkg, isPublished } of npmResults) {\n if (!isPublished) {\n continue\n }\n\n let tag = getGitTag(pkg.npmName, pkg.localVersion)\n if (!tagExists(tag)) {\n continue\n }\n\n if (!(await releaseExists(tag))) {\n missingReleases.push({\n packageName: pkg.npmName,\n version: pkg.localVersion,\n tag,\n })\n }\n }\n\n return missingReleases\n}\n\nfunction dedupePublishedPackages(packages: PublishedPackage[]): PublishedPackage[] {\n let seenTags = new Set()\n let deduped: PublishedPackage[] = []\n\n for (let pkg of packages) {\n if (seenTags.has(pkg.tag)) {\n continue\n }\n seenTags.add(pkg.tag)\n deduped.push(pkg)\n }\n\n return deduped\n}\n\nfunction isShallowRepository(): boolean {\n try {\n let output = cp.execFileSync('git', ['rev-parse', '--is-shallow-repository'], {\n stdio: 'pipe',\n encoding: 'utf-8',\n })\n return output.trim() === 'true'\n } catch {\n return false\n }\n}\n\nfunction ensureGitHistoryForVersionLookup() {\n if (isShallowRepository()) {\n console.log('\\nRepository is shallow, fetching full history for release tag anchoring...')\n logAndExec('git fetch --unshallow --tags origin')\n return\n }\n\n console.log('\\nFetching tags from origin...')\n logAndExec('git fetch --tags origin')\n}\n\nfunction resolveTagPlans(packages: PublishedPackage[]): TagPlan[] {\n let plans: TagPlan[] = []\n\n for (let pkg of packages) {\n let packageDirName = packageNameToDirectoryName(pkg.packageName)\n if (packageDirName === null) {\n throw new Error(\n `Could not map package \"${pkg.packageName}\" to a workspace directory for tag anchoring.`,\n )\n }\n\n let packageJsonPath = path\n .relative(rootDir, getPackageFile(packageDirName, 'package.json'))\n .replaceAll('\\\\', '/')\n\n let targetCommit = findVersionIntroductionCommit(packageJsonPath, pkg.version)\n if (targetCommit === null) {\n throw new Error(\n `Could not find commit that introduced ${pkg.packageName}@${pkg.version} from ${packageJsonPath}. Ensure full git history is available.`,\n )\n }\n\n plans.push({ pkg, targetCommit })\n }\n\n return plans\n}\n\nfunction verifyTagTargets(tagPlans: TagPlan[]) {\n let mismatches: Array<{\n tag: string\n scope: 'local' | 'remote'\n actual: string\n expected: string\n }> = []\n\n for (let plan of tagPlans) {\n let localTarget = getLocalTagTarget(plan.pkg.tag)\n if (localTarget !== null && localTarget !== plan.targetCommit) {\n mismatches.push({\n tag: plan.pkg.tag,\n scope: 'local',\n actual: localTarget,\n expected: plan.targetCommit,\n })\n }\n\n let remoteTarget = getRemoteTagTarget(plan.pkg.tag)\n if (remoteTarget !== null && remoteTarget !== plan.targetCommit) {\n mismatches.push({\n tag: plan.pkg.tag,\n scope: 'remote',\n actual: remoteTarget,\n expected: plan.targetCommit,\n })\n }\n }\n\n if (mismatches.length > 0) {\n let lines = ['Detected existing tags pointing at unexpected commits:']\n for (let mismatch of mismatches) {\n lines.push(\n ` • ${mismatch.tag} (${mismatch.scope}) expected ${mismatch.expected.slice(0, 12)} but found ${mismatch.actual.slice(0, 12)}`,\n )\n }\n lines.push('Refusing to continue to avoid creating inconsistent release metadata.')\n throw new Error(lines.join('\\n'))\n }\n}\n\ninterface ChangelogWarning {\n packageName: string\n version: string\n}\n\n/**\n * Preview GitHub releases for packages that would be published.\n * Returns warnings for packages with missing changelog entries.\n */\nfunction previewGitHubReleases(packages: PublishedPackage[]): { warnings: ChangelogWarning[] } {\n let warnings: ChangelogWarning[] = []\n\n console.log('GitHub Release Preview')\n console.log('═'.repeat(60))\n console.log()\n\n for (let pkg of packages) {\n let tagName = getGitTag(pkg.packageName, pkg.version)\n let releaseName = `${getPackageShortName(pkg.packageName)} v${pkg.version}`\n let changes = getChangelogEntry({ packageName: pkg.packageName, version: pkg.version })\n let body = changes?.body ?? 'No changelog entry found for this version.'\n\n if (changes === null) {\n warnings.push({ packageName: pkg.packageName, version: pkg.version })\n }\n\n console.log(`📦 ${releaseName}`)\n console.log(` Tag: ${tagName}`)\n console.log()\n console.log(' Release notes:')\n console.log()\n for (let line of body.split('\\n')) {\n console.log(` ${line}`)\n }\n console.log()\n console.log('─'.repeat(60))\n console.log()\n }\n\n return { warnings }\n}\n\nasync function main() {\n // Safety check: this script should only run in CI when not in dry run mode\n if (!process.env.CI && !skipCiCheck && !dryRun) {\n console.error('The publish script is designed for CI use only.')\n console.error('Use --skip-ci-check to bypass this check for local use.')\n console.error('Use --dry-run to preview the publish process.')\n console.error('\\nFor previewing releases, use: pnpm changes:preview')\n process.exit(1)\n }\n\n if (dryRun) {\n console.log('🔍 DRY RUN MODE - No packages will be published\\n')\n }\n\n // Check if remix is in prerelease mode\n let remixChangesConfig = readChangesConfig('remix')\n let remixPrereleaseChannel: string | null = null\n\n if (remixChangesConfig.exists) {\n if (!remixChangesConfig.valid) {\n console.error('Error reading remix changes config:', remixChangesConfig.error)\n process.exit(1)\n }\n remixPrereleaseChannel = remixChangesConfig.config.prereleaseChannel || null\n if (remixPrereleaseChannel) {\n console.log(`Remix is in prerelease mode (channel: ${remixPrereleaseChannel})`)\n console.log('Publishing in two phases: other packages as \"latest\", then remix as \"next\"\\n')\n }\n }\n\n // Publish packages to npm\n console.log('Publishing packages to npm...\\n')\n\n let published: PublishedPackage[] = []\n\n if (remixPrereleaseChannel) {\n let publishCommands = [\n // Phase 1: Publish everything in `packages` except remix (with --report-summary so we know what was published)\n 'pnpm publish --recursive --filter \"./packages/*\" --filter \"!remix\" --access public --no-git-checks --report-summary',\n // Phase 2: Publish remix with \"next\" tag (with --report-summary so we know if remix was published)\n 'pnpm publish --filter remix --tag next --access public --no-git-checks --report-summary',\n ]\n\n if (dryRun) {\n console.log('Would run:')\n for (let publishCommand of publishCommands) {\n console.log(` $ ${publishCommand}`)\n }\n console.log()\n } else {\n for (let publishCommand of publishCommands) {\n logAndExec(publishCommand)\n published.push(...readPublishSummary())\n }\n }\n } else {\n // Single-phase publish: everything as latest\n let publishCommand =\n 'pnpm publish --recursive --filter \"./packages/*\" --access public --no-git-checks --report-summary'\n\n if (dryRun) {\n console.log('Would run:')\n console.log(` $ ${publishCommand}`)\n console.log()\n } else {\n logAndExec(publishCommand)\n published.push(...readPublishSummary())\n }\n }\n\n // In dry run mode, query npm to determine what would be published\n // and preview the GitHub releases. This is designed to be run against\n // the contents of the \"Release\" PR / `pnpm changes:version` output.\n if (dryRun) {\n console.log('Checking npm for unpublished versions...\\n')\n\n let unpublished = await getUnpublishedPackages()\n\n if (unpublished.length === 0) {\n console.log('All package versions are already published to npm.')\n console.log('\\n🔍 Dry run complete.')\n return\n }\n\n console.log(\n `${unpublished.length} package${unpublished.length === 1 ? '' : 's'} would be published:\\n`,\n )\n for (let pkg of unpublished) {\n console.log(` • ${pkg.packageName}@${pkg.version}`)\n }\n console.log()\n\n let { warnings } = previewGitHubReleases(unpublished)\n\n if (warnings.length > 0) {\n console.log('⚠️ WARNINGS')\n console.log('═'.repeat(60))\n console.log()\n console.log('The following packages have no changelog entry for their version:')\n console.log()\n for (let warning of warnings) {\n console.log(` • ${warning.packageName} v${warning.version}`)\n }\n console.log()\n console.log('Their GitHub releases will show \"No changelog entry found for this version.\"')\n console.log('This may indicate a missing or malformed CHANGELOG.md entry.')\n console.log()\n }\n\n console.log(\n '🔍 Dry run complete. No packages published, no git tags or GitHub releases created.',\n )\n return\n }\n\n if (published.length > 0) {\n console.log(`\\n${published.length} package${published.length === 1 ? '' : 's'} published:`)\n for (let pkg of published) {\n console.log(` • ${pkg.packageName}@${pkg.version}`)\n }\n } else {\n console.log('\\nNo new packages were published.')\n }\n\n let packagesNeedingTagsOrReleases = dedupePublishedPackages([\n ...published,\n ...(await getPublishedPackagesMissingTags()),\n ...(await getPublishedPackagesMissingReleases()),\n ])\n\n if (packagesNeedingTagsOrReleases.length === 0) {\n console.log('\\nNo packages need git tags or GitHub releases.')\n return\n }\n\n ensureGitHistoryForVersionLookup()\n\n console.log('\\nResolving release tag targets...')\n let tagPlans = resolveTagPlans(packagesNeedingTagsOrReleases)\n\n for (let plan of tagPlans) {\n console.log(` • ${plan.pkg.tag} -> ${plan.targetCommit.slice(0, 12)}`)\n }\n\n verifyTagTargets(tagPlans)\n\n // Configure git\n console.log('\\nConfiguring git...')\n logAndExec('git config user.name \"Remix Run Bot\"')\n logAndExec('git config user.email \"hello@remix.run\"')\n\n // Create tags (skip if already exist)\n console.log(`\\nCreating tag${tagPlans.length === 1 ? '' : 's'} for published packages...`)\n let createdTags: TagPlan[] = []\n for (let plan of tagPlans) {\n let localTarget = getLocalTagTarget(plan.pkg.tag)\n let remoteTarget = getRemoteTagTarget(plan.pkg.tag)\n\n if (localTarget !== null || remoteTarget !== null) {\n let existingTarget = localTarget ?? remoteTarget\n console.log(` ⊘ ${plan.pkg.tag} (already exists at ${existingTarget?.slice(0, 12)})`)\n continue\n }\n\n cp.execFileSync('git', ['tag', plan.pkg.tag, plan.targetCommit], { stdio: 'pipe' })\n console.log(` ✓ ${plan.pkg.tag} -> ${plan.targetCommit.slice(0, 12)}`)\n createdTags.push(plan)\n }\n\n // Push tags if any were created\n if (createdTags.length > 0) {\n console.log(`\\nPushing tag${createdTags.length === 1 ? '' : 's'}...`)\n for (let plan of createdTags) {\n let ref = `refs/tags/${plan.pkg.tag}`\n process.stdout.write(` $ git push origin ${ref}\\n`)\n try {\n cp.execFileSync('git', ['push', 'origin', ref], { stdio: 'inherit' })\n } catch {\n let remoteTarget = getRemoteTagTarget(plan.pkg.tag)\n if (remoteTarget === plan.targetCommit) {\n console.log(\n ` ⊘ ${plan.pkg.tag} (already exists remotely at ${plan.targetCommit.slice(0, 12)})`,\n )\n continue\n }\n throw new Error(\n `Failed to push ${plan.pkg.tag}, and remote target does not match expected commit ${plan.targetCommit.slice(0, 12)}.`,\n )\n }\n }\n } else {\n console.log('\\nNo new tags to push.')\n }\n\n // Create GitHub releases (skip if already exists)\n console.log('\\nCreating GitHub releases...')\n let failedReleases: Array<{ pkg: PublishedPackage; error: string }> = []\n\n for (let pkg of packagesNeedingTagsOrReleases) {\n let result = await createRelease(pkg.packageName, pkg.version)\n if (result.status === 'created') {\n console.log(` ✓ ${pkg.packageName} v${pkg.version}`)\n } else if (result.status === 'skipped') {\n console.log(` ⊘ ${pkg.packageName} v${pkg.version} (${result.reason.toLowerCase()})`)\n } else {\n console.log(` ✗ ${pkg.packageName} v${pkg.version} (failed)`)\n failedReleases.push({ pkg, error: result.error })\n }\n }\n\n // Report any failures\n if (failedReleases.length > 0) {\n console.error('\\n⚠️ Some GitHub releases failed to create:')\n for (let { pkg, error } of failedReleases) {\n console.error(` • ${pkg.packageName} v${pkg.version}: ${error}`)\n }\n console.error('\\nYou may need to create these releases manually.')\n process.exit(1)\n }\n\n console.log('\\n✅ Done.')\n}\n\nmain()\n" }, { "path": "scripts/release-pr.ts", "content": "/**\n * Opens or updates the release PR.\n *\n * Usage:\n * node scripts/release-pr.ts [--preview]\n *\n * Environment:\n * GITHUB_TOKEN - Required (unless --preview)\n */\nimport { parseAllChangeFiles, generateCommitMessage } from './utils/changes.ts'\nimport { generatePrBody } from './utils/release-pr.ts'\nimport { logAndExec } from './utils/process.ts'\nimport { findOpenPr, createPr, updatePr, closePr } from './utils/github.ts'\n\nlet args = process.argv.slice(2)\nlet preview = args.includes('--preview')\n\nlet baseBranch = 'main'\nlet prBranch = 'release-pr/main'\nlet prTitle = 'Release'\n\nasync function main() {\n console.log(preview ? '🔍 PREVIEW MODE\\n' : '')\n\n // Parse and validate changes\n console.log('Validating change files...')\n let result = parseAllChangeFiles()\n\n if (!result.valid) {\n console.error('Validation errors found:')\n for (let error of result.errors) {\n console.error(` ${error.packageDirName}/${error.file}: ${error.error}`)\n }\n process.exit(1)\n }\n\n let { releases } = result\n\n if (releases.length === 0) {\n console.log('No pending changes to release.')\n\n // Check if there's a stale PR that should be closed\n if (!preview && process.env.GITHUB_TOKEN) {\n let existingPr = await findOpenPr(prBranch, baseBranch)\n if (existingPr) {\n console.log(`\\nClosing stale PR #${existingPr.number}...`)\n await closePr(\n existingPr.number,\n 'Closing automatically — all change files have been removed or released.',\n )\n console.log(`✅ Closed PR: ${existingPr.html_url}`)\n }\n }\n\n process.exit(0)\n }\n\n console.log(`\\nFound ${releases.length} package${releases.length === 1 ? '' : 's'} with changes:`)\n for (let release of releases) {\n console.log(` • ${release.packageName}: ${release.currentVersion} → ${release.nextVersion}`)\n }\n console.log()\n\n // Generate content\n let commitMessage = generateCommitMessage(releases)\n let prBody = generatePrBody(releases)\n\n if (preview) {\n console.log('Would create/update PR with:')\n console.log(` Branch: ${prBranch}`)\n console.log(` Title: ${prTitle}`)\n console.log(` Commit: ${commitMessage.split('\\n')[0]}`)\n console.log('\\nPR Body:')\n console.log('─'.repeat(60))\n console.log(prBody)\n console.log('─'.repeat(60))\n console.log('\\nPreview complete. No changes made.')\n process.exit(0)\n }\n\n // Require token for non-preview\n if (!process.env.GITHUB_TOKEN) {\n console.error('GITHUB_TOKEN environment variable is required')\n process.exit(1)\n }\n\n // Configure git\n console.log('Configuring git...')\n logAndExec('git config user.name \"Remix Run Bot\"')\n logAndExec('git config user.email \"hello@remix.run\"')\n\n // Create or switch to PR branch\n console.log(`\\nSwitching to branch: ${prBranch}`)\n logAndExec(`git checkout -B ${prBranch}`)\n\n // Reset to base branch\n logAndExec(`git reset --hard origin/${baseBranch}`)\n\n // Run version command\n console.log('\\nRunning pnpm changes:version...')\n logAndExec('pnpm changes:version')\n\n console.log('\\nPushing branch...')\n logAndExec(`git push origin ${prBranch} --force`)\n\n // Create or update PR\n console.log('\\nChecking for existing PR...')\n let existingPr = await findOpenPr(prBranch, baseBranch)\n\n if (existingPr) {\n console.log(`Updating existing PR #${existingPr.number}...`)\n await updatePr(existingPr.number, { title: prTitle, body: prBody })\n console.log(`\\n✅ Updated PR: ${existingPr.html_url}`)\n } else {\n console.log('Creating new PR...')\n let newPr = await createPr({ title: prTitle, body: prBody, head: prBranch, base: baseBranch })\n console.log(`\\n✅ Created PR #${newPr.number}: ${newPr.html_url}`)\n }\n}\n\nmain().catch((error) => {\n console.error('Error:', error.message)\n process.exit(1)\n})\n" }, { "path": "scripts/setup-installable-branch.ts", "content": "import * as fsp from 'node:fs/promises'\nimport * as path from 'node:path'\nimport * as util from 'node:util'\nimport { logAndExec } from './utils/process.ts'\n\n/**\n * This script prepares a base branch (usually `main`) to be PNPM-installable\n * directly from GitHub via a new branch (usually `preview/main`):\n *\n * pnpm install \"remix-run/remix#preview/main&path:packages/remix\"\n *\n * To do this, we can run a build, make some minor changes to the repo, and\n * commit the build + changes to the new branch. These changes would never be\n * down-merged back to the source branch.\n *\n * This script does the following:\n * - Checks out the new branch and resets it to the base (current) branch\n * - Runs a build\n * - Removes `dist/` from `.gitignore`\n * - Updates all internal `@remix-run/*` deps to use the github format for the\n * given installable branch\n * - Copies all `publishConfig`'s down so we get `exports` from `dist/` instead of `src/`\n * - Commits the changes\n *\n * Then, after pushing, `pnpm install \"remix-run/remix#preview/main&path:packages/remix\"`\n * sees the `remix` nested deps and they all point to github with similar URLs so\n * they install as nested deps the same way.\n */\n\nlet { positionals } = util.parseArgs({\n allowPositionals: true,\n})\n\n// Use first positional argument or fall back to --branch flag or default\nlet installableBranch = positionals[0]\nif (!installableBranch) {\n throw new Error('Error: You must provide an installable branch name')\n}\n\n// Error if git status is not clean\nlet gitStatus = logAndExec('git status --porcelain', true)\nif (gitStatus) {\n throw new Error('Error: Git working directory is not clean. Commit or stash changes first.')\n}\n\n// Capture the current branch name\nlet sha = logAndExec('git rev-parse --short HEAD ', true).trim()\n\nconsole.log(`Preparing installable branch \\`${installableBranch}\\` from sha ${sha}`)\n\n// Switch to new branch and reset to current commit on base branch\nlogAndExec(`git checkout -B ${installableBranch}`)\n\n// Build dist/ folders\nlogAndExec('pnpm build')\n\nawait updateGitignore()\nawait updatePackageDependencies()\n\nlogAndExec('git add .')\nlogAndExec(`git commit -a -m \"installable build from ${sha}\"`)\n\nconsole.log(\n [\n '',\n `✅ Done!`,\n '',\n `You can now push the \\`${installableBranch}\\` branch to GitHub and install via:`,\n '',\n ` pnpm install \"remix-run/remix#${installableBranch}&path:packages/remix\"`,\n ].join('\\n'),\n)\n\n// Remove `dist` from gitignore so we include built code in the repo\nasync function updateGitignore() {\n let gitignorePath = path.join(process.cwd(), '.gitignore')\n let content = await fsp.readFile(gitignorePath, 'utf-8')\n let filtered = content\n .split('\\n')\n .filter((line) => !line.trim().startsWith('dist'))\n .join('\\n')\n await fsp.writeFile(gitignorePath, filtered)\n console.log('Updated .gitignore')\n}\n\n// Update `package.json` files to point to this branch on github\nasync function updatePackageDependencies() {\n let packagesDir = path.join(process.cwd(), 'packages')\n\n let packageDirNames = await fsp.readdir(packagesDir, { withFileTypes: true })\n\n for (let dir of packageDirNames) {\n if (!dir.isDirectory()) continue\n\n let packageJsonPath = path.join(packagesDir, dir.name, 'package.json')\n let content = await fsp.readFile(packageJsonPath, 'utf-8')\n let pkg = JSON.parse(content)\n\n // Point all `@remix-run/` dependencies to this branch on github\n if (pkg.dependencies) {\n for (let name of Object.keys(pkg.dependencies)) {\n if (name.startsWith('@remix-run/')) {\n let packageDirName = name.replace('@remix-run/', '')\n pkg.dependencies[name] =\n `remix-run/remix#${installableBranch}&path:packages/${packageDirName}`\n }\n }\n }\n\n // Apply `publishConfig` overrides\n if (pkg.publishConfig) {\n Object.assign(pkg, pkg.publishConfig)\n delete pkg.publishConfig\n }\n\n await fsp.writeFile(packageJsonPath, JSON.stringify(pkg, null, 2) + '\\n')\n console.log(`Updated ${dir.name}`)\n }\n\n console.log('Done')\n}\n\nfunction commitChanges() {}\n" }, { "path": "scripts/tsconfig.json", "content": "{\n \"compilerOptions\": {\n \"lib\": [\"ES2024\"],\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"strict\": true,\n \"allowJs\": true,\n \"checkJs\": true,\n \"noEmit\": true,\n \"allowImportingTsExtensions\": true\n },\n \"exclude\": [\"dist\"]\n}\n" }, { "path": "scripts/utils/changes.test.ts", "content": "import assert from 'node:assert/strict'\nimport { test } from 'node:test'\nimport type { PackageRelease } from './changes.ts'\nimport { generateChangelogContent } from './changes.ts'\n\nfunction makeRelease(overrides: Partial = {}): PackageRelease {\n return {\n packageDirName: 'remix',\n packageName: 'remix',\n currentVersion: '3.0.0-alpha.3',\n nextVersion: '3.0.0-alpha.4',\n bump: 'patch',\n changes: [],\n dependencyBumps: [],\n ...overrides,\n }\n}\n\ntest('generateChangelogContent groups prerelease changes into a single section', () => {\n let content = generateChangelogContent(\n makeRelease({\n changes: [\n {\n file: 'minor.alpha.md',\n bump: 'minor',\n content: 'Alpha change',\n },\n {\n file: 'major.breaking.md',\n bump: 'major',\n content: 'BREAKING CHANGE: Breaking change',\n },\n {\n file: 'patch.fix.md',\n bump: 'patch',\n content: 'Patch change',\n },\n ],\n dependencyBumps: [\n {\n packageName: '@remix-run/router',\n version: '1.2.3',\n releaseUrl: 'https://example.com/router',\n },\n ],\n }),\n )\n\n assert.match(content, /^## v3\\.0\\.0-alpha\\.4/m)\n assert.match(content, /^### Pre-release Changes$/m)\n assert.doesNotMatch(content, /^### Major Changes$/m)\n assert.doesNotMatch(content, /^### Minor Changes$/m)\n assert.doesNotMatch(content, /^### Patch Changes$/m)\n assert.match(content, /- BREAKING CHANGE: Breaking change/)\n assert.match(content, /- Alpha change/)\n assert.match(content, /- Patch change/)\n assert.match(content, /- Bumped `@remix-run\\/\\*` dependencies:/)\n assert.match(content, /\\[`router@1\\.2\\.3`\\]\\(https:\\/\\/example\\.com\\/router\\)/)\n})\n\ntest('generateChangelogContent keeps stable releases grouped by bump type', () => {\n let content = generateChangelogContent(\n makeRelease({\n currentVersion: '3.0.0',\n nextVersion: '3.0.1',\n changes: [\n {\n file: 'minor.feature.md',\n bump: 'minor',\n content: 'Feature change',\n },\n ],\n dependencyBumps: [\n {\n packageName: '@remix-run/router',\n version: '1.2.3',\n releaseUrl: 'https://example.com/router',\n },\n ],\n }),\n )\n\n assert.match(content, /^## v3\\.0\\.1/m)\n assert.match(content, /^### Minor Changes$/m)\n assert.match(content, /^### Patch Changes$/m)\n assert.doesNotMatch(content, /^### Pre-release Changes$/m)\n})\n" }, { "path": "scripts/utils/changes.ts", "content": "import * as fs from 'node:fs'\nimport * as path from 'node:path'\nimport {\n getAllPackageDirNames,\n getPackageFile,\n getPackagePath,\n packageNameToDirectoryName,\n getTransitiveDependents,\n getGitHubReleaseUrl,\n getPackageDependencies,\n getGitTag,\n} from './packages.ts'\nimport { fileExists, readFile, readJson } from './fs.ts'\nimport { inc, major, prerelease, type ReleaseType } from './semver.ts'\n\nconst bumpTypes = ['major', 'minor', 'patch'] as const\ntype BumpType = (typeof bumpTypes)[number]\n\n// Changes configuration (from packages/remix/.changes/config.json)\n// Only the remix package supports changes config.\nexport interface ChangesConfig {\n prereleaseChannel: string\n}\n\nexport type ParsedChangesConfig =\n | { exists: false }\n | { exists: true; valid: true; config: ChangesConfig }\n | { exists: true; valid: false; error: string }\n\n/**\n * Reads and validates a package's .changes/config.json.\n */\nexport function readChangesConfig(packageDirName: string): ParsedChangesConfig {\n let packagePath = getPackagePath(packageDirName)\n let configJsonPath = path.join(packagePath, '.changes', 'config.json')\n\n if (!fs.existsSync(configJsonPath)) {\n return { exists: false }\n }\n\n let content: unknown\n try {\n content = JSON.parse(fs.readFileSync(configJsonPath, 'utf-8'))\n } catch {\n return { exists: true, valid: false, error: 'Invalid JSON in .changes/config.json' }\n }\n\n if (typeof content !== 'object' || content === null) {\n return {\n exists: true,\n valid: false,\n error: '.changes/config.json must be an object',\n }\n }\n\n let obj = content as Record\n\n if ('prereleaseChannel' in obj) {\n if (typeof obj.prereleaseChannel !== 'string' || obj.prereleaseChannel.trim().length === 0) {\n return {\n exists: true,\n valid: false,\n error: '.changes/config.json \"prereleaseChannel\" must be a non-empty string',\n }\n }\n return {\n exists: true,\n valid: true,\n config: { prereleaseChannel: obj.prereleaseChannel.trim() },\n }\n }\n\n return { exists: true, valid: true, config: { prereleaseChannel: '' } }\n}\n\n/**\n * Extracts the prerelease identifier from a version string (e.g., \"alpha\" from \"3.0.0-alpha.5\")\n */\nfunction getPrereleaseIdentifier(version: string): string | null {\n let parts = prerelease(version)\n if (parts === null || parts.length === 0) {\n return null\n }\n return typeof parts[0] === 'string' ? parts[0] : null\n}\n\n/**\n * Calculates the next version based on current version, bump type, and changes config.\n */\nfunction getNextVersion(\n currentVersion: string,\n bumpType: BumpType,\n changesConfig: ChangesConfig | null,\n): string {\n let currentPrereleaseId = getPrereleaseIdentifier(currentVersion)\n let isCurrentPrerelease = currentPrereleaseId !== null\n\n if (changesConfig !== null && changesConfig.prereleaseChannel) {\n // In prerelease mode\n let targetChannel = changesConfig.prereleaseChannel\n\n if (currentPrereleaseId === targetChannel) {\n // Same channel - just bump the counter\n let nextVersion = inc(currentVersion, 'prerelease', targetChannel)\n if (nextVersion == null) {\n throw new Error(`Invalid prerelease increment: ${currentVersion}`)\n }\n return nextVersion\n } else {\n // Entering prerelease or transitioning to a new channel (e.g., stable → alpha, or alpha → beta)\n // Apply the bump type to get the base version, then add prerelease suffix\n let baseVersion = isCurrentPrerelease\n ? currentVersion.replace(/-.*$/, '') // Strip existing prerelease suffix\n : inc(currentVersion, bumpType as ReleaseType)\n\n if (baseVersion == null) {\n throw new Error(`Invalid version increment: ${currentVersion} + ${bumpType}`)\n }\n\n return `${baseVersion}-${targetChannel}.0`\n }\n } else {\n // Not in prerelease mode\n if (isCurrentPrerelease) {\n // Graduating from prerelease to stable - strip the prerelease suffix\n let baseVersion = currentVersion.replace(/-.*$/, '')\n return baseVersion\n } else {\n // Normal stable release\n let nextVersion = inc(currentVersion, bumpType as ReleaseType)\n if (nextVersion == null) {\n throw new Error(`Invalid version increment: ${currentVersion} + ${bumpType}`)\n }\n return nextVersion\n }\n }\n}\n\ninterface ChangeFile {\n file: string\n bump: BumpType\n content: string\n}\n\ninterface ValidationError {\n packageDirName: string\n file: string\n error: string\n}\n\ntype ParsedPackageChanges =\n | { valid: true; changes: ChangeFile[]; changesConfig: ChangesConfig | null }\n | { valid: false; errors: ValidationError[] }\n\n/**\n * Parses and validates all change files for a package.\n * Returns changes if valid, or errors if invalid.\n */\nfunction parsePackageChanges(packageDirName: string): ParsedPackageChanges {\n let packagePath = getPackagePath(packageDirName)\n let changesDir = path.join(packagePath, '.changes')\n let changes: ChangeFile[] = []\n let errors: ValidationError[] = []\n\n // Changes directory should exist (with at least README.md)\n if (!fs.existsSync(changesDir)) {\n return {\n valid: false,\n errors: [\n {\n packageDirName,\n file: '.changes/',\n error: 'Changes directory does not exist',\n },\n ],\n }\n }\n\n // README.md should exist in .changes directory so it persists between releases\n let readmePath = path.join(changesDir, 'README.md')\n if (!fs.existsSync(readmePath)) {\n errors.push({\n packageDirName,\n file: '.changes/README.md',\n error: 'README.md is missing from .changes directory',\n })\n }\n\n // Get package version to determine validation rules\n let packageJsonPath = getPackageFile(packageDirName, 'package.json')\n let packageJson = readJson(packageJsonPath)\n let currentVersion = packageJson.version as string\n let majorVersion = major(currentVersion)\n let isV1Plus = majorVersion >= 1\n let currentVersionPrereleaseId = getPrereleaseIdentifier(currentVersion)\n let isCurrentVersionPrerelease = currentVersionPrereleaseId !== null\n\n // Handle .changes/config.json - only supported for remix package\n let changesConfig: ChangesConfig | null = null\n let configJsonPath = path.join(changesDir, 'config.json')\n\n if (packageDirName === 'remix') {\n // For remix, read and validate the changes config\n let parsedChangesConfig = readChangesConfig(packageDirName)\n if (parsedChangesConfig.exists) {\n if (!parsedChangesConfig.valid) {\n errors.push({\n packageDirName,\n file: '.changes/config.json',\n error: parsedChangesConfig.error,\n })\n return { valid: false, errors }\n }\n changesConfig = parsedChangesConfig.config\n }\n } else {\n // For non-remix packages, error if config.json exists\n if (fs.existsSync(configJsonPath)) {\n errors.push({\n packageDirName,\n file: '.changes/config.json',\n error: '.changes/config.json is only supported for the \"remix\" package. Remove this file.',\n })\n return { valid: false, errors }\n }\n }\n\n // Read all files in .changes directory\n let files = fs.readdirSync(changesDir)\n let changeFileNames = files.filter((file) => file !== 'README.md' && file !== 'config.json')\n let hasChangeFiles = changeFileNames.filter((f) => f.endsWith('.md')).length > 0\n\n // Validate changes config / version consistency\n let configPrereleaseChannel = changesConfig?.prereleaseChannel ?? null\n let isActivePrereleaseMode = Boolean(configPrereleaseChannel) && isCurrentVersionPrerelease\n if (configPrereleaseChannel) {\n // Config has prerelease channel\n if (\n currentVersionPrereleaseId !== null &&\n currentVersionPrereleaseId !== configPrereleaseChannel\n ) {\n // Channel mismatch (e.g., version is alpha but config says beta) - need change files to transition\n if (!hasChangeFiles) {\n errors.push({\n packageDirName,\n file: '.changes/config.json',\n error: `prereleaseChannel '${configPrereleaseChannel}' doesn't match version's prerelease identifier '${currentVersionPrereleaseId}'. Add a change file to transition to ${configPrereleaseChannel}.`,\n })\n }\n } else if (!isCurrentVersionPrerelease && !hasChangeFiles) {\n // Config says prerelease but version is stable AND no change files - need change files to enter prerelease\n errors.push({\n packageDirName,\n file: '.changes/config.json',\n error: `prereleaseChannel exists but version ${currentVersion} is stable. Add a change file to enter prerelease mode, or remove prereleaseChannel if this package should not be in prerelease.`,\n })\n }\n } else {\n // No prerelease channel - validate version is stable (unless graduating with change files)\n if (isCurrentVersionPrerelease && !hasChangeFiles) {\n errors.push({\n packageDirName,\n file: '.changes/',\n error: `Version ${currentVersion} is a prerelease but no prereleaseChannel exists. Either add .changes/config.json with { \"prereleaseChannel\": \"${currentVersionPrereleaseId}\" }, or add a change file to graduate to stable.`,\n })\n }\n }\n\n for (let file of changeFileNames) {\n // Skip non-.md files\n if (!file.endsWith('.md')) {\n continue\n }\n\n // Parse filename format when it follows bump naming (e.g. \"minor.add-feature.md\")\n let bump: BumpType | null = null\n\n let withoutExt = file.slice(0, -3)\n let dotIndex = withoutExt.indexOf('.')\n if (dotIndex !== -1) {\n let bumpStr = withoutExt.slice(0, dotIndex)\n let name = withoutExt.slice(dotIndex + 1)\n if (bumpTypes.includes(bumpStr as BumpType) && name.length > 0) {\n bump = bumpStr as BumpType\n }\n }\n\n if (bump == null && isActivePrereleaseMode) {\n // In prerelease mode, bump type does not affect versioning, so any filename is allowed.\n bump = 'patch'\n }\n\n if (bump == null) {\n errors.push({\n packageDirName,\n file,\n error:\n 'Change file must be a \".md\" file starting with \"major.\", \"minor.\", or \"patch.\" (e.g. \"minor.add-feature.md\")',\n })\n continue\n }\n\n // Read file content\n let filePath = path.join(changesDir, file)\n let content = fs.readFileSync(filePath, 'utf-8').trim()\n\n // Check if file is not empty\n if (content.length === 0) {\n errors.push({\n packageDirName,\n file,\n error: 'Change file cannot be empty',\n })\n continue\n }\n\n // Check if first line starts with a bullet point\n let firstLine = content.split('\\n')[0].trim()\n if (firstLine.startsWith('- ') || firstLine.startsWith('* ')) {\n errors.push({\n packageDirName,\n file,\n error:\n 'Change file should not start with a bullet point (- or *). The bullet will be added automatically in the CHANGELOG. Just write the text directly.',\n })\n continue\n }\n\n // Check for headings that aren't level 4, 5, or 6\n let invalidHeadingMatch = content.match(/^(#{1,3}|#{7,})\\s+/m)\n if (invalidHeadingMatch) {\n let headingLevel = invalidHeadingMatch[1].length\n errors.push({\n packageDirName,\n file,\n error: `Headings in change files must be level 4 (####), 5 (#####), or 6 (######), but found level ${headingLevel}. This is because change files are nested within the changelog which already uses heading levels 1-3.`,\n })\n continue\n }\n\n // Validate breaking change prefix matches the correct bump type (only for stable releases)\n // In prerelease mode, breaking changes don't need special handling since we're just bumping counter\n if (!configPrereleaseChannel) {\n let isBreakingChange = hasBreakingChangePrefix(content)\n\n if (isBreakingChange) {\n if (isV1Plus && bump !== 'major') {\n errors.push({\n packageDirName,\n file,\n error: `Breaking changes in v1+ packages must use \"major.\" prefix (current version: ${currentVersion}). Rename to \"major.${file.slice(file.indexOf('.') + 1)}\"`,\n })\n continue\n } else if (!isV1Plus && !isCurrentVersionPrerelease && bump !== 'minor') {\n errors.push({\n packageDirName,\n file,\n error: `Breaking changes in v0.x packages must use \"minor.\" prefix (current version: ${currentVersion}). Rename to \"minor.${file.slice(file.indexOf('.') + 1)}\"`,\n })\n continue\n }\n }\n }\n\n // File is valid, add to changes\n changes.push({ file, bump, content })\n }\n\n // Validate entering prerelease requires a major bump\n if (configPrereleaseChannel && !isCurrentVersionPrerelease && changes.length > 0) {\n let hasMajorBump = changes.some((c) => c.bump === 'major')\n if (!hasMajorBump) {\n errors.push({\n packageDirName,\n file: '.changes/config.json',\n error:\n 'Entering prerelease mode requires a major version bump. Add a change file with \"major.\" prefix (e.g. \"major.release-v2-alpha.md\").',\n })\n }\n }\n\n if (errors.length > 0) {\n return { valid: false, errors }\n }\n\n return { valid: true, changes, changesConfig }\n}\n\n/**\n * Represents a dependency that was bumped, triggering this release.\n */\nexport interface DependencyBump {\n packageName: string\n version: string\n releaseUrl: string\n}\n\nexport interface PackageRelease {\n packageDirName: string\n packageName: string\n currentVersion: string\n nextVersion: string\n bump: BumpType\n changes: ChangeFile[]\n /** Dependencies that were bumped, triggering this release (if any) */\n dependencyBumps: DependencyBump[]\n}\n\ntype ParsedChanges =\n | { valid: true; releases: PackageRelease[] }\n | { valid: false; errors: ValidationError[] }\n\n/**\n * Parses and validates all change files across all packages.\n * Also includes packages that need to be released due to dependency changes.\n * Returns releases if valid, or errors if invalid.\n */\nexport function parseAllChangeFiles(): ParsedChanges {\n let packageDirNames = getAllPackageDirNames()\n let errors: ValidationError[] = []\n\n // Build maps for lookup\n let dirNameToPackageName = new Map()\n let packageNameToDirName = new Map()\n\n // First pass: collect package info and validate change files\n interface ParsedPackageInfo {\n packageDirName: string\n packageName: string\n currentVersion: string\n changes: ChangeFile[]\n changesConfig: ChangesConfig | null\n }\n let parsedPackages: ParsedPackageInfo[] = []\n\n // Read the remix changes config once (only remix supports changes config)\n let remixChangesConfig = readChangesConfig('remix')\n let validRemixChangesConfig: ChangesConfig | null = null\n if (remixChangesConfig.exists && remixChangesConfig.valid) {\n validRemixChangesConfig = remixChangesConfig.config\n }\n\n for (let packageDirName of packageDirNames) {\n let parsed = parsePackageChanges(packageDirName)\n\n if (!parsed.valid) {\n errors.push(...parsed.errors)\n continue\n }\n\n let packageJsonPath = getPackageFile(packageDirName, 'package.json')\n let packageJson = readJson(packageJsonPath)\n let packageName = packageJson.name as string\n let currentVersion = packageJson.version as string\n\n dirNameToPackageName.set(packageDirName, packageName)\n packageNameToDirName.set(packageName, packageDirName)\n\n // For remix package, use the changes config even if there are no change files\n // (to correctly bump prerelease counter for dependency-triggered releases)\n let changesConfig = parsed.changesConfig\n if (packageDirName === 'remix' && changesConfig === null && validRemixChangesConfig) {\n changesConfig = validRemixChangesConfig\n }\n\n parsedPackages.push({\n packageDirName,\n packageName,\n currentVersion,\n changes: parsed.changes,\n changesConfig,\n })\n }\n\n if (errors.length > 0) {\n return { valid: false, errors }\n }\n\n // Find packages with direct changes\n let directlyChangedPackages = new Set()\n for (let pkg of parsedPackages) {\n if (pkg.changes.length > 0) {\n directlyChangedPackages.add(pkg.packageName)\n }\n }\n\n // Find all packages that transitively depend on changed packages\n let transitiveDependents = getTransitiveDependents(directlyChangedPackages)\n\n // Determine all packages that will be released\n let allReleasingPackages = new Set([\n ...directlyChangedPackages,\n ...transitiveDependents.keys(),\n ])\n\n // Compute next versions for all releasing packages\n // We need to do this in dependency order to correctly compute dependency bumps\n let packageVersions = new Map() // packageName -> nextVersion\n\n // First, compute versions for directly changed packages\n for (let pkg of parsedPackages) {\n if (pkg.changes.length > 0) {\n let bump = getHighestBump(pkg.changes.map((c) => c.bump))\n if (bump == null) continue\n let nextVersion = getNextVersion(pkg.currentVersion, bump, pkg.changesConfig)\n packageVersions.set(pkg.packageName, nextVersion)\n }\n }\n\n // Then, compute versions for dependency-triggered releases\n // We need to do this iteratively because a package's version depends on knowing\n // which of its dependencies are being released\n for (let pkg of parsedPackages) {\n if (\n !directlyChangedPackages.has(pkg.packageName) &&\n allReleasingPackages.has(pkg.packageName)\n ) {\n // This package is being released due to dependency changes\n // Use the package's changes config if it has one (e.g., remix in prerelease mode)\n let nextVersion = getNextVersion(pkg.currentVersion, 'patch', pkg.changesConfig)\n packageVersions.set(pkg.packageName, nextVersion)\n }\n }\n\n // Now build the final releases with dependency bumps\n let releases: PackageRelease[] = []\n\n for (let pkg of parsedPackages) {\n if (!allReleasingPackages.has(pkg.packageName)) {\n continue\n }\n\n let nextVersion = packageVersions.get(pkg.packageName)\n if (nextVersion == null) continue\n\n // Compute dependency bumps: which of this package's direct dependencies are being released?\n let dependencyBumps: DependencyBump[] = []\n let deps = getPackageDependencies(pkg.packageName)\n\n for (let depName of deps) {\n if (allReleasingPackages.has(depName)) {\n let depVersion = packageVersions.get(depName)\n if (depVersion) {\n dependencyBumps.push({\n packageName: depName,\n version: depVersion,\n releaseUrl: getGitHubReleaseUrl(depName, depVersion),\n })\n }\n }\n }\n\n // Sort dependency bumps alphabetically by package name\n dependencyBumps.sort((a, b) => a.packageName.localeCompare(b.packageName))\n\n let bump: BumpType = 'patch'\n if (pkg.changes.length > 0) {\n bump = getHighestBump(pkg.changes.map((c) => c.bump)) ?? 'patch'\n }\n\n releases.push({\n packageDirName: pkg.packageDirName,\n packageName: pkg.packageName,\n currentVersion: pkg.currentVersion,\n nextVersion,\n bump,\n changes: pkg.changes,\n dependencyBumps,\n })\n }\n\n // Sort by package name for consistency\n releases.sort((a, b) => a.packageName.localeCompare(b.packageName))\n\n return { valid: true, releases }\n}\n\n/**\n * Formats validation errors for display\n */\nexport function formatValidationErrors(errors: ValidationError[]): string {\n let errorsByPackageDirName: Record = {}\n for (let error of errors) {\n if (!errorsByPackageDirName[error.packageDirName]) {\n errorsByPackageDirName[error.packageDirName] = []\n }\n errorsByPackageDirName[error.packageDirName].push(error)\n }\n\n let lines: string[] = []\n\n for (let [packageDirName, packageErrors] of Object.entries(errorsByPackageDirName)) {\n lines.push(`📦 ${packageDirName}:`)\n for (let error of packageErrors) {\n lines.push(` ${error.file}: ${error.error}`)\n }\n lines.push('')\n }\n\n let packageCount = Object.keys(errorsByPackageDirName).length\n lines.push(\n `Found ${errors.length} error${errors.length === 1 ? '' : 's'} in ${packageCount} package${packageCount === 1 ? '' : 's'}`,\n )\n\n return lines.join('\\n')\n}\n\n/**\n * Determines the highest severity bump type from an array of bump types.\n */\nfunction getHighestBump(bumps: BumpType[]): BumpType | null {\n if (bumps.includes('major')) return 'major'\n if (bumps.includes('minor')) return 'minor'\n if (bumps.includes('patch')) return 'patch'\n return null\n}\n\n/**\n * Checks if content starts with \"BREAKING CHANGE: \" (case-insensitive,\n * ignoring markdown formatting and leading whitespace)\n */\nfunction hasBreakingChangePrefix(content: string): boolean {\n return content\n .trimStart()\n .replace(/^[*_]+/, '')\n .toLowerCase()\n .startsWith('breaking change: ')\n}\n\n/**\n * Formats a changelog entry from change file content\n */\nfunction formatChangelogEntry(content: string): string {\n let lines = content.trim().split('\\n')\n\n if (lines.length === 1) {\n return `- ${lines[0]}`\n }\n\n // Multi-line: first line is bullet, rest are indented\n let [firstLine, ...restLines] = lines\n let formatted = [`- ${firstLine}`]\n\n for (let line of restLines) {\n // Add proper indentation for continuation lines\n formatted.push(line ? ` ${line}` : '')\n }\n\n return formatted.join('\\n')\n}\n\nfunction sortChangelogChanges(changes: PackageRelease['changes']): PackageRelease['changes'] {\n // Sort with breaking changes hoisted to top, then alphabetically by filename\n return [...changes].sort((a, b) => {\n let aBreaking = hasBreakingChangePrefix(a.content)\n let bBreaking = hasBreakingChangePrefix(b.content)\n if (aBreaking !== bBreaking) return aBreaking ? -1 : 1\n return a.file.localeCompare(b.file)\n })\n}\n\n/**\n * Generates a section for a specific bump type (e.g., \"### Major Changes\")\n */\nconst sectionTitles: Record = {\n major: 'Major Changes',\n minor: 'Minor Changes',\n patch: 'Patch Changes',\n}\n\nfunction generateBumpTypeSection(\n changes: PackageRelease['changes'],\n bumpType: BumpType,\n subheadingLevel: number,\n): string | null {\n let filtered = changes.filter((c) => c.bump === bumpType)\n\n if (filtered.length === 0) {\n return null\n }\n\n let sorted = sortChangelogChanges(filtered)\n\n let lines: string[] = []\n let subheadingPrefix = '#'.repeat(subheadingLevel)\n\n lines.push(`${subheadingPrefix} ${sectionTitles[bumpType]}`)\n lines.push('')\n\n for (let change of sorted) {\n lines.push(formatChangelogEntry(change.content))\n lines.push('')\n }\n\n return lines.join('\\n')\n}\n\nfunction generatePrereleaseChangesSection(\n changes: PackageRelease['changes'],\n dependencyBumps: DependencyBump[],\n subheadingLevel: number,\n): string | null {\n if (changes.length === 0 && dependencyBumps.length === 0) {\n return null\n }\n\n let lines: string[] = []\n let subheadingPrefix = '#'.repeat(subheadingLevel)\n lines.push(`${subheadingPrefix} Pre-release Changes`)\n lines.push('')\n\n let sortedChanges = sortChangelogChanges(changes)\n for (let change of sortedChanges) {\n lines.push(formatChangelogEntry(change.content))\n lines.push('')\n }\n\n if (dependencyBumps.length > 0) {\n lines.push('- Bumped `@remix-run/*` dependencies:')\n for (let dep of dependencyBumps) {\n let tag = getGitTag(dep.packageName, dep.version)\n lines.push(` - [\\`${tag}\\`](${dep.releaseUrl})`)\n }\n lines.push('')\n }\n\n return lines.join('\\n')\n}\n\n/**\n * Generates the dependency bumps section for a changelog entry\n */\nfunction generateDependencyBumpsSection(\n dependencyBumps: DependencyBump[],\n subheadingLevel: number,\n): string | null {\n if (dependencyBumps.length === 0) {\n return null\n }\n\n let lines: string[] = []\n let subheadingPrefix = '#'.repeat(subheadingLevel)\n\n lines.push(`${subheadingPrefix} Patch Changes`)\n lines.push('')\n lines.push('- Bumped `@remix-run/*` dependencies:')\n\n for (let dep of dependencyBumps) {\n let tag = getGitTag(dep.packageName, dep.version)\n lines.push(` - [\\`${tag}\\`](${dep.releaseUrl})`)\n }\n\n lines.push('')\n\n return lines.join('\\n')\n}\n\n/**\n * Generates changelog content for a package release\n */\nexport function generateChangelogContent(\n release: PackageRelease,\n options: {\n /** Whether to include package name in heading. Default: false */\n includePackageName?: boolean\n /** Markdown heading level (2 = ##, 3 = ###). Default: 2 */\n headingLevel?: 2 | 3\n } = {},\n): string {\n let { includePackageName = false, headingLevel = 2 } = options\n let lines: string[] = []\n\n let headingPrefix = '#'.repeat(headingLevel)\n let packagePart = includePackageName ? `${release.packageName} ` : ''\n lines.push(`${headingPrefix} ${packagePart}v${release.nextVersion}`)\n lines.push('')\n\n let subheadingLevel = headingLevel + 1\n\n // In prerelease mode, all change-file entries are grouped into a single section.\n let isPrereleaseRelease = getPrereleaseIdentifier(release.nextVersion) !== null\n if (isPrereleaseRelease) {\n let prereleaseSection = generatePrereleaseChangesSection(\n release.changes,\n release.dependencyBumps,\n subheadingLevel,\n )\n if (prereleaseSection) {\n lines.push(prereleaseSection)\n }\n return lines.join('\\n')\n }\n\n // Generate sections in order: major, minor, patch (skipping empty sections)\n for (let bumpType of bumpTypes) {\n let section = generateBumpTypeSection(release.changes, bumpType, subheadingLevel)\n if (section) {\n lines.push(section)\n }\n }\n\n // Add dependency bumps section if there are any\n // Only add if there are no other patch changes (to avoid duplicate \"Patch Changes\" heading)\n if (release.dependencyBumps.length > 0) {\n let hasPatchChanges = release.changes.some((c) => c.bump === 'patch')\n if (hasPatchChanges) {\n // Append to existing patch section (without heading)\n lines.push('- Bumped `@remix-run/*` dependencies:')\n for (let dep of release.dependencyBumps) {\n let tag = getGitTag(dep.packageName, dep.version)\n lines.push(` - [\\`${tag}\\`](${dep.releaseUrl})`)\n }\n lines.push('')\n } else {\n // Create new patch section with heading\n let section = generateDependencyBumpsSection(release.dependencyBumps, subheadingLevel)\n if (section) {\n lines.push(section)\n }\n }\n }\n\n return lines.join('\\n')\n}\n\n/**\n * Generates the commit message for all releases\n */\nexport function generateCommitMessage(releases: PackageRelease[]): string {\n let subject = 'Release'\n let body = releases\n .map((r) => `- ${r.packageName}: ${r.currentVersion} -> ${r.nextVersion}`)\n .join('\\n')\n\n return `${subject}\\n\\n${body}`\n}\n\n// =============================================================================\n// CHANGELOG.md parsing utilities (for reading already-released changes)\n// =============================================================================\n\ninterface ChangelogEntry {\n version: string\n date?: Date\n body: string\n}\n\ntype AllChangelogEntries = Record\n\n/**\n * Parses a package's CHANGELOG.md and returns all version entries\n */\nfunction parseChangelog(packageDirName: string): AllChangelogEntries | null {\n let changelogPath = getPackageFile(packageDirName, 'CHANGELOG.md')\n\n if (!fileExists(changelogPath)) {\n return null\n }\n\n let changelog = readFile(changelogPath)\n let parser = /^## ([a-z\\d\\.\\-]+)(?: \\(([^)]+)\\))?$/gim\n\n let result: AllChangelogEntries = {}\n\n let match\n while ((match = parser.exec(changelog))) {\n let [_, versionString, dateString] = match\n let lastIndex = parser.lastIndex\n let version = versionString.startsWith('v') ? versionString.slice(1) : versionString\n let date = dateString ? new Date(dateString) : undefined\n let nextMatch = parser.exec(changelog)\n let body = changelog.slice(lastIndex, nextMatch ? nextMatch.index : undefined).trim()\n result[version] = { version, date, body }\n parser.lastIndex = lastIndex\n }\n\n return result\n}\n\n/**\n * Gets a specific version's entry from a package's CHANGELOG.md.\n * Accepts an npm package name (e.g., \"@remix-run/static-middleware\" or \"remix\").\n */\nexport function getChangelogEntry({\n packageName,\n version,\n}: {\n packageName: string\n version: string\n}): ChangelogEntry | null {\n let dirName = packageNameToDirectoryName(packageName)\n if (dirName === null) {\n return null\n }\n\n let allEntries = parseChangelog(dirName)\n if (allEntries !== null) {\n return allEntries[version] ?? null\n }\n\n return null\n}\n" }, { "path": "scripts/utils/color.ts", "content": "export let colors = {\n // Regular colors\n black: '\\x1b[30m',\n red: '\\x1b[31m',\n green: '\\x1b[32m',\n yellow: '\\x1b[33m',\n blue: '\\x1b[34m',\n magenta: '\\x1b[35m',\n cyan: '\\x1b[36m',\n white: '\\x1b[37m',\n\n // Bright colors\n gray: '\\x1b[90m',\n lightRed: '\\x1b[91m',\n lightGreen: '\\x1b[92m',\n lightYellow: '\\x1b[93m',\n lightBlue: '\\x1b[94m',\n lightMagenta: '\\x1b[95m',\n lightCyan: '\\x1b[96m',\n lightWhite: '\\x1b[97m',\n\n // Styles\n bold: '\\x1b[1m',\n dim: '\\x1b[2m',\n underline: '\\x1b[4m',\n\n reset: '\\x1b[0m',\n}\n\nexport function colorize(text: string, color: string): string {\n if (process.env.NO_COLOR) {\n return text\n }\n return `${color}${text}${colors.reset}`\n}\n" }, { "path": "scripts/utils/fs.ts", "content": "import * as fs from 'node:fs'\n\nexport function fileExists(filename: string): boolean {\n return fs.existsSync(filename)\n}\n\nexport function readFile(filename: string, encoding: BufferEncoding = 'utf-8'): string {\n try {\n return fs.readFileSync(filename, encoding)\n } catch (error) {\n if (isFsError(error) && error.code === 'ENOENT') {\n console.error(`Not found: \"${filename}\"`)\n process.exit(1)\n } else {\n throw error\n }\n }\n}\n\nfunction isFsError(error: unknown): error is { code: string } {\n return (\n typeof error === 'object' && error != null && 'code' in error && typeof error.code === 'string'\n )\n}\n\nexport function writeFile(filename: string, data: string): void {\n fs.writeFileSync(filename, data)\n}\n\nexport function readJson(filename: string): any {\n return JSON.parse(readFile(filename))\n}\n\nexport function writeJson(filename: string, data: any): void {\n writeFile(filename, JSON.stringify(data, null, 2) + '\\n')\n}\n" }, { "path": "scripts/utils/git.test.ts", "content": "import assert from 'node:assert/strict'\nimport * as cp from 'node:child_process'\nimport * as fs from 'node:fs'\nimport * as os from 'node:os'\nimport * as path from 'node:path'\nimport { test } from 'node:test'\nimport { findVersionIntroductionCommit, getLocalTagTarget } from './git.ts'\n\nfunction execGit(args: string[], cwd: string): string {\n return cp.execFileSync('git', args, { cwd, stdio: 'pipe', encoding: 'utf-8' }).trim()\n}\n\ntest('findVersionIntroductionCommit returns the commit where the target version was introduced', () => {\n let tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'remix-git-test-'))\n let originalCwd = process.cwd()\n let packageJsonPath = 'packages/example/package.json'\n\n try {\n process.chdir(tempDir)\n execGit(['init'], tempDir)\n execGit(['config', 'user.name', 'Test Bot'], tempDir)\n execGit(['config', 'user.email', 'test@example.com'], tempDir)\n\n fs.mkdirSync(path.dirname(packageJsonPath), { recursive: true })\n fs.writeFileSync(\n packageJsonPath,\n `${JSON.stringify({ name: '@remix-run/example', version: '1.0.0' }, null, 2)}\\n`,\n )\n execGit(['add', '.'], tempDir)\n execGit(['commit', '-m', 'initial release'], tempDir)\n let initialCommit = execGit(['rev-parse', 'HEAD'], tempDir)\n\n fs.writeFileSync('README.md', 'hello\\n')\n execGit(['add', 'README.md'], tempDir)\n execGit(['commit', '-m', 'docs change'], tempDir)\n\n fs.writeFileSync(\n packageJsonPath,\n `${JSON.stringify({ name: '@remix-run/example', version: '1.1.0' }, null, 2)}\\n`,\n )\n execGit(['add', packageJsonPath], tempDir)\n execGit(['commit', '-m', 'bump version'], tempDir)\n let versionBumpCommit = execGit(['rev-parse', 'HEAD'], tempDir)\n\n fs.writeFileSync(\n packageJsonPath,\n `${JSON.stringify(\n {\n name: '@remix-run/example',\n version: '1.1.0',\n description: 'metadata only',\n },\n null,\n 2,\n )}\\n`,\n )\n execGit(['add', packageJsonPath], tempDir)\n execGit(['commit', '-m', 'metadata tweak'], tempDir)\n\n assert.equal(findVersionIntroductionCommit(packageJsonPath, '1.1.0'), versionBumpCommit)\n assert.equal(findVersionIntroductionCommit(packageJsonPath, '1.0.0'), initialCommit)\n assert.equal(findVersionIntroductionCommit(packageJsonPath, '9.9.9'), null)\n\n execGit(['tag', 'example@1.1.0', versionBumpCommit], tempDir)\n assert.equal(getLocalTagTarget('example@1.1.0'), versionBumpCommit)\n } finally {\n process.chdir(originalCwd)\n fs.rmSync(tempDir, { recursive: true, force: true })\n }\n})\n" }, { "path": "scripts/utils/git.ts", "content": "import * as cp from 'node:child_process'\n\nfunction execGit(args: string[]): string {\n return cp.execFileSync('git', args, { stdio: 'pipe', encoding: 'utf-8' }).trim()\n}\n\nfunction parseVersionFromPackageJson(content: string): string | null {\n try {\n let parsed = JSON.parse(content) as Record\n return typeof parsed.version === 'string' ? parsed.version : null\n } catch {\n return null\n }\n}\n\nfunction getPackageVersionAtRef(ref: string, packageJsonPath: string): string | null {\n try {\n let content = execGit(['show', `${ref}:${packageJsonPath}`])\n return parseVersionFromPackageJson(content)\n } catch {\n return null\n }\n}\n\n/**\n * Finds the commit that introduced a specific version in a package.json file.\n * Returns null when the version can't be found in the available git history.\n */\nexport function findVersionIntroductionCommit(\n packageJsonPath: string,\n version: string,\n): string | null {\n let normalizedPath = packageJsonPath.replaceAll('\\\\', '/')\n\n let output: string\n try {\n output = execGit(['log', '--format=%H', '--', normalizedPath])\n } catch {\n return null\n }\n\n if (output.length === 0) {\n return null\n }\n\n let commits = output.split('\\n').filter((line) => line.length > 0)\n\n for (let commit of commits) {\n let commitVersion = getPackageVersionAtRef(commit, normalizedPath)\n if (commitVersion !== version) {\n continue\n }\n\n let parentLine = execGit(['rev-list', '--parents', '-n', '1', commit])\n let [_commit, ...parents] = parentLine.split(' ').filter((line) => line.length > 0)\n\n if (parents.length === 0) {\n return commit\n }\n\n let introducedInCommit = false\n for (let parent of parents) {\n let parentVersion = getPackageVersionAtRef(parent, normalizedPath)\n if (parentVersion !== version) {\n introducedInCommit = true\n break\n }\n }\n\n if (introducedInCommit) {\n return commit\n }\n }\n\n return null\n}\n\n/**\n * Gets the local commit target for a tag.\n * Returns null when the tag does not exist locally.\n */\nexport function getLocalTagTarget(tag: string): string | null {\n try {\n return execGit(['rev-parse', '--verify', `refs/tags/${tag}^{commit}`])\n } catch {\n return null\n }\n}\n\n/**\n * Gets the remote commit target for a tag from origin.\n * Returns null when the tag does not exist remotely.\n */\nexport function getRemoteTagTarget(tag: string): string | null {\n try {\n let output = execGit([\n 'ls-remote',\n '--tags',\n 'origin',\n `refs/tags/${tag}`,\n `refs/tags/${tag}^{}`,\n ])\n let lines = output.split('\\n').filter((line) => line.length > 0)\n if (lines.length === 0) {\n return null\n }\n\n let peeledLine = lines.find((line) => line.endsWith(`refs/tags/${tag}^{}`))\n if (peeledLine) {\n return peeledLine.split('\\t')[0]\n }\n\n return lines[0].split('\\t')[0]\n } catch {\n return null\n }\n}\n\n/**\n * Check if a git tag exists\n */\nexport function tagExists(tag: string): boolean {\n return getLocalTagTarget(tag) !== null || getRemoteTagTarget(tag) !== null\n}\n" }, { "path": "scripts/utils/github.ts", "content": "import { request } from '@octokit/request'\n\nimport { getChangelogEntry } from './changes.ts'\nimport { getGitTag, getPackageShortName } from './packages.ts'\n\nlet owner = 'remix-run'\nlet repo = 'remix'\n\nfunction getToken(): string {\n let token = process.env.GITHUB_TOKEN\n if (!token) {\n throw new Error('GITHUB_TOKEN environment variable is required')\n }\n return token\n}\n\nfunction auth() {\n return { headers: { authorization: `token ${getToken()}` } }\n}\n\nexport type CreateReleaseResult =\n | { status: 'created'; url: string }\n | { status: 'skipped'; reason: string }\n | { status: 'error'; error: string }\n\n/**\n * Check if a GitHub release exists for a tag.\n */\nexport async function releaseExists(tag: string): Promise {\n try {\n await request('GET /repos/{owner}/{repo}/releases/tags/{tag}', {\n ...auth(),\n owner,\n repo,\n tag,\n })\n return true\n } catch (error) {\n if (error instanceof Error && 'status' in error && error.status === 404) {\n return false\n }\n throw error\n }\n}\n\n/**\n * Creates a GitHub release for a package version.\n * Returns a result object indicating success, already exists, or error.\n */\nexport async function createRelease(\n packageName: string,\n version: string,\n options: {\n preview?: boolean\n } = {},\n): Promise {\n let { preview = false } = options\n\n let tagName = getGitTag(packageName, version)\n let releaseName = `${getPackageShortName(packageName)} v${version}`\n let changes = getChangelogEntry({ packageName, version })\n let body = changes?.body ?? 'No changelog entry found for this version.'\n\n if (preview) {\n console.log(` Tag: ${tagName}`)\n console.log(` Name: ${releaseName}`)\n console.log()\n console.log(' Body:')\n console.log()\n for (let line of body.split('\\n')) {\n console.log(` ${line}`)\n }\n console.log()\n return { status: 'skipped', reason: 'Preview mode' }\n }\n\n try {\n if (await releaseExists(tagName)) {\n return { status: 'skipped', reason: 'Already exists' }\n }\n } catch (error) {\n let message = error instanceof Error ? error.message : String(error)\n return { status: 'error', error: message }\n }\n\n try {\n let response = await request('POST /repos/{owner}/{repo}/releases', {\n ...auth(),\n owner,\n repo,\n tag_name: tagName,\n name: releaseName,\n body,\n })\n\n return { status: 'created', url: response.data.html_url }\n } catch (error) {\n let message = error instanceof Error ? error.message : String(error)\n return { status: 'error', error: message }\n }\n}\n\n/**\n * Find an open PR from a specific branch to a base branch\n */\nexport async function findOpenPr(head: string, base: string) {\n let response = await request('GET /repos/{owner}/{repo}/pulls', {\n ...auth(),\n owner,\n repo,\n state: 'open',\n head: `${owner}:${head}`,\n base,\n })\n\n return response.data.length > 0 ? response.data[0] : null\n}\n\n/**\n * Create a new PR\n */\nexport async function createPr(options: {\n title: string\n body: string\n head: string\n base: string\n}) {\n let response = await request('POST /repos/{owner}/{repo}/pulls', {\n ...auth(),\n owner,\n repo,\n title: options.title,\n body: options.body,\n head: options.head,\n base: options.base,\n })\n\n return response.data\n}\n\n/**\n * Update an existing PR\n */\nexport async function updatePr(prNumber: number, options: { title?: string; body?: string }) {\n await request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', {\n ...auth(),\n owner,\n repo,\n pull_number: prNumber,\n ...options,\n })\n}\n\n/**\n * Close a PR with an optional comment\n */\nexport async function closePr(prNumber: number, comment?: string) {\n if (comment) {\n await request('POST /repos/{owner}/{repo}/issues/{issue_number}/comments', {\n ...auth(),\n owner,\n repo,\n issue_number: prNumber,\n body: comment,\n })\n }\n\n await request('PATCH /repos/{owner}/{repo}/pulls/{pull_number}', {\n ...auth(),\n owner,\n repo,\n pull_number: prNumber,\n state: 'closed',\n })\n}\n\n/**\n * Get all comments on a PR\n */\nexport async function getPrComments(prNumber: number) {\n let response = await request('GET /repos/{owner}/{repo}/issues/{issue_number}/comments', {\n ...auth(),\n owner,\n repo,\n issue_number: prNumber,\n })\n\n return response.data\n}\n\n/**\n * Create a comment on a PR\n */\nexport async function createPrComment(prNumber: number, body: string) {\n let response = await request('POST /repos/{owner}/{repo}/issues/{issue_number}/comments', {\n ...auth(),\n owner,\n repo,\n issue_number: prNumber,\n body,\n })\n\n return response.data\n}\n\n/**\n * Update a comment on a PR\n */\nexport async function updatePrComment(commentId: number, body: string) {\n await request('PATCH /repos/{owner}/{repo}/issues/comments/{comment_id}', {\n ...auth(),\n owner,\n repo,\n comment_id: commentId,\n body,\n })\n}\n\n/**\n * Delete a comment on a PR\n */\nexport async function deletePrComment(commentId: number) {\n await request('DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}', {\n ...auth(),\n owner,\n repo,\n comment_id: commentId,\n })\n}\n" }, { "path": "scripts/utils/packages.ts", "content": "import * as fs from 'node:fs'\nimport * as path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url))\n\nexport const packagesDir = path.relative(\n process.cwd(),\n path.resolve(__dirname, '..', '..', 'packages'),\n)\n\nexport const GITHUB_REPO_URL = 'https://github.com/remix-run/remix'\n\nexport function getAllPackageDirNames(): string[] {\n return fs.readdirSync(packagesDir).filter((name) => {\n let packagePath = getPackagePath(name)\n return fs.existsSync(packagePath) && fs.statSync(packagePath).isDirectory()\n })\n}\n\nexport function getPackagePath(packageDirName: string): string {\n return path.resolve(packagesDir, packageDirName)\n}\n\nexport function getPackageFile(packageDirName: string, filename: string): string {\n return path.join(getPackagePath(packageDirName), filename)\n}\n\n/**\n * Builds a mapping from npm package names to directory names by reading\n * all package.json files in the packages directory.\n */\nlet getNpmPackageNameToDirectoryMap = (() => {\n let map: Map | null = null\n\n return function getNpmPackageNameToDirectoryMap(): Map {\n if (map !== null) {\n return map\n }\n\n map = new Map()\n let dirNames = getAllPackageDirNames()\n\n for (let dirName of dirNames) {\n let packageJsonPath = getPackageFile(dirName, 'package.json')\n if (fs.existsSync(packageJsonPath)) {\n try {\n let packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))\n if (typeof packageJson.name === 'string') {\n map.set(packageJson.name, dirName)\n }\n } catch {\n // Skip invalid package.json files\n }\n }\n }\n\n return map\n }\n})()\n\n/**\n * Converts an npm package name to the directory name in the packages folder.\n * Returns null if no mapping is found.\n *\n * Examples:\n * \"@remix-run/static-middleware\" -> \"static-middleware\"\n * \"remix\" -> \"remix\"\n */\nexport function packageNameToDirectoryName(packageName: string): string | null {\n return getNpmPackageNameToDirectoryMap().get(packageName) ?? null\n}\n\n/**\n * Returns the short name used in git tags for a package.\n * For @remix-run/* packages, strips the scope. For \"remix\", returns \"remix\".\n *\n * Examples:\n * \"@remix-run/headers\" -> \"headers\"\n * \"remix\" -> \"remix\"\n */\nexport function getPackageShortName(packageName: string): string {\n if (packageName.startsWith('@remix-run/')) {\n return packageName.slice('@remix-run/'.length)\n }\n return packageName\n}\n\n/**\n * Generates the git tag for a package release.\n *\n * Examples:\n * (\"@remix-run/headers\", \"0.11.0\") -> \"headers@0.11.0\"\n * (\"remix\", \"3.0.0\") -> \"remix@3.0.0\"\n */\nexport function getGitTag(packageName: string, version: string): string {\n return `${getPackageShortName(packageName)}@${version}`\n}\n\n/**\n * Generates the GitHub release URL for a package release.\n */\nexport function getGitHubReleaseUrl(packageName: string, version: string): string {\n let tag = getGitTag(packageName, version)\n return `${GITHUB_REPO_URL}/releases/tag/${tag}`\n}\n\ninterface PackageInfo {\n name: string\n version: string\n dirName: string\n dependencies: string[] // Only @remix-run/* dependencies\n}\n\n/**\n * Gets information about all packages in the monorepo, including their\n * @remix-run/* dependencies.\n */\nlet getPackageInfoMap = (() => {\n let map: Map | null = null\n\n return function getPackageInfoMap(): Map {\n if (map !== null) {\n return map\n }\n\n map = new Map()\n let dirNames = getAllPackageDirNames()\n\n for (let dirName of dirNames) {\n let packageJsonPath = getPackageFile(dirName, 'package.json')\n if (fs.existsSync(packageJsonPath)) {\n try {\n let packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))\n let name = packageJson.name as string\n let version = packageJson.version as string\n\n // Collect @remix-run/* dependencies from the dependencies field\n let dependencies: string[] = []\n let deps = packageJson.dependencies as Record | undefined\n if (deps) {\n for (let depName of Object.keys(deps)) {\n if (depName.startsWith('@remix-run/') || depName === 'remix') {\n dependencies.push(depName)\n }\n }\n }\n\n map.set(name, { name, version, dirName, dependencies })\n } catch {\n // Skip invalid package.json files\n }\n }\n }\n\n return map\n }\n})()\n\n/**\n * Gets the @remix-run/* dependencies for a package.\n */\nexport function getPackageDependencies(packageName: string): string[] {\n let info = getPackageInfoMap().get(packageName)\n return info?.dependencies ?? []\n}\n\n/**\n * Builds a reverse dependency graph: maps each package to the set of packages\n * that depend on it.\n */\nexport function buildReverseDependencyGraph(): Map> {\n let graph = new Map>()\n let packageInfoMap = getPackageInfoMap()\n\n // Initialize empty sets for all packages\n for (let packageName of packageInfoMap.keys()) {\n graph.set(packageName, new Set())\n }\n\n // Build reverse edges\n for (let [packageName, info] of packageInfoMap) {\n for (let dep of info.dependencies) {\n let dependents = graph.get(dep)\n if (dependents) {\n dependents.add(packageName)\n }\n }\n }\n\n return graph\n}\n\n/**\n * Gets all packages that transitively depend on any of the given packages.\n * Returns a map from dependent package name to the set of changed packages it depends on.\n */\nexport function getTransitiveDependents(changedPackages: Set): Map> {\n let reverseGraph = buildReverseDependencyGraph()\n let result = new Map>()\n\n // For each changed package, find all its transitive dependents\n function addDependents(changedPackage: string, originalChangedPackage: string) {\n let directDependents = reverseGraph.get(changedPackage)\n if (!directDependents) return\n\n for (let dependent of directDependents) {\n // Skip if this is one of the originally changed packages\n if (changedPackages.has(dependent)) continue\n\n // Track which changed packages this dependent needs\n let changedDeps = result.get(dependent)\n if (!changedDeps) {\n changedDeps = new Set()\n result.set(dependent, changedDeps)\n }\n changedDeps.add(originalChangedPackage)\n\n // Recursively process dependents\n addDependents(dependent, originalChangedPackage)\n }\n }\n\n for (let changedPackage of changedPackages) {\n addDependents(changedPackage, changedPackage)\n }\n\n return result\n}\n" }, { "path": "scripts/utils/process.ts", "content": "import * as cp from 'node:child_process'\nimport * as path from 'node:path'\n\n/**\n * Get the root directory of the monorepo (parent of scripts/).\n * Works whether called directly or via node --eval.\n */\nexport function getRootDir(): string {\n // import.meta.dirname is the directory containing this file (scripts/utils/)\n // Go up two levels to get the repo root\n if (import.meta.dirname) {\n return path.join(import.meta.dirname, '..', '..')\n }\n // Fallback for environments where import.meta.dirname isn't available\n return process.cwd()\n}\n\nexport function logAndExec(command: string, captureOutput = false): string {\n console.log(`$ ${command}`)\n if (captureOutput) {\n return cp.execSync(command, { stdio: 'pipe', encoding: 'utf-8' }).trim()\n } else {\n cp.execSync(command, { stdio: 'inherit' })\n return ''\n }\n}\n" }, { "path": "scripts/utils/release-pr.test.ts", "content": "import assert from 'node:assert/strict'\nimport { test } from 'node:test'\nimport type { PackageRelease } from './changes.ts'\nimport { generatePrBody } from './release-pr.ts'\n\nfunction makeRelease({\n packageDirName,\n packageName,\n nextVersion,\n}: {\n packageDirName: string\n packageName: string\n nextVersion: string\n}): PackageRelease {\n return {\n packageDirName,\n packageName,\n currentVersion: '1.0.0',\n nextVersion,\n bump: 'patch',\n changes: [{ file: 'patch.test-change.md', bump: 'patch', content: 'Test change' }],\n dependencyBumps: [],\n }\n}\n\ntest('generatePrBody puts remix first and sorts remaining packages alphabetically', () => {\n let body = generatePrBody([\n makeRelease({\n packageDirName: 'zeta',\n packageName: '@remix-run/zeta',\n nextVersion: '1.0.1',\n }),\n makeRelease({\n packageDirName: 'remix',\n packageName: 'remix',\n nextVersion: '3.0.0',\n }),\n makeRelease({\n packageDirName: 'beta',\n packageName: '@remix-run/beta',\n nextVersion: '1.0.1',\n }),\n makeRelease({\n packageDirName: 'alpha',\n packageName: '@remix-run/alpha',\n nextVersion: '1.0.1',\n }),\n ])\n\n let remixTableIndex = body.indexOf('| remix |')\n let alphaTableIndex = body.indexOf('| @remix-run/alpha |')\n let betaTableIndex = body.indexOf('| @remix-run/beta |')\n let zetaTableIndex = body.indexOf('| @remix-run/zeta |')\n\n assert.notEqual(remixTableIndex, -1)\n assert.notEqual(alphaTableIndex, -1)\n assert.notEqual(betaTableIndex, -1)\n assert.notEqual(zetaTableIndex, -1)\n assert.ok(remixTableIndex < alphaTableIndex)\n assert.ok(alphaTableIndex < betaTableIndex)\n assert.ok(betaTableIndex < zetaTableIndex)\n\n let remixChangelogIndex = body.indexOf('## remix v3.0.0')\n let alphaChangelogIndex = body.indexOf('## @remix-run/alpha v1.0.1')\n let betaChangelogIndex = body.indexOf('## @remix-run/beta v1.0.1')\n let zetaChangelogIndex = body.indexOf('## @remix-run/zeta v1.0.1')\n\n assert.notEqual(remixChangelogIndex, -1)\n assert.notEqual(alphaChangelogIndex, -1)\n assert.notEqual(betaChangelogIndex, -1)\n assert.notEqual(zetaChangelogIndex, -1)\n assert.ok(remixChangelogIndex < alphaChangelogIndex)\n assert.ok(alphaChangelogIndex < betaChangelogIndex)\n assert.ok(betaChangelogIndex < zetaChangelogIndex)\n})\n" }, { "path": "scripts/utils/release-pr.ts", "content": "import type { PackageRelease } from './changes.ts'\nimport { generateChangelogContent } from './changes.ts'\n\n// GitHub has a 65,536 character limit for PR body. We use 60,000 to be safe.\nlet maxBodyLength = 60_000\n\n/**\n * Generates the PR body for a release PR\n */\nexport function generatePrBody(releases: PackageRelease[]): string {\n let orderedReleases = sortReleasesForDisplay(releases)\n let header = generateHeader()\n let releasesTable = generateReleasesTable(orderedReleases)\n let changelogs = generateChangelogs(orderedReleases)\n\n let fullBody = [header, releasesTable, changelogs].join('\\n\\n')\n\n // If under limit, return full body\n if (fullBody.length <= maxBodyLength) {\n return fullBody\n }\n\n // Truncate changelogs section to fit\n let baseLength = header.length + releasesTable.length + 100 // buffer for truncation notice\n let availableForChangelogs = maxBodyLength - baseLength\n let truncatedChangelogs = truncateChangelogs(orderedReleases, availableForChangelogs)\n\n return [header, releasesTable, truncatedChangelogs].join('\\n\\n')\n}\n\nfunction sortReleasesForDisplay(releases: PackageRelease[]): PackageRelease[] {\n return [...releases].sort((a, b) => {\n let aIsRemix = a.packageDirName === 'remix'\n let bIsRemix = b.packageDirName === 'remix'\n\n if (aIsRemix && !bIsRemix) {\n return -1\n }\n\n if (!aIsRemix && bIsRemix) {\n return 1\n }\n\n return a.packageName.localeCompare(b.packageName)\n })\n}\n\nfunction generateHeader(): string {\n return [\n 'This PR is managed by the [`release-pr`](https://github.com/remix-run/remix/blob/main/.github/workflows/release-pr.yaml) workflow. ' +\n 'Do not edit it manually. ' +\n 'See [CONTRIBUTING.md](https://github.com/remix-run/remix/blob/main/CONTRIBUTING.md#releases) for more.',\n ].join('\\n')\n}\n\nfunction generateReleasesTable(releases: PackageRelease[]): string {\n let lines = ['# Releases', '', '| Package | Version |', '|---------|---------|']\n\n for (let release of releases) {\n lines.push(\n `| ${release.packageName} | \\`${release.currentVersion}\\` → \\`${release.nextVersion}\\` |`,\n )\n }\n\n return lines.join('\\n')\n}\n\nfunction generateChangelogs(releases: PackageRelease[]): string {\n let lines = ['# Changelogs']\n\n for (let release of releases) {\n lines.push('')\n lines.push(generatePackageChangelog(release))\n }\n\n return lines.join('\\n')\n}\n\nfunction generatePackageChangelog(release: PackageRelease): string {\n return generateChangelogContent(release, {\n includePackageName: true,\n headingLevel: 2,\n })\n}\n\nfunction truncateChangelogs(releases: PackageRelease[], maxLength: number): string {\n let lines = ['# Changelogs']\n let currentLength = lines.join('\\n').length\n let includedCount = 0\n\n for (let release of releases) {\n let changelog = '\\n\\n' + generatePackageChangelog(release)\n if (currentLength + changelog.length <= maxLength) {\n lines.push('')\n lines.push(generatePackageChangelog(release))\n currentLength += changelog.length\n includedCount++\n } else {\n break\n }\n }\n\n let omittedCount = releases.length - includedCount\n\n if (omittedCount > 0) {\n lines.push('')\n lines.push(\n `> ⚠️ ${omittedCount} changelog${omittedCount === 1 ? '' : 's'} omitted due to size limits. See the PR diff for full details.`,\n )\n }\n\n return lines.join('\\n')\n}\n" }, { "path": "scripts/utils/semver.ts", "content": "export type ReleaseType = 'major' | 'minor' | 'patch' | 'prerelease'\n\ntype ParsedVersion = {\n major: number\n minor: number\n patch: number\n prerelease: Array\n}\n\nconst semverPattern =\n /^(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$/\n\nfunction parse(version: string): ParsedVersion | null {\n let match = semverPattern.exec(version)\n if (match == null) {\n return null\n }\n\n let prerelease = match[4]\n ? match[4]\n .split('.')\n .filter(Boolean)\n .map((part) => (/^\\d+$/.test(part) ? Number(part) : part))\n : []\n\n return {\n major: Number(match[1]),\n minor: Number(match[2]),\n patch: Number(match[3]),\n prerelease,\n }\n}\n\nfunction format(version: ParsedVersion): string {\n let base = `${version.major}.${version.minor}.${version.patch}`\n\n if (version.prerelease.length === 0) {\n return base\n }\n\n return `${base}-${version.prerelease.join('.')}`\n}\n\nexport function major(version: string): number {\n let parsed = parse(version)\n if (parsed == null) {\n throw new Error(`Invalid semver version: ${version}`)\n }\n\n return parsed.major\n}\n\nexport function prerelease(version: string): Array | null {\n let parsed = parse(version)\n if (parsed == null) {\n throw new Error(`Invalid semver version: ${version}`)\n }\n\n return parsed.prerelease.length > 0 ? parsed.prerelease : null\n}\n\nexport function inc(version: string, releaseType: ReleaseType, identifier?: string): string | null {\n let parsed = parse(version)\n if (parsed == null) {\n return null\n }\n\n if (releaseType === 'major') {\n return format({\n major: parsed.major + 1,\n minor: 0,\n patch: 0,\n prerelease: [],\n })\n }\n\n if (releaseType === 'minor') {\n return format({\n major: parsed.major,\n minor: parsed.minor + 1,\n patch: 0,\n prerelease: [],\n })\n }\n\n if (releaseType === 'patch') {\n return format({\n major: parsed.major,\n minor: parsed.minor,\n patch: parsed.patch + 1,\n prerelease: [],\n })\n }\n\n if (identifier == null || identifier.trim() === '') {\n return null\n }\n\n let nextPrerelease = [...parsed.prerelease]\n\n if (nextPrerelease.length === 0 || nextPrerelease[0] !== identifier) {\n nextPrerelease = [identifier, 0]\n } else {\n let lastIndex = nextPrerelease.length - 1\n let lastPart = nextPrerelease[lastIndex]\n\n if (typeof lastPart === 'number') {\n nextPrerelease[lastIndex] = lastPart + 1\n } else {\n nextPrerelease.push(0)\n }\n }\n\n return format({\n major: parsed.major,\n minor: parsed.minor,\n patch: parsed.patch,\n prerelease: nextPrerelease,\n })\n}\n" } ]