building-react-native-application

React Native application

Overview

Opinionated ecosystem for building Expo/React Native apps with a consistent architecture, library stack, and UI system (src/ui).

Tech stack

Layer	Choice
Runtime	Expo
Language	TypeScript
Styling	NativeWind, Tailwind CSS, class-variance-authority
Routing	React Navigation (static config, src/routes)
Server state	TanStack Query
Client global state	Zustand
HTTP	Axios
Dates	date-fns (src/libs/date-utils/)
Presentational UI	React Native Reusables-style primitives in src/ui/

Setup

Item	Required	When	How
Standing rule	required	Scaffold new app	Add - `<target_path>` follows building-react-native-application; load it before changing code there. to root AGENTS.md (create when missing) and to root CLAUDE.md when it exists without importing AGENTS.md; skip a file that has it

Agent workflow

Follow this skill for Expo/React Native work. Resolve every required Setup row, then match Entry points and every applicable Task types row; open every linked local reference before coding. For component work, open creating-component and follow its decision tree. Platform docs live in each reference’s References section.

Entry points

Use the first matching row; combine when the task spans types.

Entry	When	Go to
Component	Building, moving, or recategorizing any component	creating-component
Structure	Folder roles, dependency flow, or where a module belongs	managing-project-structure
Task bundle	API, forms, styling, bootstrap, navigation, keyboard, fonts, splash	Task types table
Lookup	Known doc name or single reference	Reference index

Task types

Match every row that applies. Open every local link in Docs before coding.

Task type	Docs
New screen / feature	managing-project-structure, creating-feature, creating-route-component, creating-screen-component, creating-component
UI primitive (src/ui/)	creating-component, creating-ui-component, discovering-registry-components, managing-wrapper-components, add-registry-component.cjs
Feature component	creating-component, creating-feature-component, managing-wrapper-components
Bottom sheet	creating-component, creating-bottom-sheet-component, managing-wrapper-components
Async / list UI	creating-component, creating-async-component, creating-api, managing-state
Form (single step)	creating-form-component, managing-form-error, managing-state, managing-date
Multi-step form	managing-stepper-hook, managing-stepper-form, creating-form-component, managing-form-error
API + data hooks	creating-api, setting-up-axios, managing-api-error, managing-state, managing-date
Date / time	managing-date
Refactor / move component	creating-component
Styling / theme	setting-up-nativewind, managing-styling, setting-up-theming, setting-up-tailwind-theme, setting-up-navigation-theme, overriding-classname
Navigation components & backgrounds	creating-navigation-component, setting-up-navigation-theme, managing-screen-background
Navigation hooks	creating-route-component, creating-navigation-component
Keyboard	Keyboard controller — Components
Fonts	setting-up-theming, setting-up-tailwind-theme, Expo — Fonts
Splash screen	Expo — SplashScreen
Scaffold new app	scaffolding-application
Project bootstrap	managing-project-structure, managing-environment, managing-linting, managing-package-installs, setting-up-nativewind, setting-up-registry-components
Routing only	creating-route-component, creating-navigation-component

Reference index

Reference	Entry	Layer	Purpose
creating-api		API	HTTP modules under src/api/
creating-async-component		Component	Loading, error, and list UI wrappers
creating-bottom-sheet-component		Component	Bottom sheet UI in src/ui/BottomSheet/
creating-component	Component	Component	Decision tree for any component work
creating-feature		Feature	Feature module folders and barrels
creating-feature-component		Component	Domain UI blocks in features
creating-form-component		Form	Form fields and form shells
creating-navigation-component		Route	Reusable headers, tab bars, drawer content
creating-route-component		Route	[Name][NavigatorType] modules in src/routes/
creating-screen-component		Feature	Route-facing *Screen in features
creating-ui-component		Component	Shared primitives in src/ui/
discovering-registry-components		Component	Registry lookup by intent and labels
managing-api-error		API	API error handling patterns
managing-date		Date	date-fns and src/libs/date-utils/
managing-environment		Setup	Feature env.ts and env vars
managing-form-error		Form	Form validation and error display
managing-linting		Setup	ESLint and Prettier setup
managing-package-installs		Setup	Package manager detection and install scripts
managing-project-structure	Structure	Architecture	Folder layout and dependency flow
managing-screen-background		Route	Screen background vs navigation theme
managing-state		State	TanStack Query hooks and Zustand stores
managing-stepper-form		Form	Multi-step form UI
managing-stepper-hook		Form	Multi-step form state hook
managing-styling		Styling	Styling conventions and tokens
managing-wrapper-components		Component	Wrapper and composition patterns
overriding-classname		Styling	className override rules
scaffolding-application		Setup	Expo blank-typescript scaffold
setting-up-axios		API	Axios client setup
setting-up-nativewind		Styling	NativeWind install; pnpm isolated JSX runtime
setting-up-navigation-theme		Styling	React Navigation theme objects
setting-up-registry-components		Setup	Registry / src/ui/ bootstrap
setting-up-theming		Styling	Design tokens and theme CSS
setting-up-tailwind-theme		Styling	Tailwind / NativeWind theme config