forge

Forge

Forge is a schema-first OpenAPI code generation and surface tooling framework. It provides a plugin-based architecture for resolving OpenAPI 3.x specifications, applying JSONPath-based overlays, and generating typed SDKs, CLI interfaces, runtime helpers, and documentation.

Packages

This monorepo contains:

• @cloudflare/forge: Core engine: OpenAPI 3.x resolver, typed schema model, JSONPath overlay runner, plugin lifecycle manager, and RFC runtime helpers.
• astro-fern: Generic Astro engine for rendering Fern-based API documentation.
• fern-forge: astro-fern extension for validating and adapting Forge OpenAPI metadata for documentation.
• docs-site: API reference documentation website consuming astro-fern.
• @cloudflare/fern-config: Shared Fern generator configuration and workspace staging.
• @cloudflare/forge-sdk-ts: TypeScript SDK package wrapper and sdk-map generator.
• @cloudflare/forge-transformer-sdk-ts: Standalone TypeScript SDK generator that turns any bundled OpenAPI specification into an idiomatic TypeScript client library.
• @cloudflare/forge-sdk-{lang}: Multi-language SDK workspace wrappers (Python, Go, Java, PHP, C#, Ruby, Rust, Swift).

Architecture

Forge separates the API definition from surface implementations:

+--------------------------------+
                  |  OpenAPI 3.x Specification     |
                  +---------------+----------------+
                                  |
                                  v
                  +--------------------------------+
                  |  JSONPath Overlays (Optional)  |
                  +---------------+----------------+
                                  |
                                  v
+--------------------------------------------------------------------+
|                         @cloudflare/forge                          |
|                                                                    |
|  - OpenApiResolver: $ref dereferencing, parameter/body extraction   |
|  - Schema model: typed command/method hierarchy                     |
|  - Plugin lifecycle: init -> transform -> finalize                |
+---------------------------------+----------------------------------+
                                  |
            +---------------------+---------------------+
            |                                           |
            v                                           v
+-----------------------+                   +-----------------------+
|  TypeScript SDK       |                   |  Other Surface        |
|  (@cloudflare/forge-  |                   |  Transformers (CLI,   |
|   transformer-sdk-ts) |                   |   docs, runtimes)     |
+-----------------------+                   +-----------------------+

Getting Started

Installation

pnpm add @cloudflare/forge

Basic Usage

import { Forge, init } from '@cloudflare/forge';

// Load any OpenAPI 3.x specification
const spec = {
  openapi: '3.0.0',
  info: { title: 'Sample API', version: '1.0.0' },
  paths: {
    '/users': {
      get: {
        operationId: 'listUsers',
        summary: 'List all users',
        responses: {
          '200': { description: 'Success' },
        },
      },
    },
  },
};

// Initialize a Forge instance with overlays applied
const forge = await init(spec);

// Access resolved operations and schemas
const op = forge.getVerbPath('listUsers');
console.log(op?.path, op?.verb); // /users get

CLI

Install the standalone Forge CLI to generate a TypeScript SDK from a bundled OpenAPI specification:

pnpm add --save-dev @cloudflare/forge-transformer-sdk-ts
pnpm exec forge openapi.json --out ./generated

Use - to read the OpenAPI document from stdin. Full generation requires Docker. The output directory contains the finalized OpenAPI document, generated SDK source, and sdk-map.json.

Development

# Install dependencies
pnpm install

# Run tests across all packages
pnpm test

# Typecheck
pnpm typecheck

# Lint and format
pnpm check

License

Apache-2.0 © Cloudflare, Inc.

---

Summary

Cloudflare’s schema-first OpenAPI codegen and surface tooling framework (229 stars, Apache-2.0, TypeScript monorepo): plugin architecture over OpenAPI 3.x — JSONPath overlays, typed SDK generation, CLI interfaces, runtime helpers, Astro/Fern-based docs rendering. Multi-language SDK workspace wrappers (Python, Go, Java, PHP, C#, Ruby, Rust, Swift) from one bundled spec.

Learnings

• The heavyweight alternative to clientele for ocli-style workflows: clientele generates a Python client from an OpenAPI spec (what ocli/Typer CLIs are built on); forge’s pitch is the whole surface family — SDKs, CLIs, docs, runtime helpers — from one spec with overlays for divergence. Cloudflare dogfoods it for their own API surface. Cost: TS monorepo + plugin architecture vs clientele’s single-purpose simplicity. Also feeds the python-openapi-client skill’s tool comparison.

Gotchas

• (none yet)

Hands-on

(research only)