AGENTS.md · remix-run/remix

Sections

1. Repo Shape
2. Git Workflow
3. Default Development Loop
4. Code Style
5. Tests And Docs
6. GitHub
7. Release Notes
8. Repo Skills
9. App And Demo Skills

First lines (shown under the repo's MIT license)

# Remix Agent Guide

This repository includes the source code for Remix 3, a web framework for building modern web applications using TypeScript/JavaScript and web standard APIs.

## Repo Shape

- **Monorepo**: pnpm workspace with most product code under `packages/`
- **Public API layout**: every `exports` entry in `package.json` should map to a dedicated top-level `src/*.ts` file
- **Implementation layout**: `src/lib` is implementation-only; do not add barrel re-exports or thin pass-through wrappers inside `src/lib`
- **Cross-package boundaries**: do not re-export APIs or types from another package; import from the owning package directly
- **Platform stance**: prefer Web APIs and standards-aligned primitives over Node-specific APIs whenever possible

## Git Workflow

- **Worktrees**: do your work in a dedicated git worktree, not the main checkout. Don't nest worktrees inside the main checkout; they inherit its config files like `.oxlintrc.json`, which breaks `oxlint`
- **Main checkout**: leave the main Remix checkout on `main` and do not check out `main` in any other worktree; git only allows a branch to be checked out in one worktree at a time
- **Cleanup**: remove a worktree with `git worktree remove <path>` once its branch is merged or abandoned
- **Branch names**: use `<author>/<pr-description>`, where `author` is the GitHub username of the person making the commit and `pr-description` is a few meaningful, hyphen-separated words describing the pull request, for example `mjackson/fix-flaky-bun-test`

## Default Development Loop

- **Fast local loop**: `pnpm run validate-package-meta`, `pnpm run lint`, `pnpm run test:changed`, `pnpm run typecheck:changed`
- **Full CI-style validation**: `pnpm test` and `pnpm run typecheck`
- **When to use full runs locally**: broad cross-workspace changes, shared root config changes, release/publish flow changes, or anything that could affect the whole repo
- **Single package commands**: `pnpm --filter @remix-run/<package> run test --quiet`, `pnpm --filter @remix-run/<package> run typecheck`, `pnpm --filter @remix-run/<package> run build`
- **Single test file**: `cd packages/<package> && pnpm test --quiet src/**/<filename>.test.ts`
- **Scoped test names**: add `--only '<suite-or-test-regex>'` to focus tests by full suite/test name without editing source, for example `pnpm test --quiet --only 'loader redirects'`
- **Lint**: `pnpm run lint` or `pnpm run lint:fix`
- **Format**: `pnpm run format` or `pnpm run format:check`

The changed-workspace commands default to diffing against `origin/main` and include uncommitted working tree changes when `head-ref` is `HEAD`.

## Code Style

- **Imports**: use `import type { X }` and `export type { X }`; include `.ts` extensions
- **Variables**: use `let` for locals, `const` for module scope, never `var`
- **Functions**: use regular functions by default; use arrow functions for callbacks; use concise arrow bodies when they only return an expression
- **Object methods**: use shorthand method syntax
- **Classes**: omit TS accessibility modifiers; use native fields and `#private`
- **Generics**: use descriptive lowercase names like `source`, `pattern`, or `method`
- **Comments**: add non-JSDoc comments only when behavior is surprising or non-obvious
- **Formatting**: Oxfmt with `printWidth: 100`, no semicolons, single quotes, spaces not tabs

## Tests And Docs

- **Tests run from source**: no build step required
- **Test structure**: do not generate tests inside `describe()` with loops or conditionals; it breaks per-test IDE execution
- **Test guidance**: use the `write-tests` skill when adding, refactoring, or reviewing tests, fixtures, test scripts, or test-only dependencies
- **Docs and examples**: if you change a public API, update the related docs, JSDoc, README examples, and tests in the same change
- **README/install conventions**: use `npm i remix` in install snippets and import from `remix`, not `@remix-run/*`
- **README link conventions**: use full GitHub URLs for cross-file or cross-package repo links so copied docs render correctly; keep same-document anchors and README self-links relative

## GitHub

- **GitHub work**: when commenting on issues or pull requests, inspecting GitHub state, or otherwise working with GitHub, always use the `gh` command line tool when possible instead of an agent-specific connector
- **Agent attribution**: do not identify, credit, or attribute work to yourself or any other AI or agentic tool in commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar agent-specific attribution. Present the work transparently in terms of the changes made and their rationale.

## Release Notes

- If a change affects published packages, add or update the appropriate change file.
- Package `.changes/` directories are optional. Create `packages/<package>/.changes/` on demand when adding a change file or prerelease config.
- Prerelease channels come from `packages/*/.changes/config.json` and control the version suffix such as `alpha` or `beta`; prerelease packages still publish to the npm `next` dist-tag.
- If you modify release or publish flow code, validate it with the preview or dry-run scripts before finishing.

## Repo Skills

For work on this repository itself, use the skills in `.agents/skills/`:

- `add-package` at `.agents/skills/add-package/SKILL.md`: Create or align a package under `packages/` with repo conventions.
- `author-ui-primitives` at `.agents/skills/author-ui-primitives/SKILL.md`: Build idiomatic headless primitives under `packages/ui`, including accessibility behavior and required structural styles.
- `fix-issue` at `.agents/skills/fix-issue/SKILL.md`: Fix bugs reported in GitHub issues.
- `make-changes` at `.agents/skills/make-changes/SKILL.md`: Create or update package change files under `packages/*/.changes`.
- `make-decision-doc` at `.agents/skills/make-decision-doc/SKILL.md`: Add a numbered decision document under `decisions/` capturing a non-obvious architectural choice.
- `make-demo` at `.agents/skills/make-demo/SKILL.md`: Create or revise demos in this repository with production-quality Remix patterns.
- `make-pr` at `.agents/skills/make-pr/SKILL.md`: Prepare and open clear, reviewer-friendly pull requests.
- `make-tracking-issue` at `.agents/skills/make-tracking-issue/SKILL.md`: Create or revise focused GitHub tracking issues with implementor context, a concise work plan, and required gates.
- `publish-placeholder-package` at `.agents/skills/publish-placeholder-package/SKILL.md`: Publish a `0.0.0` placeholder package to reserve an npm name.
- `review-pr` at `.agents/skills/review-pr/SKILL.md`: Review Remix pull requests from a local checkout.
- `remix` at `.agents/skills/remix/SKILL.md`: Build, review, and refactor Remix apps end to end, including project layout, routes, controllers, middleware, validation, data access, auth, sessions, uploads, UI, hydration, navigation, animations, and tests.
- `supersede-pr` at `.agents/skills/supersede-pr/SKILL.md`: Replace one pull request with another and close the superseded PR safely.
- `typescript-expert` at `.agents/skills/typescript-expert/SKILL.md`: Write, refactor, or review TypeScript with strict, precise, maintainable types.
- `update-pr` at `.agents/skills/update-pr/SKILL.md`: Rewrite an existing pull request title and body to match the current diff.
- `write-api-docs` at `.agents/skills/write-api-docs/SKILL.md`: Write or tighten JSDoc for exported public APIs.
- `write-readme` at `.agents/skills/write-readme/SKILL.md`: Draft or revise package READMEs in the repo's style.
- `write-tests` at `.agents/skills/write-tests/SKILL.md`: Write, refactor, or review tests with repo runner, fixture, assertion, dependency, and validation conventions.
- `write-ui-module-readme` at `.agents/skills/write-ui-module-readme/SKILL.md`: Write concise module README files for `packages/ui/src/lib/*` primitives.
- `write-ui-examples` at `.agents/skills/write-ui-examples/SKILL.md`: Design, document and review focused UI library examples, including an adversarial product UX review.

## App And Demo Skills

For working on Remix code in demos or writing Remix app code, use the root `remix` skill listed above.

The CLI prepack step copies `.agents/skills/remix` into the default app template so scaffolded apps can refer to `./.agents/skills/remix/SKILL.md`.