@bcelep/capint 0.4.2 → 0.6.5

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

@@ -0,0 +1,214 @@
+---
+title: Native Assets
+impact: HIGH
+tags: assets, images, asset-catalog, app-thinning
+---
+
+# Skill: Native Assets
+
+Configure platform-specific asset delivery to reduce app download size.
+
+## Quick Config
+
+**iOS Asset Catalog (Build Phase):**
+
+```bash
+# Add to "Bundle React Native code and images" build phase
+export EXTRA_PACKAGER_ARGS="--asset-catalog-dest ./"
+```
+
+**Android**: Automatic via AAB — Play Store delivers correct density per device.
+
+## When to Use
+
+- Images bloating app size
+- Different device densities need different assets
+- Want to leverage App Store/Play Store optimization
+- Using high-resolution images
+
+## Concept: Size Suffixes
+
+React Native convention for multiple resolutions:
+
+```
+assets/
+├── image.jpg       # 1x resolution (base)
+├── image@2x.jpg    # 2x resolution
+└── image@3x.jpg    # 3x resolution
+```
+
+```tsx
+// React Native selects best one for device
+<Image source={require('./assets/image.jpg')} />
+```
+
+## Android: Automatic Optimization
+
+Android handles this automatically.
+
+### How It Works
+
+1. Build AAB:
+   ```bash
+   cd android && ./gradlew bundleRelease
+   ```
+
+2. Metro places images in density folders:
+   ```
+   android/app/build/outputs/bundle/release/
+   └── base/
+       └── res/
+           ├── drawable-mdpi-v4/     # 1x
+           ├── drawable-hdpi-v4/     # 1.5x
+           ├── drawable-xhdpi-v4/    # 2x
+           ├── drawable-xxhdpi-v4/   # 3x
+           └── drawable-xxxhdpi-v4/  # 4x
+   ```
+
+3. Play Store delivers only needed density per device.
+
+**No configuration required** for Android.
+
+## iOS: Asset Catalog Setup
+
+iOS requires explicit configuration.
+
+### Step 1: Create Asset Catalog
+
+Create folder in `ios/`:
+
+```
+ios/RNAssets.xcassets/
+```
+
+**Important**: Must be named exactly `RNAssets.xcassets` (hardcoded in React Native).
+
+### Step 2: Configure Build Phase
+
+In Xcode:
+1. Open project settings
+2. Go to **Build Phases**
+3. Find **"Bundle React Native code and images"**
+4. Add before line 8:
+
+```bash
+export EXTRA_PACKAGER_ARGS="--asset-catalog-dest ./"
+```
+
+### Step 3: Build
+
+Run build to populate asset catalog:
+
+```bash
+npx react-native run-ios --mode Release
+```
+
+Or manually:
+
+```bash
+npx react-native bundle \
+  --entry-file index.js \
+  --bundle-output ios-bundle.js \
+  --platform ios \
+  --dev false \
+  --asset-catalog-dest ios \
+  --assets-dest ios/assets
+```
+
+### Step 4: Verify
+
+After build, `RNAssets.xcassets` contains:
+
+```
+ios/RNAssets.xcassets/
+└── assets_image_image.imageset/
+    ├── Contents.json
+    ├── image.jpg
+    ├── image@2x.jpg
+    └── image@3x.jpg
+```
+
+App Store then delivers only needed resolution.
+
+## Before/After Comparison
+
+### Without Asset Catalog (All Variants)
+
+```
+App bundle contains:
+├── image.jpg       (100 KB)
+├── image@2x.jpg    (300 KB)
+└── image@3x.jpg    (600 KB)
+Total: 1 MB
+```
+
+### With Asset Catalog (Device-Specific)
+
+```
+iPhone 15 Pro receives:
+└── image@3x.jpg    (600 KB)
+Total: 600 KB  (40% smaller)
+```
+
+## Asset Optimization Tips
+
+### 1. Compress Images
+
+Use tools before adding to project:
+
+```bash
+# ImageOptim (macOS)
+# TinyPNG (web)
+# sharp (programmatic)
+
+npx sharp-cli input.jpg -o output.jpg --quality 80
+```
+
+### 2. Use Appropriate Formats
+
+| Format | Best For |
+|--------|----------|
+| JPEG | Photos |
+| PNG | Icons, transparency |
+| WebP | Both (smaller) |
+| SVG | Vector icons |
+
+### 3. Consider react-native-fast-image
+
+Caching and better image handling:
+
+```bash
+npm install react-native-fast-image
+```
+
+## Verification
+
+### iOS App Thinning Report
+
+After export, check `App Thinning Size Report.txt`:
+
+```
+Variant: MyApp-<UUID>.ipa
+Supported variant descriptors: iPhone15,2 ...
+App size: 3.5 MB compressed, 10.6 MB uncompressed
+```
+
+### Use Emerge Tools
+
+Upload IPA to see asset breakdown.
+
+## Common Pitfalls
+
+- **Wrong folder name**: Must be `RNAssets.xcassets` exactly
+- **Missing build phase config**: Assets not processed
+- **Not using size suffixes**: All variants included anyway
+- **Forgetting to rebuild**: Changes need fresh build
+
+## Future Note
+
+As of January 2025, Asset Catalog is not default. May become default in future React Native versions.
+
+## Related Skills
+
+- [bundle-analyze-app.md](./bundle-analyze-app.md) - Verify asset impact
+- [bundle-r8-android.md](./bundle-r8-android.md) - Android code optimization

package/skills/react-native-best-practices/references/bundle-r8-android.md

@@ -0,0 +1,225 @@
+---
+title: R8 Code Shrinking
+impact: HIGH
+tags: android, r8, proguard, minify, shrink
+---
+
+# Skill: R8 Code Shrinking
+
+Enable R8 for Android to shrink, optimize, and obfuscate native code.
+
+## Quick Config
+
+```groovy
+// android/app/build.gradle
+def enableProguardInReleaseBuilds = true
+
+android {
+    buildTypes {
+        release {
+            minifyEnabled true
+            shrinkResources true
+        }
+    }
+}
+```
+
+## When to Use
+
+- Android app size too large
+- Want to obfuscate code for security
+- Building release APK/AAB
+
+## What is R8?
+
+R8 replaces ProGuard in Android:
+- **Shrinks**: Removes unused code
+- **Optimizes**: Improves bytecode
+- **Obfuscates**: Renames classes/methods
+
+**Compatibility**: Uses ProGuard configuration format.
+
+## Step-by-Step Instructions
+
+### 1. Enable R8
+
+Edit `android/app/build.gradle`:
+
+```groovy
+def enableProguardInReleaseBuilds = true
+```
+
+This sets `minifyEnabled = true` for release builds.
+
+### 2. Enable Resource Shrinking (Optional)
+
+Further reduces size by removing unused resources:
+
+```groovy
+android {
+    buildTypes {
+        release {
+            minifyEnabled true
+            shrinkResources true  // Requires minifyEnabled
+            
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+```
+
+### 3. Configure ProGuard Rules (If Needed)
+
+Edit `android/app/proguard-rules.pro`. React Native defaults are usually sufficient—only add rules when specific libraries break after enabling R8.
+
+**Only add if using Firebase (`@react-native-firebase/*`):**
+
+```proguard
+-keep class io.invertase.firebase.** { *; }
+-dontwarn io.invertase.firebase.**
+```
+
+**Only add if using Retrofit:**
+
+```proguard
+-keepattributes Signature
+-keepattributes *Annotation*
+-keep class retrofit2.** { *; }
+-dontwarn retrofit2.**
+```
+
+See [Common Library Rules](#common-library-rules) and [Troubleshooting](#troubleshooting) for more examples.
+
+### 4. Build and Test
+
+```bash
+cd android
+./gradlew assembleRelease
+# or
+./gradlew bundleRelease
+```
+
+**Critical**: Test thoroughly! R8 can remove code it thinks is unused.
+
+## ProGuard Rules Reference
+
+| Rule | Effect |
+|------|--------|
+| `-keep class X` | Don't remove class X |
+| `-keepclassmembers` | Keep members but allow rename |
+| `-keepnames` | Keep names but allow removal if unused |
+| `-dontwarn X` | Suppress warnings for X |
+| `-dontobfuscate` | Disable obfuscation |
+
+### Keep Entire Package
+
+```proguard
+-keep class com.mypackage.** { *; }
+```
+
+### Keep Classes with Annotation
+
+```proguard
+-keep @interface com.facebook.proguard.annotations.DoNotStrip
+-keep @com.facebook.proguard.annotations.DoNotStrip class *
+-keepclassmembers class * {
+    @com.facebook.proguard.annotations.DoNotStrip *;
+}
+```
+
+## Disable Obfuscation (If Needed)
+
+```proguard
+# proguard-rules.pro
+-dontobfuscate
+```
+
+Use when:
+- Debugging crashes (stack traces more readable)
+- Library requires class names
+
+## Size Impact
+
+Example from guide:
+- **Without R8**: 9.5 MB
+- **With R8**: 6.3 MB
+- **Savings**: 33%
+
+Larger apps may see 20-30% reduction.
+
+## Troubleshooting
+
+### App Crashes After R8
+
+Usually means needed class was removed.
+
+**Debug steps**:
+
+1. Check crash log for class name
+2. Add keep rule:
+   ```proguard
+   -keep class com.example.CrashedClass { *; }
+   ```
+3. Rebuild and test
+
+### Library Specific Rules
+
+Many libraries provide ProGuard rules. Check:
+- Library README
+- Library's `consumer-proguard-rules.pro`
+- Stack Overflow for library + proguard
+
+### Common Library Rules
+
+```proguard
+# Hermes (usually auto-included)
+-keep class com.facebook.hermes.unicode.** { *; }
+
+# React Native
+-keep class com.facebook.react.** { *; }
+
+# Gson
+-keepattributes Signature
+-keep class com.google.gson.** { *; }
+
+# OkHttp
+-dontwarn okhttp3.**
+-dontwarn okio.**
+```
+
+## Verification
+
+### Check APK Size
+
+```bash
+# Build
+./gradlew assembleRelease
+
+# Check size
+ls -la android/app/build/outputs/apk/release/
+```
+
+### Use Ruler for Detailed Analysis
+
+See [bundle-analyze-app.md](./bundle-analyze-app.md).
+
+### Verify Obfuscation
+
+Decompile APK to check class names are obfuscated:
+
+```bash
+# Using jadx or similar
+jadx android/app/build/outputs/apk/release/app-release.apk
+```
+
+## Common Pitfalls
+
+- **Not testing release build**: Always QA with R8 enabled
+- **Missing library rules**: Check library docs
+- **Over-keeping**: Too many keep rules negates benefits
+- **Reflection**: Code using reflection may break
+
+## Related Skills
+
+- [bundle-analyze-app.md](./bundle-analyze-app.md) - Measure size impact
+- [bundle-native-assets.md](./bundle-native-assets.md) - Further size reduction

package/skills/react-native-best-practices/references/bundle-tree-shaking.md

@@ -0,0 +1,214 @@
+---
+title: Tree Shaking
+impact: HIGH
+tags: bundle, tree-shaking, dead-code, metro, repack
+---
+
+# Skill: Tree Shaking
+
+Enable dead code elimination to remove unused exports from your JavaScript bundle.
+
+## Quick Config
+
+```bash
+# .env (Expo SDK 52+)
+EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
+EXPO_UNSTABLE_TREE_SHAKING=1
+```
+
+```javascript
+// metro.config.js
+config.transformer.getTransformOptions = async () => ({
+  transform: { experimentalImportSupport: true },
+});
+```
+
+```javascript
+// babel.config.js (non-Expo projects must set `disableImportExportTransform`)
+module.exports = {
+  presets: [
+    [
+      'module:@react-native/babel-preset',
+      { disableImportExportTransform: true },
+    ],
+  ],
+};
+```
+
+## When to Use
+
+- Bundle includes unused library code
+- Want automatic barrel export optimization
+- Using Expo SDK 52+ (recommended approach)
+- Project already uses Re.Pack (`@callstack/repack`)
+
+## Platform Support
+
+| Bundler        | Tree Shaking    | Notes                        |
+| -------------- | --------------- | ---------------------------- |
+| Metro          | ❌ No           | Use metro-serializer-esbuild |
+| Expo (SDK 52+) | ✅ Experimental | Requires config              |
+| Re.Pack        | ✅ Yes          | Built-in via Webpack/Rspack  |
+
+## Setup: Expo SDK 52+
+
+### 1. Enable Import Support
+
+```javascript
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+
+const config = getDefaultConfig(__dirname);
+
+config.transformer.getTransformOptions = async () => ({
+  transform: {
+    experimentalImportSupport: true,
+  },
+});
+
+module.exports = config;
+```
+
+### 2. Enable Tree Shaking
+
+Create/edit `.env`:
+
+```bash
+EXPO_UNSTABLE_METRO_OPTIMIZE_GRAPH=1
+EXPO_UNSTABLE_TREE_SHAKING=1
+```
+
+**Note**: Only applies in production builds.
+
+## Setup: Metro with ESBuild
+
+```bash
+npm install @rnx-kit/metro-serializer-esbuild
+```
+
+Configure in metro.config.js.
+
+## Setup: Re.Pack (Only If Already Installed)
+
+> **Important**: Re.Pack (`@callstack/repack`) is a custom bundler using Rspack/Webpack. Only apply these instructions if the project already has Re.Pack configured. Do not suggest migrating a codebase to Re.Pack—it's rarely necessary and requires significant setup.
+
+**If project has `@callstack/repack` in dependencies:**
+
+Tree shaking is enabled by default with Rspack. Verify in config:
+
+```javascript
+// rspack.config.js or webpack.config.js
+module.exports = {
+  optimization: {
+    usedExports: true, // Mark unused exports
+    minimize: true, // Remove during minification
+  },
+};
+```
+
+## Platform Shaking
+
+Code inside `Platform.OS` and `Platform.select` checks is removed for other platforms:
+
+```tsx
+// IMPORTANT: import Platform directly from 'react-native'
+import { Platform } from 'react-native';
+
+if (Platform.OS === 'ios') {
+  // Removed from Android bundle
+}
+
+if (Platform.select({ ios: true, android: false }) === 'ios') {
+  // Removed from Android bundle
+}
+```
+
+**Critical**: Must use direct import. This does NOT work:
+
+```tsx
+import * as RN from 'react-native';
+if (RN.Platform.OS === 'ios') {
+  // NOT removed - optimization fails
+}
+```
+
+For non-Expo projects, requires both `experimentalImportSupport: true` in Metro config and `disableImportExportTransform: true` in Babel config.
+
+Impact: Savings from enabling platform shaking on a bare React Native Community CLI project are:
+- 5% smaller Hermes bytecode (2.79 MB → 2.64 MB)
+- 15% smaller minified JS bundle (1 MB → 0.85 MB)
+
+## Requirements for Tree Shaking
+
+### ESM Imports Required
+
+```tsx
+// ✅ ESM - Tree shakeable
+import { foo } from './module';
+
+// ❌ CommonJS - Not tree shakeable
+const { foo } = require('./module');
+```
+
+### Side Effects Declaration
+
+Libraries must declare side-effect-free in `package.json`:
+
+```json
+{
+  "sideEffects": false
+}
+```
+
+Or specify files with side effects:
+
+```json
+{
+  "sideEffects": ["*.css", "./src/polyfills.js"]
+}
+```
+
+## Size Impact
+
+| Bundle Type       | Metro (MB) | Re.Pack (MB) | Change   |
+| ----------------- | ---------- | ------------ | -------- |
+| Production        | 35.63      | 38.48        | +8%      |
+| Prod Minified     | 15.54      | 13.36        | **-14%** |
+| Prod HBC          | 21.79      | 19.35        | **-11%** |
+| Prod Minified HBC | 21.62      | 19.05        | **-12%** |
+
+**Expected improvement**: 10-15% bundle size reduction.
+
+## Verification
+
+1. Build production bundle (see [bundle-analyze-js.md](./bundle-analyze-js.md))
+2. Analyze with source-map-explorer (see [bundle-analyze-js.md](./bundle-analyze-js.md))
+3. Search for functions you know are unused
+4. If found → tree shaking not working
+
+### Test Example
+
+```tsx
+// test-treeshake.js
+export const usedFunction = () => 'used';
+export const unusedFunction = () => 'unused'; // Should be removed
+
+// app.js
+import { usedFunction } from './test-treeshake';
+```
+
+After building, search bundle for `unusedFunction`. Should not exist.
+
+## Common Pitfalls
+
+- **Not using production build**: Tree shaking only in prod
+- **CommonJS modules**: Need ESM for full effectiveness
+- **Side effects not declared**: Library may not be shakeable
+- **Dynamic imports**: `require(variable)` prevents analysis
+- **Babel/Metro config mismatch**: `disableImportExportTransform` must match `experimentalImportSupport`
+
+## Related Skills
+
+- [bundle-analyze-js.md](./bundle-analyze-js.md) - Verify tree shaking effect
+- [bundle-barrel-exports.md](./bundle-barrel-exports.md) - Manual alternative
+- [bundle-code-splitting.md](./bundle-code-splitting.md) - Re.Pack code splitting