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)

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

Then build and open a dev client:

npx expo run:ios
npx expo run:android

Using Other Package Managers

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

CLI Options

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

Example Variants

Only the base template ships in this repo. Use:

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.

npm run start

Then run a dev client when you need native modules:

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

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.