create-disposabl-app 0.0.4 → 0.1.1

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

@@ -0,0 +1,264 @@
+---
+title: Analyze JS Bundle Size
+impact: CRITICAL
+tags: bundle, analysis, source-map-explorer, expo-atlas
+---
+
+# Skill: Analyze JS Bundle Size
+
+Use source-map-explorer and Expo Atlas to visualize what's in your JavaScript bundle.
+
+## Quick Command
+
+```bash
+# React Native CLI
+npx react-native bundle \
+  --entry-file index.js \
+  --bundle-output output.js \
+  --platform ios \
+  --sourcemap-output output.js.map \
+  --dev false --minify true && \
+npx source-map-explorer output.js --no-border-checks
+
+# Expo
+EXPO_UNSTABLE_ATLAS=true npx expo export --platform ios && npx expo-atlas
+```
+
+## When to Use
+
+- JS bundle seems too large
+- Want to identify heavy dependencies
+- Investigating startup time issues
+- Before/after optimization comparison
+
+> **Note**: This skill involves visual treemap output (source-map-explorer, Expo Atlas). When regression checks include device flows, use `agent-device` for app evidence; install it through the environment's approved/trusted path or ask the user if verification needs it and it is missing. Treemap analysis itself may still require exported reports, browser screenshots, or human review. Record the largest modules and before/after bundle sizes in text when asking an agent to reason about them.
+
+## Understanding Hermes Bytecode
+
+Release builds using Hermes, the default engine in modern React Native, ship Hermes bytecode rather than raw JavaScript:
+- Skips parsing at runtime
+- Still benefits from smaller bundles
+- Heavy imports still execute on startup
+
+**Impact of bundle size:**
+- Larger bytecode = longer download from store
+- More imports on init path = slower TTI
+
+Development builds fetch JS from the dev server, and non-Hermes engines have different startup tradeoffs. Smaller bytecode helps app size and startup, but startup also depends on what executes on the initialization path. Imports that eagerly touch native modules can defeat Turbo Module lazy loading and hurt TTI.
+
+## Method 1: source-map-explorer
+
+### Generate Bundle with Source Map
+
+**React Native CLI:**
+
+```bash
+npx react-native bundle \
+  --entry-file index.js \
+  --bundle-output output.js \
+  --platform ios \
+  --sourcemap-output output.js.map \
+  --dev false \
+  --minify true
+```
+
+**Expo (SDK 51+):**
+
+```bash
+npx expo export --platform ios --source-maps --output-dir dist
+# Bundle at: dist/ios/_expo/static/js/ios/*.js
+# Source map at: dist/ios/_expo/static/js/ios/*.map
+```
+
+### Analyze
+
+```bash
+npx source-map-explorer output.js --no-border-checks
+```
+
+**Note**: `--no-border-checks` needed due to Metro's non-standard source maps.
+
+Opens browser with treemap visualization:
+
+![Bundle Treemap from source-map-explorer](images/bundle-treemap-source-map-explorer.png)
+
+The treemap shows:
+- **Hierarchy**: `node_modules/` → `react-native/` → `Libraries/` → individual files
+- **Size**: Box area proportional to file size (KB shown in labels)
+- **Major components visible**: 
+  - `react-native` (724.18 KB, 80.5%)
+  - `Renderer` (208.44 KB) - ReactNativeRenderer-prod.js, ReactFabric-prod.js
+  - `Components` (125.29 KB) - Touchable, ScrollView, etc.
+  - `Animated` (79.48 KB) - Animation system
+  - `virtualized-lists` (57.57 KB) - FlatList internals
+
+Click on any section to drill down into that directory.
+
+**Limitation**: May lose ~30% info due to mapping issues.
+
+## Method 2: Expo Atlas
+
+More accurate for Expo projects (or with workaround for bare RN).
+
+### For Expo Projects
+
+```bash
+# Start with Atlas enabled
+EXPO_UNSTABLE_ATLAS=true npx expo start --no-dev
+
+# Or export
+EXPO_UNSTABLE_ATLAS=true npx expo export
+```
+
+Then launch UI:
+
+```bash
+npx expo-atlas
+```
+
+![Expo Atlas Treemap](images/expo-atlas-treemap.png)
+
+Expo Atlas provides more accurate visualization for Expo projects, with similar treemap interface showing module sizes and dependencies.
+
+### For Non-Expo Projects
+
+Use `expo-atlas-without-expo` package.
+
+## Method 3: Re.Pack Bundle Analysis (Webpack/Rspack)
+
+If using Re.Pack:
+
+### webpack-bundle-analyzer
+
+```bash
+rspack build --analyze
+```
+
+### bundle-stats / statoscope
+
+```bash
+# Generate stats
+npx react-native bundle \
+  --platform android \
+  --entry-file index.js \
+  --dev false \
+  --minify true \
+  --json stats.json
+
+# Analyze
+npx bundle-stats --html --json stats.json
+```
+
+### Rsdoctor
+
+```javascript
+// rspack.config.js
+const { RsdoctorRspackPlugin } = require('@rsdoctor/rspack-plugin');
+
+module.exports = {
+  plugins: [
+    process.env.RSDOCTOR && new RsdoctorRspackPlugin(),
+  ].filter(Boolean),
+};
+```
+
+Run with:
+
+```bash
+RSDOCTOR=true npx react-native start
+```
+
+## What to Look For
+
+### Red Flags
+
+| Finding | Problem | Solution |
+|---------|---------|----------|
+| Entire library imported | Barrel exports | Use direct imports |
+| Duplicate packages | Multiple versions | Dedupe in package.json |
+| Dev dependencies in bundle | Incorrect imports | Check conditional imports |
+| Large polyfills | Unnecessary for Hermes | Remove (see native-sdks-over-polyfills.md) |
+| Moment.js with locales | Bloated date library | Switch to date-fns or dayjs |
+
+### Common Offenders
+
+- **Lodash full import**: Prefer built-ins or specific imports
+- **Moment.js**: Replace with `date-fns` or `dayjs`
+- **Intl polyfills**: Check Hermes API and method coverage before removing them
+- **AWS SDK**: Import specific services only
+
+## Code Examples
+
+### Identify Barrel Import Impact
+
+```tsx
+// BAD: Imports entire library through barrel
+import { format } from 'date-fns';
+
+// In bundle: All of date-fns loaded
+
+// GOOD: Direct import
+import format from 'date-fns/format';
+
+// In bundle: Only format function
+```
+
+## Comparing Bundles
+
+### source-map-explorer
+
+```bash
+# Generate baseline
+npx react-native bundle ... --bundle-output baseline.js --sourcemap-output baseline.js.map
+
+# Make changes, generate new bundle
+npx react-native bundle ... --bundle-output current.js --sourcemap-output current.js.map
+
+# Compare manually in browser
+```
+
+### Re.Pack (automated)
+
+```bash
+npx bundle-stats compare baseline-stats.json current-stats.json
+```
+
+## Quick Commands
+
+**React Native CLI:**
+
+```bash
+# iOS bundle analysis
+npx react-native bundle \
+  --entry-file index.js \
+  --bundle-output ios-bundle.js \
+  --platform ios \
+  --sourcemap-output ios-bundle.js.map \
+  --dev false \
+  --minify true && \
+npx source-map-explorer ios-bundle.js --no-border-checks
+
+# Android bundle analysis  
+npx react-native bundle \
+  --entry-file index.js \
+  --bundle-output android-bundle.js \
+  --platform android \
+  --sourcemap-output android-bundle.js.map \
+  --dev false \
+  --minify true && \
+npx source-map-explorer android-bundle.js --no-border-checks
+```
+
+**Expo:**
+
+```bash
+# Use Expo Atlas (recommended for Expo projects)
+EXPO_UNSTABLE_ATLAS=true npx expo export --platform ios
+npx expo-atlas
+```
+
+## Related Skills
+
+- [bundle-barrel-exports.md](./bundle-barrel-exports.md) - Fix barrel import issues
+- [bundle-tree-shaking.md](./bundle-tree-shaking.md) - Enable dead code elimination
+- [bundle-library-size.md](./bundle-library-size.md) - Check library sizes before adding

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

@@ -0,0 +1,250 @@
+---
+title: Avoid Barrel Exports
+impact: CRITICAL
+tags: bundle, imports, barrel, tree-shaking
+---
+
+# Skill: Avoid Barrel Exports
+
+Refactor barrel imports (index files) to reduce bundle size and improve startup time.
+
+## Quick Pattern
+
+**Incorrect:**
+
+```tsx
+import { Button } from './components';
+// Loads ALL exports from components/index.ts
+```
+
+**Correct:**
+
+```tsx
+import Button from './components/Button';
+// Loads only Button
+```
+
+## When to Use
+
+- Bundle contains unused code from libraries
+- Circular dependency warnings in Metro
+- Hot Module Replacement (HMR) breaks frequently
+- TTI is slow due to module evaluation
+
+## What Are Barrel Exports?
+
+```tsx
+// components/index.ts (barrel file)
+export { Button } from './Button';
+export { Card } from './Card';
+export { Modal } from './Modal';
+export { Sidebar } from './Sidebar';
+
+// Usage (barrel import)
+import { Button } from './components';
+```
+
+## Problems with Barrel Imports
+
+### 1. Bundle Size Overhead
+
+Without effective tree shaking or a library-specific Babel plugin, barrel imports can make all re-exported modules reachable and evaluated even when only one export is used:
+
+```tsx
+// Only need Button, but entire barrel is bundled
+import { Button } from './components';
+// Card, Modal, Sidebar also included!
+```
+
+### 2. Runtime Overhead
+
+All modules evaluate before returning your import:
+
+```tsx
+import { Button } from './components';
+// JavaScript must evaluate:
+// - Button.tsx
+// - Card.tsx
+// - Modal.tsx  
+// - Sidebar.tsx
+// Even though you only use Button
+```
+
+### 3. Circular Dependencies
+
+Barrel files make cycles easier to create accidentally:
+
+```
+Warning: Require cycle:
+  components/index.ts -> Button.tsx -> utils/index.ts -> components/index.ts
+```
+
+Breaks HMR, causes unpredictable behavior.
+
+## Solution 1: Direct Imports
+
+Replace barrel imports with direct paths:
+
+```tsx
+// BEFORE: Barrel import
+import { Button, Card } from './components';
+
+// AFTER: Direct imports
+import Button from './components/Button';
+import Card from './components/Card';
+```
+
+### Enforce with ESLint
+
+```bash
+npm install -D eslint-plugin-no-barrel-files
+```
+
+```javascript
+// eslint.config.js
+import noBarrelFiles from 'eslint-plugin-no-barrel-files';
+
+export default [
+  {
+    plugins: { 'no-barrel-files': noBarrelFiles },
+    rules: {
+      'no-barrel-files/no-barrel-files': 'error',
+    },
+  },
+];
+```
+
+## Solution 2: Tree Shaking (Automatic)
+
+Enable tree shaking to automatically remove unused barrel exports.
+
+### Expo SDK 52+
+
+```tsx
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const config = getDefaultConfig(__dirname);
+
+config.transformer.getTransformOptions = async () => ({
+  transform: {
+    experimentalImportSupport: true,
+  },
+});
+
+module.exports = config;
+```
+
+```bash
+# .env
+EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
+EXPO_UNSTABLE_TREE_SHAKING=1
+```
+
+### metro-serializer-esbuild
+
+```bash
+npm install @rnx-kit/metro-serializer-esbuild
+```
+
+### Re.Pack (Webpack/Rspack)
+
+Tree shaking built-in.
+
+## Real-World Example: date-fns
+
+```tsx
+// BAD: Imports entire library
+import { format, addDays, isToday } from 'date-fns';
+
+// GOOD: Direct imports
+import format from 'date-fns/format';
+import addDays from 'date-fns/addDays';
+import isToday from 'date-fns/isToday';
+```
+
+If the project uses a bundler/configuration with working tree shaking, top-level ESM imports from libraries such as `date-fns` may be optimized automatically. Without that, submodule imports are still the safer pattern. Measure with bundle analysis.
+
+## Library-Specific Solutions
+
+Some libraries provide Babel plugins:
+
+### React Native Paper
+
+```javascript
+// babel.config.js
+module.exports = {
+  plugins: [
+    'react-native-paper/babel',  // Auto-transforms imports
+  ],
+};
+```
+
+Transforms:
+```tsx
+import { Button } from 'react-native-paper';
+// Into:
+import Button from 'react-native-paper/lib/module/components/Button';
+```
+
+## Refactoring Strategy
+
+### Step 1: Identify Barrel Files
+
+Look for `index.ts` files with multiple exports:
+
+```bash
+grep -r "export \* from" src/
+grep -r "export { .* } from" src/
+```
+
+### Step 2: Update Imports
+
+```tsx
+// Find all usages
+// VS Code: Cmd+Shift+F for "from './components'"
+
+// Replace each with direct import
+import Button from './components/Button';
+```
+
+### Step 3: (Optional) Keep Barrel for External API
+
+If your package is consumed by others:
+
+```tsx
+// Keep index.ts for package API
+// components/index.ts
+export { Button } from './Button';
+
+// Internal code uses direct imports
+// src/screens/Home.tsx
+import Button from '../components/Button';
+```
+
+## Migration Script Example
+
+```bash
+# Use codemod or search-replace
+# Find: import { (\w+) } from '\.\/components';
+# Replace: import $1 from './components/$1';
+```
+
+## Verification
+
+After refactoring:
+
+1. Run bundle analysis (see [bundle-analyze-js.md](./bundle-analyze-js.md))
+2. Compare sizes before/after
+3. Check for circular dependency warnings
+
+## Common Pitfalls
+
+- **Breaking external consumers**: If publishing a library, keep barrel for public API
+- **IDE auto-imports**: Configure IDE to prefer direct imports
+- **Inconsistent patterns**: Enforce with ESLint across team
+
+## Related Skills
+
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Verify impact
+- [bundle-tree-shaking.md](./bundle-tree-shaking.md) - Automatic solution
+- [bundle-library-size.md](./bundle-library-size.md) - Check library patterns