# React Stack

> Applies the user's Bun-based React stack across Next.js web and Expo universal profiles, deferring backend and repository details to their domain skills. Use when scaffolding a React app, upgrading dependencies, choosing MVP tooling, or selecting a project profile.

- Skill: `frostney/react-stack` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add frostney/react-stack`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frostney/react-stack/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: Unlicense OR MIT
- Author: frostney (https://skillmd.com/u/frostney)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frostney/react-stack

---


# React stack

Apply only decisions material to the requested work. Preserve valid project
choices; do not turn a narrow change into a stack or layout migration.

## Select the profile

| Profile | Use when |
| --- | --- |
| Web | Next.js App Router; server-rendered/static web; SEO; Vercel |
| Universal | Expo Router; mobile-first iOS, Android, and web |

Document the choice in project context. If neither fits, follow the project's
AGENTS.md instead of forcing this stack. Read the matching profile reference
before scaffolding, routing, styling, deployment, or a framework upgrade:

- [references/web.md](references/web.md)
- [references/universal.md](references/universal.md)

## Shared decisions

- Bun is the only runtime/package manager; keep `bun.lock` and forbid other
  package-manager lockfiles.
- Use `typescript-stack/SKILL.md` for compiler configuration, type and API design,
  module boundaries, language-level code style, and TypeScript validation.
- Biome owns lint, format, and import ordering.
- `bun test` unit tests are co-located with source. End-to-end tests live in
  root `e2e/`.
- Source lives under `src/` by domain. `src/app/` contains framework routes only.
- Components use Atomic Design folders (`atoms`, `molecules`, `organisms`) with
  downward-only dependencies and co-located companions.
- Convex owns application data; Clerk owns identity. Use
  `convex-conventions/SKILL.md` for backend policy.
- Clerk Billing is the default; use Stripe only for a documented capability gap.
- Vercel AI Gateway is the default AI lane. Use a native provider only for a
  verified unsupported capability and isolate the exception.
- Use Zod outside Convex and Convex validators inside it.
- Knip checks dead code; Fallow reports complexity and churn hotspots.
- Use Portless for stable worktree-aware local URLs.
- Use `.env.local` for solo work and Doppler once a team shares secrets.

Read [references/shared-tooling.md](references/shared-tooling.md) when
scaffolding layout, observability, generators, hooks, or package scripts.
`project-structure/SKILL.md` owns language-neutral repository policy.

## Evidence and boundaries

- Verify dependency versions and release status live before adding or upgrading
  them; read migration notes for framework, Convex, and Clerk version jumps.
- Confirm Bun and framework/native-package compatibility on the deployment
  target.
- A single `bun run check` runs the project's format, lint, tests, typecheck,
  dead-code/health checks, and build as applicable.
- After dependency changes, run a frozen install plus the check and production
  build on the target runtime.
- If this skill does not prescribe a category, recommend a current
  Vercel-friendly option with its version, fit, and tradeoffs. Wait for the user
  before adding that new product or service.

Do not claim completion without observing the relevant project gate.