pkg-types

Node.js utilities and TypeScript definitions for package.json, tsconfig.json, and other configuration files.

Install

# ✨ Auto-detect
npx nypm install pkg-types
# npm
npm install pkg-types
# yarn
yarn add pkg-types
# pnpm
pnpm add pkg-types
# bun
bun install pkg-types
# deno
deno install npm:pkg-types

Usage

Package Configuration

readPackage

Reads any package file format (package.json, package.json5, or package.yaml) with automatic format detection.

import{readPackage}from"pkg-types";constlocalPackage=awaitreadPackage();// orconstpkg=awaitreadPackage("/fully/resolved/path/to/folder");

writePackage

Writes package data with format detection based on file extension.

import{writePackage}from"pkg-types";awaitwritePackage("path/to/package.json",pkg);awaitwritePackage("path/to/package.json5",pkg);awaitwritePackage("path/to/package.yaml",pkg);

findPackage

Finds the nearest package file (package.json, package.json5, or package.yaml).

import{findPackage}from"pkg-types";constfilename=awaitfindPackage();// orconstfilename=awaitfindPackage("/fully/resolved/path/to/folder");

readPackageJSON

import{readPackageJSON}from"pkg-types";constlocalPackageJson=awaitreadPackageJSON();// orconstpackageJson=awaitreadPackageJSON("/fully/resolved/path/to/folder");

writePackageJSON

import{writePackageJSON}from"pkg-types";awaitwritePackageJSON("path/to/package.json",pkg);

resolvePackageJSON

import{resolvePackageJSON}from"pkg-types";constfilename=awaitresolvePackageJSON();// orconstpackageJson=awaitresolvePackageJSON("/fully/resolved/path/to/folder");

updatePackage

Reads a package file and passes a proxied PackageJson to a callback (the callback may mutate it in-place or return a new object). The updated package is then written back using the same file format (.json/.json5/.yaml). The proxy auto-creates common map fields (e.g. scripts, dependencies) when accessed.

import{updatePackage}from"pkg-types";awaitupdatePackage("path/to/package",(pkg)=>{pkg.version="1.0.1";pkg.dependencies.lodash="^4.17.21";});

sortPackage

Returns a new PackageJson that reorders known top-level fields according to the convention and alphabetically sorts certain nested maps (like dependencies, devDependencies, optionalDependencies, peerDependencies and scripts). Unknown top-level keys retain their original relative order. The input object is not mutated.

import{sortPackage}from"pkg-types";constsorted=sortPackage(pkg);

normalizePackage

Normalizes a PackageJson for stable output: sorts top-level fields and dependency maps, and removes dependency fields (dependencies, devDependencies, optionalDependencies, peerDependencies) if they are not plain objects. Returns a new normalized object.

import{normalizePackage}from"pkg-types";constnormalized=normalizePackage(pkg);

TypeScript Configuration

readTSConfig

import{readTSConfig}from"pkg-types";consttsconfig=awaitreadTSConfig();// orconsttsconfig2=awaitreadTSConfig("/fully/resolved/path/to/folder");

writeTSConfig

import{writeTSConfig}from"pkg-types";awaitwriteTSConfig("path/to/tsconfig.json",tsconfig);

resolveTSConfig

import{resolveTSConfig}from"pkg-types";constfilename=awaitresolveTSConfig();// orconsttsconfig=awaitresolveTSConfig("/fully/resolved/path/to/folder");

File Resolution

findFile

import{findFile}from"pkg-types";constfilename=awaitfindFile("README.md",{startingFrom: id,rootPattern: /^node_modules$/,test: (filename)=>filename.endsWith(".md"),});

findNearestFile

import{findNearestFile}from"pkg-types";constfilename=awaitfindNearestFile("package.json");

findFarthestFile

import{findFarthestFile}from"pkg-types";constfilename=awaitfindFarthestFile("package.json");

resolveLockfile

Find path to the lock file (yarn.lock, package-lock.json, pnpm-lock.yaml, npm-shrinkwrap.json, bun.lockb, bun.lock, deno.lock) or throws an error.

import{resolveLockfile}from"pkg-types";constlockfile=awaitresolveLockfile(".");

findWorkspaceDir

Try to detect workspace dir by in order:

1. Farthest workspace file (pnpm-workspace.yaml, lerna.json, turbo.json, rush.json, deno.json, deno.jsonc)
2. Closest .git/config file
3. Farthest lockfile
4. Farthest package.json file

If fails, throws an error.

import{findWorkspaceDir}from"pkg-types";constworkspaceDir=awaitfindWorkspaceDir(".");

Git Configuration

resolveGitConfig

Finds closest .git/config file.

import{resolveGitConfig}from"pkg-types";constgitConfig=awaitresolveGitConfig(".");

readGitConfig

Finds and reads closest .git/config file into a JS object.

import{readGitConfig}from"pkg-types";constgitConfigObj=awaitreadGitConfig(".");

writeGitConfig

Stringifies git config object into INI text format and writes it to a file.

import{writeGitConfig}from"pkg-types";awaitwriteGitConfig(".git/config",gitConfigObj);

parseGitConfig

Parses a git config file in INI text format into a JavaScript object.

import{parseGitConfig}from"pkg-types";constgitConfigObj=parseGitConfig(gitConfigINI);

stringifyGitConfig

Stringifies a git config object into a git config file INI text format.

import{stringifyGitConfig}from"pkg-types";constgitConfigINI=stringifyGitConfig(gitConfigObj);

Types

• Note: In order to make types work, you need to install typescript as a devDependency.

You can directly use typed interfaces:

importtype{TSConfig,PackageJson,GitConfig}from"pkg-types";

Define Utilities

You can use define utilities for type support and auto-completion when working in plain .js files. These functions simply return the input object but provide TypeScript type hints.

definePackageJSON

Provides type safety and auto-completion for package.json objects.

import{definePackageJSON}from"pkg-types";constpkg=definePackageJSON({name: "my-package",version: "1.0.0",// TypeScript will provide auto-completion here});

defineTSConfig

Provides type safety and auto-completion for tsconfig.json objects.

import{defineTSConfig}from"pkg-types";consttsconfig=defineTSConfig({compilerOptions: {target: "ES2020",// TypeScript will provide auto-completion here},});

defineGitConfig

Provides type safety and auto-completion for git config objects.

import{defineGitConfig}from"pkg-types";constgitConfig=defineGitConfig({user: {name: "John Doe",email: "john@example.com",},// TypeScript will provide auto-completion here});

Alternatives

• dominikg/tsconfck

License

Published under the MIT license. Made by @pi0, @danielroe and community 💛