bulletproof-web

name	bulletproof-web
description	Bulletproof React conventions for frontend apps in this repo. Use when creating, moving, or reviewing files in a frontend app — deciding folder placement, import paths, or how to compose a feature.

Bulletproof React conventions

Frontend apps in this repo follow Bulletproof React. When you add or move a file, place it by these rules.

Layout

src/
├── app/          Routes and layouts — thin
├── components/   Shared UI used across features
├── config/       Env and constants (non-JSX)
├── features/     Feature modules — most code lives here
│   └── <feature>/
│       ├── api/          Data access for this feature
│       ├── components/
│       ├── hooks/
│       ├── stores/
│       ├── types/
│       ├── utils/        Pure functions — unit-test these
│       └── index.ts      Public API
├── hooks/        Shared hooks only
├── lib/          Preconfigured clients (HTTP, query, web3)
├── types/
└── utils/

Rules

Rule	Detail
Thin routes	Route files compose features and do little else — no data fetching or business logic inline
Feature public API	Import across features only through features/<x>/index.ts, never reach into internals
Logic out of components	Domain and math logic goes in features/*/utils or lib/ so it tests without rendering; hooks wrap IO
Shared means shared	Something used by one feature belongs to that feature, not components/
No parallel layer schemes	Don't add screens/, widgets/, entities/, or a Pages-Router pages/ alongside this structure

When reviewing

Check placement before logic. A file in the wrong layer is a problem that compounds — features that import each other's internals get hard to move or delete later.

If a feature has grown enough that its index.ts exports a dozen things, that's a signal it's really two features.