npm Package README Template
An npm package README is displayed directly on the npmjs.com package page, making it a critical piece of marketing and discoverability content in addition to developer documentation. npm users decide in seconds whether to add a dependency based on what they see in the README — a poorly structured README leads to fewer downloads even when the package solves a real problem better than alternatives.
The npm-specific README differs from a general open source README in several ways. Bundle size information is critical for frontend packages — developers using webpack, Rollup, or Vite are deeply concerned about adding kilobytes to their bundles. Include the minified and gzip-compressed bundle size prominently, ideally with a bundlephobia badge. Browser compatibility and Node.js version support requirements must be explicit because npm packages are used in wildly different environments.
TypeScript support disclosure matters because a large proportion of modern JavaScript development uses TypeScript. State clearly whether your package ships types (bundled types preferred over @types/ packages), whether types are complete or partial, and the minimum TypeScript version supported. Show an import example with the exact module path and type annotations.
The API reference section is where npm READMEs most often fall short. Each exported function or class should have: the function signature with parameter types, a description of each parameter and its default value, the return type and what it represents, and at least one working code example. For packages with many exports, a brief overview table linking to more detailed documentation is preferable to one enormous README.
Peer dependencies deserve explicit documentation. If your package requires React 18+ or a specific version of a framework, developers need to know before installing. Explain what the peer dependencies are for and what versions are compatible.
Changelog or "what's new" information helps users decide whether to upgrade existing installations. A link to the CHANGELOG.md or GitHub releases page should appear near the version badge.
Template Preview
{"projectType":"npm-package","language":"TypeScript","includesBadges":true,"includesInstallation":true,"includesAPIReference":true,"includesTypeScriptTypes":true,"includesBundleSize":true,"license":"MIT"}Customize this template with your own details using the free generator:
▸Open in GeneratorFAQ
- How do I show my package's bundle size in the README?
- Use bundlephobia.com/badge — it dynamically renders your package's minified and gzip sizes. Add the badge with: [](https://bundlephobia.com/package/your-package-name). This updates automatically when you publish new versions, so users always see current size data.
- Should I include a full API reference in the README or link to separate docs?
- For packages with 1–10 exported functions, include the full reference in the README. For larger packages, keep the README focused on the most common use cases (the 80% scenario) and link to hosted documentation built with tools like TypeDoc, API Extractor, or Docusaurus. A long, scrollable README with buried information is worse than a short README with clear links.
- How do I add code examples that stay synchronized with my source?
- Use markdown code fences with language hints for syntax highlighting. For complex examples, maintain them as actual test files in your repository (e.g., examples/ directory) and use a documentation tool that can extract them. Running your examples as integration tests ensures they stay correct as the API evolves — nothing is worse than a README example that no longer works.