Imported from remix-run/remix (AGENTS.md). Install upstream with npx skills add remix-run/remix. Copyright stays with the author.

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

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.
• 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

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-components at .agents/skills/author-ui-components/SKILL.md: Build idiomatic packages/ui components, including first-party UI style mixins, headless primitives, styled component wrappers, and shared component utilities.
• 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.

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.