@git.zone/tspublish

publish multiple, concise and small packages from monorepos

Install

To install @git.zone/tspublish, you can use npm. To use the latest stable version, run:

npm install @git.zone/tspublish

Alternatively, if you are using yarn, the equivalent command would be:

yarn add @git.zone/tspublish

These commands will add @git.zone/tspublish as a dependency in your package.json file and install the package into your node_modules directory.

Usage

@git.zone/tspublish is designed to manage the publishing of multiple, small-scale packages within monorepos. The following sections will guide you through its usage, from setting up your environment to effectively publishing packages.

Getting Started with TypeScript and Module Setup

@git.zone/tspublish works with monorepos that are organized using TypeScript. The package structure should follow a convention where each submodule intended for publishing is located in a directory prefixed with ts, for example, tsModuleName. Each submodule directory should contain a tspublish.json file to correctly configure the package to be published separately. This file is critical for the tspublish process to identify valid package directories and should also include necessary metadata for the package.

Your monorepo structure might resemble:

my-monorepo/
├── ts-package1/
│   ├── src/
│   ├── tspublish.json
├── ts-package2/
│   ├── src/
│   ├── tspublish.json

Configuring tspublish.json

Each submodule must include a tspublish.json within its directory. This JSON file should include essential details for your publishable package, including its dependencies. Here's a basic example of what tspublish.json could look like:

{
  "name": "@myorg/ts-package1",
  "dependencies": {
    "some-dependency": "^1.0.0"
  }
}

Running the CLI

@git.zone/tspublish includes a CLI that simplifies the publishing process. Begin by importing the CLI runner in a script within your project:

import { runCli } from '@git.zone/tspublish';

runCli();

This function call orchestrates the publishing operation. It reads each directory prefixed with ts, looks for a tspublish.json, and creates an individual package based on the gathered data.

Core Features

Publishing Modules

The core functionality provided by @git.zone/tspublish involves processing directories to check for valid submodules that are ready to be published. This occurs via the publish method in TsPublish class. This method does the following:

• Reads all directories within the specified monorepo path.
• Identifies directories that start with ts and validates the presence of tspublish.json.
• Logs information about found packages for user awareness and debugging.
• Checks for collisions with existing versions on the npm registry to prevent overriding published versions.

import { TsPublish } from '@git.zone/tspublish';

const tspublish = new TsPublish();
await tspublish.publish('/path/to/your/monorepo');

Package Initialization

Once valid submodules are identified, the init method in the PublishModule class initializes the publish module. This includes:

• Parsing tspublish.json for metadata.
• Constructing full paths for necessary operations.
• Verifying package existence to avoid duplication.

import { PublishModule } from '@git.zone/tspublish';

const publishModule = new PublishModule({
  monoRepoDir: '/path/to/monorepo',
  packageSubFolder: 'ts-package1',
});

await publishModule.init();

Creating package.json

Part of the publishing process involves automatically creating a package.json tailored to each submodule. This dynamically generated JSON will incorporate dependencies from tspublish.json and associate them with the latest version of tsbuild from the registry:

await publishModule.createPackageJson();

This creates a structured package.json which includes scripts to build your TypeScript files before publishing.

Constructing Publish-ready Directory

After all configurations are verified and the package.json is created, the submodule is ready to be published. This step involves setting up a dist_publish_ directory specific to each module:

await publishModule.createPublishModuleDir();

The above method ensures that each module's source files are copied and prepared under a dedicated directory meant for packaging and distribution.

Logging and Debugging

The package includes a structured logging mechanism using smartlog which provides insights into the publishing process, helping in runtime debugging and status tracking of operations:

import { logger } from '@git.zone/tspublish/logging';

logger.log('info', 'Publishing process initialized');

This powerful logging helps in tracking the status of each step and understanding potential issues during the operations.

Testing with tapbundle

To ensure that your publishing workflow is functioning correctly, you can utilize the test suite set up with tapbundle. This library facilitates behavior-driven testing for your monorepo. Below is a basic test setup to verify the import and initial function accessibility of @git.zone/tspublish:

import { expect, tap } from '@push.rocks/tapbundle';
import * as tspublish from '@git.zone/tspublish';

tap.test('Should run the CLI without errors', async () => {
  await tspublish.runCli();
  expect(tspublish).toBeTruthy();
});

tap.start();

Comprehensive usage example

Let's combine all the steps into a complete example where you prepare a monorepo, configure each module, and execute the publishing workflow.

Suppose you have a project structure as follows:

my-monorepo/
├── ts-package1/
│   ├── src/
│   ├── tspublish.json
├── ts-package2/
│   ├── src/
│   ├── tspublish.json

Follow these steps:

1. Ensure each package has tspublish.json properly configured with necessary metadata.
2. Create a CLI script such as publish.js:

import { runCli } from '@git.zone/tspublish';

runCli()
  .then(() => {
    console.log('Publishing completed successfully');
  })
  .catch((error) => {
    console.error('Error during publishing:', error);
  });

3. Execute your CLI script:

node publish.js

Your script will call runCli, which will traverse each ts-package, verify their publish readiness, and handle individual publishing processes.

By following these comprehensive guidelines and utilizing the structured approach provided by @git.zone/tspublish, you can efficiently manage and publish multiple sub-packages from within a monorepo, facilitating organized, modular package management in projects of any scale. undefined