@git.zone/tspublish

publish multiple, concise and small packages from monorepos

readme.md for @git.zone/tspublish

Effortlessly publish multiple TypeScript packages from your monorepo

npm version License: MIT

๐ŸŒŸ What is tspublish?

@git.zone/tspublish is a powerful CLI tool and library for managing and publishing multiple TypeScript packages from a monorepo. It automates the tedious parts of package publishing โ€” discovery, dependency resolution, building, version validation, and multi-registry publishing โ€” while giving you full control over the process. Whether you're maintaining a suite of microservices, a component library, or any collection of related packages, tspublish makes your life dramatically easier.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

โœจ Key Features

๐Ÿ“ฅ Installation

# Using pnpm (recommended)
pnpm add -D @git.zone/tspublish

# Global installation for CLI usage
pnpm add -g @git.zone/tspublish

๐Ÿš€ Quick Start

1๏ธโƒฃ Structure Your Monorepo

Organize your packages using directories that start with ts:

my-awesome-monorepo/
โ”œโ”€โ”€ package.json            # Main monorepo package.json (version is inherited)
โ”œโ”€โ”€ tsconfig.json           # Shared TypeScript config
โ”œโ”€โ”€ .smartconfig.json       # Optional: base registry configuration
โ”œโ”€โ”€ ts_core/                # Core package
โ”‚   โ”œโ”€โ”€ index.ts            # Entry point
โ”‚   โ”œโ”€โ”€ readme.md           # Package-specific documentation
โ”‚   โ””โ”€โ”€ tspublish.json      # Publishing configuration
โ”œโ”€โ”€ ts_utils/               # Utilities package
โ”‚   โ”œโ”€โ”€ index.ts
โ”‚   โ”œโ”€โ”€ readme.md
โ”‚   โ””โ”€โ”€ tspublish.json
โ””โ”€โ”€ ts_cli/                 # CLI package
    โ”œโ”€โ”€ index.ts
    โ”œโ”€โ”€ readme.md
    โ””โ”€โ”€ tspublish.json

2๏ธโƒฃ Configure Each Package

Create a tspublish.json in each publishable directory:

{
  "name": "@myorg/core",
  "order": 1,
  "dependencies": [
    "@push.rocks/smartpromise",
    "@push.rocks/smartfile"
  ],
  "registries": [
    "registry.npmjs.org:public"
  ],
  "bin": []
}

Configuration Options

Field Type Description
name string The published package name (e.g., @myorg/core)
order number Build order for interdependent packages (lower builds first)
dependencies string[] Dependencies to include โ€” versions are resolved from the monorepo's package.json
registries string[] Target registries with access level (format: "url:accessLevel")
bin string[] CLI executable names (generates a cli.js wrapper automatically)

3๏ธโƒฃ Publish

# From your monorepo root
npx tspublish

That's it! tspublish will discover all ts* directories containing tspublish.json, build them in order, validate versions against the registry, and publish.

๐ŸŽฏ Advanced Usage

Registry Configuration

TSPublish offers three approaches for configuring target registries:

1. Explicit Registries

Define specific registries directly in tspublish.json:

{
  "registries": [
    "registry.npmjs.org:public",
    "npm.pkg.github.com:private"
  ]
}

The format is "registryUrl:accessLevel" where accessLevel is public or private.

2. Use Base Configuration (useBase)

Inherit registries from your project's .smartconfig.json (managed by @git.zone/cli):

{
  "registries": ["useBase"]
}

This reads from .smartconfig.json at the key @git.zone/cli.release.registries.

3. Extend Base Configuration (extendBase)

Start with base registries and add or remove specific ones:

{
  "registries": [
    "extendBase",
    "custom-registry.example.com:public",
    "-https://registry.npmjs.org"
  ]
}

The - prefix excludes a registry from the base configuration. All other entries (besides extendBase) are added.

Empty Registries

If registries is an empty array [], the package will be built but not published โ€” useful for internal-only packages that other packages depend on.

Build Order Management

When packages depend on each other, use the order field to control build sequence:

// ts_core/tspublish.json โ€” builds first
{
  "name": "@myorg/core",
  "order": 1,
  "dependencies": [],
  "registries": ["useBase"],
  "bin": []
}

// ts_utils/tspublish.json โ€” builds second, depends on core
{
  "name": "@myorg/utils",
  "order": 2,
  "dependencies": ["@myorg/core"],
  "registries": ["useBase"],
  "bin": []
}

CLI Binary Packages

For packages that ship CLI tools, specify the binary names in the bin array:

{
  "name": "@myorg/cli",
  "order": 3,
  "dependencies": ["commander", "@myorg/core"],
  "registries": ["registry.npmjs.org:public"],
  "bin": ["my-cli", "my-tool"]
}

TSPublish will:

  1. Fetch the standard cli.js template from the @git.zone/cli assets repository
  2. Adjust the import path to point to the correct dist_* folder
  3. Configure the bin field in the generated package.json

Programmatic Usage

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

const publisher = new TsPublish();
await publisher.publish(process.cwd());

Custom Publishing Pipeline

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

const publisher = new TsPublish();
const modules = await publisher.getModuleSubDirs('./my-monorepo');

for (const [name, config] of Object.entries(modules)) {
  const mod = new PublishModule(publisher, {
    monoRepoDir: './my-monorepo',
    packageSubFolder: name,
  });

  await mod.init();                   // Resolve deps, validate version
  await mod.createPublishModuleDir(); // Scaffold dist_publish_* directory
  await mod.build();                  // Compile TypeScript
  await mod.publish();                // Publish to registries
}

๐Ÿ”ง How It Works

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                   tspublish pipeline                     โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                          โ”‚
โ”‚  1. ๐Ÿ” Discovery                                        โ”‚
โ”‚     Scan for ts* directories containing tspublish.json   โ”‚
โ”‚                                                          โ”‚
โ”‚  2. ๐Ÿ“‹ Preparation                                      โ”‚
โ”‚     Create dist_publish_* with generated package.json,   โ”‚
โ”‚     tsconfig.json, source files, readme, and license     โ”‚
โ”‚                                                          โ”‚
โ”‚  3. ๐Ÿ”จ Build                                            โ”‚
โ”‚     Run `tsbuild tsfolders` in the publish directory     โ”‚
โ”‚                                                          โ”‚
โ”‚  4. โœ… Validation                                       โ”‚
โ”‚     Check npm registry โ€” abort if version already exists โ”‚
โ”‚                                                          โ”‚
โ”‚  5. ๐Ÿš€ Publish                                          โ”‚
โ”‚     pnpm publish to each configured registry             โ”‚
โ”‚                                                          โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

For each discovered module, tspublish:

  1. Discovers all directories starting with ts that contain a tspublish.json
  2. Resolves dependencies from the monorepo's package.json, using the monorepo version for packages not found in dependencies
  3. Creates an isolated publish directory (dist_publish_<folder>) with a generated package.json, tsconfig.json, source code copy, readme, and license
  4. Builds the package using pnpm run build (which calls tsbuild tsfolders)
  5. Validates against the target registry โ€” if the name+version already exists, it exits with an error
  6. Publishes to each configured registry via pnpm publish

๐Ÿ“š API Reference

TsPublish

class TsPublish {
  /** Publish all discovered modules in a monorepo directory */
  async publish(monorepoDirPath: string): Promise<void>;

  /** Discover and return all publishable modules with their tspublish.json configs */
  async getModuleSubDirs(dirPath: string): Promise<Record<string, ITsPublishJson>>;
}

PublishModule

class PublishModule {
  /** Initialize: resolve dependencies, validate version against registry */
  async init(): Promise<void>;

  /** Create the dist_publish_* directory with all necessary files */
  async createPublishModuleDir(): Promise<void>;

  /** Build the TypeScript package */
  async build(): Promise<void>;

  /** Publish to all configured registries */
  async publish(): Promise<void>;
}

ITsPublishJson

interface ITsPublishJson {
  name: string;           // Published package name
  order: number;          // Build sequence (lower = earlier)
  dependencies: string[]; // Dependencies to include from monorepo
  registries: string[];   // Target registries ("url:accessLevel", "useBase", or "extendBase")
  bin: string[];          // CLI binary names
}

GiteaAssets

class GiteaAssets {
  constructor(options: { giteaBaseUrl: string; token?: string });

  /** Fetch files from a Gitea repository directory */
  async getFiles(owner: string, repo: string, directory: string, branch?: string): Promise<IRepoFile[]>;

  /** Get the standard cli.js entry file template */
  async getBinCliEntryFile(): Promise<IRepoFile>;
}

๐Ÿ› Troubleshooting

Problem Solution
"Package X already exists with version Y" Bump the version in your monorepo's package.json
No publish modules found Ensure directories start with ts and contain a valid tspublish.json
Build failures Check TypeScript errors โ€” tspublish runs tsbuild tsfolders in the generated directory
useBase/extendBase error Ensure .smartconfig.json has registries at @git.zone/cli.release.registries
Missing dependency versions Add the dependency to your monorepo's package.json dependencies field

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @git.zone/tspublish

2026-03-24 - 1.11.4 - fix(config)

rename npmextra configuration to .smartconfig.json and align publish packaging with updated config handling

2026-03-24 - 1.11.3 - fix(config)

replace npmextra with smartconfig for base registry resolution

2026-03-05 - 1.11.2 - fix(deps)

bump @push.rocks/smartshell dependency to ^3.3.7 and update package version to 1.11.1

2026-03-05 - 1.11.1 - fix(deps)

bump @push.rocks/smartshell dependency to ^3.3.7

2025-12-16 - 1.11.0 - feat(publish)

add registry resolution (useBase/extendBase) and migrate filesystem operations to async SmartFs; improve publish flow and docs

2025-12-15 - 1.10.4 - fix(.serena)

cleanup: remove .serena assistant memories, cache and project config

2025-08-18 - 1.10.3 - fix(devDependencies)

Bump development dependencies and add local Claude settings

2025-08-18 - 1.10.2 - fix(dependencies)

Update dependency versions and add local Claude settings

2025-08-08 - 1.10.1 - fix(core)

Refactor smartrequest usage, update dependency versions, and improve documentation and tests

2025-08-08 - 1.10.0 - feat(logging)

Enhance logging and module publishing with color-coded output, progress tracking, and improved CLI startup

2025-01-02 - 1.9.1 - fix(publishmodule)

Fix incorrect CLI script path during publish module creation

2025-01-02 - 1.9.0 - feat(core)

Refactor gitea asset handling and module initialization

2025-01-01 - 1.8.0 - feat(core)

Added GiteaAssets class for managing files in Gitea repositories

2024-11-05 - 1.7.7 - fix(core)

Fix dependency resolution in package initialization

2024-11-05 - 1.7.6 - fix(tspublish)

Fix the logging of the number of found publish modules

2024-11-05 - 1.7.5 - fix(core)

Fix issue with tspublish.json name validation in TsPublish class

2024-11-05 - 1.7.4 - fix(classes.tspublish)

Refactor getModuleSubDirs method to streamline name validation for publish modules

2024-11-05 - 1.7.3 - fix(TsPublish)

Add validation for tspublish.json name field

2024-11-05 - 1.7.2 - fix(project)

Fixed minor formatting issues and improved code consistency.

2024-11-05 - 1.7.1 - fix(core)

Implement error handling for missing publish module directories

2024-11-05 - 1.7.0 - feat(core)

Enhanced tspublish with ordered compilation and updated dependencies

2024-10-28 - 1.6.0 - feat(classes.publishmodule)

Added copying of readme and license files to publish directory

2024-10-28 - 1.5.5 - fix(core)

Handled non-existent package in publish module to avoid errors

2024-10-28 - 1.5.4 - fix(core)

Fix issues with path keys in tsconfig and logger setup in logging.ts.

2024-10-28 - 1.5.3 - fix(core)

Fix incorrect logging and directory preparation

2024-10-28 - 1.5.2 - fix(core)

Add logging for found publish modules

2024-10-28 - 1.5.1 - fix(core)

Fixes handling of undefined paths in tsconfig generation.

2024-10-28 - 1.5.0 - feat(classes.publishmodule)

Add method to create and write tsconfig.json during publish module setup

2024-10-26 - 1.4.0 - feat(core)

Refactor directory reading and module discovery for publishing process

2024-10-23 - 1.3.3 - fix(core)

Fix logging mechanism on existing package version check

2024-10-23 - 1.3.2 - fix(core)

Corrected file patterns in dynamically created package.json files.

2024-10-23 - 1.3.1 - fix(classes.publishmodule)

Fix template string in createPackageJson method for export path

2024-10-21 - 1.3.0 - feat(core)

Add support for multiple registries in the publish process

2024-10-21 - 1.2.4 - fix(publishmodule)

Fix syntax errors and improve formatting in classes.publishmodule.ts

2024-10-21 - 1.2.3 - fix(logs)

Improve logging mechanism with structured logs for publish process

2024-10-21 - 1.2.3 - fix(classes.publishmodule)

Add missing 'type: module' to dynamically generated package.json

2024-10-21 - 1.2.3 - fix(classes.publishmodule)

Add missing 'type: module' to dynamically generated package.json

2024-10-21 - 1.2.2 - fix(publishmodule)

Fix bug in package.json creation for publish module

2024-10-21 - 1.2.1 - fix(package.json)

Ensure bin field is properly restructured

2024-10-21 - 1.2.0 - feat(core)

Enhance package publication workflow with dependency handling and CLI improvements.

2024-10-21 - 1.1.0 - feat(core)

Add runCli function to execute TsPublish process

2024-10-21 - 1.0.1 - Initial Release

Initial release of the project.