create-expo-boilerplate 1.1.1 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # create-expo-boilerplate
 
-Scaffold a new Expo app from [React-Native-Expo-Boilterplate](https://github.com/EndLess728/React-Native-Expo-Boilterplate) — no cloning, no deleting example code by hand.
+Scaffold a new Expo app from [react-native-expo-boilerplate](https://github.com/EndLess728/react-native-expo-boilerplate) ([docs](https://endless728.github.io/react-native-expo-boilerplate/)) — no cloning, no deleting example code by hand.
 
 ```bash
 npx create-expo-boilerplate my-app
@@ -48,6 +48,31 @@ Every option has the same screens and the same light/dark theme tokens (`src/sty
 
 Every combination uses the same feature-based layout (`src/features/<feature>`, `src/shared`, …). Screens only talk to state through the auth feature's hooks (`useIsLoggedIn`, `useLogin`, …), which is why switching the state library or the navigator doesn't touch a single screen.
 
+## Adding modules later
+
+From the root of a generated project:
+
+```bash
+npx create-expo-boilerplate add notifications
+npx create-expo-boilerplate add notifications --dry-run   # list what would change, write nothing
+```
+
+| Module | What you get |
+|---|---|
+| `notifications` | Push (Firebase Cloud Messaging) and local notifications via NotifyKit: permission handling with a five-state banner, Android channels, foreground/background/killed delivery, allowlisted tap routing including cold start, token sync to your backend, tests. Docs land in `src/notifications/README.md`. |
+| `subscriptions` | In-app subscriptions via RevenueCat: `useSubscription()` / `requirePremium()`, a premium gate sheet, a full paywall driven by the current offering, and every store state (grace period, account hold, trial, pause, cancelled, family sharing, promotional, lifetime, cross-store, plan changes, pending payments). Docs land in `src/subscription/README.md`. |
+
+`add` reads the stack from `boilerplate.json` (written by every new project; older projects are detected from their files) and writes the variant that fits: Expo Router or React Navigation, Unistyles / StyleSheet / Tailwind, TypeScript or JavaScript. It:
+
+- refuses to run with uncommitted changes (`--force` overrides), so the module lands as one diff you can review;
+- builds everything in a staging copy first, so a failure leaves the project untouched;
+- patches the files it wires into (entry, `AppProviders`, `app.config.ts`, Jest config, translations). If one of them has been customised past recognition, it doesn't guess: it applies the rest and prints the edit to make by hand;
+- refuses to add a module twice.
+
+`notifications` flags: `--token-endpoint <path>` (default `devices/push-token`), `--google-services <path>` / `--google-service-info <path>` (Firebase files to copy into `firebase/`; prompted for, and skippable), `--banner` / `--no-banner` (permission banner on Settings), plus the shared `--yes`, `--dry-run`, `--force`, `--no-install`.
+
+`subscriptions` flags: `--entitlement <id>` (default `premium`), `--revenuecat-ios-key <key>` / `--revenuecat-android-key <key>` (public SDK keys; prompted for, and skippable).
+
 ## How it works
 
 The repo root **is** the template: the Expo Router + Zustand + TypeScript app with ESLint and Husky. Nobody maintains a second copy.
@@ -68,6 +93,10 @@ cli/
 │       ├── javascript.ts     # TS → JS with the TypeScript compiler, last
 │       ├── readme.ts         # README for the exact stack chosen
 │       └── format.ts         # Prettier with the project's .prettierrc
+│   ├── add.ts                # `add <module>`: preflight, staging copy, JS pass, write back
+│   ├── manifest.ts           # boilerplate.json (stack + added modules), detection fallback
+│   └── modules/              # one generator per module, registered in index.ts;
+│                             #   shared.ts: translations merge, AppProviders wrap, nav ref
 ├── overlays/                 # files that differ per option, written in TypeScript
 │   ├── react-navigation/
 │   ├── redux/{common,thunk,saga}/
@@ -75,6 +104,7 @@ cli/
 │       ├── common/           #   styled components, screens, theme hooks (+ global.css, metro.config.js)
 │       ├── expo-router/      #   route files that only exist with Expo Router
 │       └── docs/             #   replacement sections for .skills/ui-creation.md and the screen snippet
+├── modules/<name>/           # module sources: files/ (base stack), overlays/ (per option), translations/
 └── scripts/
     ├── sync-template.mjs     # copies the repo root into template/ when packing
     └── test-matrix.mjs       # generates + checks every combination
@@ -107,6 +137,7 @@ npm run test:matrix            # 26 core combinations
 npm run test:matrix -- --all   # all 144
 npm run test:matrix -- --export   # also bundle each with `expo export` (slow)
 npm run test:matrix -- --only redux-saga.react-navigation.tailwind
+npm run test:matrix -- --add notifications   # also add a module to each, and check it refuses a second add
 ```
 
 The script generates each project into your temp dir, installs **one** shared superset of dependencies, and checks each project for leftovers (stray markers, Zustand imports in Redux apps, Unistyles in StyleSheet / Tailwind apps, …), circular imports (madge), `tsc`, ESLint (or Prettier when ESLint is off), Jest, and `expo config`. CI runs the core set on every PR that touches the app or the CLI.
@@ -118,6 +149,13 @@ The script generates each project into your temp dir, installs **one** shared su
 3. Pin any new packages in `versions.ts`.
 4. Add the dimension to `scripts/test-matrix.mjs` and run it.
 
+### Adding a module
+
+1. Put its sources in `modules/<name>/files/`, written for the base stack (Expo Router, Unistyles, TypeScript) and mirroring project paths; per-option replacements go in `modules/<name>/overlays/`.
+2. Write a `ModuleGenerator` in `src/modules/<name>.ts` (prompts + flags, file copy, patches through `Patcher`, next steps) and register it in `src/modules/index.ts`.
+3. Pin its packages in `versions.ts` — the test matrix installs them.
+4. Run `npm run test:matrix -- --add <name>`. A patch that falls back to "do this by hand" fails the matrix.
+
 ### Upgrading the Expo SDK
 
 Upgrade the boilerplate at the repo root as usual, then bump the overlay-only packages in `src/versions.ts` (React Navigation, Redux, Uniwind / Tailwind), and run `npm run test:matrix -- --all --export`.

package/dist/add.js

@@ -0,0 +1,218 @@
+import { existsSync } from 'node:fs';
+import { cp, mkdtemp, readFile, rm } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join, relative, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadManifest, isBoilerplateProject, saveManifest } from './manifest.js';
+import { MODULES } from './modules/index.js';
+import { CancelledError, Patcher } from './modules/types.js';
+import { formatFiles } from './steps/format.js';
+import { transpileFiles } from './steps/javascript.js';
+import { detectPackageManager, PM } from './steps/packageManager.js';
+import { commandExists, run } from './utils/exec.js';
+import { ProjectFiles } from './utils/files.js';
+import { PackageJsonEditor } from './utils/packageJson.js';
+/** Never copied into the staging area — large, generated, or not ours to touch. */
+const SKIP = new Set(['node_modules', '.git', 'ios', 'android', '.expo', 'dist', 'web-build']);
+async function isDirty(dir) {
+    try {
+        return (await run('git', ['status', '--porcelain'], dir)).trim() !== '';
+    }
+    catch {
+        return null; // not a git repo
+    }
+}
+/** Files that differ between the staging copy and the project: added/changed, and removed. */
+async function diff(project, staged) {
+    const before = new Set(await listOwn(project));
+    const after = await listOwn(staged);
+    const changed = [];
+    for (const rel of after) {
+        if (!before.has(rel))
+            changed.push(rel);
+        else if (!(await readFile(project.abs(rel))).equals(await readFile(staged.abs(rel)))) {
+            changed.push(rel);
+        }
+    }
+    const removed = [...before].filter((rel) => !after.includes(rel));
+    return { changed, removed, created: changed.filter((rel) => !before.has(rel)) };
+}
+async function listOwn(files) {
+    return (await files.list()).filter((rel) => !SKIP.has(rel.split('/')[0]));
+}
+export async function addModule(name, flags, cliVersion) {
+    const cwd = process.cwd();
+    const interactive = !flags.yes && Boolean(process.stdout.isTTY);
+    console.log();
+    p.intro(pc.bgCyan(pc.black(' create-expo-boilerplate add ')));
+    // ── Which module ─────────────────────────────────────────
+    if (!name) {
+        if (!interactive)
+            throw new Error(`Name a module: ${Object.keys(MODULES).join(', ')}.`);
+        const picked = await p.select({
+            message: 'Which module?',
+            options: Object.values(MODULES).map((m) => ({
+                value: m.name,
+                label: m.name,
+                hint: m.description,
+            })),
+        });
+        if (p.isCancel(picked))
+            return cancelled();
+        name = picked;
+    }
+    const mod = MODULES[name];
+    if (!mod)
+        throw new Error(`Unknown module "${name}". Available: ${Object.keys(MODULES).join(', ')}.`);
+    // ── Preflight ────────────────────────────────────────────
+    const project = new ProjectFiles(cwd);
+    if (!isBoilerplateProject(project)) {
+        throw new Error("This doesn't look like a create-expo-boilerplate project. Run `add` from the project root.");
+    }
+    const { manifest, detected } = await loadManifest(project);
+    const moduleDir = `src/${mod.dir ?? mod.name}`;
+    if (manifest.modules[mod.name] || project.exists(moduleDir)) {
+        throw new Error(`${mod.name} is already in this project (${moduleDir}/).`);
+    }
+    if (detected) {
+        p.log.warn(`No boilerplate.json — detected ${manifest.navigation}, ${manifest.styling}, ${manifest.state}, ${manifest.language.toUpperCase()}. It will be written now.`);
+    }
+    else if (manifest.cliVersion !== cliVersion) {
+        p.log.warn(`This project was created with v${manifest.cliVersion}; this is v${cliVersion}. If anything doesn't fit, run ${pc.bold(`npx create-expo-boilerplate@${manifest.cliVersion} add ${mod.name}`)}.`);
+    }
+    const dirty = await isDirty(cwd);
+    if (dirty && !flags.force && !flags.dryRun) {
+        throw new Error('You have uncommitted changes. Commit or stash them first (or pass --force), so the module lands as one reviewable diff.');
+    }
+    if (dirty === null)
+        p.log.warn("Not a git repository — you won't get a diff to review.");
+    // ── Generate into a staging copy ─────────────────────────
+    // Nothing touches the project until everything succeeded, which also makes
+    // --dry-run exact.
+    const stagingDir = await mkdtemp(join(tmpdir(), 'ceb-add-'));
+    let nextSteps = [];
+    let manual = [];
+    try {
+        await cp(cwd, stagingDir, {
+            recursive: true,
+            filter: (src) => !SKIP.has(relative(cwd, src).split(sep)[0]),
+        });
+        const staged = new ProjectFiles(stagingDir);
+        const pkg = await PackageJsonEditor.load(staged);
+        const patch = new Patcher(staged);
+        try {
+            nextSteps = await mod.apply({ files: staged, pkg, stack: manifest, patch, interactive, cwd }, flags);
+        }
+        catch (error) {
+            if (error instanceof CancelledError)
+                return cancelled();
+            throw error;
+        }
+        await pkg.save();
+        manual = patch.manual;
+        if (manifest.language === 'js') {
+            const created = (await diff(project, staged)).created;
+            await transpileFiles(staged, created.filter((rel) => /\.tsx?$/.test(rel) && !rel.endsWith('.d.ts')));
+        }
+        manifest.modules[mod.name] = { cliVersion };
+        await saveManifest(staged, manifest);
+        const { changed, removed, created } = await diff(project, staged);
+        // Module sources ship formatted with the template's Prettier. Re-formatting
+        // them with another version can disagree with the project's ESLint, so only
+        // edited files and freshly transpiled JS are formatted.
+        const toFormat = manifest.language === 'js' ? changed : changed.filter((rel) => !created.includes(rel));
+        await formatFiles(staged, toFormat, await projectPrettier(cwd));
+        // ── Report / write ─────────────────────────────────────
+        p.note([
+            ...changed.map((rel) => `${created.includes(rel) ? pc.green('+') : pc.yellow('~')} ${rel}`),
+            ...removed.map((rel) => `${pc.red('-')} ${rel}`),
+        ].join('\n'), flags.dryRun ? 'Would change' : 'Changes');
+        if (flags.dryRun) {
+            if (patch.manual.length)
+                p.note(patch.manual.map((m) => `• ${m}`).join('\n'), 'Would need doing by hand');
+            p.outro('Dry run — nothing was written.');
+            return;
+        }
+        for (const rel of changed) {
+            await project.write(rel, '');
+            await cp(staged.abs(rel), project.abs(rel));
+        }
+        await project.remove(...removed);
+        await eslintFix(project, changed);
+    }
+    finally {
+        await rm(stagingDir, { recursive: true, force: true });
+    }
+    // ── Install ──────────────────────────────────────────────
+    const pm = projectPackageManager(project);
+    let installed = false;
+    if (flags.install) {
+        if (await commandExists(pm)) {
+            // The animated spinner floods non-interactive output (CI logs, pipes).
+            const s = process.stdout.isTTY
+                ? p.spinner()
+                : { start: p.log.step, stop: p.log.success, error: p.log.error };
+            s.start(`Installing dependencies with ${pm}`);
+            try {
+                await run(pm, ['install'], cwd);
+                installed = true;
+                s.stop('Dependencies installed');
+            }
+            catch (error) {
+                s.error(`${pm} install failed — run it yourself to see why`);
+                if (process.env.DEBUG)
+                    console.error(error);
+            }
+        }
+        else {
+            p.log.warn(`${pm} isn't installed — skipping dependency install.`);
+        }
+    }
+    // ── What's left ──────────────────────────────────────────
+    if (manual.length) {
+        p.note(manual.map((m) => `• ${m}`).join('\n'), pc.yellow("Couldn't patch — do these by hand"));
+    }
+    const steps = [installed ? null : PM[pm].install, ...nextSteps].filter(Boolean);
+    p.note(steps.map((step, i) => `${i + 1}. ${step}`).join('\n'), 'Next steps');
+    p.outro(`${pc.green('✔')} Added ${pc.bold(mod.name)} — docs in src/${mod.dir ?? mod.name}/README.md`);
+}
+function projectPackageManager(project) {
+    const byLockfile = Object.keys(PM).find((pm) => project.exists(PM[pm].lockfile));
+    return byLockfile ?? detectPackageManager() ?? 'yarn';
+}
+/**
+ * Runs the project's own ESLint autofix over the files `add` touched, when it
+ * is installed — import/export order rules depend on the final file (after the
+ * JS pass), which only the project's config can judge. Best effort.
+ */
+async function eslintFix(project, changed) {
+    const bin = project.abs('node_modules/.bin/eslint');
+    const targets = changed.filter((rel) => /\.(jsx?|tsx?)$/.test(rel));
+    if (!existsSync(bin) || !project.exists('eslint.config.js') || !targets.length)
+        return;
+    try {
+        await run(bin, ['--fix', '--no-warn-ignored', ...targets], project.root);
+    }
+    catch {
+        // Remaining problems are the project's lint to report, not a failed add.
+    }
+}
+/** The project's installed Prettier, if any (see `formatFiles`). */
+async function projectPrettier(cwd) {
+    try {
+        const entry = createRequire(join(cwd, 'package.json')).resolve('prettier');
+        const mod = await import(pathToFileURL(entry).href);
+        // The CommonJS entry puts the API under `default`.
+        const api = typeof mod.format === 'function' ? mod : mod.default;
+        return typeof api?.format === 'function' ? api : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function cancelled() {
+    p.cancel('Cancelled — nothing was changed.');
+}

package/dist/generate.js

@@ -8,6 +8,7 @@ import { applyState } from './steps/state.js';
 import { applyStyling } from './steps/styling.js';
 import { applyTooling } from './steps/tooling.js';
 import { formatProject } from './steps/format.js';
+import { writeManifest } from './manifest.js';
 import { copyBaseTemplate } from './template.js';
 import { ProjectFiles } from './utils/files.js';
 import { PackageJsonEditor } from './utils/packageJson.js';
@@ -18,7 +19,7 @@ import { PackageJsonEditor } from './utils/packageJson.js';
  * Order matters: every overlay is written in TypeScript, so the TS → JS pass
  * runs after all of them, and formatting runs last.
  */
-export async function generateProject(options, onStep = () => { }) {
+export async function generateProject(options, cliVersion, onStep = () => { }) {
     const files = new ProjectFiles(options.targetDir);
     onStep('Copying the boilerplate');
     await copyBaseTemplate(options.targetDir);
@@ -42,6 +43,7 @@ export async function generateProject(options, onStep = () => { }) {
     }
     await pkg.save();
     await writeReadme(files, options);
+    await writeManifest(files, options, cliVersion);
     onStep('Formatting');
     await formatProject(files);
 }

package/dist/index.js

@@ -5,7 +5,9 @@ import { basename, join, relative, resolve } from 'node:path';
 import * as p from '@clack/prompts';
 import { Command, InvalidArgumentError } from 'commander';
 import pc from 'picocolors';
+import { addModule } from './add.js';
 import { generateProject } from './generate.js';
+import { MODULES } from './modules/index.js';
 import { CHOICES, defaultBundleId, DEFAULTS, STYLING_LABEL, toDisplayName, toPackageName, validateBundleId, validateProjectName, } from './options.js';
 import { detectPackageManager, PM } from './steps/packageManager.js';
 import { PACKAGE_ROOT } from './template.js';
@@ -18,8 +20,10 @@ const oneOf = (choices) => (value) => {
     return value;
 };
 const program = new Command()
+    // Options after `add` belong to `add`, not to project creation.
+    .enablePositionalOptions()
     .name('create-expo-boilerplate')
-    .description('Scaffold an Expo app from the React-Native-Expo-Boilterplate.')
+    .description('Scaffold an Expo app from react-native-expo-boilerplate.')
     .version(version)
     .argument('[directory]', 'where to create the project')
     .option('--state <library>', 'zustand | redux', oneOf(CHOICES.state))
@@ -43,7 +47,34 @@ Examples:
   $ npx create-expo-boilerplate my-app
   $ npx create-expo-boilerplate my-app --state redux --redux-middleware saga --navigation react-navigation
   $ npx create-expo-boilerplate my-app --styling tailwind
-  $ npx create-expo-boilerplate my-app --yes --js --no-husky`);
+  $ npx create-expo-boilerplate my-app --yes --js --no-husky
+
+Add a module to an existing project (run from its root):
+  $ npx create-expo-boilerplate add notifications`)
+    .action(() => createProject());
+const addCommand = program
+    .command('add')
+    .description('add a module to the project in the current directory')
+    .argument('[module]', Object.keys(MODULES).join(' | '))
+    .option('-y, --yes', 'accept defaults instead of prompting')
+    .option('--dry-run', 'show what would change without writing anything')
+    .option('--force', 'run even with uncommitted changes')
+    .option('--no-install', 'skip installing dependencies')
+    .addHelpText('after', `
+Modules:
+${Object.values(MODULES)
+    .map((m) => `  ${m.name.padEnd(16)}${m.description}`)
+    .join('\n')}
+
+Examples:
+  $ npx create-expo-boilerplate add notifications
+  $ npx create-expo-boilerplate add notifications --dry-run
+  $ npx create-expo-boilerplate add notifications --yes --token-endpoint users/me/devices`)
+    .action((name, flags) => addModule(name, flags, version));
+for (const mod of Object.values(MODULES)) {
+    for (const flag of mod.flags)
+        addCommand.option(flag.flags, flag.description);
+}
 function bail(value) {
     if (p.isCancel(value)) {
         p.cancel('Cancelled — nothing was created.');
@@ -68,8 +99,7 @@ async function isEmptyDir(dir) {
         return true; // doesn't exist yet
     }
 }
-async function main() {
-    program.parse();
+async function createProject() {
     const [dirArg] = program.args;
     const flags = program.opts();
     const defaults = Boolean(flags.yes) || !process.stdout.isTTY;
@@ -186,7 +216,7 @@ async function main() {
     const s = p.spinner();
     s.start('Generating project');
     try {
-        await generateProject(options, (msg) => s.message(msg));
+        await generateProject(options, version, (msg) => s.message(msg));
     }
     catch (error) {
         s.error('Generation failed');
@@ -248,7 +278,7 @@ async function main() {
         .filter(Boolean)
         .join(' · ')}`);
 }
-main().catch((error) => {
+program.parseAsync().catch((error) => {
     p.log.error(error instanceof Error ? error.message : String(error));
     process.exit(1);
 });

package/dist/manifest.js

@@ -0,0 +1,51 @@
+/**
+ * `boilerplate.json` — written into every generated project so `add` knows
+ * which stack it is patching. Projects created before it existed are detected
+ * from their files instead (see `detectStack`).
+ */
+export const MANIFEST_FILE = 'boilerplate.json';
+export async function writeManifest(files, options, cliVersion) {
+    const manifest = {
+        cliVersion,
+        navigation: options.navigation,
+        state: options.state,
+        styling: options.styling,
+        language: options.language,
+        modules: {},
+    };
+    await saveManifest(files, manifest);
+}
+export async function saveManifest(files, manifest) {
+    await files.write(MANIFEST_FILE, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+/** The manifest, or one rebuilt from the project's files when it's missing. */
+export async function loadManifest(files) {
+    if (files.exists(MANIFEST_FILE)) {
+        return { manifest: JSON.parse(await files.read(MANIFEST_FILE)), detected: false };
+    }
+    return {
+        manifest: { cliVersion: 'unknown', modules: {}, ...(await detectStack(files)) },
+        detected: true,
+    };
+}
+async function detectStack(files) {
+    const pkg = JSON.parse(await files.read('package.json'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return {
+        navigation: deps['expo-router'] ? 'expo-router' : 'react-navigation',
+        state: deps['@reduxjs/toolkit'] ? 'redux' : 'zustand',
+        styling: deps['react-native-unistyles']
+            ? 'unistyles'
+            : deps.uniwind
+                ? 'tailwind'
+                : 'stylesheet',
+        language: files.exists('tsconfig.json') ? 'ts' : 'js',
+    };
+}
+/** True when `dir` looks like a project this CLI generated. */
+export function isBoilerplateProject(files) {
+    return (files.exists(MANIFEST_FILE) ||
+        (files.exists('package.json') &&
+            (files.exists('src/providers/AppProviders.tsx') ||
+                files.exists('src/providers/AppProviders.jsx'))));
+}

package/dist/modules/index.js

@@ -0,0 +1,7 @@
+import { notifications } from './notifications.js';
+import { subscriptions } from './subscriptions.js';
+/** Every module `add` can generate. Add new ones here. */
+export const MODULES = {
+    [notifications.name]: notifications,
+    [subscriptions.name]: subscriptions,
+};