pncat

Advanced dependency management for pnpm workspaces with catalog support.

[!NOTE] Enhanced pnpm workspace management with intelligent dependency cataloging, inspired by taze and @antfu/nip.

pnpm add -D pncat

Features

Detect Catalogable Dependencies

pncat detect

Scans your workspace to identify dependencies that could be moved to catalogs.

Smart Catalog Migration

pncat migrate

Automatically groups dependencies by rules (e.g., lint, test, utils), it updates both pnpm.workspace.yaml and relevant package.json.

Default rules can be found in src/rules.ts. To customize theme, you can create a pncat.config.ts file in the root directory.

Migration Guide

To preverse existing catalog, run pncat migrate, this will only migrate uncataloged dependencies.

To update catalog catalog groups according to rules, run pncat catalog -f, or do a clean migration with pncat revert → pncat migrate.

Add with Catalog Support

pncat add vue

Add dependencies with prompts and catalogs support (powered by @antfu/nip).

Safe Dependency Removal

pncat remove vitest

Display which catalog group is using the dependency. If confirmed, it will remove the dependency from both pnpm.workspace.yaml and package.json.

Catalog Cleanup

pncat clean

Find unused catalog dependencies and remove them from pnpm.workspace.yaml.

Revert Cataloged Dependencies

pncat revert

Reverts cataloged dependencies to package.json. Maybe useful for when shared dependencies during monorepo restructuring or migration.

Configuration

Create a pncat.config.ts file to customize behavior.

The configuration below shows the default values — you can override only what you need:

import { defineConfig, mergeCatalogRules } from 'pncat'

export default defineConfig({
  // custom catalog groups (extends defaults)
  catalogRules: mergeCatalogRules([
    {
      name: 'inlined',
      match: ['@antfu/utils'], // string or RegExp
      priority: 0 // smaller numbers represent higher priority
    },
  ]),
  // default execution mode
  mode: 'detect',
  // force cataloging according to rules, ignoring original configurations
  force: false,
  // skip prompt confirmation
  yes: false,
  // allowed protocols in specifier to not be converted to catalog
  allowedProtocols: ['workspace', 'link', 'file'],
  // ignore paths for looking for package.json in monorepo
  ignorePaths: [
    '**/node_modules/**',
    '**/dist/**',
    '**/public/**',
    '**/fixture/**',
    '**/fixtures/**',
  ],
  // ignore package.json that in other workspaces (with their own .git,pnpm-workspace.yaml,etc.)
  ignoreOtherWorkspaces: true,
  // disable catalog for "overrides" package.json field
  depFields: {
    packageManager: false
  },
  // control how specifier ranges are processed
  specifierOptions: {
    // whether to skip complex version ranges (e.g., "||", "-", ">=16.0.0")
    skipComplexRanges: true,
    // list of specific range types to skip (overrides skipComplexRanges)
    skipRangeTypes: [],
    // whether to allow pre-release versions (e.g., "4.0.0-beta")
    allowPreReleases: true,
    // whether to allow wildcard versions (e.g., "3.x", "*")
    allowWildcards: false
  }
})

Why pncat?

For monorepo repositories, it is crucial to maintain consistent dependency versions across multiple packages. Grouping dependencies can significantly improve project understanding, making it easier to collaborate within teams or keep track of the project’s structure.

Currently, pnpm's catalog support is limited. For example, there is no built-in feature for adding or migrating dependencies into specific groups. Managing the catalog manually across the entire project can be time-consuming and error-prone. To address this, we developed pncat.

Additionally, when migrating a specific package in a monorepo that uses catalogs, it's important to also migrate the pnpm.workspace.yaml file. This requires manually comparing which catalogs need to be removed. To streamline this process, we introduced the clean and revert commands to automate this task.

Special thanks to @antfu — his article Categorizing Dependencies provided great inspiration and guidance during the development of this tool.

Roadmap

Core Features

• [x] Detect catalogable dependencies
• [x] Migrate to catalogs
• [x] Install dependency with catalog support
• [x] Safely remove dependency
• [x] Cleanup unused catalog dependencies
• [x] Revert cataloged dependencies version to package.json

Advanced

• [x] Config file support
• [x] Custom grouping rules

License

MIT License © jinghaihan