Launch guideDeveloper tools
How to launch an npm package
An npm package launch is mostly done inside package.json and the README. The name, description and keywords feed npm search; the README is the package page; and provenance tells cautious teams where the code was built. Trusted publishing now lets you publish from CI without long-lived tokens, which is worth setting up before your first public release.
Updated · platform facts checked against the official docs linked below
At a glance
Where people find npm packages
- npm search: Name, description and keywords help people find the package.
- GitHub: Developers often find packages through repos, issues and example code.
- JavaScript newsletters and communities: Framework Discords, subreddits and weekly newsletters for your ecosystem.
- Hacker News (Show HN): For packages with a clear demo or a broad audience.
Assets to prepare
| Asset | Spec or guidance |
|---|---|
| package.json metadata | description, keywords, repository, homepage, bugs, license, types if you ship TypeScript types. |
| README | What it does, install, a 10-line example, API, bundle size or dependency notes. |
| Public repository field | Must match where you publish from for provenance (case-sensitive).[1] |
| CI publish workflow | Trusted publishing or --provenance with ID-token permissions.[2] |
| Demo | A StackBlitz or CodeSandbox link people can open without installing. |
Store and listing rules
What the platform itself says, with a link to the page we checked.
- Provenance needs npm CLI 9.5.0+, a supported CI (GitHub Actions or GitLab CI/CD) and a public repository matching
repositoryin package.json.[1] - Trusted publishing supports GitHub Actions, GitLab CI/CD and CircleCI cloud runners (not self-hosted), needs npm CLI 11.5.1+ and Node 22.14.0+, and generates provenance automatically for public repos on GitHub or GitLab.[2]
- npm's provenance docs use
npm publish --provenance --access publicfor a package's first publish.[1]
A 4-week launch timeline
Week 1 · four weeks out
- Pick a name that says what it does and check it's free.
- Fill every package.json metadata field.
- Write the README example first, then the code to match.
Week 2 · three weeks out
- Set up trusted publishing in CI.
- Publish a pre-release tag (
next) for testers. - Build a live demo link.
Week 3 · two weeks out
- Collect feedback from five developers who'd use it.
- Write docs for the top three use cases.
- Prepare the Show HN or community post.
Week 4 · launch week
- Publish 1.0 with provenance.
- Write release notes.
- Add the package to your docs site and LaunchRanked.
Launch-day checklist
- Publish 1.0 and confirm the provenance badge shows on npm.
- Post the live demo in the framework community.
- Post Show HN if the audience is broad.
- Respond to issues and PRs quickly.
After launch: SEO steps
Launch boards reset; search pages don't. These steps keep people finding you after launch week.
- Give the package a docs page on your own domain; npm pages rank mostly for the package name.
- Write "how to {task} in {framework}" tutorials that use the package.
- Keep keywords and description accurate as features change.
Common mistakes
- An empty or missing
repositoryfield, which breaks provenance and trust. - Long-lived publish tokens stored in CI when trusted publishing is available.
- A README without a runnable example.
Templates for this launch
- Release notesRelease notes for a notable launch or version: what's new, why it matters, how to use it, upgrade steps and known issues, with a filled example.
- Changelog entryA changelog entry template grouped by Added, Changed, Fixed and Removed, written for users rather than commit logs, with a filled example.
- Show HN postA Show HN template that follows Hacker News rules: a plain title, a link people can try, and a first comment on why you built it and how it works.
FAQ
What is npm provenance?
A signed statement, logged publicly, that links a package version to its source repo and build. You publish with --provenance from supported CI, or get it automatically with trusted publishing.
What do I need for npm trusted publishing?
A supported CI provider (GitHub Actions, GitLab CI/CD or CircleCI cloud), npm CLI 11.5.1 or later and Node 22.14.0 or later, plus a trusted publisher configured on npm.
How do people find npm packages?
npm search, GitHub, tutorials and the communities for each framework. Good metadata and a clear README help with all of them.
Should I publish a pre-release first?
Yes. A next or beta tag lets testers install it without affecting people on latest.
Sources
Checked . Platforms change their rules; open the source before you rely on a number.
Related launch guides
- How to launch a Python libraryLaunch a Python library on PyPI: pyproject metadata, README rendering, classifiers, trusted publishing, docs that rank, and where Python developers look.
- How to launch a CLI toolLaunch a command-line tool: install paths (Homebrew tap vs core, winget, npm, pip), terminal GIFs, Show HN and docs that rank for the problems it solves.
- How to launch an open-source projectLaunch an open-source project: README and repo setup, GitHub topics and social preview, Show HN rules, awesome lists, and docs that rank on Google.
- How to launch a developer APILaunch a developer API: time to first call, docs, OpenAPI, a Postman public workspace, keys and limits, and docs pages that rank.