agentleFS
Sign inStart free
wataru-maedawataru-maeda/react-native-boilerplate/AGENTS.md

react-native-boilerplate

AGENTS.md521 starsChanged 15 days agoMITView on GitHub

See README for setup and structure. Use Node ≥24 and npm ≥11. Run from the repository root. Each environment has its own env file and script prefix: Copy .env.<env>.example to create each file. Each environment uses its own EAS project through EXPOPROJECTID. The commands below use dev. Replace it with stg or prod for the other environments.

  • Reads credentials

We split this AGENTS.md into the rules it gives an agent

37 rules. About 0 are common, 6 are distinctive, and 31 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 31

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use Node ≥24 and npm ≥11.

    line 5
  2. Distinctive:

    Verify rules against code.

    line 9
  3. Very specific:

    Use manage-docs before editing README.md, AGENTS.md, or skills in .agents/skills.

    line 10
  4. Very specific:

    Keep secrets out of git. Write variable names to .env.*.example only.

    line 11
  5. Very specific:

    Import with @/, which maps to src/.

    line 16
  6. Distinctive:

    Use function declarations for components.

    line 18
  7. Very specific:

    Keep console.log out of production code.

    line 20
  8. Very specific:

    Put screens in src/scenes/<name>/<Name>.tsx.

    line 24
  9. Very specific:

    Put reusable controls in src/components/elements/.

    line 25
  10. Very specific:

    Use Expo Router for navigation.

    line 27
  11. Very specific:

    Import navigation helpers such as DrawerActions from expo-router/react-navigation.

    line 28
  12. Very specific:

    Use StyleSheet.create. Read colors, fonts, and images from @/theme.

    line 29
  13. Very specific:

    Import SafeAreaView from react-native-safe-area-context.

    line 31
  14. Very specific:

    Read app settings from @/utils/config.

    line 35
  15. Very specific:

    Add a new environment variable in three places: .env.*.example, extra in app.config.ts, and src/utils/config.ts.

    line 36
  16. Very specific:

    Treat values in extra as public.

    line 37
  17. Very specific:

    Read platform and dimensions from @/utils/deviceInfo.

    line 38
  18. Very specific:

    Use useAppSlice from @/slices for shared app state.

    line 39
  19. Very specific:

    Use useDataPersist from @/hooks for local storage.

    line 40
  20. Very specific:

    Call APIs through @/services.

    line 44
  21. Very specific:

    Put each resource in src/services/<resource>.service.ts with <action><Resource>Async functions.

    line 45
  22. Very specific:

    Add Expo and React Native packages with npx expo install <package> so versions match the SDK.

    line 50
  23. Very specific:

    Run npm run dev:doctor after changing dependencies.

    line 51
  24. Very specific:

    Place *.test.tsx beside each new component.

    line 56
  25. Very specific:

    Use React Native Testing Library.

    line 57
  26. Very specific:

    Add a Maestro flow in .maestro/ for each new screen or user flow.

    line 58
  27. Very specific:

    Start each flow with runFlow: subflows/launch.yaml.

    line 59
  28. Distinctive:

    Run from the repository root.

    line 63
  29. Very specific:

    Start: npm run dev. Use dev:ios, dev:android, or dev:web for one platform.

    line 74
  30. Very specific:

    Check Expo setup: npm run dev:doctor.

    line 75
  31. Very specific:

    Test: npm run test. Watch: npm run test:watch.

    line 88
  32. Very specific:

    Run E2E flows: npm run e2e or npm run e2e:android.

    line 89
  33. Distinctive:

    Run only requested Git operations.

    line 93
  34. Very specific:

    Never commit directly to dev, stg, or main.

    line 94
  35. Distinctive:

    Keep each branch and commit focused.

    line 95
  36. Very specific:

    Use dev for development, stg for staging, and main for production.

    line 100
  37. Very specific:

    After a hotfix reaches main, merge main back into stg and dev with merge commits.

    line 125

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

React Native Boilerplate Rules

See README for setup and structure.

Use Node ≥24 and npm ≥11.

Before Editing

  • Verify rules against code. Correct outdated rules.
  • Use manage-docs before editing README.md, AGENTS.md, or skills in .agents/skills.
  • Keep secrets out of git. Write variable names to .env.*.example only.

Code

  • Reuse existing components, hooks, and utilities.
  • Import with @/, which maps to src/. Keep TypeScript strict.
  • Export props of reusable elements as interface <Component>Props. Import shared types from @/types.
  • Use function declarations for components. Call hooks before early returns.
  • Name components and types in PascalCase. Name utilities in camelCase. Prefix hooks with use.
  • Keep console.log out of production code.

Screens and Styles

  • Put screens in src/scenes/<name>/<Name>.tsx. Keep src/app/ files limited to routing and layouts.
  • Put reusable controls in src/components/elements/. Put navigation and sheet layouts in src/components/layouts/.
  • Give each component its own folder with <Name>.tsx and an index.ts that re-exports it.
  • Use Expo Router for navigation. Use <Redirect> for rendered redirects. Use router.push or router.replace in event handlers.
  • Import navigation helpers such as DrawerActions from expo-router/react-navigation. Import themes from expo-router. Do not add @react-navigation/* packages.
  • Use StyleSheet.create. Read colors, fonts, and images from @/theme.
  • Support dark and light mode with useColorScheme from @/hooks/useColorScheme.
  • Import SafeAreaView from react-native-safe-area-context.

State and Configuration

  • Read app settings from @/utils/config. Do not hardcode environment values.
  • Add a new environment variable in three places: .env.*.example, extra in app.config.ts, and src/utils/config.ts.
  • Treat values in extra as public. They ship inside the app bundle.
  • Read platform and dimensions from @/utils/deviceInfo.
  • Use useAppSlice from @/slices for shared app state. Add new state as a slice in src/slices/ and register it in src/utils/store.ts.
  • Use useDataPersist from @/hooks for local storage. Use useKeyboard from @/hooks for keyboard state.

API Calls

  • Call APIs through @/services. Do not call APIs directly from components.
  • Put each resource in src/services/<resource>.service.ts with <action><Resource>Async functions. Export it from src/services/index.ts.
  • Handle loading and errors. Show readable error messages.

Dependencies

  • Add Expo and React Native packages with npx expo install <package> so versions match the SDK.
  • Run npm run dev:doctor after changing dependencies.
  • Load env files with dotenvx run -f .env.<env>. Do not add dotenv-cli.

Tests

  • Place *.test.tsx beside each new component. Test behavior, including success and failure.
  • Use React Native Testing Library. Await render and user events. Mock external dependencies.
  • Add a Maestro flow in .maestro/ for each new screen or user flow. Target elements by testID.
  • Start each flow with runFlow: subflows/launch.yaml.

Commands

Run from the repository root. Each environment has its own env file and script prefix:

EnvironmentEnv filePrefixENVEAS build profile
Development.env.devdevdevdevelopment
Staging.env.stgstgstgstaging
Production.env.prodprodprodproduction

Copy .env.<env>.example to create each file. Each environment uses its own EAS project through EXPO_PROJECT_ID. The commands below use dev. Replace it with stg or prod for the other environments.

  • Start: npm run dev. Use dev:ios, dev:android, or dev:web for one platform.
  • Check Expo setup: npm run dev:doctor.
  • Show loaded config: npm run dev:config:public.
  • Build and run native apps locally: npm run dev:run:ios or npm run dev:run:android.
  • Build with EAS: npm run dev:build:mobile. It uploads .env.dev to the EAS project first.
  • Build and deploy web: npm run dev:deploy:web. prod:deploy:web deploys to the production alias.

ios/ and android/ are generated and ignored by git. Delete them before <env>:run:* after changing env files or app.config.ts.

Checks

  • Check types: npm run check-types.
  • Lint: npm run lint.
  • Rewrite formatting: npm run format.
  • Test: npm run test. Watch: npm run test:watch.
  • Run E2E flows: npm run e2e or npm run e2e:android. They use .env.dev. Install the app with dev:run:* first and keep Metro running.

Git

  • Run only requested Git operations.
  • Never commit directly to dev, stg, or main.
  • Keep each branch and commit focused.
  • Submit changes through a PR. Use manage-prs.

Branches

Use dev for development, stg for staging, and main for production. dev is the default branch.

ChangeBranchStart fromMerge into
Featurefeat/<name>devdev
Fixfix/<name>devdev
Refactorrefactor/<name>devdev
Dependencies, SDKchore/<name>devdev
Docsdocs/<name>devdev
Stagingdev—stg
Releasestg—main
Production fixhotfix/<name>mainmain, then stg and dev

Commits

Use type(scope): description.

  • Types: feat, fix, docs, style, refactor, test, chore.
  • Scopes are optional: deps, ios, android, web, ci.
  • The pre-commit hook runs lint, format, and tests on staged files.

Merge and Version

  • Squash merge work branches into dev.
  • Promote with merge commits: open a PR from dev to stg, test the staging build, then open a PR from stg to main.
  • After a hotfix reaches main, merge main back into stg and dev with merge commits.
  • Bump version in package.json on dev before promoting a release.
  • Tag releases as vMAJOR.MINOR.PATCH on main. Use manage-prs to publish them.
  • Increment major for Expo SDK upgrades and breaking changes, minor for features, and patch for fixes.

Download now (ZIP)

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository5 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free