Copy page

SDK Library

TypeScript Build Configuration

TypeScript Build Configuration

Relevant source files

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

• .gitignore
• package.json
• tsconfig.json

The @primebrick/sdk utilizes a modern TypeScript configuration designed for Node.js environments, ensuring high performance, strict type safety, and compatibility with ECMAScript Modules (ESM). The build process transforms the source files located in src/ into a distributable format in dist/, suitable for consumption by other microservices.

Compiler Settings and Target

The SDK targets ES2022 to leverage modern JavaScript features while maintaining a balance of performance and compatibility within recent Node.js LTS versions tsconfig.json:3-3.

The project is configured as a pure ESM package, indicated by "type": "module" in the manifest package.json:5-5. To support this, the compiler uses NodeNext for both module and moduleResolution tsconfig.json:4-5. This ensures that the generated code respects modern Node.js resolution algorithms, including the requirement for file extensions in imports and the correct handling of the exports map defined in the package manifest package.json:19-21.

Setting	Value	Purpose
target	ES2022	Modern JS feature support (Classes, Private fields, etc.)
module	NodeNext	ESM compatibility for Node.js
moduleResolution	NodeNext	Modern module lookup strategy
outDir	dist	Destination for compiled assets tsconfig.json:7-7
rootDir	src	Source code entry point tsconfig.json:8-8

Sources:

• tsconfig.json:1-8
• package.json:5-5
• package.json:19-21

---

Strictness and Dependency Inversion

While the project enforces strict mode tsconfig.json:9-9, it specifically disables strictPropertyInitialization tsconfig.json:10-10.

This decision is architectural. The SDK heavily utilizes a Ports and Adapters (Hexagonal) pattern where classes often have properties that are initialized via Dependency Injection (DI) or late-binding patterns rather than directly in the constructor. Disabling this check prevents the compiler from erroring when properties are intended to be populated by external adapters or setup routines after instantiation.

Sources:

• tsconfig.json:9-10

---

Build Output and Declarations

The build process is configured to generate comprehensive metadata for consuming packages:

1. Declaration Files (.d.ts): Enabled via declaration: true, these files provide the type definitions required by TypeScript consumers tsconfig.json:14-14.
2. Declaration Maps (.d.ts.map): Enabled via declarationMap: true, these allow consumers to use "Go to Definition" in their IDEs and land directly in the SDK's original TypeScript source code instead of the compiled type definitions tsconfig.json:15-15.
3. Source Maps (.js.map): Enabled via sourceMap: true, these facilitate debugging of the compiled JavaScript back to the original source tsconfig.json:16-16.

Build Pipeline Visualization

The following diagram illustrates how the tsconfig.json configuration directs the flow from source code to the final published package.

Source to Distribution Flow

Code
graph TD
    subgraph "Code Entity Space"
        SRC["src/index.ts"]
        TEST["src/**/*.test.ts"]
        DIST_JS["dist/index.js"]
        DIST_DTS["dist/index.d.ts"]
        DIST_MAP["dist/index.d.ts.map"]
    end

    subgraph "Process Space"
        TSC["'tsc' (TypeScript Compiler)"]
        PNPM["'pnpm build'"]
    end

    PNPM --> TSC
    SRC -- "included by [tsconfig.json:18]" --> TSC
    TEST -- "excluded by [tsconfig.json:19]" --> TSC
    
    TSC -- "target: ES2022" --> DIST_JS
    TSC -- "declaration: true" --> DIST_DTS
    TSC -- "declarationMap: true" --> DIST_MAP

Sources:

• tsconfig.json:14-19
• package.json:24-24

---

Scripts and Package Integration

The SDK uses pnpm as its package manager package.json:46-46. The build lifecycle is managed through standard NPM scripts:

• build: Executes tsc to perform a full compilation of the project package.json:24-24.
• prepare: Also executes tsc, ensuring that the code is compiled whenever the package is installed from a git dependency or before publishing package.json:25-25.

The package.json explicitly defines which files are included in the published NPM artifact. Only the dist/ directory is bundled, ensuring that source files and test suites are not shipped to production environments package.json:22-22.

Build Script Mapping

Code
graph LR
    subgraph "Commands"
        PB["pnpm build"]
        PP["pnpm prepare"]
    end

    subgraph "Execution"
        TSC_EXEC["tsc"]
    end

    subgraph "Output Artifacts"
        OUT["./dist/"]
    end

    PB --> TSC_EXEC
    PP --> TSC_EXEC
    TSC_EXEC --> OUT
    OUT -->|referenced by| MAIN["package.json: 'main' [17]"]
    OUT -->|referenced by| TYPES["package.json: 'types' [18]"]

Sources:

• package.json:17-25
• package.json:46-46
• .gitignore:2-2

---