building-packages

name	building-packages
description	Explains how packages are built in this monorepo. Use when working on build configuration, tsup config, package exports, or troubleshooting build issues.

Building Packages

Overview

Publishable packages are built with tsup (esbuild-based), orchestrated by Turborepo.

Publishable Packages

• @core-ai/core-ai — core types, utilities, error classes
• @core-ai/openai — OpenAI provider
• @core-ai/openai-compat — OpenAI-compatible endpoints provider
• @core-ai/azure-openai — Azure OpenAI provider
• @core-ai/anthropic — Anthropic provider
• @core-ai/anthropic-vertex — Vertex AI Anthropic (Claude) provider
• @core-ai/google-genai — Google GenAI provider
• @core-ai/google-vertex — Vertex AI Google provider
• @core-ai/mistral — Mistral provider
• @core-ai/omnifact — Omnifact provider
• @core-ai/kimi — Kimi API provider
• @core-ai/langfuse — Langfuse observability middleware
• @core-ai/opentelemetry — OpenTelemetry observability middleware
• @core-ai/axiom — Axiom OTLP exporter preset

Internal packages (testing, eslint-config, typescript-config, esbuild-config) are not published.

Build Commands

# Build all packages (runs tsup per package in dependency order)
npm run build

# Build a single package
npm run build -w @core-ai/openai

How It Works

Turborepo orchestration

turbo.json defines the build task with dependsOn: ["^build"], so core-ai builds first, then providers build in parallel. Build outputs (dist/**) are cached.

tsup configuration

Each publishable package has a tsup.config.ts:

import { defineConfig } from 'tsup';

export default defineConfig({
    entry: ['src/index.ts'],
    format: ['esm'],
    dts: true,
    clean: true,
    outDir: 'dist',
});

This produces:

• dist/index.js — ESM JavaScript bundle (dependencies externalized)
• dist/index.d.ts — TypeScript declarations

Package exports

Each package.json points to built output:

{
    "main": "./dist/index.js",
    "types": "./dist/index.d.ts",
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "import": "./dist/index.js",
            "require": "./dist/index.js",
            "default": "./dist/index.js"
        }
    },
    "files": ["dist", "README.md", "LICENSE"]
}

TypeScript and .ts imports

Some packages use .ts import extensions (see the extension conventions in AGENTS.md), enabled by allowImportingTsExtensions: true and noEmit: true in the shared tsconfig. tsup/esbuild handles these extensions during bundling, and dts: true uses emitDeclarationOnly mode for declaration generation.

Dependency Graph

Published package dependencies must remain acyclic. Current runtime dependency layers are:

• Base providers (anthropic, google-genai, mistral, openai) depend on core-ai.
• Composed providers depend on core-ai and their base provider:
  • anthropic-vertex → anthropic
  • azure-openai, openai-compat, omnifact → openai
  • kimi → openai
  • google-vertex → google-genai
• Integrations:
  • langfuse, opentelemetry → core-ai
  • axiom → opentelemetry

Do not add reverse dependencies from a base package to a composed provider.

Troubleshooting

check-types fails after build with "Could not find declaration file"

Turbo must run build before check-types for provider packages. Use npm run release:check which sequences build before lint/check-types.

Adding a new publishable package

1. Create packages/<name>/tsup.config.ts (copy from any existing package).
2. Add "build": "tsup" to the package's scripts.
3. Set exports, main, types, and files pointing to dist/.
4. Add the package to the fixed group in .changeset/config.json.