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/spec-package-publish.md
View on GitHub---
title: Preparing the Package for npm Publishing
impact: MEDIUM
tags: package.json, npm, publish, files, author, metadata, npm-pack, podspec
---
# Skill: Preparing the Package for npm Publishing
Covers publish metadata and npm package contents.
## Quick Config
```json
{
"name": "react-native-math",
"version": "0.1.0",
"description": "Fast, type-safe math utilities for React Native powered by Nitro Modules",
"author": "Your Name <your@email.com>",
"contributors": ["Contributor Name <contributor@email.com>"],
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/yourusername/react-native-math.git"
},
"homepage": "https://math.margelo.com",
"bugs": {
"url": "https://github.com/yourusername/react-native-math/issues"
},
"keywords": ["react-native", "nitro-modules", "ios", "android", "math"],
"scripts": {
"typecheck": "tsc --noEmit",
"build": "tsc",
"specs": "tsc --noEmit false && nitrogen"
},
"files": [
"src",
"react-native.config.js",
"lib",
"nitrogen",
"android/build.gradle",
"android/gradle.properties",
"android/fix-prefab.gradle",
"android/CMakeLists.txt",
"android/src",
"ios/**/*.h",
"ios/**/*.m",
"ios/**/*.mm",
"ios/**/*.cpp",
"ios/**/*.swift",
"cpp/**/*.h",
"cpp/**/*.hpp",
"cpp/**/*.cpp",
"nitro.json",
"*.podspec",
"README.md"
]
}
```
## When to Use
- Before publishing to npm for the first time
- When consumers report missing files after installing the package
- When `nitro.json` autolinking fails for consumers of the published package
## Prerequisites
- Module builds and tests pass
- Example app runs on both Android and iOS
- `lib/` directory exists (run the build step first)
## Step-by-Step
### 1. Update SEO and ownership metadata
Set a concise, catchy description and complete metadata in `packages/react-native-math/package.json`. Keep this aligned with GitHub's About description, repository topics, README intro, npm tags, and docs site.
In `packages/react-native-math/package.json`:
```json
{
"description": "Fast, type-safe math utilities for React Native powered by Nitro Modules",
"keywords": ["react-native", "nitro-modules", "ios", "android", "math"],
"author": "Your Full Name <your@email.com>",
"contributors": ["Contributor Name <contributor@email.com>"],
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/yourusername/react-native-math.git"
},
"homepage": "https://math.margelo.com",
"bugs": {
"url": "https://github.com/yourusername/react-native-math/issues"
}
}
```
For Margelo repos, prefer a short docs domain such as `<simple-name>.margelo.com` when a docs site exists. Otherwise use the GitHub README URL as `homepage`.
### 2. Set the `files` field
This controls what gets uploaded to npm. **Missing files = broken package for consumers.**
```json
{
"files": [
"src",
"react-native.config.js",
"lib",
"nitrogen",
"android/build.gradle",
"android/gradle.properties",
"android/fix-prefab.gradle",
"android/CMakeLists.txt",
"android/src",
"ios/**/*.h",
"ios/**/*.m",
"ios/**/*.mm",
"ios/**/*.cpp",
"ios/**/*.swift",
"cpp/**/*.h",
"cpp/**/*.hpp",
"cpp/**/*.cpp",
"nitro.json",
"*.podspec",
"README.md"
]
}
```
Critical files that must be included:
- `nitrogen/` — Generated native glue and autolinking files; consumers need these for builds. These files may or may not be committed to git, but they must be published to npm.
- `nitro.json` — Required for autolinking to work
- `*.podspec` — Required for iOS CocoaPods integration. Prefer a root podspec named after `ios.iosModuleName`, for example `NitroMath.podspec` with `s.name = "NitroMath"`.
- `android/build.gradle`, `android/gradle.properties`, `android/CMakeLists.txt`, and `android/src` — Android build config and source files
- `ios/**/*.{h,m,mm,cpp,swift}` — iOS source files
- `cpp/**/*.{h,hpp,cpp}` — C++ implementation files (if using C++)
- `lib/` — Compiled TypeScript output (JS + type definitions)
- `src/` — TypeScript source for consumers who use `react-native` field in package.json
- `react-native.config.js` — Required if the package customizes React Native autolinking
### 3. Verify `main`, `module`, and `types` fields
```json
{
"main": "lib/index",
"module": "lib/index",
"types": "lib/index.d.ts",
"react-native": "src/index",
"source": "src/index"
}
```
### 4. Build the package
```bash
cd packages/react-native-math
bun run build
# or:
bun run prepare
```
Ensure `lib/` is populated before packing.
Run `bun run specs` before publishing whenever `.nitro.ts` files changed so `nitrogen/` is current.
### 5. Dry run to verify file list
```bash
npm pack --dry-run
```
Check the output — every file listed in step 2 must appear. If `nitro.json`, `nitrogen/`, or `*.podspec` are missing, consumers' builds will fail.
### 6. Publish
```bash
npm publish
```
For one-command release automation, use [release-it-publishing.md](release-it-publishing.md).
## Code Examples
### Complete `package.json` metadata section
```json
{
"name": "react-native-math",
"version": "0.1.0",
"description": "Fast, type-safe math utilities for React Native powered by Nitro Modules",
"main": "lib/index",
"module": "lib/index",
"types": "lib/index.d.ts",
"react-native": "src/index",
"source": "src/index",
"author": "Your Name <your@email.com>",
"contributors": ["Contributor Name <contributor@email.com>"],
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/yourusername/react-native-math.git"
},
"homepage": "https://math.margelo.com",
"bugs": {
"url": "https://github.com/yourusername/react-native-math/issues"
},
"keywords": ["react-native", "nitro-modules", "ios", "android", "math"],
"scripts": {
"typecheck": "tsc --noEmit",
"build": "tsc",
"specs": "tsc --noEmit false && nitrogen"
},
"files": [
"src",
"react-native.config.js",
"lib",
"nitrogen",
"android/build.gradle",
"android/gradle.properties",
"android/fix-prefab.gradle",
"android/CMakeLists.txt",
"android/src",
"ios/**/*.h",
"ios/**/*.m",
"ios/**/*.mm",
"ios/**/*.cpp",
"ios/**/*.swift",
"cpp/**/*.h",
"cpp/**/*.hpp",
"cpp/**/*.cpp",
"nitro.json",
"*.podspec",
"README.md"
],
"peerDependencies": {
"react": "*",
"react-native": "*",
"react-native-nitro-modules": "*"
}
}
```
### `.npmignore` (optional, to exclude dev files)
```
apps/
__tests__/
.github/
*.test.ts
tsconfig.json
babel.config.js
```
## Common Pitfalls
- **Missing `nitrogen` in `files`** — Consumers' native builds will fail because the generated C++ glue and autolinking files are absent
- **Missing `nitro.json` in `files`** — Autolinking won't work for consumers; they'll get "native module not found" errors
- **Publishing before building** — `lib/` must be populated before publishing; build first
- **Missing `*.podspec` in `files`** — iOS consumers won't be able to run `pod install`. The VisionCamera-style pattern is a root podspec, not one hidden under `ios/`.
- **Incorrect `types` path** — Points to a file that doesn't exist after build. VisionCamera-style packages use `lib/index.d.ts` when `build` emits a flat `lib/index`.
## Related Skills
- [setup-monorepo-init.md](setup-monorepo-init.md) — Review the Nitrogen scaffold
- [spec-nitro-json.md](spec-nitro-json.md) — Ensure `nitro.json` is complete before publishing
- [release-it-publishing.md](release-it-publishing.md) — Configure `bun release` with `release-it`
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: 198k | Updated | Claude CodeCodex | Verified | Install |