create-disposabl-app 0.0.4 → 0.1.1

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/bundle-code-splitting.md

@@ -0,0 +1,255 @@
+---
+title: Remote Chunk Loading
+impact: MEDIUM
+tags: code-splitting, lazy-loading, chunks, release-artifacts, remote-code
+---
+
+# Skill: Remote Chunk Loading
+
+Harden remote JavaScript chunk loading when a React Native app already uses Re.Pack or has an explicit remote-code-loading requirement.
+
+## Quick Pattern
+
+**Before (static import):**
+
+```jsx
+import SettingsScreen from './screens/SettingsScreen';
+```
+
+**After (lazy loaded chunk):**
+
+```jsx
+const SettingsScreen = React.lazy(() =>
+  import(/* webpackChunkName: "settings" */ './screens/SettingsScreen')
+);
+
+<Suspense fallback={<Loading />}>
+  <SettingsScreen />
+</Suspense>
+```
+
+## When to Use
+
+Consider code splitting when:
+- **Not using Hermes** (JSC/V8 benefits more)
+- App size approaches app-store or base-module limits
+- The app already has a micro-frontend architecture
+- Loading features based on user permissions
+- Other bundle-size optimizations are exhausted
+- Remote delivery is an explicit product or release requirement
+
+Do not recommend adopting Re.Pack for ordinary bundle-size work. Keep the default path on Metro/Expo unless remote chunk loading is already present or specifically required.
+
+**Note**: Hermes already uses memory mapping for efficient bundle reading. Benefits of code splitting are minimal with Hermes or even counterproductive in some cases.
+
+## Security Model
+
+Chunks are executable application code. Prefer chunks packaged with the app or resolved from a release manifest produced by your CI. Hosted chunks are acceptable only when they are first-party release artifacts, not arbitrary runtime URLs.
+
+Keep these guardrails in place:
+- Serve chunks only from a first-party, HTTPS-only origin you control
+- Resolve `scriptId` through a fixed allowlist or signed release manifest
+- If using Re.Pack, enable code signing for remotely hosted chunks and use strict signature verification in production
+- Fail closed if a chunk is missing or unexpected
+- Do not load chunks from user-controlled input, query params, or third-party domains
+
+## Prerequisites
+
+- Project already uses Re.Pack, or remote chunk loading is an explicit requirement approved after measuring simpler alternatives
+- Remote chunks are produced by the same release pipeline as the app
+- Chunk locations come from a fixed allowlist or signed release manifest
+
+If the project does not already use Re.Pack, do not start here. First confirm Metro/Expo bundle analysis, import cleanup, asset cleanup, native app-size work, and store delivery constraints.
+
+## Step-by-Step Instructions
+
+### 1. Create Split Point with React.lazy
+
+```tsx
+// BEFORE: Static import
+import SettingsScreen from './screens/SettingsScreen';
+
+// AFTER: Dynamic import (creates split point)
+const SettingsScreen = React.lazy(() =>
+  import(/* webpackChunkName: "settings" */ './screens/SettingsScreen')
+);
+```
+
+### 2. Wrap with Suspense
+
+```tsx
+import React, { Suspense } from 'react';
+
+const App = () => {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <SettingsScreen />
+    </Suspense>
+  );
+};
+```
+
+### 3. Configure Chunk Loading
+
+```jsx
+// index.js (before AppRegistry)
+import { ScriptManager, Script } from '@callstack/repack/client';
+
+const RELEASE_CHUNKS = Object.freeze({
+  settings: {
+    release: '42',
+  },
+});
+
+ScriptManager.shared.addResolver(async (scriptId) => {
+  if (__DEV__) {
+    return {
+      url: Script.getDevServerURL(scriptId),
+      cache: false,
+    };
+  }
+
+  const chunk = RELEASE_CHUNKS[scriptId];
+
+  if (!chunk) {
+    throw new Error(`Unknown chunk: ${scriptId}`);
+  }
+
+  return {
+    url: Script.getRemoteURL(
+      getFirstPartyChunkBaseURL(scriptId, chunk.release)
+    ),
+    verifyScriptSignature: 'strict',
+  };
+});
+
+function getFirstPartyChunkBaseURL(scriptId, release) {
+  // App-owned helper: read a signed CI manifest and return the first-party
+  // base URL without ".chunk.bundle"; Script.getRemoteURL appends it.
+  // Do not accept hostnames, paths, or script IDs from runtime input.
+  return ReleaseManifest.getChunkBaseURL({ scriptId, release });
+}
+
+AppRegistry.registerComponent(appName, () => App);
+```
+
+For app-bundled chunks in a Re.Pack project, configure `extraChunks` with `type: 'local'` and resolve those script IDs from the filesystem:
+
+```jsx
+if (LOCAL_CHUNKS.has(scriptId)) {
+  return {
+    url: Script.getFileSystemURL(scriptId),
+    absolute: true,
+  };
+}
+```
+
+### 4. Build and Deploy Chunks
+
+Build generates:
+- `index.bundle` - Main bundle
+- `settings.chunk.bundle` - Lazy-loaded chunk
+
+Remote chunks are written to `build/output/<platform>/remotes` by default. Deploy chunks as first-party release artifacts. Prefer app-bundled assets; if hosted, publish them through CI to an app-owned HTTPS origin and keep the allowlist or signed manifest in sync with the app release.
+
+## Complete Example
+
+```tsx
+// App.tsx
+import React, { Suspense, useState } from 'react';
+import { Button, View, ActivityIndicator } from 'react-native';
+
+// Lazy load heavy feature
+const HeavyFeature = React.lazy(() =>
+  import(/* webpackChunkName: "heavy-feature" */ './HeavyFeature')
+);
+
+const App = () => {
+  const [showFeature, setShowFeature] = useState(false);
+  
+  return (
+    <View>
+      <Button 
+        title="Load Feature" 
+        onPress={() => setShowFeature(true)} 
+      />
+      
+      {showFeature && (
+        <Suspense fallback={<ActivityIndicator />}>
+          <HeavyFeature />
+        </Suspense>
+      )}
+    </View>
+  );
+};
+```
+
+## Module Federation
+
+Only use Module Federation when the app already has a micro-frontend architecture and the organizational boundary is worth the runtime trust boundary:
+
+```tsx
+// Host app loads remote module
+const RemoteModule = React.lazy(() =>
+  import('remote-app/Module')
+);
+```
+
+Federation increases the trust boundary. Keep the same first-party origin, release-manifest, code-signing, and allowlist rules as above.
+
+## Caching Strategy
+
+```tsx
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+ScriptManager.shared.setStorage(AsyncStorage);
+```
+
+Set storage before adding resolvers so Re.Pack can cache resolved script locator data. Return `cache: false` for dev server chunks or any script that should bypass caching.
+
+## When NOT to Use
+
+| Scenario | Why Not |
+|----------|---------|
+| Using Hermes | mmap already efficient |
+| Small app | Overhead not worth it |
+| Simple navigation | Native navigation better |
+| Quick iteration needed | Added complexity |
+
+## Hermes Memory Mapping
+
+Hermes reads bytecode lazily via mmap:
+- Only loads executed code into memory
+- No parse step needed
+- Code splitting provides marginal benefit
+
+## Verification
+
+```tsx
+// Check if chunk loaded correctly
+ScriptManager.shared.on('loading', (script) => {
+  console.log(`Loading: ${script.scriptId}`);
+});
+
+ScriptManager.shared.on('loaded', (script) => {
+  console.log(`Loaded: ${script.scriptId}`);
+});
+
+ScriptManager.shared.on('error', (error) => {
+  console.error('Script loading failed:', error);
+});
+```
+
+## Common Pitfalls
+
+- **Forgetting Suspense**: Lazy components need fallback
+- **Wrong CDN path**: Chunks 404 in production
+- **No caching**: Re-downloads on every load
+- **Too many chunks**: Network overhead exceeds savings
+- **Untrusted chunk source**: JS chunks from third-party or user-controlled origins are equivalent to remote code execution
+
+## Related Skills
+
+- [bundle-tree-shaking.md](./bundle-tree-shaking.md) - Tree-shaking caveats
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Measure chunk sizes
+- [native-measure-tti.md](./native-measure-tti.md) - Verify TTI impact

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/bundle-hermes-mmap.md

@@ -0,0 +1,167 @@
+---
+title: Disable JS Bundle Compression
+impact: HIGH
+tags: android, hermes, mmap, tti, startup
+---
+
+# Skill: Disable JS Bundle Compression
+
+Disable Android JS bundle compression to enable Hermes memory mapping for faster startup on React Native 0.78 and earlier.
+
+## Quick Config
+
+```groovy
+// android/app/build.gradle, React Native 0.78 and earlier fallback
+android {
+    androidResources {
+        noCompress += ["bundle"]
+    }
+}
+```
+
+**Note**: React Native 0.79+ defaults to uncompressed Android JS bundles. Prefer checking/toggling `react { enableBundleCompression = false }` there instead of adding `androidResources.noCompress` manually.
+
+## When to Use
+
+- Android app using Hermes
+- Want faster TTI (Time to Interactive)
+- Willing to trade install size for startup speed
+- React Native version is 0.78 or earlier, skip otherwise (see applicability)
+
+## Background
+
+Android compresses most files in APK/AAB by default, including `index.android.bundle`.
+
+**Problem**: Compressed files can't be memory-mapped (mmap).
+
+**Impact**: Hermes must decompress before reading, losing one of its key optimizations.
+
+## How Hermes Memory Mapping Works
+
+Without compression:
+1. Hermes opens bytecode file
+2. OS memory-maps directly to disk
+3. Only pages actually accessed are loaded
+4. **Result**: Fast startup, low memory
+
+With compression:
+1. Android decompresses entire bundle
+2. Loaded into memory
+3. Then Hermes processes
+4. **Result**: Slower startup, higher memory
+
+## Step-by-Step Implementation
+
+### Edit build.gradle
+
+For React Native 0.78 and earlier, edit `android/app/build.gradle`:
+
+```groovy
+android {
+    androidResources {
+        noCompress += ["bundle"]
+    }
+}
+```
+
+### Full Context
+
+```groovy
+android {
+    namespace "com.myapp"
+    defaultConfig {
+        applicationId "com.myapp"
+        // ...
+    }
+    
+    androidResources {
+        noCompress += ["bundle"]
+    }
+    
+    buildTypes {
+        release {
+            minifyEnabled true
+            // ...
+        }
+    }
+}
+```
+
+### Rebuild
+
+```bash
+cd android
+./gradlew clean
+./gradlew bundleRelease
+# or
+./gradlew assembleRelease
+```
+
+## Trade-offs
+
+| Metric | Without Change | With Change |
+|--------|----------------|-------------|
+| Download size | Same | Same |
+| Install size | Smaller | **+8% larger** |
+| TTI | Slower | **-16% faster** |
+
+**Real example**: 75.9 MB install → 82 MB install, but 450ms faster startup.
+
+## Applicability
+
+**React Native 0.78 and earlier**: Apply this optimization manually.
+
+**React Native 0.79+**: Skip this unless the project explicitly enabled bundle compression.
+
+## Verification
+
+### Check APK Contents
+
+```bash
+# Unzip APK
+unzip app-release.apk -d apk-contents
+
+# Check if bundle is compressed
+file apk-contents/assets/index.android.bundle
+# Should show: "data" (not "gzip compressed")
+```
+
+### Measure TTI Impact
+
+Use performance markers (see [native-measure-tti.md](./native-measure-tti.md)) to compare before/after.
+
+## Multiple File Types
+
+If you have other files that benefit from mmap:
+
+```groovy
+androidResources {
+    noCompress += ["bundle", "hbc", "data"]
+}
+```
+
+## Common Pitfalls
+
+- **Not rebuilding**: Change requires clean build
+- **Wrong config location**: Must be in `android` block
+- **Ignoring size increase**: Monitor user feedback on install size
+- **Already default**: Check if React Native version includes this
+
+## Expo Notes
+
+For Expo projects, run `npx expo prebuild` first to generate `android/` folder, then apply the `build.gradle` changes. Add `android/` to version control or use a [config plugin](https://docs.expo.dev/config-plugins/introduction/) for persistent changes.
+
+## Should You Enable This?
+
+| Scenario | Recommendation |
+|----------|---------------|
+| RN 0.78 or earlier startup-critical app | ✅ Enable |
+| Storage-sensitive users | ⚠️ Test impact |
+| Already fast TTI | Maybe not worth it |
+| RN 0.79+ default config | Skip |
+
+## Related Skills
+
+- [native-measure-tti.md](./native-measure-tti.md) - Measure TTI improvement
+- [bundle-analyze-app.md](./bundle-analyze-app.md) - Check size impact
+- [bundle-r8-android.md](./bundle-r8-android.md) - Offset size increase

package/dist/templates/default/apps/mobile/.agents/skills/react-native-best-practices/references/bundle-library-size.md

@@ -0,0 +1,164 @@
+---
+title: Determine Library Size
+impact: MEDIUM
+tags: dependencies, bundlephobia, library-size
+---
+
+# Skill: Determine Library Size
+
+Evaluate third-party library size impact before adding to your project.
+
+## Quick Command
+
+```bash
+# Check size before installing
+# Visit: https://bundlephobia.com/package/[package-name]
+
+# Or use CLI
+npx bundle-phobia-cli <package-name>
+```
+
+## When to Use
+
+- Evaluating new dependencies
+- Comparing alternative libraries
+- Auditing existing dependencies
+- Investigating bundle bloat
+
+## Tools Overview
+
+| Tool | Type | Best For |
+|------|------|----------|
+| bundlephobia.com | Web | Quick size check |
+| pkg-size.dev | Web | Backup/alternative |
+| Import Cost (VS Code) | IDE extension | Rough JS import feedback |
+
+## bundlephobia.com
+
+### Usage
+
+Visit [bundlephobia.com](https://bundlephobia.com) and enter package name.
+
+### Shows
+
+- **Minified size**: Raw JS size
+- **Minified + Gzipped**: Network transfer size
+- **Download time**: Estimated on various connections
+- **Dependencies**: What else gets pulled in
+- **Composition**: Breakdown by dependency
+
+### Example Analysis
+
+```
+react-native-paper
+├── Minified: 312 kB
+├── Gzipped: 78 kB
+└── Dependencies: 12 packages
+    ├── @callstack/react-theme-provider
+    ├── color
+    └── ...
+```
+
+## pkg-size.dev
+
+Backup when bundlephobia fails.
+
+Visit [pkg-size.dev](https://pkg-size.dev) with package name.
+
+**Difference**: Actually installs package in web container, may be more accurate for edge cases.
+
+## Import Cost (VS Code Extension)
+
+### Install
+
+Search "Import Cost" in VS Code extensions or:
+
+```bash
+code --install-extension wix.vscode-import-cost
+```
+
+### Usage
+
+Shows inline size next to imports:
+
+```tsx
+import React from 'react';           // 6.5K (gzipped)
+import lodash from 'lodash';         // 71.5K (gzipped: 24.7K)
+import get from 'lodash/get';        // 8K (gzipped: 2.9K)
+```
+
+### Limitations
+
+- Uses Webpack internally (not Metro)
+- May fail on React Native-specific packages
+- Doesn't account for tree shaking
+
+Bundlephobia, pkg-size.dev, and Import Cost measure JavaScript package cost. They do not capture native code added by React Native libraries such as maps, Reanimated, Firebase, camera, video, or analytics SDKs. For native dependencies, always verify the actual IPA/AAB/APK size after installation.
+
+## Comparison Workflow
+
+### Before Adding Dependency
+
+1. Check on bundlephobia:
+   ```
+   https://bundlephobia.com/package/[package-name]
+   ```
+
+2. Compare alternatives:
+   ```
+   moment (289 kB) vs date-fns (75 kB) vs dayjs (6 kB)
+   ```
+
+3. Check what you actually need:
+   - Full library import vs specific functions
+   - Native alternative available?
+
+### After Adding
+
+1. Analyze bundle (see [bundle-analyze-js.md](./bundle-analyze-js.md))
+2. Verify actual impact matches expected
+3. Check for duplicate dependencies
+
+## Common Large Dependencies
+
+| Library | Size (gzipped) | Alternative |
+|---------|----------------|-------------|
+| moment | ~70 KB | dayjs (~3 KB) |
+| lodash (full) | ~25 KB | Built-ins or direct imports |
+| aws-sdk (full) | 200+ KB | @aws-sdk/client-* |
+| crypto-js | ~15 KB | react-native-quick-crypto |
+
+## Quick Size Check Script
+
+```bash
+# Check size before installing
+npx bundle-phobia-cli <package-name>
+
+# Or use npm directly (less accurate)
+npm pack <package-name> --dry-run 2>&1 | grep "total files"
+```
+
+## Decision Rule
+
+Prefer the smallest option that satisfies correctness and platform requirements, then verify the real app artifact. JS package size alone is not enough for React Native dependencies with native code.
+
+## Code Example: Optimizing Imports
+
+```tsx
+// BAD: Full library
+import _ from 'lodash';
+_.get(obj, 'path.to.value');
+
+// BETTER: Specific import
+import get from 'lodash/get';
+get(obj, 'path.to.value');
+
+// BEST: Native JS
+obj?.path?.to?.value;
+```
+
+## Related Skills
+
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Verify actual bundle impact
+- [bundle-barrel-exports.md](./bundle-barrel-exports.md) - Optimize how you import
+- [native-sdks-over-polyfills.md](./native-sdks-over-polyfills.md) - Native alternatives to JS libs