@zaeper/pkgm v1.1.13

Installation

To install PKGM globally, run:

npm install -g @zaeper/pkgm

Getting Started

⚠️ Important: Run PKGM from the root directory of your multi-project setup.

PKGM can run in any multi-project setup. So you can nest your projects and libraries just the way you like.

:root dir * <--- Run PKGM from here
│
└───libs
│   │
│   └───Library1
│   └───Library2
│       ...
└───Project1
└───Project2

Setup

Interactive Setup

Run pkgm in an uninitialized directory to launch the initialization mode:

pkgm

Follow the on-screen instructions. PKGM will scan all subdirectories from its execution directory to identify npm projects. If the scanning process takes too long, create a pkgm.ignore file to exclude specific directories from the scan.

Example pkgm.ignore file:

**/.idea/**
**/.git/**
**/logs/**
**/build/**

Manual Setup

Alternatively, configure PKGM manually with a pkgm.json file in your project directory.

Example pkgm.json file:

{
  "npmClient": "** npm | pnpm | yarn | bun **",
  "projects": [
    "** Paths to your npm projects **"
  ],
  "workspaces": [
    "** Optional **",
    "** Paths to your npm workspaces **"
  ],
  "excludeSymlinks": [
    "** Optional **",
    "** NPM Projects to be excluded from linking **"
  ],
  "versions": {
    "** optional **": "*",
    "NPM Package Name": "Version"
  }
}

Usage

Modes

Interactive Mode

Simply run pkgm without arguments to start PKGM in interactive mode, allowing you to manage projects through a guided interface.

Command

pkgm

Command-Line Mode

Run specific commands directly to perform tasks.

Example:

pkgm listScripts --scope-path=libs/

Available Commands

Global Parameters

You can use all global parameters alongside the commands listed above.

Linking Projects

To link your projects together, add the target project to your package.json.

Let’s assume that Project1 needs access to Library1. Here's how you can set it up:

package.json for Project1:

{
  "name": "project1",
  "version": "1.0.1",
  "main": "index.js",
  "dependencies": {
    "library1": "0.0.1"
  }
}

Once you've added Library1 as a dependency in Project1, run the pkgm link command from your root directory, either in command-line or interactive mode.

Example in command-line mode:

pkgm link --scope-package-name=project1

After running the command, your package.json for Project1 should look like this:

{
  "name": "project1",
  "version": "1.0.1",
  "main": "index.js",
  "dependencies": {
    "library1": "file://./path/to/library1"
  }
}

To ensure the symlink works with buildWatch, make sure to disable the preserveSymlink option in your tsconfig file.

Building Projects

To properly build your projects, ensure that each project you want to build includes both a build and build:watch script in its package.json.

Example package.json for an Angular library:

{
  "name": "library1",
  "version": "0.0.1",
  "main": "index.js",
  "scripts": {
    "build": "ng build",
    "build:watch": "ng build --watch"
  }
}

Once the build scripts are configured, you can run the pkgm build or pkgm build:watch command:

pkgm build --scope-package-name=library1

or

pkgm buildWatch --scope-package-name=library1

Watching Multiple Projects

Since build watchers run asynchronously, there’s a chance that one project might still be building while another project that depends on it starts its build process. This can lead to errors if the dependent project attempts to build before the previous one has finished.

Since PKGM cannot automatically detect when a build process has completed, you’ll need to manually wait for the previous build to finish before initiating the next one.

Roadmap

• Adding the ability to create libraries and projects directly from PKGM.
• Multilevel dependency scanning for better dependency management.
• Setting up comprehensive documentation on zaeper.io
• Supporting version overrides in Version Manager
• Implementing and creating an external API Server for caching and faster dependency evaluation in Version Manager

About Zaeper

Zaeper is an innovative, unfunded digital signage startup based in Switzerland. Our vision is to create a public SaaS digital signage platform that empowers users worldwide. To support this mission, we have and will continue to open-source our development tools we use daily, fostering collaboration and transparency within the community.

If you like this project, please consider to support us on Github Sponsors. This will help us to further maintain and develop our products.

🚀 Learn more about Zaeper at https://zaeper.com.

Thank you for considering a sponsorship! ❤️