npm — Claude Code rule: what it does, how to install
npm is a Claude Code rule that guides the packaging of UI components into versioned releases. It enforces strict exports mapping, peer dependency boundaries, and build steps.
Apache-2.0 ★ 141 updated 2026-11-17
.claude/rules/npm.mdWhat npm does
This rule enforces production-ready standards for publishing JavaScript and React libraries. It ensures dependencies like React live under peerDependencies while specifying dual ESM and CommonJS outputs through the exports field alongside TypeScript declarations.
The guidance includes a build workflow using tsup with a mandatory prepublishOnly check. It also defines how consumers must declare the package path via @source so Tailwind can scan class names across node_modules.
What it helps with
- configure package.json for publishing dual ESM and CJS modules
- prevent bundling host libraries by isolating peerDependencies
- set up automated tsup compilation scripts with type declarations
- document Tailwind source scanning for packaged component classes
Example prompts for the agent
- Configure package.json exports for my component library
- Set up a tsup build script that outputs ESM, CJS, and types
- Show how consumers should configure Tailwind for this package
How to install npm
Manually: put the files in place
.claude/rules/npm.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/npm.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/npm.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/npm.mdManually: put the files in place
.clinerules/npm.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about npm
How to install npm in Claude Code?
Place the rule file into your project at .claude/rules/npm.md.
What does the npm rule do?
It guides the agent to structure package manifests, module exports, and build configurations correctly for registry distribution.
What tools are needed for the npm rule build flow?
The suggested compilation setup relies on tsup to bundle index files into dual formats with generated .d.ts files.
Source text
npm.md · Apache-2.0
---
title: Publishing to NPM
impact: LOW
impactDescription: Traditional package distribution
tags: npm, package, publishing, versioning, exports
---
## Publishing Components to NPM
Distribute components as npm packages for stable, versioned dependencies with centralized updates.
### When to Use NPM
Choose npm when:
- Users need stable, versioned dependencies
- Centralized control over updates
- Automatic dependency resolution
- Users don't need source code access
### Package Configuration
**Bad:**
```json
{
"name": "@acme/ui-components",
"version": "1.0.0",
"main": "./src/index.ts",
"types": "./src/index.ts",
"dependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0"
}
}
```
Missing `exports` field, pointing to source files instead of built dist, and including React in dependencies instead of peerDependencies.
**Correct:**
```json
{
"name": "@acme/ui-components",
"version": "1.0.0",
"description": "Accessible React components",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
},
"./styles.css": "./dist/styles.css"
},
"files": ["dist"],
"scripts": {
"build": "tsup",
"prepublishOnly": "npm run build"
},
"peerDependencies": {
"react": "^18.0.0",
"react-dom": "^18.0.0"
},
"dependencies": {
"clsx": "^2.0.0",
"tailwind-merge": "^2.0.0"
}
}
```
**Key points:**
- Use `exports` for modern module resolution
- Include ESM (`module`) and CommonJS (`main`)
- Specify `types` for TypeScript
- Use `peerDependencies` for React
- Limit published files with `files` array
### Tailwind Configuration
**Critical:** Document this requirement for Tailwind-based components:
**Example:**
```css
@import "tailwindcss";
/* Users must add this to scan your package */
@source "../node_modules/@acme/ui-components";
```
### Build and Publish
**Example:**
```json
{
"scripts": {
"build": "tsup src/index.ts --format cjs,esm --dts",
"prepublishOnly": "npm run build"
}
}
```
**Steps:**
1. Build (`npm run build`)
2. Verify `dist` contents
3. Update version (`npm version patch|minor|major`)
4. Publish (`npm publish`)
### Trade-offs
**Source Code:**
- Users cannot modify directly
- Bug fixes require package updates
- Customization limited to exposed API
**Bundle Size:**
- All components included
- Tree-shaking helps but imperfect
**Customization:**
- Work within exposed API only
- Forking required for deep changes
### Usage
**Example:**
```bash
npm install @acme/ui-components
```
```tsx
import { Button } from "@acme/ui-components";
// Pre-built, versioned code from node_modules
```
### Choosing Distribution
**npm when:**
- Stable, versioned dependencies needed
- Centralized updates preferred
- Source access not required
**Registry when:**
- Source code access needed
- Customization beyond props important
- Copy-paste workflow preferred
Consider offering both to let developers choose.
© maxtrigify · Apache-2.0 · maxtrigify/Otto