Package and TypeScript Configuration Utilities

Common errors

• ReferenceError: require is not defined in ES module scope

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Starting 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`.
• gotcha The `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.
• 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.
• 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.

Install

• npm install pkg-types npm
• yarn add pkg-types yarn
• pnpm add pkg-types pnpm

Imports

• readPackage
  wrong:

  const readPackage = require('pkg-types')

  correct:

  import { readPackage } from '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
  wrong:

  import { PackageJson } from 'pkg-types'

  correct:

  import type { 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
  wrong:

  import readTSConfig from 'pkg-types'

  correct:

  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.

Quickstart

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();