pkg-types

library2.3.0jsnpmunverified

pkg-types is a utility library providing Node.js functions and comprehensive TypeScript definitions for common project configuration files, including `package.json`, `tsconfig.json`, and various lock files (e.g., `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb`, `deno.lock`). The current stable version is 2.3.0. The package has an active development cycle, with frequent releases bringing enhancements and bug fixes. A key differentiator is its automatic format detection for `package.json` (supporting `.json`, `.json5`, `.yaml`) and robust utilities for finding and reading workspace configurations across different package managers and monorepo tools like Lerna, Turborepo, and Rush. It streamlines the process of programmatically interacting with project metadata, making it ideal for tooling development.

serialization devops

npm install pkg-types

github ↗package ↗

INSTALL

IMPORT

SIG · PKG-TYPES

pkg-types

serializationjavascriptv2.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

readPackage

✓ import { readPackage } from 'pkg-types'

✗ const readPackage = require('pkg-types')

Primary utility for reading `package.json`, `package.json5`, or `package.yaml` files with automatic format detection. The package became ESM-only in v2.0.0.

PackageJson

✓ import type { PackageJson } from 'pkg-types'

✗ import { PackageJson } from 'pkg-types'

Import `PackageJson` as a type for robust type-checking of `package.json` structures. It should be imported with `type` for tree-shaking and avoiding runtime overhead.

readTSConfig

✓ import { readTSConfig } from 'pkg-types'

✗ import readTSConfig from 'pkg-types'

Utility for reading `tsconfig.json` files. This is a named export, not a default export.

findWorkspaceDir

✓ import { findWorkspaceDir } from 'pkg-types'

Locates the root directory of a workspace, supporting various monorepo configurations and lock files. Requires a named import.

Demonstrates how to find and read project `package.json` and `tsconfig.json` files, and detect the workspace root directory using various utilities from `pkg-types`.

import { readPackage, findPackage, readTSConfig, findWorkspaceDir } from 'pkg-types'; import path from 'node:path'; async function getProjectConfig() { try { // Find the nearest package.json, package.json5, or package.yaml const packageFile = await findPackage(process.cwd()); if (packageFile) { console.log(`Found package file: ${packageFile}`); // Read the package configuration, automatically detecting format const pkg = await readPackage(path.dirname(packageFile)); console.log('Project Name:', pkg.name); console.log('Project Version:', pkg.version); } else { console.log('No package file found in current directory or ancestors.'); } // Read the nearest tsconfig.json const tsconfigPath = await findPackage(process.cwd(), { filenames: ['tsconfig.json'] }); if (tsconfigPath) { const tsconfig = await readTSConfig(path.dirname(tsconfigPath)); console.log('TSConfig Compiler Options:', tsconfig?.compilerOptions); } else { console.log('No tsconfig.json found.'); } // Find the workspace root directory const workspaceRoot = await findWorkspaceDir(process.cwd()); if (workspaceRoot) { console.log('Detected workspace root:', workspaceRoot); } else { console.log('No workspace root detected.'); } } catch (error) { console.error('Failed to read project configuration:', (error as Error).message); } } getProjectConfig();

Debug

Known issues

breakingStarting with v2.0.0, `pkg-types` is an ESM-only distribution. CommonJS `require()` statements will no longer work and will result in runtime errors.

fix

Migrate your project to use ES module `import` syntax. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions for files importing `pkg-types`.

affects: >=2.0.0

gotchaThe `workspaces` field in `package.json` now supports an object format in addition to arrays since v2.3.0. If your tooling expects only array formats, ensure it can gracefully handle the new object structure.

fix

Update parsing logic to account for both `string[]` and `object` types for the `workspaces` field when reading `PackageJson` data.

affects: >=2.3.0

gotcha`readPackage` and `findPackage` support multiple file formats (`package.json`, `package.json5`, `package.yaml`) and will automatically detect them. If you expect a specific format, ensure your directory doesn't contain conflicting files that might lead to unexpected reads.

fix

When explicit behavior is needed, specify the full file path to functions like `readPackage` instead of relying solely on directory-based discovery. Alternatively, manage your project's configuration files to avoid ambiguity.

affects: >=2.3.0

gotcha`findWorkspaceDir` employs a specific detection strategy (workspace config files, `.git/config`, lockfiles, then `package.json`). In complex monorepo setups, understanding this order is crucial for predictable results.

fix

Familiarize yourself with the `findWorkspaceDir` detection order documented in the README. If the default strategy is not suitable, consider using more specific file resolution functions like `findPackage` with custom `filenames` options.

affects: >=2.1.0

Errors

Common errors & fixes

ReferenceError: require is not defined in ES module scope

Attempting to use `require()` to import `pkg-types` in an environment where it's treated as an ES module.

fix

Replace `const { ... } = require('pkg-types')` with `import { ... } from 'pkg-types'`. Ensure your Node.js environment or build setup correctly handles ES modules.

Error: No package file found starting from /path/to/project

The `findPackage` or `readPackage` utility could not locate any `package.json`, `package.json5`, or `package.yaml` file in the specified path or its ancestors.

fix

Verify that a valid package configuration file exists in the target directory or any parent directories. Ensure the provided path is correct and accessible. Handle the potential error in your application logic.

Error: No lock file found starting from /path/to/project

The `resolveLockFile` utility failed to find any known lock file (`yarn.lock`, `package-lock.json`, etc.) in the given directory or its ancestors.

fix

Confirm that a lock file generated by a package manager (npm, yarn, pnpm, bun, deno) exists in your project. Check the starting path provided to `resolveLockFile` to ensure it's correct.

Upgrade

Version history

2.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unjs/pkg-types ↗

packagehttps://www.npmjs.com/package/pkg-types ↗