create-twinbloc-app 0.1.2 → 0.1.3

package/README.md

@@ -1,6 +1,20 @@
 # Create Twinbloc App
 
-Create a React Native app from the Twinbloc starter template (Expo + Expo Router).
+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
+- NativeWind + Tailwind utilities, themed UI primitives, and tokens
+- 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
 
@@ -8,7 +22,7 @@ Create a React Native app from the Twinbloc starter template (Expo + Expo Router
 - npm, yarn, pnpm, or bun
 - Xcode for iOS (macOS) and/or Android Studio for Android
 
-## Quick Start
+## Quick Start (npm)
 
 ```bash
 npx create-twinbloc-app@latest MyApp
@@ -16,6 +30,13 @@ 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
@@ -24,7 +45,7 @@ pnpm create twinbloc-app MyApp
 bun create twinbloc-app MyApp
 ```
 
-## Options
+## CLI Options
 
 ```bash
 npx create-twinbloc-app@latest MyApp --example base
@@ -35,16 +56,23 @@ npx create-twinbloc-app@latest MyApp --pm pnpm
 npx create-twinbloc-app@latest MyApp --pm bun
 ```
 
-## Running the App (Dev Client)
+### Example Variants
 
-This template uses a development build. After creating the project:
+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
-cd MyApp
 npm run start
 ```
 
-Then build and open a dev client:
+Then run a dev client when you need native modules:
 
 ```bash
 npx expo run:ios
@@ -57,19 +85,58 @@ npx expo run:android
 MyApp/
   app/              # Expo Router routes
   assets/           # Images and icons
-  src/              # App state and shared utilities
-  app.json          # Expo configuration
+  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        # NativeWind 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:
+
+- `EXPO_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
-- State: Zustand example in `src/state`
+- Styling: NativeWind + Tailwind utilities
+- 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.

package/bin/cli.js

@@ -68,6 +68,11 @@ const runInstall = (dir, pm) => {
 
 const brandPrimary = chalk.hex("#6CABDD");
 const brandDeep = chalk.hex("#1C2C5B");
+const rnBlue = chalk.hex("#61DAFB");
+const uiMuted = chalk.gray;
+const uiAccent = chalk.hex("#9FD7F2");
+const uiActive = chalk.hex("#88C6FF");
+const uiSelected = chalk.hex("#6EDC91");
 
 const printBanner = () => {
   const lines = [
@@ -83,6 +88,7 @@ const printBanner = () => {
     console.log(paint(line));
   });
   console.log(brandPrimary("React Native Starter"));
+  console.log(rnBlue("     ⚛  React Native  •  Expo + Router  •  TypeScript  •  Zustand"));
   console.log("");
 };
 
@@ -113,9 +119,9 @@ const getExistingAgentKeys = async (rootDir) => {
 const renderAgentSelection = (choices, selectedKeys, activeIndex) => {
   output.write("\x1b[2J\x1b[0;0H");
   printBanner();
-  console.log(brandPrimary.bold("Select agent configs to include:"));
-  console.log(brandDeep("Use ↑/↓ to move, space to toggle, enter to confirm."));
-  console.log(brandDeep("Press enter with nothing selected for none."));
+  console.log(brandPrimary.bold("Select agent configs to include"));
+  console.log(uiMuted("Use ↑/↓ to move, space to toggle, enter to confirm."));
+  console.log(uiMuted("Press enter with nothing selected for none."));
   console.log("");
 
   choices.forEach((choice, index) => {
@@ -124,7 +130,15 @@ const renderAgentSelection = (choices, selectedKeys, activeIndex) => {
     const cursor = isActive ? ">" : " ";
     const mark = isSelected ? "x" : " ";
     const line = `${cursor} [${mark}] ${choice.label}`;
-    console.log(isActive ? brandPrimary.bold(line) : brandDeep(line));
+    if (isActive) {
+      console.log(uiActive.bold(line));
+      return;
+    }
+    if (isSelected) {
+      console.log(uiSelected(line));
+      return;
+    }
+    console.log(uiAccent(line));
   });
 };
 
@@ -230,16 +244,16 @@ const main = async () => {
     [
       brandPrimary.bold("Project created successfully."),
       "",
-      brandDeep(`Agent configs: ${selectedLabels.length > 0 ? selectedLabels.join(", ") : "none"}`),
+      uiMuted(`Agent configs: ${selectedLabels.length > 0 ? selectedLabels.join(", ") : "none"}`),
       "",
-      brandPrimary("Next steps:"),
-      brandDeep(`  cd ${appName}`),
-      options.skipInstall ? brandDeep("  npm install") : null,
-      brandDeep("  npm run start"),
+      brandPrimary("Next steps"),
+      uiAccent(`  cd ${appName}`),
+      options.skipInstall ? uiAccent("  npm install") : null,
+      uiAccent("  npm run start"),
       "",
-      brandPrimary("Then:"),
-      brandDeep("  - Build a dev client (if you haven’t): npx expo run:ios / npx expo run:android"),
-      brandDeep("  - Open the app from the dev client on your device or simulator"),
+      brandPrimary("Then"),
+      uiMuted("  - Build a dev client (if you haven’t): npx expo run:ios / npx expo run:android"),
+      uiMuted("  - Open the app from the dev client on your device or simulator"),
     ]
       .filter(Boolean)
       .join("\n"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-twinbloc-app",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "React Native starter template with optional examples",
   "type": "module",
   "bin": {