@bcelep/capint 0.4.2 → 0.7.0

package/skills/react-native-best-practices/references/bundle-analyze-js.md

@@ -0,0 +1,262 @@
+---
+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 interpreting visual treemap output (source-map-explorer, Expo Atlas). AI agents cannot yet process screenshots autonomously. Use this as a guide while reviewing the visualization manually, or await MCP-based visual feedback integration (see roadmap).
+
+## Understanding Hermes Bytecode
+
+Modern React Native (0.70+) uses Hermes bytecode, not 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
+
+## 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**: Use `lodash-es` or specific imports
+- **Moment.js**: Replace with `date-fns` or `dayjs`
+- **Intl polyfills**: Check Hermes support
+- **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/skills/react-native-best-practices/references/bundle-barrel-exports.md

@@ -0,0 +1,248 @@
+---
+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
+
+Metro includes **all exports** even if you use one:
+
+```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';
+```
+
+## 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