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 pkgDir should 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. This runs before level filters the result, which means that if level is set to 'error', all warnings (elevated as errors) will still be reported.

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 nodeBuffer = await fs.readFile('./mylib-1.0.0.tgz')
const tarballBuffer = nodeBuffer.buffer.slice(
  nodeBuffer.byteOffset,
  nodeBuffer.byteOffset + nodeBuffer.byteLength
)
+const result = await publint({ pack: { tarball: tarballBuffer } })

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 } })