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.
Where to list it and how to rank it
Where to submit your npm package, and the SEO plan that fits it.
- Directory listWhere to submit a developer toolWhere to submit a developer tool, library or dev service: dev tool directories and open-source lists, checked for…
- Directory categoryDeveloper tool directories: where to submitDirectories for developer tools, APIs and dev products, each checked on its own site: pricing, link type, review…
- SEO playbookSEO & AI search playbook for developer toolsHonest X vs Y pages, framework guides and error pages, for readers who try everything themselves.
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.