rails-native

Opinionated React Native app generator — "Rails for React Native."

This is currently a pre-alpha release and has not been tested on mobile applications (coming) and has bare functionality. It is not ready for productionn at this time.

rails-native is a CLI (rn) that scaffolds a cross-platform (iOS / Android / web) Expo app with sensible defaults already wired up: email + Google auth, a swappable token-based theme, unit + component tests, and a green CI pipeline. Generate an app, then keep using rn inside it to scaffold screens, components, and hooks.

Published on npm as rails-native.

Install

npm install -g rails-native
# or run without installing:
npx rails-native new myapp

Requires Node 22+.

Usage

rn new <app-name> [options]       Generate a new app
rn doctor                         Validate a generated app's environment (run inside it)
rn test [--no-typecheck]          Run the app's unit tests + typecheck (run inside it)
rn generate <type> <name>         Scaffold a component, screen, or hook + test (alias: rn g)

rn new options

Flag	Effect
--mock	Use the offline mock auth adapter (skip Supabase)
--no-ci	Don't generate GitHub Actions CI
--bundle-id <id>	Native bundle identifier (default: com.railsnative.<app>)
--no-install	Skip npm install
--no-git	Skip git init
-h, --help	Show help
-v, --version	Show version

Examples

rn new myapp                  # Full stack: Supabase + GitHub Actions
rn new myapp --mock           # Local-only, no backend needed
rn new myapp --no-ci --mock   # Bare minimum

What you get

Every generated app is built around three swappable seams, each with an escape hatch (full detail ships in the app's own README):

• Auth — all app code depends on src/auth/AuthAdapter.ts. Default is SupabaseAuthAdapter; swap in your own by implementing the port, or use the offline mock adapter.
• Styling — screens use only the primitives in src/components/ui/, driven by src/theme/tokens.ts. Reskinning is a token edit; screens never change.
• CI — pipeline stages live in scripts/ci/*.sh, wrapped by GitHub Actions by default. Set ci: 'none' to drive them from any CI system.

The generator refuses to invent identifiers you didn't type — e.g. rn generate hook requires the use prefix rather than silently adding it. No surprises.

Development

npm run build     # tsc → dist/
npm test          # node:test suite over src/**/*.test.ts
npm run dev -- new myapp   # run the CLI from source (tsx, no build)

The CLI's own tests use node:test. Template files are never run by the repo's test suite — they target Expo + React 19 and only run inside a generated app via rn test. Correctness of template changes is proven by dogfooding: generate an app and run rn test in it.

Architecture

src/
  index.ts          CLI entry / arg parsing
  commands/         new, doctor, test, generate
  engine/           generation engine — walk, resolve, substitute, plan, write, pkg…
  manifest.ts       file/feature manifest driving what gets generated
template/           the app that gets scaffolded (copied + templated into new apps)
docs/superpowers/   specs & implementation plans (one per feature slice)

Feature work follows a slice workflow: brainstorm → spec → plan → implement (TDD / subagent-driven) → dogfood → release. Specs and plans live under docs/superpowers/.

Releasing

Publishing is manual (npm 2FA). Bump version in package.json, commit, then:

npm run build && npm publish --access public

Generated apps devDep rails-native, so CLI changes reach new apps only after a re-publish.