create-expo-boilerplate 1.1.2 → 1.2.0

package/dist/modules/notifications.js

@@ -0,0 +1,241 @@
+import { existsSync } from 'node:fs';
+import { copyFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import * as p from '@clack/prompts';
+import { MODULES_DIR } from '../template.js';
+import { pick } from '../versions.js';
+import { mergeTranslations, wireNavigationRef, wrapAppChildren } from './shared.js';
+import { CancelledError } from './types.js';
+const DIR = join(MODULES_DIR, 'notifications');
+const DEFAULT_ENDPOINT = 'devices/push-token';
+const FIREBASE_FILES = [
+    { name: 'google-services.json', platform: 'Android', flag: 'googleServices' },
+    { name: 'GoogleService-Info.plist', platform: 'iOS', flag: 'googleServiceInfo' },
+];
+const JEST_MOCKS = `
+// Push notifications (added by \`create-expo-boilerplate add notifications\`).
+// NotifyKit ships its own mock with real enum values. Firebase is stubbed to
+// exactly the modular surface \`src/notifications/service.ts\` calls, so a
+// regression to the deprecated namespaced API fails here rather than on device.
+jest.mock('react-native-notify-kit', () => require('react-native-notify-kit/jest-mock'));
+
+jest.mock('@react-native-firebase/app', () => ({
+  __esModule: true,
+  getApp: jest.fn().mockReturnValue({ name: '[DEFAULT]' }),
+}));
+
+jest.mock('@react-native-firebase/messaging', () => ({
+  __esModule: true,
+  getMessaging: jest.fn().mockReturnValue({}),
+  getToken: jest.fn().mockResolvedValue('test-fcm-token'),
+  registerDeviceForRemoteMessages: jest.fn().mockResolvedValue(undefined),
+  onTokenRefresh: jest.fn().mockReturnValue(jest.fn()),
+  onMessage: jest.fn().mockReturnValue(jest.fn()),
+  onNotificationOpenedApp: jest.fn().mockReturnValue(jest.fn()),
+  getInitialNotification: jest.fn().mockResolvedValue(null),
+  setBackgroundMessageHandler: jest.fn(),
+}));
+`;
+const firebaseHelper = (ts) => `
+// Firebase config files live in ./firebase/ (added by \`create-expo-boilerplate
+// add notifications\`). A missing file only warns here so Metro and
+// \`expo config\` keep working; \`expo prebuild\` fails until both are added.
+const firebaseFile = (name${ts ? ': string' : ''}) => {
+  const path = resolve(__dirname, 'firebase', name);
+  if (existsSync(path)) return path;
+  console.warn(\`[app.config] firebase/\${name} not found — native builds fail until you add it.\`);
+  return undefined;
+};
+`;
+async function askEndpoint(ctx, flag) {
+    const validate = (v) => !v?.trim()
+        ? 'An endpoint is required.'
+        : /[\s'"`\\]/.test(v)
+            ? 'No spaces, quotes or backslashes.'
+            : undefined;
+    if (typeof flag === 'string') {
+        const error = validate(flag);
+        if (error)
+            throw new Error(`--token-endpoint: ${error}`);
+        return flag.trim();
+    }
+    if (!ctx.interactive)
+        return DEFAULT_ENDPOINT;
+    const answer = await p.text({
+        message: 'Backend endpoint that receives the push token (POST, relative to EXPO_PUBLIC_API_URL)',
+        initialValue: DEFAULT_ENDPOINT,
+        validate,
+    });
+    if (p.isCancel(answer))
+        throw new CancelledError();
+    return answer.trim();
+}
+async function askBanner(ctx, flag) {
+    if (typeof flag === 'boolean')
+        return flag;
+    if (!ctx.interactive)
+        return true;
+    const answer = await p.confirm({
+        message: 'Show the notification permission banner on the Settings screen?',
+        initialValue: true,
+    });
+    if (p.isCancel(answer))
+        throw new CancelledError();
+    return answer;
+}
+/** Copies the Firebase files the user points at into ./firebase/. Returns the ones still missing. */
+async function copyFirebaseFiles(ctx, flags) {
+    const missing = [];
+    for (const file of FIREBASE_FILES) {
+        const dest = `firebase/${file.name}`;
+        if (ctx.files.exists(dest))
+            continue;
+        let source = typeof flags[file.flag] === 'string' ? flags[file.flag] : '';
+        if (!source && ctx.interactive) {
+            const answer = await p.text({
+                message: `Path to ${file.name} (${file.platform}) — press Enter to skip and add it later`,
+                placeholder: `~/Downloads/${file.name}`,
+                validate: (v) => {
+                    if (!v?.trim())
+                        return undefined;
+                    return existsSync(expand(v, ctx.cwd)) ? undefined : 'No file at that path.';
+                },
+            });
+            if (p.isCancel(answer))
+                throw new CancelledError();
+            source = answer ?? '';
+        }
+        if (!source.trim()) {
+            missing.push(file.name);
+            continue;
+        }
+        const abs = expand(source, ctx.cwd);
+        if (!existsSync(abs))
+            throw new Error(`${file.name}: no file at ${abs}`);
+        await ctx.files.write(dest, '');
+        await copyFile(abs, ctx.files.abs(dest));
+    }
+    return missing;
+}
+function expand(path, cwd) {
+    const trimmed = path.trim().replace(/^['"]|['"]$/g, '');
+    const home = process.env.HOME ?? '';
+    return resolve(cwd, trimmed.startsWith('~/') ? join(home, trimmed.slice(2)) : trimmed);
+}
+export const notifications = {
+    name: 'notifications',
+    description: 'Push + local notifications (Firebase Cloud Messaging + NotifyKit)',
+    flags: [
+        {
+            flags: '--token-endpoint <path>',
+            description: `notifications: token API (default ${DEFAULT_ENDPOINT})`,
+        },
+        {
+            flags: '--google-services <path>',
+            description: 'notifications: google-services.json to copy in',
+        },
+        {
+            flags: '--google-service-info <path>',
+            description: 'notifications: GoogleService-Info.plist to copy in',
+        },
+        // Both forms, so the prompt still runs when neither is passed.
+        { flags: '--banner', description: 'notifications: add the permission banner to Settings' },
+        { flags: '--no-banner', description: 'notifications: skip the permission banner' },
+    ],
+    async apply(ctx, flags) {
+        const { files, pkg, stack, patch } = ctx;
+        const ts = stack.language === 'ts';
+        const ext = (base) => ts ? base : base.replace(/\.ts$/, '.js').replace(/\.tsx$/, '.jsx');
+        const endpoint = await askEndpoint(ctx, flags.tokenEndpoint);
+        const banner = await askBanner(ctx, flags.banner);
+        const missingFirebase = await copyFirebaseFiles(ctx, flags);
+        // ── Module files ─────────────────────────────────────────
+        await files.overlay(join(DIR, 'files'));
+        if (stack.navigation === 'react-navigation') {
+            await files.overlay(join(DIR, 'overlays', 'react-navigation'));
+            await files.replace('src/notifications/useNotificationPermission.ts', "import { useFocusEffect } from 'expo-router';", "import { useFocusEffect } from '@react-navigation/native';");
+        }
+        if (stack.styling !== 'unistyles') {
+            await files.overlay(join(DIR, 'overlays', 'styling', stack.styling));
+        }
+        await files.replace('src/notifications/useNotificationSync.ts', '__TOKEN_ENDPOINT__', endpoint);
+        pkg.addDeps(pick('@react-native-firebase/app', '@react-native-firebase/messaging', 'react-native-notify-kit'));
+        // ── Copy ─────────────────────────────────────────────────
+        await mergeTranslations(ctx, DIR);
+        // ── Wiring ───────────────────────────────────────────────
+        await patch.insertBefore(patch.find('index.ts', 'index.js'), /^import (?:'expo-router\/entry'|\{ registerRootComponent \} from 'expo');/m, 
+        // The blank line keeps it out of the sorted `expo` import group (React Navigation entry).
+        "// Push notifications: background handlers + Android channels, before anything renders.\nimport '@/notifications/setup';\n\n", "add `import '@/notifications/setup';` to the entry file, above the router/app import.");
+        await wrapAppChildren(patch, 'NotificationRoot', '@/notifications');
+        if (stack.navigation === 'react-navigation') {
+            await wireNavigationRef(patch, 'notification taps can navigate');
+        }
+        if (banner) {
+            const settings = patch.find('src/features/settings/screens/SettingsScreen.tsx', 'src/features/settings/screens/SettingsScreen.jsx');
+            const bannerMsg = 'render `<NotificationPermissionBanner />` (from `@/notifications`) on the screen that should ask for permission.';
+            if (await patch.insertAfter(settings, /<ScreenWrapper[^>]*>\n/, '<NotificationPermissionBanner />\n', bannerMsg)) {
+                await patch.insertBefore(settings, /^import Button from/m, "import { NotificationPermissionBanner } from '@/notifications';\n", bannerMsg);
+            }
+        }
+        // ── Native config ────────────────────────────────────────
+        const appConfig = patch.find('app.config.ts', 'app.config.js');
+        const cfgMsg = (what) => `${what} — see src/notifications/README.md § Native setup.`;
+        await patch.insertAfter(appConfig, /^import Env from '\.\/env';\n/m, `${firebaseHelper(ts)}`, cfgMsg('add a `firebaseFile()` helper that resolves files in ./firebase/'));
+        const nodeImports = "import { existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\n";
+        await patch.edit(appConfig, (src) => {
+            if (src.includes("from 'node:fs'"))
+                return src;
+            // Sorted the way the project's simple-import-sort wants: with the other
+            // packages (`expo/config`, TS only), above the relative `./env` group.
+            const expoConfig = /^import \{[^}]*\} from 'expo\/config';\n/m.exec(src);
+            if (expoConfig) {
+                const end = expoConfig.index + expoConfig[0].length;
+                return src.slice(0, end) + nodeImports + src.slice(end);
+            }
+            const env = /^import Env from '\.\/env';/m.exec(src);
+            return env ? `${src.slice(0, env.index)}${nodeImports}\n${src.slice(env.index)}` : null;
+        }, cfgMsg("import `existsSync` from 'node:fs' and `resolve` from 'node:path'"));
+        await patch.insertAfter(appConfig, /^ {2}ios: \{\n/m, [
+            "    googleServicesFile: firebaseFile('GoogleService-Info.plist'),",
+            '    // No config plugin adds these. Without `aps-environment` iOS never issues an',
+            '    // APNs token, so FCM has nothing to send to. `development` is right for',
+            '    // App Store builds too — Xcode rewrites it to `production` when archiving.',
+            "    entitlements: { 'aps-environment': 'development' },",
+            "    infoPlist: { UIBackgroundModes: ['remote-notification'] },",
+            '',
+        ].join('\n'), cfgMsg("set `ios.googleServicesFile`, `ios.entitlements['aps-environment']` and `ios.infoPlist.UIBackgroundModes`"));
+        await patch.insertAfter(appConfig, /^ {2}android: \{\n/m, "    googleServicesFile: firebaseFile('google-services.json'),\n", cfgMsg('set `android.googleServicesFile`'));
+        await patch.insertBefore(appConfig, /^ {4}\[\n {6}'expo-build-properties',/m, [
+            "    '@react-native-firebase/app',",
+            "    '@react-native-firebase/messaging',",
+            "    'react-native-notify-kit',",
+            '    // Must match DEFAULT_CHANNEL_ID in src/notifications/config.ts.',
+            "    './plugins/withAndroidDefaultNotificationChannel',",
+            '',
+        ].join('\n'), cfgMsg('add the `@react-native-firebase/app`, `@react-native-firebase/messaging`, `react-native-notify-kit` and `./plugins/withAndroidDefaultNotificationChannel` plugins'));
+        await patch.edit(appConfig, (src) => {
+            if (src.includes('useFrameworks'))
+                return src;
+            const anchor = /'expo-build-properties',\n {6}\{\n/;
+            return anchor.test(src)
+                ? src.replace(anchor, (m) => `${m}        // React Native Firebase v27 pulls Firebase in via SPM, which needs frameworks.\n        ios: { useFrameworks: 'dynamic' },\n`)
+                : null;
+        }, cfgMsg("set `ios.useFrameworks: 'dynamic'` in the `expo-build-properties` plugin options"));
+        // ── Tests ────────────────────────────────────────────────
+        await patch.edit(patch.find('jest.setup.ts', 'jest.setup.js'), (src) => src.includes("jest.mock('react-native-notify-kit'")
+            ? src
+            : `${src.trimEnd()}\n${JEST_MOCKS}`, 'add the Firebase and NotifyKit mocks from src/notifications/README.md § Testing.');
+        await patch.edit('jest.config.js', (src) => src.includes('react-native-notify-kit')
+            ? src
+            : src.includes("'node_modules/(?!(' +\n")
+                ? src.replace("'node_modules/(?!(' +\n", "'node_modules/(?!(' +\n      'react-native-notify-kit|' +\n")
+                : null, 'add `react-native-notify-kit` to `transformIgnorePatterns`.');
+        // ── What's left ──────────────────────────────────────────
+        const steps = [];
+        if (missingFirebase.length) {
+            steps.push(`Required before the next native build: download ${missingFirebase.join(' and ')} from Firebase console → Project settings → Your apps (register the app with your bundle id / package first), and save ${missingFirebase.length > 1 ? 'them' : 'it'} in firebase/.`);
+        }
+        steps.push('Upload your APNs auth key (.p8) in Firebase console → Project settings → Cloud Messaging, so FCM can deliver to iOS.', `Make your backend accept POST ${endpoint} with { token, platform } (or edit ${ext('src/notifications/useNotificationSync.ts')}).`, 'Rebuild the dev client — these are new native modules: npx expo prebuild --clean, then run ios:development / android:development.', 'Test remote push on a physical iPhone; the iOS simulator gets no push token.');
+        return steps;
+    },
+};

package/dist/modules/shared.js

@@ -0,0 +1,67 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Adds `source`'s keys to `target`, recursively. Existing values always win. */
+export function deepMerge(target, source) {
+    const out = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        const existing = out[key];
+        out[key] =
+            value && typeof value === 'object' && existing && typeof existing === 'object'
+                ? deepMerge(existing, value)
+                : (existing ?? value);
+    }
+    return out;
+}
+/**
+ * Merges `<moduleDir>/translations/<lang>.json` into every translation file the
+ * project has. A language the module doesn't ship gets the English strings.
+ */
+export async function mergeTranslations({ files }, moduleDir) {
+    const dir = join(moduleDir, 'translations');
+    const fallback = JSON.parse(await readFile(join(dir, 'en.json'), 'utf8'));
+    for (const rel of await files.list('src/localization/translations')) {
+        if (!rel.endsWith('.json'))
+            continue;
+        const lang = rel.split('/').pop().replace('.json', '');
+        const own = join(dir, `${lang}.json`);
+        const strings = existsSync(own) ? JSON.parse(await readFile(own, 'utf8')) : fallback;
+        const merged = deepMerge(JSON.parse(await files.read(rel)), strings);
+        await files.write(rel, `${JSON.stringify(merged, null, 2)}\n`);
+    }
+}
+/**
+ * Wraps the navigation root (`{children}` inside `<APIProvider>` in
+ * AppProviders) in `<Tag>`, and imports it. Works whichever modules already
+ * wrapped it: the new wrapper goes innermost.
+ */
+export async function wrapAppChildren(patch, tag, from) {
+    const providers = patch.find('src/providers/AppProviders.tsx', 'src/providers/AppProviders.jsx');
+    const manual = `wrap the navigation root in \`<${tag}>\` (from \`${from}\`), inside \`<APIProvider>\`.`;
+    const wrapped = await patch.edit(providers, (src) => {
+        if (src.includes(`<${tag}>`))
+            return src;
+        const re = /(<APIProvider>[\s\S]*?)\{children\}/;
+        return re.test(src) ? src.replace(re, `$1<${tag}>{children}</${tag}>`) : null;
+    }, manual);
+    if (wrapped) {
+        await patch.insertBefore(providers, /^import \{ APIProvider \}/m, `import { ${tag} } from '${from}';\n`, manual);
+    }
+}
+/**
+ * React Navigation only: passes `src/navigation/navigationRef` to the
+ * `NavigationContainer`, so code outside a screen can navigate. The ref file
+ * itself comes from the module's react-navigation overlay.
+ */
+export async function wireNavigationRef(patch, why) {
+    const app = patch.find('src/App.tsx', 'src/App.jsx');
+    const manual = `pass \`ref={navigationRef}\` (from \`@/navigation/navigationRef\`) to \`<NavigationContainer>\` so ${why}.`;
+    const wired = await patch.edit(app, (src) => src.includes('ref={navigationRef}')
+        ? src
+        : /<NavigationContainer(\s)/.test(src)
+            ? src.replace(/<NavigationContainer(\s)/, '<NavigationContainer ref={navigationRef}$1')
+            : null, manual);
+    if (wired) {
+        await patch.insertBefore(app, /^import \{ AppProviders/m, "import { navigationRef } from '@/navigation/navigationRef';\n", manual);
+    }
+}

package/dist/modules/subscriptions.js

@@ -0,0 +1,223 @@
+import { join } from 'node:path';
+import * as p from '@clack/prompts';
+import { MODULES_DIR } from '../template.js';
+import { pick } from '../versions.js';
+import { mergeTranslations, wireNavigationRef, wrapAppChildren } from './shared.js';
+import { CancelledError } from './types.js';
+const DIR = join(MODULES_DIR, 'subscriptions');
+const DEFAULT_ENTITLEMENT = 'premium';
+const ENV_FILES = ['.env.development', '.env.staging', '.env.production'];
+const KEY_IOS = 'EXPO_PUBLIC_REVENUECAT_API_KEY_IOS';
+const KEY_ANDROID = 'EXPO_PUBLIC_REVENUECAT_API_KEY_ANDROID';
+const JEST_MOCKS = `
+// Subscriptions (added by \`create-expo-boilerplate add subscriptions\`).
+// react-native-purchases needs native modules and ships untranspiled ESM. The
+// enums are mocked whole, with the SDK's real values: a partial mock leaves
+// codes \`undefined\`, so distinct \`switch\` cases collapse into the first one.
+jest.mock('@gorhom/bottom-sheet', () => require('@gorhom/bottom-sheet/mock'));
+jest.mock('react-native-purchases', () => ({
+  __esModule: true,
+  LOG_LEVEL: { DEBUG: 'DEBUG', ERROR: 'ERROR' },
+  PURCHASES_ERROR_CODE: {
+    UNKNOWN_ERROR: '0',
+    PURCHASE_CANCELLED_ERROR: '1',
+    STORE_PROBLEM_ERROR: '2',
+    PURCHASE_NOT_ALLOWED_ERROR: '3',
+    PURCHASE_INVALID_ERROR: '4',
+    PRODUCT_NOT_AVAILABLE_FOR_PURCHASE_ERROR: '5',
+    PRODUCT_ALREADY_PURCHASED_ERROR: '6',
+    RECEIPT_ALREADY_IN_USE_ERROR: '7',
+    INVALID_RECEIPT_ERROR: '8',
+    MISSING_RECEIPT_FILE_ERROR: '9',
+    NETWORK_ERROR: '10',
+    INVALID_CREDENTIALS_ERROR: '11',
+    UNEXPECTED_BACKEND_RESPONSE_ERROR: '12',
+    RECEIPT_IN_USE_BY_OTHER_SUBSCRIBER_ERROR: '13',
+    INVALID_APP_USER_ID_ERROR: '14',
+    OPERATION_ALREADY_IN_PROGRESS_ERROR: '15',
+    UNKNOWN_BACKEND_ERROR: '16',
+    INVALID_APPLE_SUBSCRIPTION_KEY_ERROR: '17',
+    INELIGIBLE_ERROR: '18',
+    INSUFFICIENT_PERMISSIONS_ERROR: '19',
+    PAYMENT_PENDING_ERROR: '20',
+    INVALID_SUBSCRIBER_ATTRIBUTES_ERROR: '21',
+    LOG_OUT_ANONYMOUS_USER_ERROR: '22',
+    CONFIGURATION_ERROR: '23',
+    UNSUPPORTED_ERROR: '24',
+    EMPTY_SUBSCRIBER_ATTRIBUTES_ERROR: '25',
+    PRODUCT_DISCOUNT_MISSING_IDENTIFIER_ERROR: '26',
+    PRODUCT_DISCOUNT_MISSING_SUBSCRIPTION_GROUP_IDENTIFIER_ERROR: '28',
+    CUSTOMER_INFO_ERROR: '29',
+    SYSTEM_INFO_ERROR: '30',
+    BEGIN_REFUND_REQUEST_ERROR: '31',
+    PRODUCT_REQUEST_TIMED_OUT_ERROR: '32',
+    API_ENDPOINT_BLOCKED: '33',
+    INVALID_PROMOTIONAL_OFFER_ERROR: '34',
+    OFFLINE_CONNECTION_ERROR: '35',
+    TEST_STORE_SIMULATED_PURCHASE_ERROR: '42',
+  },
+  PACKAGE_TYPE: {
+    UNKNOWN: 'UNKNOWN',
+    CUSTOM: 'CUSTOM',
+    LIFETIME: 'LIFETIME',
+    ANNUAL: 'ANNUAL',
+    SIX_MONTH: 'SIX_MONTH',
+    THREE_MONTH: 'THREE_MONTH',
+    TWO_MONTH: 'TWO_MONTH',
+    MONTHLY: 'MONTHLY',
+    WEEKLY: 'WEEKLY',
+  },
+  INTRO_ELIGIBILITY_STATUS: {
+    INTRO_ELIGIBILITY_STATUS_UNKNOWN: 0,
+    INTRO_ELIGIBILITY_STATUS_INELIGIBLE: 1,
+    INTRO_ELIGIBILITY_STATUS_ELIGIBLE: 2,
+    INTRO_ELIGIBILITY_STATUS_NO_INTRO_OFFER_EXISTS: 3,
+  },
+  STORE_REPLACEMENT_MODE: {
+    WITHOUT_PRORATION: 'WITHOUT_PRORATION',
+    WITH_TIME_PRORATION: 'WITH_TIME_PRORATION',
+    CHARGE_FULL_PRICE: 'CHARGE_FULL_PRICE',
+    CHARGE_PRORATED_PRICE: 'CHARGE_PRORATED_PRICE',
+    DEFERRED: 'DEFERRED',
+  },
+  default: {
+    addCustomerInfoUpdateListener: jest.fn(),
+    checkTrialOrIntroductoryPriceEligibility: jest.fn().mockResolvedValue({}),
+    configure: jest.fn(),
+    getAppUserID: jest.fn().mockResolvedValue('mock-app-user-id'),
+    getCustomerInfo: jest.fn().mockResolvedValue(null),
+    getOfferings: jest.fn().mockResolvedValue({ current: null, all: {} }),
+    invalidateCustomerInfoCache: jest.fn().mockResolvedValue(undefined),
+    isAnonymous: jest.fn().mockResolvedValue(true),
+    logIn: jest.fn().mockResolvedValue({ customerInfo: null, created: false }),
+    logOut: jest.fn().mockResolvedValue(null),
+    purchasePackage: jest.fn().mockResolvedValue({ customerInfo: null }),
+    removeCustomerInfoUpdateListener: jest.fn(),
+    restorePurchases: jest.fn().mockResolvedValue(null),
+    setDisplayName: jest.fn().mockResolvedValue(undefined),
+    setEmail: jest.fn().mockResolvedValue(undefined),
+    setLogLevel: jest.fn(),
+    syncPurchases: jest.fn().mockResolvedValue(undefined),
+  },
+}));
+`;
+async function ask(ctx, flag, prompt, fallback) {
+    if (typeof flag === 'string')
+        return flag.trim();
+    if (!ctx.interactive)
+        return fallback;
+    const answer = await p.text(prompt);
+    if (p.isCancel(answer))
+        throw new CancelledError();
+    return (answer ?? '').trim();
+}
+const NO_QUOTES = /^[^'"`\\\n]*$/;
+export const subscriptions = {
+    name: 'subscriptions',
+    dir: 'subscription',
+    description: 'In-app subscriptions (RevenueCat): paywall, premium gate, every store state',
+    flags: [
+        {
+            flags: '--entitlement <id>',
+            description: `subscriptions: RevenueCat entitlement id (default ${DEFAULT_ENTITLEMENT})`,
+        },
+        { flags: '--revenuecat-ios-key <key>', description: 'subscriptions: public SDK key (appl_…)' },
+        {
+            flags: '--revenuecat-android-key <key>',
+            description: 'subscriptions: public SDK key (goog_…)',
+        },
+    ],
+    async apply(ctx, flags) {
+        const { files, pkg, stack, patch } = ctx;
+        const ts = stack.language === 'ts';
+        const ext = (rel) => (ts ? rel : rel.replace(/\.ts$/, '.js').replace(/\.tsx$/, '.jsx'));
+        const entitlement = await ask(ctx, flags.entitlement, {
+            message: 'RevenueCat entitlement identifier (RevenueCat → Product catalog → Entitlements)',
+            initialValue: DEFAULT_ENTITLEMENT,
+            validate: (v) => !v?.trim() ? 'Required.' : NO_QUOTES.test(v) ? undefined : 'No quotes or backslashes.',
+        }, DEFAULT_ENTITLEMENT);
+        if (!entitlement || !NO_QUOTES.test(entitlement)) {
+            throw new Error('--entitlement: a non-empty id without quotes or backslashes.');
+        }
+        const keyPrompt = (platform, prefix) => ({
+            message: `RevenueCat ${platform} public SDK key (${prefix}…) — press Enter to skip and add it later`,
+            validate: (v) => !v?.trim() || /^[A-Za-z0-9_]+$/.test(v.trim()) ? undefined : 'Letters, digits and _ only.',
+        });
+        const iosKey = await ask(ctx, flags.revenuecatIosKey, keyPrompt('iOS', 'appl_'), '');
+        const androidKey = await ask(ctx, flags.revenuecatAndroidKey, keyPrompt('Android', 'goog_'), '');
+        // ── Module files ─────────────────────────────────────────
+        await files.overlay(join(DIR, 'files'));
+        if (stack.navigation === 'react-navigation') {
+            await files.remove('src/app'); // the Expo Router route file
+            await files.overlay(join(DIR, 'overlays', 'react-navigation'));
+        }
+        if (stack.styling !== 'unistyles') {
+            await files.overlay(join(DIR, 'overlays', 'styling', stack.styling));
+        }
+        await files.replace('src/subscription/config.ts', '__ENTITLEMENT_ID__', entitlement);
+        pkg.addDeps(pick('react-native-purchases', '@gorhom/bottom-sheet'));
+        await mergeTranslations(ctx, DIR);
+        // ── Env: the RevenueCat keys ─────────────────────────────
+        const envFile = patch.find('env.ts', 'env.js');
+        const envMsg = `add optional \`${KEY_IOS}\` / \`${KEY_ANDROID}\` to the env schema and object in env.ts.`;
+        await patch.insertAfter(envFile, /^ *EXPO_PUBLIC_API_URL: z\.string\(\)[^\n]*\n/m, `\n  // RevenueCat public SDK keys (optional — subscriptions stay off without them)\n  ${KEY_IOS}: z.string().optional(),\n  ${KEY_ANDROID}: z.string().optional(),\n`, envMsg);
+        await patch.insertAfter(envFile, /^ *EXPO_PUBLIC_API_URL: process\.env\.EXPO_PUBLIC_API_URL[^\n]*\n/m, `  ${KEY_IOS}: process.env.${KEY_IOS},\n  ${KEY_ANDROID}: process.env.${KEY_ANDROID},\n`, envMsg);
+        await patch.edit('.env.example', (src) => src.includes(KEY_IOS)
+            ? src
+            : `${src.trimEnd()}\n\n# RevenueCat public SDK keys (Project settings → API keys). Public by design.\n${KEY_IOS}=\n${KEY_ANDROID}=\n`, `add \`${KEY_IOS}=\` and \`${KEY_ANDROID}=\` to .env.example.`);
+        for (const rel of ENV_FILES) {
+            if (!files.exists(rel))
+                continue;
+            const src = await files.read(rel);
+            if (src.includes(KEY_IOS))
+                continue;
+            await files.write(rel, `${src.trimEnd()}\n\n# RevenueCat public SDK keys\n${KEY_IOS}=${iosKey}\n${KEY_ANDROID}=${androidKey}\n`);
+        }
+        // ── Wiring ───────────────────────────────────────────────
+        await wrapAppChildren(patch, 'SubscriptionRoot', '@/subscription');
+        if (stack.navigation === 'expo-router') {
+            await patch.insertAfter(patch.find('src/app/_layout.tsx', 'src/app/_layout.jsx'), /^ *<Stack\.Screen name="\(tabs\)" \/>\n/m, '        <Stack.Screen name="subscription" />\n', 'register `<Stack.Screen name="subscription" />` inside the signed-in `Stack.Protected` guard.');
+        }
+        else {
+            await wireNavigationRef(patch, 'the premium gate can open the paywall');
+            const routeMsg = "register the paywall: `subscription: 'Subscription'` in NAVIGATION, a `[NAVIGATION.subscription]: undefined` param, `[NAVIGATION.subscription]: 'subscription'` in linking.ts, and `<Stack.Screen component={PaywallScreen} name={NAVIGATION.subscription} />` in the signed-in branch of RootNavigator.";
+            await patch.insertBefore(patch.find('src/shared/constants/navigation.ts', 'src/shared/constants/navigation.js'), 
+            // `} as const;` in TypeScript, `};` once transpiled to JavaScript.
+            /^}( as const)?;/m, "  subscription: 'Subscription',\n", routeMsg);
+            if (ts) {
+                await patch.insertAfter('src/navigation/types.ts', /^ *\[NAVIGATION\.main\]: NavigatorScreenParams<MainTabParamList>;\n/m, '  [NAVIGATION.subscription]: undefined;\n', routeMsg);
+            }
+            await patch.insertAfter(patch.find('src/navigation/linking.ts', 'src/navigation/linking.js'), /^ {4}screens: \{\n/m, "      [NAVIGATION.subscription]: 'subscription',\n", routeMsg);
+            const rootNavigator = patch.find('src/navigation/RootNavigator.tsx', 'src/navigation/RootNavigator.jsx');
+            const mainScreen = '<Stack.Screen component={MainTabNavigator} name={NAVIGATION.main} />';
+            if (await patch.edit(rootNavigator, (src) => src.includes('NAVIGATION.subscription')
+                ? src
+                : src.includes(mainScreen)
+                    ? src.replace(mainScreen, `<>\n${mainScreen}\n<Stack.Screen component={PaywallScreen} name={NAVIGATION.subscription} />\n</>`)
+                    : null, routeMsg)) {
+                await patch.insertAfter(rootNavigator, /^import \{ NAVIGATION \} from '@\/shared\/constants';\n/m, "import { PaywallScreen } from '@/subscription';\n", routeMsg);
+            }
+        }
+        // ── Tests ────────────────────────────────────────────────
+        await patch.edit(patch.find('jest.setup.ts', 'jest.setup.js'), (src) => src.includes("jest.mock('react-native-purchases'")
+            ? src
+            : `${src.trimEnd()}\n${JEST_MOCKS}`, 'add the react-native-purchases and @gorhom/bottom-sheet mocks to jest.setup.');
+        // The tests format real copy through i18n, which loads expo-localization
+        // and, through it, other expo-* packages — all untranspiled ESM. Projects
+        // created before the template covered expo-* need it added.
+        await patch.edit('jest.config.js', (src) => 
+        // Templates from this version on already include it.
+        src.includes('expo-[a-z-]+')
+            ? src
+            : src.includes("'node_modules/(?!(' +\n")
+                ? src.replace("'node_modules/(?!(' +\n", "'node_modules/(?!(' +\n      'expo-[a-z-]+|' +\n")
+                : null, 'add `expo-[a-z-]+` to `transformIgnorePatterns`, so expo-* packages are transpiled.');
+        // ── What's left ──────────────────────────────────────────
+        const steps = [];
+        if (!iosKey || !androidKey) {
+            steps.push(`Add your RevenueCat public SDK keys to .env.development / .staging / .production (${KEY_IOS}, ${KEY_ANDROID}). Until then subscriptions are switched off and the paywall says plans couldn't load.`);
+        }
+        steps.push(`Map your user to a RevenueCat id in ${ext('src/subscription/useSubscriptionUser.ts')} — until then purchases are attributed to an anonymous id per install.`, `Set TERMS_OF_USE_URL and PRIVACY_POLICY_URL in ${ext('src/subscription/config.ts')} — both stores reject a paywall without them.`, `In RevenueCat: create the "${entitlement}" entitlement, attach your products, and mark an offering as current.`, 'Gate a feature: const { requirePremium } = useSubscription(); requirePremium(() => doIt()).', 'Rebuild the dev client — react-native-purchases is a native module: npx expo prebuild --clean, then run ios:development / android:development.', 'Test purchases with sandbox/test accounts (StoreKit sandbox on iOS, a license tester on Play); the simulator can show offerings but not complete a real purchase.');
+        return steps;
+    },
+};

package/dist/modules/types.js

@@ -0,0 +1,57 @@
+/** Thrown when the user cancels a prompt. */
+export class CancelledError extends Error {
+}
+/** Edits to files the user owns, with a manual fallback when one no longer matches. */
+export class Patcher {
+    files;
+    /** Instructions for edits that couldn't be applied automatically. */
+    manual = [];
+    constructor(files) {
+        this.files = files;
+    }
+    /** The first of `candidates` that exists (e.g. `index.ts` / `index.js`). */
+    find(...candidates) {
+        return candidates.find((rel) => this.files.exists(rel)) ?? null;
+    }
+    /**
+     * Applies `edit` to `rel`. `edit` returns the new content, or `null` when its
+     * anchor isn't there (the file was customised) — then `manual` is recorded
+     * for the user instead of guessing. Returns whether the edit was applied.
+     */
+    async edit(rel, edit, manual) {
+        if (!rel || !this.files.exists(rel)) {
+            this.manual.push(manual);
+            return false;
+        }
+        const source = await this.files.read(rel);
+        const next = edit(source);
+        if (next === null) {
+            this.manual.push(`${rel}: ${manual}`);
+            return false;
+        }
+        if (next !== source)
+            await this.files.write(rel, next);
+        return true;
+    }
+    /** Inserts `text` before the first match of `anchor`, unless `text` is already present. */
+    insertBefore(rel, anchor, text, manual) {
+        return this.edit(rel, (src) => {
+            if (src.includes(text.trim()))
+                return src;
+            const match = anchor.exec(src);
+            return match ? src.slice(0, match.index) + text + src.slice(match.index) : null;
+        }, manual);
+    }
+    /** Inserts `text` after the first match of `anchor`, unless `text` is already present. */
+    insertAfter(rel, anchor, text, manual) {
+        return this.edit(rel, (src) => {
+            if (src.includes(text.trim()))
+                return src;
+            const match = anchor.exec(src);
+            if (!match)
+                return null;
+            const end = match.index + match[0].length;
+            return src.slice(0, end) + text + src.slice(end);
+        }, manual);
+    }
+}

package/dist/steps/format.js

@@ -8,11 +8,20 @@ const JSON_FILES = ['package.json', 'eas.json', 'jsconfig.json', 'tsconfig.json'
  * for files nobody touched.
  */
 export async function formatProject(files) {
-    const config = (await prettier.resolveConfig(files.abs('.prettierrc'))) ?? {};
     const targets = (await files.list()).filter((rel) => (CODE_RE.test(rel) && !rel.startsWith('scripts/')) || JSON_FILES.includes(rel));
+    await formatFiles(files, targets);
+}
+/**
+ * Prettier over `rels` (code and JSON only), with the project's own config.
+ * Pass the project's own Prettier when it has one installed: another version
+ * can format the same code differently, and the project's ESLint would flag it.
+ */
+export async function formatFiles(files, rels, engine = prettier) {
+    const config = (await engine.resolveConfig(files.abs('.prettierrc'))) ?? {};
+    const targets = rels.filter((rel) => CODE_RE.test(rel) || rel.endsWith('.json'));
     for (const rel of targets) {
         const source = await files.read(rel);
-        const formatted = await prettier.format(source, { ...config, filepath: files.abs(rel) });
+        const formatted = await engine.format(source, { ...config, filepath: files.abs(rel) });
         if (formatted !== source)
             await files.write(rel, formatted);
     }