Website · Documentation

monoswan

pleasant monorepos

monoswan keeps package configuration consistent across a monorepo. Define shared package shapes once, check them with rules, and use the same definitions to create new packages. It discovers packages from pnpm, npm, Yarn, and Bun workspace declarations.

• Centrally managed configuration: Share package.json, TypeScript, JSON, and text configuration through composable variants.
• Rules and consistency: Check packages with built-in or custom rules, with autofix support.
• Package templates: Create packages from variant defaults and initialization content.

Quick start prompt

Copy this prompt into your coding agent:

monoswan is a monorepo management tool to help keep your package.json, tsconfig.json, and other standard files consistent across packages in a monorepo. Set up monoswan in this monorepo, you can view the full documentation at monoswan.com/llms.txt. Inspect the workspace first so you can preserve its package manager, structure, and existing conventions. Install monoswan as a development dependency at the workspace root, run its init command, then review the workspace packages and define practical variants in monoswan.config.ts for their shared package.json, TypeScript, JSON, and text-file configuration. Assign the appropriate variant or variants to each package, run the monoswan linter, fix any issues it reports without changing unrelated behavior, and summarize the configuration and files you changed.

Requirements

• Node.js 22.13 or newer
• A pnpm-workspace.yaml or a workspaces declaration in the root package.json

Install

Install monoswan at the workspace root.

# pnpm
pnpm add -D -w monoswan

# npm
npm install -D monoswan

# yarn
yarn add -D -W monoswan

# bun
bun add -D monoswan

Initialize a configuration:

pnpm exec monoswan init

Use npx monoswan, yarn monoswan, or bunx monoswan in the commands below when using a different package manager.

Workspace discovery supports pnpm workspace files, npm and Bun workspace arrays, and both Yarn workspace forms, including modern Yarn Plug'n'Play installations. monoswan reads workspace declarations directly and does not invoke the package manager during discovery.

Then describe a shared package shape in monoswan.config.ts:

import { defineConfig, enforceVariants, sortPackageJson } from "monoswan";

export default defineConfig({
  variants: {
    "my-library": {
      packageJson: { type: "module" },
      tsConfig: { compilerOptions: { strict: true } },
    },
  },
  rules: [enforceVariants(), sortPackageJson()],
});

Assign the variant to a workspace package:

{
  "name": "@myrepo/example",
  "monoswan": {
    "variants": ["my-library"]
  }
}

Check the workspace:

pnpm exec monoswan lint .

Commands

Run pnpm exec monoswan <command> --help for complete command syntax.

Documentation and support

Full documentation is available at monoswan.com/docs. Report bugs and request features through the project's GitHub issues.

Development

This repository uses pnpm and pins the contributor runtime in package.json.

pnpm install
pnpm lint
pnpm check
pnpm test
pnpm build

License

MIT