create-du-app 0.1.2 → 0.1.4

package/README.md

@@ -1,64 +1,84 @@
 # create-du-app
 
-> The `create-app` CLI — scaffolds a standalone product monorepo from company templates.
+> Scaffold a standalone product monorepo from company templates — in one command.
 
-Prompts for a project name and a selection of stacks (Mobile / Frontend / Backend), then copies
-the matching templates, renames manifests, substitutes the project name, and emits a ready-to-run
-pnpm workspace.
+Run it, answer a couple of prompts (project name + which stacks), and you get a ready-to-run
+pnpm monorepo with only the stacks you picked.
 
-## Installation
+## Quick start
+
+No install needed. In a real terminal (Terminal.app / iTerm):
 
 ```bash
-cd packages/cli
-pnpm install
-pnpm link --global   # registers the global `create-app` command
+npx create-du-app
 ```
 
-Or run without linking:
+You'll be asked:
+
+1. **Project name?** → e.g. `my-shop`
+2. **Select the groups** → press **`Space`** to tick Mobile / Frontend / Backend, then **`Enter`**
+3. **Pick one technology** per group → **↑ / ↓** then **`Enter`**
+
+Then:
 
 ```bash
-node src/index.js
+cd my-shop && pnpm install
 ```
 
-## Usage
+Done. 🎉
 
-**Interactive** (requires a real terminal):
+## Non-interactive (CI / IDE terminals)
+
+Pass everything as flags — no prompts, works anywhere:
 
 ```bash
-create-app
+npx create-du-app --name my-shop --mobile expo --fe nextjs --be nestjs
 ```
 
-**Non-interactive** (CI or any terminal):
+| Flag | Values | Required |
+|------|--------|----------|
+| `--name` | your project name | ✅ |
+| `--mobile` | `rn` · `expo` · `flutter` | optional |
+| `--fe` | `nextjs` · `reactjs` | optional |
+| `--be` | `nodejs` · `nestjs` · `php` | optional |
+
+## Install globally (optional)
+
+Scaffold often? Install once so you don't re-download it each time:
 
 ```bash
-create-app --name my-shop --mobile expo --fe nextjs --be nestjs
+npm install -g create-du-app     # or: pnpm add -g create-du-app
+create-du-app                    # same as npx create-du-app
 ```
 
-### Options
+## Available stacks
+
+| Group    | Technologies                  | Output folder  |
+|----------|-------------------------------|----------------|
+| Mobile   | React Native · Expo · Flutter | `apps/mobile`  |
+| Frontend | Next.js · ReactJS             | `apps/web`     |
+| Backend  | Node.js · NestJS · PHP        | `apps/backend` |
+
+`packages/shared` (`@repo/shared` — shared data contracts, built with tsup) is added
+automatically when you pick **≥ 2** JS/TS stacks, and every JS/TS app is wired to it
+as a `workspace:*` dependency.
 
-| Flag                 | Description                              |
-|----------------------|------------------------------------------|
-| `-n`, `--name <name>`| Project name                             |
-| `--mobile <id>`      | `rn` · `expo` · `flutter`                |
-| `--fe <id>`          | `nextjs` · `reactjs`                     |
-| `--be <id>`          | `nodejs` · `nestjs` · `php`              |
-| `-h`, `--help`       | Print help                               |
-| `-v`, `--version`    | Print version                            |
+---
 
-## How it works
+## For maintainers
+
+Working on the CLI source or the templates? See the
+[repository README](../../README.md) and **[CONTRIBUTING.md](../../CONTRIBUTING.md)**.
 
 | File          | Responsibility |
 |---------------|----------------|
-| `index.js`    | Entry point. Parses flags, decides interactive vs. non-interactive, runs the generator. |
-| `registry.js` | **Data declaration** of groups, technologies, `templatePath`, and `lang`. The only file to edit when adding or removing a stack. |
-| `prompts.js`  | Interactive prompts (`@clack/prompts`): project name → multi-select groups → select one technology per group. |
-| `generate.js` | Copies templates, renames `_package.json` → `package.json`, generates the root `package.json` + `pnpm-workspace.yaml`, conditionally creates `packages/shared`, and substitutes `{{PROJECT_NAME}}`. |
-
-## Template conventions
+| `src/index.js`    | Entry point. Parses flags, runs interactive or non-interactive, then generates. |
+| `src/registry.js` | **Data declaration** of groups, technologies, `templatePath`, and `lang`. Edit this to add/remove a stack. |
+| `src/prompts.js`  | Interactive prompts (`@clack/prompts`). |
+| `src/generate.js` | Copies templates, renames `_package.json` → `package.json`, substitutes `{{PROJECT_NAME}}`, emits the root config (`package.json`, `pnpm-workspace.yaml`, `turbo.json`, `tsconfig.base.json`, `.gitignore`, `.npmrc`, `scripts/bootstrap.mjs`), and wires JS/TS apps to `@repo/shared`. |
+| `scripts/validate-templates.mjs` | Validates every registered template (gates `prepack`/publish). Run with `pnpm validate`. |
 
-- A manifest named `_package.json` is renamed to `package.json` on generate. Likewise
-  `_gitignore` → `.gitignore` and `_npmrc` → `.npmrc`.
-- Any text file containing `{{PROJECT_NAME}}` has it replaced with the real project name.
-- `packages/shared` is created only when **≥ 2** selections have `lang === 'js'`.
+Before publishing, `prepack` runs template validation automatically. Run the full
+check (validate + generate smoke test) from the repo root with `pnpm test`.
 
-See **[CONTRIBUTING.md](../../CONTRIBUTING.md)** for the full workflow of adding real source.
+Release a new version: `pnpm release` (see [scripts/release.mjs](scripts/release.mjs)).

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "create-du-app",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI generator: pick templates (Mobile/FE/BE) and scaffold a product monorepo",
   "type": "module",
   "bin": {
-    "create-app": "src/index.js"
+    "create-du-app": "src/index.js"
   },
   "files": [
     "src",
@@ -12,14 +12,15 @@
   ],
   "scripts": {
     "start": "node src/index.js",
+    "validate": "node scripts/validate-templates.mjs",
     "release": "node scripts/release.mjs",
-    "prepack": "node scripts/bundle-templates.mjs",
+    "prepack": "node scripts/validate-templates.mjs && node scripts/bundle-templates.mjs",
     "postpack": "node scripts/bundle-templates.mjs --clean"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
-  "packageManager": "pnpm@9.0.0",
+  "packageManager": "pnpm@9.12.0",
   "dependencies": {
     "@clack/prompts": "^0.7.0",
     "fs-extra": "^11.2.0"

package/src/generate.js

@@ -1,13 +1,24 @@
-// generate.js — copy templates + rename + generate dynamic package.json + replace placeholders.
+// generate.js — copy templates + rename + generate dynamic root config + replace placeholders.
 //
 // Input: the plan from prompts.js → { projectName, selections: [{group, option}] }
 // and `repoRoot` (the company-starter root that contains templates/).
+//
+// The output is a standard pnpm + Turborepo monorepo (modeled on the life-master layout):
+//   <project>/
+//     package.json          (turbo scripts + devDeps)
+//     pnpm-workspace.yaml
+//     turbo.json
+//     tsconfig.base.json     (paths: @repo/* -> packages/*/src)
+//     .gitignore  .npmrc
+//     apps/<web|backend|mobile>/   (selected stacks — source dropped in later)
+//     packages/shared/             (@repo/shared — only when >= 2 JS/TS apps)
 
 import path from 'node:path';
 import fse from 'fs-extra';
 import {
   SHARED_TEMPLATE_PATH,
   SHARED_OUTPUT_DIR,
+  SHARED_PACKAGE_NAME,
 } from './registry.js';
 
 const PLACEHOLDER = /\{\{PROJECT_NAME\}\}/g;
@@ -38,7 +49,6 @@ function renameBasename(name) {
 
 // Copy one template folder → destination, renaming files and replacing {{PROJECT_NAME}}.
 async function copyTemplate(srcDir, destDir, projectName) {
-  // An empty template (real source not dropped in yet) must still work.
   if (!(await fse.pathExists(srcDir))) {
     throw new Error(`Template not found: ${srcDir}`);
   }
@@ -66,14 +76,33 @@ async function copyTemplate(srcDir, destDir, projectName) {
   }
 }
 
-// Build the project's root package.json dynamically (pnpm: NO "workspaces" field).
-function buildRootPackageJson(projectName) {
+// ---------------------------------------------------------------------------
+// Dynamic root files (pnpm + Turborepo standard).
+// ---------------------------------------------------------------------------
+
+// Build the project's root package.json (pnpm: NO "workspaces" field).
+function buildRootPackageJson(projectName, hasShared) {
   return {
     name: projectName,
     version: '0.1.0',
     private: true,
-    engines: { node: '>=18' },
-    packageManager: 'pnpm@9.0.0',
+    packageManager: 'pnpm@9.12.0',
+    engines: { node: '>=20' },
+    scripts: {
+      bootstrap: 'node scripts/bootstrap.mjs',
+      build: 'turbo run build',
+      dev: 'turbo run dev',
+      lint: 'turbo run lint',
+      typecheck: 'turbo run typecheck',
+      test: 'turbo run test',
+      ...(hasShared
+        ? { 'shared:build': `turbo run build --filter=${SHARED_PACKAGE_NAME}` }
+        : {}),
+    },
+    devDependencies: {
+      turbo: '^2.3.3',
+      typescript: '^5.8.3',
+    },
   };
 }
 
@@ -85,6 +114,181 @@ function buildPnpmWorkspaceYaml(createdAppDirs) {
   return `packages:\n${lines.join('\n')}\n`;
 }
 
+const TURBO_JSON = {
+  $schema: 'https://turbo.build/schema.json',
+  tasks: {
+    build: {
+      dependsOn: ['^build'],
+      outputs: ['dist/**', '.next/**', '!.next/cache/**', 'build/**'],
+    },
+    lint: { dependsOn: ['^build'] },
+    typecheck: { dependsOn: ['^build'] },
+    test: { dependsOn: ['^build'], outputs: ['coverage/**'] },
+    dev: { cache: false, persistent: true },
+  },
+};
+
+const TSCONFIG_BASE = {
+  $schema: 'https://json.schemastore.org/tsconfig',
+  compilerOptions: {
+    target: 'ESNext',
+    module: 'ESNext',
+    moduleResolution: 'Bundler',
+    lib: ['ESNext'],
+    strict: true,
+    esModuleInterop: true,
+    allowSyntheticDefaultImports: true,
+    forceConsistentCasingInFileNames: true,
+    skipLibCheck: true,
+    resolveJsonModule: true,
+    isolatedModules: true,
+    declaration: true,
+    baseUrl: '.',
+    paths: { '@repo/*': ['packages/*/src'] },
+  },
+  exclude: ['node_modules', 'dist', 'build'],
+};
+
+const GITIGNORE = `# Dependencies
+node_modules/
+.pnpm-store/
+
+# Turborepo
+.turbo/
+
+# Build outputs
+dist/
+build/
+out/
+.next/
+*.tsbuildinfo
+
+# Expo / React Native
+.expo/
+web-build/
+.metro-health-check*
+
+# Environment variables
+.env
+.env.*
+!.env.example
+!.env.*.example
+
+# Testing
+coverage/
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+*.iml
+`;
+
+const NPMRC = `# Hoist node_modules so Metro (Expo / React Native) resolves packages and
+# workspace dependencies (@repo/*) correctly. Harmless for web/back-end apps.
+node-linker=hoisted
+
+# Keep peer-dependency resolution lenient — the RN ecosystem has many loose
+# peer ranges that would otherwise fail install.
+strict-peer-dependencies=false
+`;
+
+// One-command bootstrap, written to the generated repo as scripts/bootstrap.mjs.
+// Run it (`pnpm bootstrap`) AFTER dropping the real stack source in: it installs
+// deps, builds @repo/shared, then verifies the apps can resolve it.
+// NOTE: not named "setup" because `pnpm setup` is a reserved pnpm built-in.
+const SETUP_MJS = `// bootstrap.mjs — one-command bootstrap for this monorepo.
+//
+// Run it after you have dropped the real source into apps/* :
+//
+//     pnpm bootstrap
+//
+// It installs dependencies, builds @repo/shared (so its dist/ exists), and
+// verifies every app that depends on it can resolve \`@repo/shared\`.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SHARED = '@repo/shared';
+
+function sh(command) {
+  console.log(\`\\n$ \${command}\`);
+  const r = spawnSync(command, { cwd: root, stdio: 'inherit', shell: true });
+  if (r.status !== 0) {
+    console.error(\`\\n\\u2717 Failed: \${command}\`);
+    process.exit(r.status ?? 1);
+  }
+}
+
+// 1) Install all workspace dependencies.
+sh('pnpm install');
+
+// 2) Build the shared package (if present) so apps can import its dist output.
+const sharedDir = path.join(root, 'packages', 'shared');
+const hasShared = existsSync(sharedDir);
+if (hasShared) {
+  sh(\`pnpm --filter \${SHARED} build\`);
+} else {
+  console.log('\\n\\u2022 No packages/shared in this repo — skipping shared build.');
+}
+
+// 3) Verify each app that depends on @repo/shared can actually resolve it.
+if (hasShared) {
+  const appsDir = path.join(root, 'apps');
+  const apps = existsSync(appsDir)
+    ? readdirSync(appsDir, { withFileTypes: true }).filter((e) => e.isDirectory())
+    : [];
+
+  let failures = 0;
+  for (const app of apps) {
+    const pkgPath = path.join(appsDir, app.name, 'package.json');
+    if (!existsSync(pkgPath)) continue;
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (!deps[SHARED]) continue;
+
+    const require = createRequire(path.join(appsDir, app.name, 'noop.js'));
+    try {
+      require.resolve(SHARED);
+      console.log(\`\\n\\u2713 apps/\${app.name} resolves \${SHARED}\`);
+    } catch {
+      console.error(\`\\n\\u2717 apps/\${app.name} cannot resolve \${SHARED}\`);
+      failures++;
+    }
+  }
+
+  if (failures > 0) {
+    console.error(\`\\n\${failures} app(s) cannot resolve \${SHARED}. Check the \"\${SHARED}\" dependency and that its build produced dist/.\`);
+    process.exit(1);
+  }
+}
+
+console.log('\\n\\u2713 Setup complete. Start developing with:  pnpm dev');
+`;
+
+// ---------------------------------------------------------------------------
+
+// Add "@repo/shared": "workspace:*" to a JS/TS app's package.json (if present).
+async function wireSharedDependency(appPkgPath) {
+  if (!(await fse.pathExists(appPkgPath))) return false;
+  const pkg = await fse.readJson(appPkgPath);
+  pkg.dependencies = { ...(pkg.dependencies ?? {}), [SHARED_PACKAGE_NAME]: 'workspace:*' };
+  await fse.writeJson(appPkgPath, pkg, { spaces: 2 });
+  return true;
+}
+
 export async function generate(plan, repoRoot, cwd = process.cwd()) {
   const { projectName, selections } = plan;
   const projectRoot = path.resolve(cwd, projectName);
@@ -107,27 +311,54 @@ export async function generate(plan, repoRoot, cwd = process.cwd()) {
   }
 
   // 2) packages/shared is CONDITIONAL: >= 2 selections with lang === 'js'.
-  const jsCount = selections.filter((s) => s.option.lang === 'js').length;
-  if (jsCount >= 2) {
+  const jsSelections = selections.filter((s) => s.option.lang === 'js');
+  const hasShared = jsSelections.length >= 2;
+  if (hasShared) {
     const srcDir = path.resolve(repoRoot, SHARED_TEMPLATE_PATH);
     const destDir = path.resolve(projectRoot, SHARED_OUTPUT_DIR);
     await copyTemplate(srcDir, destDir, projectName);
-    logs.push(`✓ shared → ${SHARED_OUTPUT_DIR} (${jsCount} JS/TS apps)`);
+    logs.push(`✓ shared → ${SHARED_OUTPUT_DIR} (${jsSelections.length} JS/TS apps)`);
+
+    // Wire each JS/TS app to depend on the shared package.
+    for (const { group } of jsSelections) {
+      const appPkg = path.join(projectRoot, group.outputDir, 'package.json');
+      if (await wireSharedDependency(appPkg)) {
+        logs.push(`  ↳ ${group.outputDir} depends on ${SHARED_PACKAGE_NAME} (workspace:*)`);
+      }
+    }
   } else {
-    logs.push(`• Skipping shared: not enough JS/TS apps (need >= 2, have ${jsCount}).`);
+    logs.push(`• Skipping shared: not enough JS/TS apps (need >= 2, have ${jsSelections.length}).`);
   }
 
-  // 3) Generate the root package.json + pnpm-workspace.yaml dynamically.
-  const rootPkg = buildRootPackageJson(projectName);
-  await fse.writeJson(path.join(projectRoot, 'package.json'), rootPkg, { spaces: 2 });
+  // 3) Generate the root config files dynamically.
+  await fse.writeJson(
+    path.join(projectRoot, 'package.json'),
+    buildRootPackageJson(projectName, hasShared),
+    { spaces: 2 },
+  );
   logs.push('✓ package.json');
 
-  const wsEntries = [...createdAppDirs, 'packages/*'];
   await fse.writeFile(
     path.join(projectRoot, 'pnpm-workspace.yaml'),
     buildPnpmWorkspaceYaml(createdAppDirs),
   );
-  logs.push(`✓ pnpm-workspace.yaml (packages: ${wsEntries.join(', ')})`);
+  logs.push(`✓ pnpm-workspace.yaml (packages: ${[...createdAppDirs, 'packages/*'].join(', ')})`);
+
+  await fse.writeJson(path.join(projectRoot, 'turbo.json'), TURBO_JSON, { spaces: 2 });
+  logs.push('✓ turbo.json');
+
+  await fse.writeJson(path.join(projectRoot, 'tsconfig.base.json'), TSCONFIG_BASE, { spaces: 2 });
+  logs.push('✓ tsconfig.base.json');
+
+  await fse.writeFile(path.join(projectRoot, '.gitignore'), GITIGNORE);
+  logs.push('✓ .gitignore');
+
+  await fse.writeFile(path.join(projectRoot, '.npmrc'), NPMRC);
+  logs.push('✓ .npmrc');
+
+  await fse.ensureDir(path.join(projectRoot, 'scripts'));
+  await fse.writeFile(path.join(projectRoot, 'scripts', 'bootstrap.mjs'), SETUP_MJS);
+  logs.push('✓ scripts/bootstrap.mjs (run `pnpm bootstrap` after dropping source in)');
 
   return { projectRoot, logs };
 }

package/src/index.js

@@ -2,8 +2,8 @@
 // index.js — entry point. Parse args + run prompts (TTY) or generate directly (flags).
 //
 // Usage:
-//   create-app                                 interactive (requires a real terminal)
-//   create-app --name my-shop --be nestjs      non-interactive (runs anywhere)
+//   create-du-app                                 interactive (requires a real terminal)
+//   create-du-app --name my-shop --be nestjs      non-interactive (runs anywhere)
 //   node src/index.js
 //
 // Flags:
@@ -56,11 +56,11 @@ async function readVersion() {
 
 function printHelp() {
   console.log(`
-create-app — scaffold a product monorepo from company templates
+create-du-app — scaffold a product monorepo from company templates
 
 Usage:
-  create-app                                interactive (requires a real terminal)
-  create-app --name my-shop --be nestjs     non-interactive (runs anywhere)
+  create-du-app                                interactive (requires a real terminal)
+  create-du-app --name my-shop --be nestjs     non-interactive (runs anywhere)
   node src/index.js                         equivalent (when not linked)
 
 Options:
@@ -73,7 +73,7 @@ Options:
   -y, --yes               generate without prompting (needs --name + >=1 group)
 
 Example:
-  create-app --name my-shop --mobile expo --fe nextjs --be nestjs
+  create-du-app --name my-shop --mobile expo --fe nextjs --be nestjs
 
 Add/remove templates: edit packages/cli/src/registry.js
 `);
@@ -93,7 +93,7 @@ function parseArgs(argv) {
       case '--fe': out.fe = argv[++i]; break;
       case '--be': out.be = argv[++i]; break;
       default:
-        throw new Error(`Invalid argument: ${a}. See: create-app --help`);
+        throw new Error(`Invalid argument: ${a}. See: create-du-app --help`);
     }
   }
   return out;
@@ -155,7 +155,7 @@ async function main() {
     throw new Error(
       'This terminal does not support interactive mode (stdin is not a TTY).\n' +
       '  → Run it in Terminal.app/iTerm, OR use flags:\n' +
-      '    create-app --name my-shop --mobile expo --fe nextjs --be nestjs',
+      '    create-du-app --name my-shop --mobile expo --fe nextjs --be nestjs',
     );
   } else {
     plan = await runPrompts();

package/src/prompts.js

@@ -24,7 +24,7 @@ function ensureNotCancelled(value) {
 }
 
 export async function runPrompts() {
-  intro('create-app — scaffold a product monorepo from company templates');
+  intro('create-du-app — scaffold a product monorepo from company templates');
 
   // 1) Project name
   const projectName = ensureNotCancelled(

package/src/registry.js

@@ -43,9 +43,11 @@ export const GROUPS = [
   },
 ];
 
-// Path to the shared template folder (only copied when >= 2 selections have lang === 'js').
+// Shared package config. Only copied when >= 2 selections have lang === 'js'.
+// Uses the `@repo/*` scope so it matches the `paths` mapping in tsconfig.base.json.
 export const SHARED_TEMPLATE_PATH = 'templates/shared';
 export const SHARED_OUTPUT_DIR = 'packages/shared';
+export const SHARED_PACKAGE_NAME = '@repo/shared';
 
 // Quickly look up a single option by (groupId, optionId).
 export function findOption(groupId, optionId) {

package/templates/mobile/expo/.env.example

@@ -0,0 +1,5 @@
+# Copy to .env and fill in. Read at build time by react-native-config.
+# NEVER commit the real .env — only this example.
+
+# Base URL of your API (include trailing slash).
+BASE_URL=https://api.example.com/

package/templates/mobile/expo/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  root: true,
+  extends: '@react-native',
+  rules: {
+    semi: 0,
+  },
+};

package/templates/mobile/expo/.prettierrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  arrowParens: 'avoid',
+  bracketSameLine: true,
+  bracketSpacing: true,
+  singleQuote: true,
+  trailingComma: 'all',
+};

package/templates/mobile/expo/.svgrrc.js

@@ -0,0 +1,9 @@
+module.exports = {
+    replaceAttrValues: {
+        '{currentColor}': '{props.color || "#0D1F2D"}',
+        '{292929}': '{props.color || "#292929"}',
+        '{D4D4FF}': '{props.color || "#D4D4FF"}',
+        '{7C7C7C}': '{props.color || "#7C7C7C"}',
+        '{D97706}': '{props.color || "#D97706"}',
+    },
+}

package/templates/mobile/expo/README.md

@@ -1,11 +1,46 @@
-# Placeholder: Expo (mobile/expo)
+# {{PROJECT_NAME}} — Mobile (Expo)
 
-This is a **placeholder** for the **Expo** template.
+An Expo + React Native starter built from the company's production core. The
+reusable infrastructure (`src/core`) is ported as-is; only product-specific
+features (audio/player, real-estate, IAP, maps, blur) were removed. Build your
+features under `src/modules/`.
 
-Drop the standard Expo source here. Conventions:
+## Architecture
 
-- Name the template's `package.json` as **`_package.json`** (the CLI renames it on generate).
-- Name `.gitignore` as **`_gitignore`**, `.npmrc` as **`_npmrc`** if present.
-- Wherever you need the project name, write `{{PROJECT_NAME}}` — the CLI replaces it with the real name.
+```
+src/
+├── app/        composition: providers, navigation, global stores (auth/loading/common), i18n
+├── core/       reusable infrastructure (see below)
+├── modules/    your features (home/profile examples included)
+└── assets/     i18n, svgs (sync-generated barrel), images, lotties
+```
 
-`lang: js` → this app counts toward the condition for creating `packages/shared`.
+### `src/core` — the reusable kit
+| Area | Where |
+|------|-------|
+| API | `services/api.service.ts` (axios + auth header + device-id + 401 session handling), `api/example.api.ts` (React Query pattern) |
+| Data | `utils/query-client.util.ts`, `utils/query-persister.util.ts` (MMKV offline cache) |
+| Theme | `theme/` — context + `Colors` design tokens (`useTheme`, `useThemedStyles`) |
+| UI kit | `components/ui/*` — button, text-field/area, checkbox, radio, toggle, modal, bottom-sheet, header, tabs, otp-input, search-box, skeleton, app-image, image-slider… |
+| Forms | `components/forms/*` — react-hook-form bindings over the DS fields |
+| Hooks | `hook/*` — useDebounce, useTimeout, useNetworkStatus, useEndReached, useAppNavigation… |
+| Utils | `utils/*` — storage, translator (i18n), validate/schema (yup), date/number format, enum, toast, size/typography… |
+
+### Shared contracts
+The core imports domain contracts (`ApiEndpoints`, `ExternalUrls`, enums) from
+**`@repo/shared`** — generate this app alongside another JS/TS stack so that
+package exists; the CLI wires `"@repo/shared": "workspace:*"` automatically.
+
+## Getting started
+
+```bash
+pnpm bootstrap                                  # install + build @repo/shared
+pnpm --filter {{PROJECT_NAME}}-mobile typecheck # verify
+pnpm --filter {{PROJECT_NAME}}-mobile start     # expo dev server
+```
+
+Add an icon: drop `name.svg` in `src/assets/svgs/` then `pnpm --filter {{PROJECT_NAME}}-mobile sync-svgs`.
+
+Native folders (`ios/`, `android/`) are git-ignored — run `expo prebuild` to generate them.
+
+> Before shipping: set `name`, `slug`, `scheme`, and the iOS/Android bundle ids in `app.json`.

package/templates/mobile/expo/_gitignore

@@ -0,0 +1,20 @@
+# Native build artifacts (regenerated by `expo prebuild`)
+/ios
+/android
+.expo/
+web-build/
+
+# Dependencies
+node_modules/
+
+# Metro
+.metro-health-check*
+
+# Env (keep .env.example)
+.env
+.env.*
+!.env.example
+
+# Logs / OS
+*.log
+.DS_Store