Doko-Demo-Doa/react-native-pdf-editor / .agents/skills/build-nitro-modules
build-nitro-modules
VerifiedBuilds and designs React Native Nitro Modules with Nitrogen, HybridObject TypeScript specs, generated native implementations, zero-copy and native-state APIs, Swift/Kotlin/C++ bindings, example apps, and testing. Use when creating a Nitro Module, adding or reviewing HybridObjects, designing Nitro-specific public APIs, implementing native functionality, or setting up the nitrogen codegen pipeline. Pair with api-design for general library API shape.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 41.6 KB |
| references/example-android-config.md | markdown | 7.3 KB |
| references/example-app-setup.md | markdown | 5.7 KB |
| references/example-metro-install.md | markdown | 6.4 KB |
| references/native-implement-cpp.md | markdown | 13.2 KB |
| references/native-implement-kotlin.md | markdown | 21.4 KB |
| references/native-implement-swift.md | markdown | 23.5 KB |
| references/native-nitrogen-codegen.md | markdown | 6.6 KB |
| references/release-it-publishing.md | markdown | 4.1 KB |
| references/repo-structure-and-workflow.md | markdown | 6.2 KB |
| references/setup-monorepo-init.md | markdown | 5.6 KB |
| references/spec-hybrid-object.md | markdown | 27.5 KB |
| references/spec-nitro-json.md | markdown | 5.9 KB |
| references/spec-package-publish.md | markdown | 7.6 KB |
| references/vision-camera-golden-standard.md | markdown | 10.0 KB |
references/example-metro-install.md
View on GitHub---
title: Metro Config, Library Install, and Running the Example
impact: HIGH
tags: metro, watchFolders, bun, install, App.tsx, example, android, ios, scripts, pod-install
---
# Skill: Metro Config, Library Install, and Running the Example
Covers Steps 16–20: configuring Metro watchFolders, installing the library in the example app, implementing App.tsx, adding root scripts, and running on Android and iOS.
## Quick Commands
```bash
# Configure Metro if it cannot resolve the package from the chosen example app layout
# Install library in the example app.
# apps/example layout:
cd apps/example
bun add ../../packages/react-native-math
bun add react-native-nitro-modules@<same-version-as-package>
# example/ layout:
# cd example
# bun add ../packages/react-native-math
# bun add react-native-nitro-modules@<same-version-as-package>
# iOS: install pods
cd ios && pod install && cd ..
# Run
bun example android
bun example ios
```
## When to Use
- After Android Gradle paths are verified or configured
- When Metro can't resolve the local library package
- When setting up the example app to test the module
## Prerequisites
- Example app created in `apps/example/`, `example/`, or another chosen layout
- Android Gradle paths verified, or corrected only if the chosen layout requires it
- Library package is in `packages/<name>`
## Step-by-Step
### 1. Configure Metro watchFolders
Open `apps/example/metro.config.js` and add the monorepo root to `watchFolders`:
```javascript
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const path = require('node:path');
const root = path.resolve(__dirname, '..', '..');
const config = {
watchFolders: [root],
};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);
```
Without `watchFolders`, Metro only watches the example app directory and can't find your library in `packages/`.
For a shallower `example/` layout, the monorepo root is one level up instead:
```javascript
const root = path.resolve(__dirname, '..');
```
### 2. Install the library
```bash
cd apps/example
bun add ../../packages/react-native-math
```
This creates a symlink from `apps/example/node_modules/react-native-math` to `packages/react-native-math`.
For a shallower `example/` layout, use:
```bash
cd example
bun add ../packages/react-native-math
```
### 3. Install `react-native-nitro-modules` at a pinned version
The version must match what `packages/react-native-math` uses:
```bash
# Check what version the package uses
cat ../../packages/react-native-math/package.json | grep nitro-modules
# from example/: cat ../packages/react-native-math/package.json | grep nitro-modules
# Install the same version in example
bun add react-native-nitro-modules@<same-version-as-package>
```
Having two different versions of `react-native-nitro-modules` can cause runtime/build crashes.
### 4. Install iOS pods
```bash
cd apps/example/ios
pod install
cd ../../..
```
Run this after any new native dependency is added.
### 5. Implement App.tsx
Replace the default `apps/example/App.tsx` with a test implementation:
```tsx
import React, { useState } from 'react';
import { Button, StyleSheet, Text, View } from 'react-native';
import { math } from 'react-native-math';
function App(): React.JSX.Element {
const [result, setResult] = useState<number | null>(null);
return (
<View style={styles.container}>
<Text style={styles.title}>Math Module Test</Text>
<Button title="Add 5 + 7" onPress={() => setResult(math.add(5, 7))} />
{result !== null && <Text style={styles.result}>Result: {result}</Text>}
</View>
);
}
const styles = StyleSheet.create({
container: { flex: 1, justifyContent: 'center', alignItems: 'center' },
title: { fontSize: 24, fontWeight: 'bold', marginBottom: 20 },
result: { fontSize: 32, marginTop: 20 },
});
export default App;
```
### 6. Add root scripts
In the monorepo root `package.json`:
```json
{
"scripts": {
"specs": "bun --cwd packages/react-native-math run specs",
"example": "bun --cwd apps/example"
}
}
```
This enables:
- `bun example android` — runs the example on Android
- `bun example ios` — runs the example on iOS
- `bun example start` — starts the Metro bundler
### 7. Run on Android
```bash
bun example android
# or directly:
cd apps/example && bun android
```
Watch for errors in logcat if the build succeeds but the app crashes.
### 8. Run on iOS
```bash
bun example ios
# or directly:
cd apps/example && bun ios
```
## Code Examples
### `apps/example/metro.config.js` (complete)
```javascript
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const path = require('node:path');
const root = path.resolve(__dirname, '..', '..');
/**
* Metro configuration
* https://reactnative.dev/docs/metro
*
* @type {import('@react-native/metro-config').MetroConfig}
*/
const config = {
watchFolders: [root],
};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);
```
### Root `package.json` scripts (complete)
```json
{
"scripts": {
"specs": "bun --cwd packages/react-native-math run specs",
"example": "bun --cwd apps/example",
"example:android": "bun --cwd apps/example android",
"example:ios": "bun --cwd apps/example ios"
}
}
```
### Async method usage in App.tsx
```tsx
const [fibResult, setFibResult] = useState<number | null>(null);
const calculateFib = async () => {
const result = await math.calculateFibonacci(10);
setFibResult(result);
};
```
## Common Pitfalls
- **Missing `watchFolders`** — Metro won't find the library package; add it to `metro.config.js`
- **`react-native-nitro-modules` version mismatch** — Install the exact same version in example as in the package
- **Forgetting `pod install`** — iOS won't pick up new native libraries without running `pod install`
- **Only testing JS bundling** — Nitro code needs a native build. Test on an iOS simulator/device or Android emulator/device, not only Metro, web, or a JS-only test runner.
- **Metro cache stale** — If you change the lib and Metro doesn't pick it up, run `bun example start --reset-cache`
## Related Skills
- [example-app-setup.md](example-app-setup.md) — Create the example app first
- [example-android-config.md](example-android-config.md) — Verify Android Gradle paths, and fix them only when the chosen layout requires it
- [spec-package-publish.md](spec-package-publish.md) — Final step: prepare for npm publishing
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |