Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/npm.md
Open on GitHub

What 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.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set18

The whole set →
registry registry is a Claude Code rule for publishing UI components as source code. It defines registry metadata and a deployment flow. CX Codex +1 ★ 141repo stars marketplaces The marketplaces rule for Claude Code organizes component discovery and integration from external registries. It helps the agent evaluate code quality before adding dependencies. CX Codex +1 ★ 141repo stars design-tokens design-tokens is a Claude Code rule that replaces hardcoded colors with semantic tokens. Light and dark themes then change variable values instead of component classes. CX Codex +1 ★ 141repo stars composition The composition rule for Claude Code guides the breakdown of complex UI components into small, focused parts. It serves when building component libraries or flexible interfaces. CX Codex +1 ★ 141repo stars overview overview is a Claude Code rule for designing accessible, composable UI components. It comes into play while shaping component APIs and shared patterns. CX Codex +1 ★ 141repo stars types The types rule for Claude Code standardizes component prop definitions in TypeScript. It provides a framework for building flexible, type-safe interfaces across React projects. CX Codex +1 ★ 141repo stars data-attributes data-attributes is a Claude Code rule for styling component states and targeting nested parts with data-state and data-slot. CX Codex +1 ★ 141repo stars principles The principles rule for Claude Code establishes six core standards for component design. It guides agents during component creation, refactoring, and evaluation. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open