@uipath/solutionpackager-tool-core

UiPath Solution Packager Tool Core

Core contracts and interfaces for building UiPath Solution Packager tools. This package provides the type definitions and base classes for creating tools that restore, validate, build, and pack UiPath projects and solutions.

Installation

From GitHub Packages

Prerequisites

Create a GitHub Personal Access Token with read:packages permission:

• Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
• Generate new token with read:packages scope
• Set as environment variable:

Windows (PowerShell):

$env:GH_NPM_REGISTRY_TOKEN = "your-token-here"

Linux/macOS:

export GH_NPM_REGISTRY_TOKEN="your-token-here"

Install

Create .npmrc in your project root:

@uipath:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GH_NPM_REGISTRY_TOKEN}

Then install:

npm install @uipath/solutionpackager-tool-core

Quick Start

1. Implement a Project Tool

Extend ProjectTool and override the operations you need:

import {
  ProjectTool,
  type IProjectBuildOptions,
  type IProjectRestoreOptions,
  ToolResult,
  type IToolLogger,
  type IFileSystem,
  Path,
} from "@uipath/solutionpackager-tool-core";

export class ApiWorkflowsTool extends ProjectTool {
  constructor(fileSystem: IFileSystem, logger: IToolLogger) {
    super(fileSystem, logger);
  }

  override async restoreAsync(
    options: IProjectRestoreOptions,
    cancellationToken?: AbortSignal
  ): Promise<ToolResult> {
    this.logger.info("Restoring dependencies...");
    return ToolResult.success();
  }

  override async buildAsync(
    options: IProjectBuildOptions,
    cancellationToken?: AbortSignal
  ): Promise<ToolResult> {
    this.logger.info("Building project...");
    const outputFolder = Path.join(options.outputPath, "output");

    await this.fileSystem.mkdir(outputFolder);
    await this.fileSystem.writeFile(
      Path.join(outputFolder, "artifact.txt"),
      "Build Artifact"
    );

    return new ToolResult(ToolErrorCodes.Success, "Build completed", [outputFolder]);
  }

  override async dispose(): Promise<void> {
    // Cleanup resources
  }
}

2. Create a Tool Factory

Implement IProjectToolFactory:

import {
  type IProjectToolFactory,
  type ProjectTool,
  ProjectTypes,
  type ProjectType,
  type IToolLogger,
  type IFileSystem,
} from "@uipath/solutionpackager-tool-core";

export class ApiWorkflowToolFactory implements IProjectToolFactory {
  readonly supportedTypes: readonly ProjectType[] = [ProjectTypes.Api];

  constructor(private readonly fileSystem: IFileSystem) {}

  async createAsync(logger: IToolLogger): Promise<ProjectTool> {
    return new ApiWorkflowsTool(this.fileSystem, logger);
  }
}

3. Register Your Tool

Register with the SolutionPackager instance:

import type { IToolsFactoryRepositoryConfigurator } from "@uipath/solutionpackager-tool-core";

export function registerProjectToolFactory(
  configurator: IToolsFactoryRepositoryConfigurator,
  fileSystem: IFileSystem
): void {
  configurator.registerProjectToolFactory(
    new ApiWorkflowToolFactory(fileSystem)
  );
}

// Usage:
// const solutionPackager = await createBrowserSolutionPackager();
// registerApiWorkflowTool(solutionPackager, solutionPackager.fileSystem);

Core Concepts

Tool Base Classes

ProjectTool - Override operations your tool supports:

• restoreAsync() - Restore dependencies
• validateAsync() - Validate project
• buildAsync() - Build/compile
• packAsync() - Package project
• dispose() - Cleanup

SolutionTool - Similar to ProjectTool but operates at solution level.

Logging

Access logger via this.logger:

this.logger.info("Starting build");
this.logger.progress("Building", 50);
this.logger.warn("Deprecated API");
this.logger.error("Build failed", { code: "BUILD_001" });

File System

Access via this.fileSystem with consistent API across Node.js and Browser:

// Read file
const content = await this.fileSystem.readFile("path/to/file.json");

// Write file
await this.fileSystem.writeFile("output/config.xml", "<config></config>");

// Create directory (recursive)
await this.fileSystem.mkdir("dist/assets/images");

// Check existence
if (await this.fileSystem.exists("entrypoints.json")) { }

// List directory
const files = await this.fileSystem.readdir("src/components");

// Delete (recursive for directories)
await this.fileSystem.rm("temp_build");

Tool Results

// Success
return ToolResult.success();

// Error with code and message
return ToolResult.error(ToolErrorCodes.InternalError, "Syntax error");

// With package paths
return new ToolResult(ToolErrorCodes.Success, "done", [packagePath]);

Built-in Types

Project Types

• ProjectTypes.Agent
• ProjectTypes.Api
• ProjectTypes.Connector
• ProjectTypes.Process
• ProjectTypes.Library
• ProjectTypes.WebApp
• ProjectTypes.Tests

Error Codes

• ToolErrorCodes.Success
• ToolErrorCodes.InternalError

Extend with custom codes:

type MyToolErrorCode = ToolErrorCode | "COMPILATION_FAILED" | "VALIDATION_ERROR";

Utilities

Path Utilities

import { Path } from "@uipath/solutionpackager-tool-core";
const fullPath = Path.join(basePath, "subfolder", "file.json");

NuGet Constants

import { NugetConstants } from "@uipath/solutionpackager-tool-core";

NugetConstants.OutputFolderName;           // "bundle"
NugetConstants.ContentFolderName;          // "content"
NugetConstants.OperateFileName;            // "operate.json"
NugetConstants.EntryPointsFileName;        // "entrypoints.json"
NugetConstants.PackageDescriptorFileName;  // "package-descriptor.json"

Architecture

┌─────────────────────────────────────────────────────────────┐
│              tool.core (contracts)                          │
│  IToolLogger  IFileSystem  ProjectTool  SolutionTool        │
└─────────────────────────────────────────────────────────────┘
                          ▲
          implements/uses │
┌─────────────────────────┼───────────────────────────────────┐
│              solutionpackager                               │
│  ToolLogger  FileSystem  ToolsFactory            │
└─────────────────────────────────────────────────────────────┘

• tool.core provides interfaces and base classes
• Tools implement interfaces and register factories
• SolutionPackager discovers and creates tool instances
• Tools execute operations with injected logger and file system

Development

# Build
npm run build

# Run tests
npm test

# Pack
npm pack

# Publish
npm publish

Troubleshooting

Installation Issues

404 Not Found:

• Verify package exists at https://github.com/orgs/UiPath/packages
• Check GH_NPM_REGISTRY_TOKEN environment variable is set
• Ensure token has read:packages permission

401 Unauthorized:

• Verify token hasn't expired
• Check environment variable: echo $env:GH_NPM_REGISTRY_TOKEN (Windows) or echo $GH_NPM_REGISTRY_TOKEN (Linux/macOS)

Examples

See @uipath/tool-apiworkflow for a complete reference implementation.

Package Information

• Registry: GitHub Packages (npm)
• Organization: UiPath
• Package: @uipath/solutionpackager-tool-core
• Repository: https://github.com/UiPath/Studio.Common