The moment you publish an npm package with a broken export map or missing entry point, you've created a debugging nightmare for every developer who tries to use it. Whether it's a CJS/ESM mismatch that breaks in Vite, an invalid exports field that confuses Node.js, or a missing browser build that fails in webpack, these packaging mistakes are surprisingly easy to make and painfully hard to debug.
Publint solves this by doing what most of us should do but rarely remember to: validating your package configuration before it reaches npm. Created by Bjorn Lu, this tool simulates how real bundlers and runtimes will interpret your package.json, catching the subtle mistakes that cause downstream headaches.
The packaging pain is real
Modern JavaScript packaging has become a minefield. You're not just shipping code anymore—you're shipping a configuration that needs to work across Node.js, browsers, Vite, webpack, Rollup, and whatever new bundler emerges next month. Each environment has its own way of resolving modules, and getting the main, module, types, and exports fields right requires understanding the intricate dance between these tools.
<> "Broken npm packages often fail due to small packaging mistakes" - and these mistakes compound quickly when you're supporting both CommonJS and ESM, or trying to provide separate browser and Node.js builds./>
The worst part? You often don't discover these issues until a user reports that your package doesn't work in their specific setup. By then, you're playing detective, trying to reproduce their exact bundler configuration and Node.js version.
How Publint actually works
Publint takes a different approach than typical linters. Instead of checking your source code, it analyzes your package as npm would actually publish it. When you run it locally, it uses npm-pack-list to determine exactly which files would be included in your published package, then validates the configuration against those real files.
For published packages, it fetches directly from npm and runs the same analysis. This means you're not just validating your intentions—you're validating reality.
1# Basic usage - analyzes your current project
2npx publint
3
4# Check a specific published package
5npx publint lodash
6
7# Analyze from a tarball or directory
8npx publint ./path/to/package
9npx publint https://registry.npmjs.org/package/-/package-1.0.0.tgzThe tool simulates how different environments resolve your package:
- Node.js: Checks if
mainandexportsfields resolve correctly - Bundlers: Validates
modulefield and ESM exports - TypeScript: Ensures
typesfield points to valid declaration files - Browsers: Verifies browser-specific exports work as expected
Beyond basic validation
What makes Publint particularly valuable is its understanding of the edge cases that break real-world usage. It catches issues like:
- Export maps that work in Node.js but fail in Vite
- TypeScript declaration files that don't match your runtime exports
- CJS files accidentally published as ESM (or vice versa)
- Missing entry points that exist in your source but not in the published package
- Browser builds that reference Node.js-only APIs
The online version at publint.dev makes this even more accessible. You can paste any npm package name and get instant feedback, which is invaluable when you're investigating why someone else's package isn't working in your project.
Integrating validation into your workflow
The real power comes from making validation automatic. Rather than remembering to run Publint before every release, build it into your development process:
1{
2 "scripts": {
3 "prepublishOnly": "publint",
4 "validate": "publint && npm run test",
5 "prepack": "publint"
6 }
7}The VSCode extension (search "vscode-publint") provides real-time feedback as you edit your package.json, catching issues before you even run a build. This immediate feedback loop helps you understand how changes to your package configuration affect different environments.
For teams managing multiple packages, tools like renoma can run Publint across entire monorepos:
1npx renoma --filter-rules publintThe bigger picture
Publint represents something important: tooling that understands the complexity we've created. The JavaScript ecosystem's flexibility is both a strength and a weakness. We can support any environment and any module system, but only if we get the configuration exactly right.
<> The fact that pnpm's team proposed integrating Publint for pre-publish validation shows how critical this type of checking has become for ecosystem health./>
Rather than expecting every developer to become an expert in the nuances of module resolution across every possible bundler and runtime, tools like Publint encode that expertise and make it accessible.
Why this matters now
Packaging validation isn't just about preventing bugs—it's about confidence. When you know your package configuration is solid, you can focus on building features instead of debugging environment-specific issues. Your users spend less time filing issues and more time building with your code.
The JavaScript ecosystem moves fast, and packaging standards continue to evolve. Having automated validation means you can adapt to new bundler requirements and Node.js features without manually tracking every edge case.
If you maintain any npm packages, add npx publint to your pre-publish checklist today. If you're dealing with mysterious import errors from third-party packages, check them at publint.dev to see if it's a known packaging issue. The five minutes you spend validating can save hours of debugging later.
