Create Twinbloc App

Create a React Native app with the Twinbloc starter template. This CLI scaffolds a production-ready Expo SDK 54 project with Expo Router, TypeScript, native modules, and a curated set of defaults for state, API, UI, and localization.

What You Get

- Expo SDK 54 project with Expo Router and typed routes
- React Native 0.81 + React 19 setup
- TypeScript-first structure with strict TS config
- UniWind (Universal Tailwind) for styling
- Built-in AI Agent Skills (Cursor, Copilot, Trae, Windsurf, etc.)
- Zustand store examples with persisted auth state
- TanStack Query with MMKV persistence
- Axios API client with auth-aware helpers
- i18next localization with English, Spanish, French, and Arabic samples
- Reanimated-ready bottom sheet provider and gesture handler setup
- Toasts, haptics, blur, image, and icon tooling prewired
- Environment-driven app config for name, slug, scheme, bundle IDs

Requirements

- Node.js 18+
- npm, yarn, pnpm, or bun
- Xcode for iOS (macOS) and/or Android Studio for Android

Quick Start (npm)

``bash
npx create-twinbloc-app@latest MyApp
cd MyApp
npm run start
`

Then build and open a dev client:

`bash
npx expo run:ios
npx expo run:android
`

Using Other Package Managers

`bash
yarn create twinbloc-app MyApp
pnpm create twinbloc-app MyApp
bun create twinbloc-app MyApp
`

CLI Options

`bash
npx create-twinbloc-app@latest MyApp --example base
npx create-twinbloc-app@latest MyApp --skip-install
npx create-twinbloc-app@latest MyApp --pm npm
npx create-twinbloc-app@latest MyApp --pm yarn
npx create-twinbloc-app@latest MyApp --pm pnpm
npx create-twinbloc-app@latest MyApp --pm bun
`

$3

Only the base template ships in this repo. Use:

`bash
npx create-twinbloc-app@latest MyApp --example base
`

Running the App

This starter includes native modules, so you should use a development build instead of Expo Go.

`bash
npm run start
`

Then run a dev client when you need native modules:

`bash
npx expo run:ios
npx expo run:android
`

Project Structure

`
MyApp/
app/ # Expo Router routes
assets/ # Images and icons
src/
api/ # Axios client and React Query helpers
components/ # UI components and providers
hooks/ # App hooks
lib/ # i18n, env, storage, utilities
store/ # Zustand stores
translations/ # i18n resource files
app.config.ts # Env-driven Expo config
global.css # UniWind globals
package.json # Scripts and dependencies
tsconfig.json # TypeScript config
`

Environment Configuration

The template loads environment values from .env.{APP_ENV} and .env with APP_ENV=development|staging|production.

Required by default:

- PUBLIC_API_URL for your API base URL

Optional overrides:

- APP_NAME, APP_SLUG, APP_SCHEME
- APP_BUNDLE_ID_DEVELOPMENT, APP_BUNDLE_ID_STAGING, APP_BUNDLE_ID_PRODUCTION
- APP_PACKAGE_DEVELOPMENT, APP_PACKAGE_STAGING, APP_PACKAGE_PRODUCTION

Values are validated on startup. If you update .env files and still see errors, restart the dev server with -c to clear cache.

Scripts

`bash
npm run start # Expo dev server
npm run ios # Build iOS dev client
npm run android # Build Android dev client
npm run web # Run web build
npm run lint # Lint project
npm run test # Jest tests
npm run reset-project # Move starter to app-example and create a fresh app
`

Template Details

- Location: template/react-native-starter
- Framework: Expo SDK 54 + Expo Router
- Styling: UniWind
- AI Readiness: Built-in Agent Skills support
- State: Zustand stores in src/store
- Data: TanStack Query helpers in src/api
- i18n: src/lib/i18n and src/translations

Troubleshooting

- If install fails, retry with --pm` to force a package manager.
- If the folder is not empty, choose a new directory name.
- If your app launches but native modules crash, rebuild the dev client.