Usage

To use MonoPKG, you need to have a project with workspaces field in the root level package.json file. The workspaces field should contain an array of paths to the packages in the monorepo.

What is Workspace?

A workspace is a directory containing one or more packages. A package can be an app, library, or any other type of code that have its own package.json.

package.json

{
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

You can also convert an existing project into workspace.

Learn More

Check this section for more information about workspaces.

To run a command, use the following syntax:

Global

monopkg [command] [options]

Bun

bun x monopkg [command] [options]

NPM

npx monopkg [command] [options]

Yarn

yarn dlx monopkg [command] [options]

NOTE

Replace [command] with the command you want to run and [options] with the options you want to use. For example:

monopkg list -i name version

Tips

If you prefer, you can use the short alias mpkg instead of monopkg if MonoPKG is installed globally. For example:

mpkg list -i name version

Getting Help

To see the available commands and options, you can run the following command:

Global

monopkg --help

Bun

bun x monopkg --help

NPM

npx monopkg --help

Yarn

yarn dlx monopkg --help

To see the options for a specific command, you can run:

Global

monopkg [command] --help

Bun

bun x monopkg [command] --help

NPM

npx monopkg [command] --help

Yarn

yarn dlx monopkg [command] --help

Interactive

Interactive mode will guide you through the available commands and options, allowing you to select the desired action without typing the command manually, and prevent you from making mistakes.

For example, to create a new package, you'll be prompted to select the available workspace to create the package in, select the available template, and enter the package name, etc.

To run MonoPKG in interactive mode, simply run the command without any arguments. The interactive mode will start and guide you through the available commands and options.

Example

Interactive

Interactive

monopkg add eslint typescript prettier

The command above will prompt you to select all the required options.

NOTES

To skip the interactive prompts, you can use -y or --yes option. It will use the default options.

Filtering

Most of the commands support filtering options. Filtering allows you to include or exclude specific packages from the command.

Options

• -f, --filter <packages...> - Include specific packages.
• -e, --exclude <packages...> - Exclude specific packages.
• -w, --workspace <workspaces...> - Filter by workspaces of the packages.

TIPS

• You can use the package name as the filter. E.g., -f @scope/pkg-a.
• You can use the package's base name as the filter. E.g., -f pkg-a.
• You can use the package's base name pattern as the filter. E.g., -f pkg-*.
• You can use the package's path as the filter. E.g., -f apps/pkg-a.
• You can use the package's path pattern as the filter. E.g., -f apps/*.

Filter

To include specific packages, you can use the --filter option. It will only include the packages that match the filter. Example:

Global

monopkg run dev --filter package-1 package-2

Bun

bun x monopkg run dev --filter package-1 package-2

NPM

npx monopkg run dev --filter package-1 package-2

Yarn

yarn dlx monopkg run dev --filter package-1 package-2

TIPS

To include all packages, you can use the --filter * option. It will skip the interactive prompts and include all packages.

Workspace Filter

To filter by workspaces of the packages, you can use the --workspace option. It will limit the packages in interactive mode to the specified workspaces. Example:

Global

monopkg run dev --workspace apps

Bun

bun x monopkg run dev --workspace apps

NPM

npx monopkg run dev --workspace apps

Yarn

yarn dlx monopkg run dev --workspace apps

Dry Run

To run the command in dry mode, you can use the --dry option. It will show you the commands that will be executed without actually running them. No changes will be made to the project. Example:

Global

monopkg add eslint typescript prettier --dry

Bun

bun x monopkg add eslint typescript prettier --dry

NPM

npx monopkg add eslint typescript prettier --dry

Yarn

yarn dlx monopkg add eslint typescript prettier --dry

The command above will show you the commands that will be executed without actually running them.

Defaults

To skip the prompts and use the default options, you can use the --yes option. It will use the default options without asking for confirmation. Example:

Global

monopkg add eslint typescript prettier --yes

Bun

bun x monopkg add eslint typescript prettier --yes

NPM

npx monopkg add eslint typescript prettier --yes

Yarn

yarn dlx monopkg add eslint typescript prettier --yes

The command above will use the default options without asking for confirmation.