npm-publishing

Original source / Raw SKILL.md

---
name: npm-publishing
# prettier-ignore
description: Use when publishing npm packages - covers package.json configuration, versioning, and provenance
---

# npm Publishing Best Practices

## Quick Start

```json
{
  "name": "lea-lang",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build && npm test"
  }
}
```

## Package Configuration

### Essential Fields

```json
{
  "name": "lea-lang",
  "version": "1.1.3",
  "description": "Pipe-oriented functional programming language",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "lea": "./dist/cli/index.js"
  },
  "files": [
    "dist",
    "README.md"
  ],
  "keywords": ["language", "interpreter", "functional", "pipes"],
  "author": "Your Name",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/user/lea.git"
  },
  "engines": {
    "node": ">=18"
  }
}
```

### Exports (Modern)

```json
{
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.js"
    },
    "./parser": {
      "types": "./dist/parser.d.ts",
      "import": "./dist/parser.mjs",
      "require": "./dist/parser.js"
    }
  }
}
```

## Versioning

### Semantic Versioning

```
MAJOR.MINOR.PATCH

1.0.0 → 1.0.1  # Patch: bug fixes
1.0.1 → 1.1.0  # Minor: new features (backwards compatible)
1.1.0 → 2.0.0  # Major: breaking changes
```

### Version Commands

```bash
npm version patch  # 1.0.0 → 1.0.1
npm version minor  # 1.0.0 → 1.1.0
npm version major  # 1.0.0 → 2.0.0
```

## Publishing

### First-Time Setup

```bash
npm login
npm publish --access public  # For scoped packages
```

### With Provenance (Recommended)

```bash
npm publish --provenance --access public
```

### Dry Run

```bash
npm publish --dry-run
npm pack  # Creates tarball to inspect
```

## Files to Include/Exclude

### .npmignore

```
src/
__tests__/
tests/
*.test.ts
.github/
docs/
```

### Or use package.json "files"

```json
{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}
```

## Pre-publish Checks

```json
{
  "scripts": {
    "prepublishOnly": "npm run build && npm test && npm run lint"
  }
}
```

## Reference Files

- [references/scopes.md](references/scopes.md) - Scoped packages
- [references/tags.md](references/tags.md) - Dist tags (latest, beta, next)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/scopes.md

```markdown
# Scoped Packages

## Creating a Scoped Package

```json
{
  "name": "@yourname/package-name",
  "version": "1.0.0"
}
```

## Publishing Scoped Packages

Scoped packages are private by default:

```bash
# First publish must specify access
npm publish --access public

# Subsequent publishes
npm publish
```

Or configure in package.json:

```json
{
  "name": "@yourname/package",
  "publishConfig": {
    "access": "public"
  }
}
```

## Installing Scoped Packages

```bash
npm install @yourname/package-name
```

## Scope Organizations

### npm Organizations

- Create at npmjs.com/org
- Shared ownership and permissions
- `@orgname/package`

### GitHub Packages

```json
{
  "name": "@owner/package",
  "publishConfig": {
    "registry": "https://npm.pkg.github.com"
  }
}
```

## Registry Configuration

### Per-Scope Registry

```ini
# .npmrc
@yourscope:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```

### In package.json

```json
{
  "publishConfig": {
    "registry": "https://registry.npmjs.org",
    "@yourscope:registry": "https://npm.pkg.github.com"
  }
}
```

## Importing Scoped Packages

```typescript
// Standard import
import { something } from "@yourname/package";

// Subpath import
import { util } from "@yourname/package/utils";
```

## Benefits of Scopes

1. **Namespace protection** - No conflicts with global names
2. **Organization** - Group related packages
3. **Access control** - Private packages with paid plans
4. **Team management** - Shared publishing rights

```

### references/tags.md

```markdown
# Distribution Tags

## Default Tags

```bash
npm publish              # Publishes to "latest" tag
npm install package      # Installs "latest" tag
```

## Common Tags

| Tag | Purpose |
|-----|---------|
| `latest` | Stable production release |
| `next` | Upcoming major version |
| `beta` | Beta testing |
| `alpha` | Alpha testing |
| `canary` | Nightly/continuous builds |
| `legacy` | Old major version |

## Publishing with Tags

```bash
# Publish to a specific tag
npm publish --tag beta

# Publish to next
npm publish --tag next
```

## Installing Specific Tags

```bash
npm install package@beta
npm install package@next
npm install package@legacy
```

## Managing Tags

### Add/Move Tag

```bash
# Add tag to specific version
npm dist-tag add [email protected] beta

# Move tag to new version
npm dist-tag add [email protected] beta
```

### Remove Tag

```bash
npm dist-tag rm package beta
```

### List Tags

```bash
npm dist-tag ls package
# latest: 1.1.0
# beta: 1.2.0-beta.1
```

## Prerelease Versions

Combine with semantic versioning:

```json
{
  "version": "1.2.0-beta.1"
}
```

```bash
npm version prerelease --preid=beta
# 1.2.0 → 1.2.1-beta.0
# 1.2.1-beta.0 → 1.2.1-beta.1
```

## Workflow Example

```bash
# Development cycle
npm version prerelease --preid=alpha
npm publish --tag alpha

# Beta testing
npm version prerelease --preid=beta
npm publish --tag beta

# Release candidate
npm version prerelease --preid=rc
npm publish --tag next

# Stable release
npm version minor  # or major/patch
npm publish  # Goes to "latest"
```

## CI/CD Tag Strategy

```yaml
- name: Determine tag
  id: tag
  run: |
    if [[ "${{ github.ref }}" == refs/tags/v*-beta* ]]; then
      echo "tag=beta" >> $GITHUB_OUTPUT
    elif [[ "${{ github.ref }}" == refs/tags/v*-alpha* ]]; then
      echo "tag=alpha" >> $GITHUB_OUTPUT
    else
      echo "tag=latest" >> $GITHUB_OUTPUT
    fi

- run: npm publish --tag ${{ steps.tag.outputs.tag }}
```

```