home / skills / vercel / ai / list-npm-package-content

list-npm-package-content skill

safe

This skill lists the exact contents of an npm package tarball before publishing to verify included files and aid debugging.

npx playbooks add skill vercel/ai --skill list-npm-package-content

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

Files (2)

SKILL.md

1.0 KB

---
name: list-npm-package-content
description: List the contents of an npm package tarball before publishing. Use when the user wants to see what files are included in an npm bundle, verify package contents, or debug npm publish issues.
metadata:
  internal: true
---

# List npm Package Content

This skill lists the exact contents of an npm package tarball - the same files that would be uploaded to npm and downloaded by users.

## Usage

Run the script from the package directory (e.g., `packages/ai`):

```bash
bash scripts/list-package-files.sh
```

The script will build the package, create a tarball, list its contents, and clean up automatically.

## Understanding Package Contents

The files included are determined by:

1. **`files` field in `package.json`** - explicit allowlist of files/directories
2. **`.npmignore`** - files to exclude (if present)
3. **`.gitignore`** - used if no `.npmignore` exists
4. **Always included**: `package.json`, `README`, `LICENSE`, `CHANGELOG`
5. **Always excluded**: `.git`, `node_modules`, `.npmrc`, etc.

Overview

This skill lists the exact contents of an npm package tarball before publishing. It builds the package, creates the npm tarball, prints the files that would be published, and then cleans up the temporary artifacts. Use it to verify what end users will receive and to catch accidental or missing files before running npm publish.

How this skill works

The script runs from the package directory, builds the package, and creates a tarball using npm packing tooling. It extracts and lists the tarball entries to show the precise set of files included. The process respects package.json 'files', .npmignore, .gitignore (when .npmignore is absent), and npm's always-included or always-excluded defaults.

When to use it

Before publishing a new version to verify included files
When debugging unexpected files being uploaded to npm
To confirm build output and distribution artifacts are present
When preparing a minimal package and checking .npmignore/files settings
During CI to assert package contents match expectations

Best practices

Run the script from the package directory (e.g., packages/ai) so paths match the published tarball
Ensure your build step runs first so generated artifacts are included in the listing
Use the package.json 'files' field to explicitly allow files and keep .npmignore minimal
Rely on .npmignore for exclusions; remember .gitignore is used only if .npmignore is absent
Treat listed always-included files (package.json, README, LICENSE, CHANGELOG) as required in the package

Example use cases

Confirm transpiled JS and type declarations are included before publishing a TypeScript package
Detect accidental inclusion of source tests, large assets, or local configs that bloat the package
Validate CI pipeline output by adding the script as a step that fails on unexpected files
Compare package contents across versions to ensure breaking changes didn't remove important files

FAQ

Does the script modify my repo or publish to npm?

No. It builds and creates a local tarball, lists its contents, and then removes the temporary tarball. It does not publish to npm or change remote state.

Which files are always included or excluded?

Npm always includes package.json, README, LICENSE, and CHANGELOG. It always excludes .git, node_modules, .npmrc, and other internal files; follow npm docs for the complete list.