publint

Lint packaging errors

weekly downloads442K

versionv0.3.17

licenseMIT

categorytoolchain

publishlint

Overview

publint is a specialized linter that validates npm package configurations before publication, ensuring your package works correctly across different JavaScript environments including Node.js, browsers, Vite, Webpack, and Rollup. It simulates how package managers and bundlers resolve your package by analyzing package.json fields like main, module, exports, and types, then validates the actual files that would be published to npm.

The tool addresses a critical pain point in JavaScript library development: packages often work perfectly in the author's environment but fail when consumed by users with different bundlers or runtime configurations. publint catches issues like missing browser builds, incorrect exports conditions for ESM/CJS dual packages, mismatched TypeScript declarations, and files referenced in package.json that won't actually be included in the published tarball.

With over 440,000 weekly downloads, publint has become essential infrastructure for library maintainers navigating the complexity of modern JavaScript module systems. It runs locally via CLI (npx publint), integrates into build tools like Rsbuild and VSCode, and provides severity-tiered feedback (errors, warnings, suggestions) that helps developers fix problems before users encounter them. The tool works by fetching published tarballs from npm or using npm-pack-list locally to simulate exactly what npm publish would upload.

publint is particularly valuable during the ESM migration period, where maintaining compatibility between CommonJS consumers and ESM-native tools requires precise package.json configuration. It enforces best practices around conditional exports, validates that dual packages correctly expose both formats, and ensures TypeScript types align with JavaScript exports across all supported environments.

Quick Start

typescript

// Run publint programmatically in a build script or test
import { publint } from 'publint';
import { formatMessage } from 'publint';

const { messages } = await publint({
  // Validate local package before publishing
  pkgDir: './dist',
  // Or validate published package: { package: 'my-lib@1.0.0' }
  level: 'suggestion', // Show all issues
  strict: true
});

if (messages.length > 0) {
  console.log('📦 Package validation issues found:\n');
  
  for (const message of messages) {
    const formatted = formatMessage(message, 'tty');
    console.log(`[${message.type}] ${formatted}\n`);
  }
  
  const errors = messages.filter(m => m.type === 'error');
  if (errors.length > 0) {
    throw new Error(`Found ${errors.length} packaging errors`);
  }
} else {
  console.log('✅ Package validation passed');
}

// CLI usage for quick checks:
// npx publint
// npx publint --strict
// npx publint ./path/to/package

Use Cases

Pre-publish validation in CI/CD pipelines: Add publint as a CI step to prevent publishing broken packages. Run npx publint in GitHub Actions before npm publish to catch export misconfigurations, missing files, or compatibility issues that would force a patch release.

ESM/CJS dual package development: When maintaining libraries that export both module formats, publint verifies your exports field correctly maps conditions like import, require, types, and default to the right files, preventing runtime errors where Node.js or bundlers can't resolve your package.

Build tool integration for monorepos: Integrate publint into Rsbuild or custom build scripts with pluginPublint({ level: 'error', throwOn: 'error' }) to fail builds when packaging errors are detected, ensuring all workspace packages meet quality standards before deployment.

TypeScript declaration validation: Verify that .d.ts files are correctly placed and referenced in package.json, ensuring TypeScript consumers get proper type inference. publint checks that types or exports conditions point to existing declaration files matching your JavaScript exports.

Debugging resolution issues: When users report "Cannot find module" errors, run publint against your published package to identify why specific bundlers or Node.js versions fail to resolve exports, often revealing issues with conditional exports order or missing file extensions.

Pros & Cons

Pros

+Simulates resolution across multiple environments (Node.js, Vite, Webpack, Rollup, browsers) in a single run, catching compatibility issues other tools miss
+Works both locally and against published packages, allowing validation before and after publishing without needing to upload test versions
+Provides actionable, severity-tiered feedback with specific fixes rather than generic errors, making it accessible even for developers new to package exports
+Zero configuration required for basic usage—just run npx publint and get immediate validation results
+Integrates seamlessly into existing toolchains via CLI, VSCode extension, and build tool plugins

Cons

−Requires Node.js 18 or higher, limiting use in projects locked to older LTS versions
−Limited customization options for suppressing specific rules or adding project-specific validation logic without forking
−Documentation around advanced exports patterns (like subpath imports or wildcards) could be more comprehensive with examples
−No automatic fixing capability—it identifies problems but requires manual package.json edits to resolve issues
−Can produce false positives for unconventional package structures that intentionally deviate from best practices

Install

bash

npm install publint

bash

pnpm add publint

bash

bun add publint

Overview

Quick Start

typescript

// Run publint programmatically in a build script or test
import { publint } from 'publint';
import { formatMessage } from 'publint';

const { messages } = await publint({
  // Validate local package before publishing
  pkgDir: './dist',
  // Or validate published package: { package: 'my-lib@1.0.0' }
  level: 'suggestion', // Show all issues
  strict: true
});

if (messages.length > 0) {
  console.log('📦 Package validation issues found:\n');
  
  for (const message of messages) {
    const formatted = formatMessage(message, 'tty');
    console.log(`[${message.type}] ${formatted}\n`);
  }
  
  const errors = messages.filter(m => m.type === 'error');
  if (errors.length > 0) {
    throw new Error(`Found ${errors.length} packaging errors`);
  }
} else {
  console.log('✅ Package validation passed');
}

// CLI usage for quick checks:
// npx publint
// npx publint --strict
// npx publint ./path/to/package

Use Cases

Pros & Cons

Pros

+Simulates resolution across multiple environments (Node.js, Vite, Webpack, Rollup, browsers) in a single run, catching compatibility issues other tools miss
+Works both locally and against published packages, allowing validation before and after publishing without needing to upload test versions
+Provides actionable, severity-tiered feedback with specific fixes rather than generic errors, making it accessible even for developers new to package exports
+Zero configuration required for basic usage—just run npx publint and get immediate validation results
+Integrates seamlessly into existing toolchains via CLI, VSCode extension, and build tool plugins

Cons

−Requires Node.js 18 or higher, limiting use in projects locked to older LTS versions
−Limited customization options for suppressing specific rules or adding project-specific validation logic without forking
−Documentation around advanced exports patterns (like subpath imports or wildcards) could be more comprehensive with examples
−No automatic fixing capability—it identifies problems but requires manual package.json edits to resolve issues
−Can produce false positives for unconventional package structures that intentionally deviate from best practices