Copy page

SDK Library

Build, Tooling & CI/CD

Build, Tooling & CI/CD

Relevant source files

The following files were used as context for generating this wiki page:

• .github/workflows/ci.yml
• package.json
• tsconfig.json

This page provides a high-level overview of the @primebrick/sdk build pipeline, the tooling ecosystem, and the automated release workflow. The SDK is built using TypeScript with a focus on modern ECMAScript standards and secure, automated publishing via GitHub Actions.

Build Pipeline Overview

The SDK utilizes pnpm as its package manager and the TypeScript compiler (tsc) for its build process package.json:24-25, 46. The pipeline transforms source files from src/ into a distributable dist/ directory containing JavaScript modules, type definitions, and source maps tsconfig.json:7-8, 14-16.

Source to Distribution Mapping

The following diagram illustrates the relationship between the source code entities and the generated build artifacts.

Build Artifact Mapping

Code
graph TD
    subgraph "Source Space (src/)"
        A["index.ts"]
        B["Module Logic (e.g., config/, nats/)"]
        C["Tests (*.test.ts)"]
    end

    subgraph "Tooling"
        TSC["tsc (TypeScript Compiler)"]
        PNPM["pnpm build"]
    end

    subgraph "Distribution Space (dist/)"
        D["index.js (ESM)"]
        E["index.d.ts (Types)"]
        F["index.d.ts.map (Declaration Maps)"]
    end

    A --> TSC
    B --> TSC
    PNPM --> TSC
    TSC --> D
    TSC --> E
    TSC --> F
    C -. "Excluded via tsconfig" .-> TSC

Sources: package.json:17-24, tsconfig.json:7-8, 14-16, 19

For detailed information on compiler flags, target environments, and why certain strict checks are modified for Dependency Injection patterns, see TypeScript Build Configuration.

Tooling & Dependency Management

The project is configured as a modern Node.js ESM (ECMAScript Module) package package.json:5. It leverages pnpm for efficient, deterministic dependency resolution via pnpm-lock.yaml.

Key Tooling Components

• Runtime Target: ES2022 with NodeNext module resolution tsconfig.json:3-5.
• Package Manager: pnpm (v9.15.9) package.json:46.
• Testing: vitest for unit and integration testing package.json:26-27, 44.
• Peer Dependencies: nats is treated as an optional peer dependency, allowing consumers to use the SDK without forcing a NATS installation if messaging is not required package.json:34-39.

Sources: package.json:5, 34-46, tsconfig.json:3-5

CI/CD & Automated Release

The SDK employs a fully automated release workflow triggered by version tags. This process ensures that every published version has passed type-checking and build gates.

Release Workflow Logic

The release process is governed by GitHub Actions and utilizes OIDC (OpenID Connect) Trusted Publishing. This eliminates the need for long-lived NPM_TOKEN secrets by allowing GitHub to authenticate directly with npmjs.com ci.yml:9-14.

CI/CD Pipeline Flow

Code
graph LR
    subgraph "GitHub Repository"
        TAG["git tag v*.*.*"]
        WORKFLOW[".github/workflows/ci.yml"]
    end

    subgraph "Release Job"
        INSTALL["pnpm install --frozen-lockfile"]
        BUILD["pnpm run build"]
        CHECK["npx tsc --noEmit"]
        PUBLISH["npm publish --provenance"]
    end

    subgraph "External Registries"
        NPM["npmjs.com"]
    end

    TAG --> WORKFLOW
    WORKFLOW --> INSTALL
    INSTALL --> BUILD
    BUILD --> CHECK
    CHECK --> PUBLISH
    PUBLISH --> NPM

Sources: .github/workflows/ci.yml:1-47

Security & Provenance

The workflow uses npm publish --provenance to provide supply-chain attestation, linking the published package directly to the source code and the specific GitHub Action run that generated it ci.yml:47.

For a deep dive into the OIDC configuration, the least-privilege permissions model, and the specific steps in the release job, see CI/CD & NPM Publishing.

---