tspublish/readme.md

# @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:

```bash
npm install @git.zone/tspublish
```

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

```bash
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:

```json
{
  "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:

```typescript
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.

```typescript
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.

```typescript
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:

```typescript
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:

```typescript
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:

```typescript
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`:

```typescript
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:

```plaintext
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`:

```typescript
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:

```bash
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