JavaScript API

To programmatically run publint, import it from the package and execute it:

import { publint } from 'publint'

const { messages } = await publint({
  // options...
})

messages is an array of message object that describes the the code, severity, and location of the issue. To format it as a string, you can use the formatMessage utility:

import { publint } from 'publint'
import { formatMessage } from 'publint/utils'

const { messages, pkg } = await publint({
  // options...
})

for (const message of messages) {
  console.log(formatMessage(message, pkg))
}

Options

pkgDir

Type: string

Path to your package that contains a package.json file.

Environment notes

• Node.js: Defaults to process.cwd().
• Browser: Automatically inferred from { tarball: ArrayBuffer | ReadableStream }. If { files: PackFile[] } is used, this must be the shared directory of all files in files. e.g. if name has "package/src/index.js", the pkgDirshould be"package"`.

level

Type: 'suggestion' | 'warning' | 'error'

The level of messages to log (default: 'suggestion').

• suggestion: logs all messages
• warning: logs only warning and error messages
• error: logs only error messages

pack

Type:

| 'auto'
| 'npm'
| 'yarn'
| 'pnpm'
| 'bun'
| { tarball: ArrayBuffer | ReadableStream<Uint8Array> }
| { files: PackFile[] }
| false

The package manager to use for packing the pkgDir. The list of packed files is used in certain linting rules, e.g. files marked as entrypoints but not published.

• 'auto': Automatically detects the package manager using package-manager-detector.
• 'npm'/'yarn'/'pnpm'/'bun': Uses the respective package manager to pack.
• { tarball }: The packed tarball represented as an ArrayBuffer or a ReadableStream.
• { files }: The manually-unpacked files from a tarball.
• false: Skips packing the package. This should only be used if all the files in pkgDir are assumed to be published, e.g. in node_modules.

Environment notes

• Node.js: Defaults to 'auto'. All options above are supported. When using a package manager to pack, lifecycle scripts like prepack and postpack are ignored (except for yarn as it does not allow ignoring lifecycle scripts).
• Browser: Only { tarball } and { files } are supported and either must be passed to work, as the browser does not have access to the file system.

strict

Type: boolean

Report warnings as errors.

Examples

Basic usage

Works in Node.js.

import { publint } from 'publint'

const result = await publint({ pkgDir: './packages/mylib' })

Lint a tarball

Works in Node.js and browsers.

import { publint } from 'publint'

// Fetch tarball
const response = await fetch(
  'https://registry.npmjs.org/mylib/-/mylib-1.0.0.tgz',
)
if (!response.body) throw new Error('Failed to fetch tarball')

const result = await publint({ pack: { tarball: response.body } })

Lint a tarball locally

Works in Node.js.

import fs from 'node:fs/promises'
import { publint } from 'publint'

const tarballBuffer = await fs.readFile('./mylib-1.0.0.tgz')
const result = await publint({ pack: { tarball: tarballBuffer.buffer } })

Manually unpack and pass as files

Works in Node.js and browsers.

import { publint } from 'publint'
import { unpack } from '@publint/pack'

// Fetch tarball
const response = await fetch(
  'https://registry.npmjs.org/mylib/-/mylib-1.0.0.tgz',
)
if (!response.body) throw new Error('Failed to fetch tarball')

const { rootDir, files } = await unpack(response.body)
// Do something with `files` if needed

const result = await publint({ pkgDir: rootDir, pack: { files } })