home / skills / toilahuongg / shopify-agents-kit / npm-publish

npm-publish skill

safe

This skill guides you through publishing npm packages, including configuration, versioning, dry runs, and post-publish verification.

npx playbooks add skill toilahuongg/shopify-agents-kit --skill npm-publish

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.1 KB

---
name: npm-publish
description: Guide for publishing packages to the npm registry. Use this skill when the user wants to publish a new package, release a new version, or manage npm package configurations.
---

# npm Publish Guide

This skill guides you through the process of publishing a package to the npm registry.

## 1. Prerequisites

Before publishing, ensure you are logged in to npm.

```bash
npm whoami
```

If not logged in:
```bash
npm login
```

## 2. Preparation & Configuration

### Critical `package.json` Fields
Ensure these fields are correct:
- **name**: Unique package name (scoped names like `@org/pkg` are recommended for organizations).
- **version**: SemVer compliant version (e.g., `1.0.0`).
- **main/module/exports**: Entry points for your library.
- **files**: Whitelist of files to include (reduces package size).
- **private**: Must be `false` (or missing) to publish.

### Excluding Files
Use a `.npmignore` file or the `files` array in `package.json` to prevent publishing unnecessary files (tests, src, config files).
**Tip**: `npm publish --dry-run` shows exactly what will be packed.

### Build (If applicable)
If your package requires compilation (TypeScript, Babel, etc.), run the build script first.
```bash
npm run build
```

## 3. Versioning

Update the package version before publishing. This command increments the version in `package.json` and creates a git tag.

```bash
# Choose one:
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
```

## 4. Publishing

### Dry Run
Always do a dry run first to verify contents.
```bash
npm publish --dry-run
```

### Scoped Packages
If publishing a scoped package (e.g., `@myorg/my-pkg`) publicly for the first time:
```bash
npm publish --access public
```

### Standard Publish
```bash
npm publish
```

## 5. Post-Publish

### Push Tags
Push the new version commit and tags to your git repository.
```bash
git push --follow-tags
```

### Verification
Check the npm registry or install the package in a test project to verify.
```bash
npm view <package-name> version
```

Overview

This skill guides you through publishing packages to the npm registry. It covers prerequisites, package configuration, versioning, dry-run checks, scoped publishing, and post-publish verification. Use it to avoid common pitfalls and to make your release process repeatable and safe.

How this skill works

The skill inspects your package.json for critical fields (name, version, main/module/exports, files, private) and walks you through preparing build artifacts and excluding unnecessary files. It explains version bumping with npm version, performing npm publish --dry-run to preview the tarball, and the correct commands for publishing scoped or public packages. It also covers post-publish steps like pushing tags and verifying the published version.

When to use it

Publishing a new package to the npm registry for the first time.
Releasing a new version after code or build changes.
Preparing a package that requires a build step (TypeScript, Babel, etc.).
Ensuring only intended files are included in the published package.
Publishing scoped packages publicly or managing access settings.

Best practices

Confirm you're logged in with npm whoami before publishing.
Keep package.json fields accurate: name, version, main/module/exports, files, and private.
Use files or .npmignore to exclude tests, source, and config files; run npm publish --dry-run to verify.
Run your build script (npm run build) before publishing compiled packages.
Use npm version to update semver and create a git tag, then git push --follow-tags after publish.
For scoped public packages include --access public on the first publish.

Example use cases

Publishing a new utility library after compiling TypeScript to JavaScript.
Releasing a patch version fix: npm version patch, npm publish, then push tags.
Publishing a scoped organization package publicly: npm publish --access public.
Verifying published output in a test project by running npm view <package-name> version and installing it locally.
Reducing package size by listing only distributable files in package.json files array and confirming with a dry run.

FAQ

What if npm whoami fails?

Run npm login and provide your credentials or token, then re-run npm whoami to confirm.

How do I prevent secret files from being published?

Add them to .npmignore or omit them from the package.json files array; validate with npm publish --dry-run.

Do I need --access public for scoped packages every time?

Only for the first public publish of a scoped package. Subsequent publishes use the existing access level.