Braidwire

The smart API client generator that respects your code.

Braidwire bridges the gap between your OpenAPI/Swagger specification and your frontend codebase. Unlike traditional generators that overwrite your files and destroy your manual work, Braidwire uses a Safe-Regen engine to surgically update your API client while preserving your custom logic.

Why Braidwire?

• 🛡️ Safe-Regen Engine: Keep your custom helper functions and error handling safe. We only update what we generated.
• 🏗️ Deep Schema Parsing: Fully resolves nested objects, arrays, and enums from your spec into perfect TypeScript interfaces or JSDoc typedefs.
• 🎨 Output Matrix: Choose your flavor—TypeScript or JavaScript, Fetch API or Axios.
• ⚡ Zero-Install Workflow: Run it instantly with npx. No global bloat.
• 📦 Atomic Writes: Zero risk of file corruption during synchronization.

Quick Start

Initialize your project and generate your first API client in seconds:

npx braidwire init

The interactive wizard will help you connect your OpenAPI spec and configure your preferred stack.

Core Concepts

The "Safe-Regen" Guarantee

Braidwire wraps every generated function in protected regions. Any code you write outside these tags is 100% safe and will never be touched during a synchronization.

// [braidwire-start:getUserById]
export const getUserById = async (id: string): Promise<Types.User> => {
  return await request(`/users/${id}`, { method: 'GET' });
};
// [braidwire-end:getUserById]

// ✅ YOUR CUSTOM CODE HERE - BRAIDWIRE WILL NEVER DELETE THIS
export const formatUserTitle = (user: Types.User) => {
  return `Mr/Ms. ${user.fullName}`;
};

Usage

Commands

| Command | Description | | ------- | --------------------------------------------------------------------------- | | init | Launches the interactive setup wizard and creates braidwire.config.json. | | sync | Synchronizes your local code with the latest API specification. (Default) |

Global Flags

| Flag | Description | | ------------------- | ---------------------------------------------------------------- | | --dry | Preview Mode. See what would change without modifying files. | | -s, --spec <path> | Override the path to your OpenAPI spec. | | -o, --out <path> | Override the output directory. | | --ts / --js | Specify language via CLI to bypass wizard prompts. | | --axios / --fetch | Specify driver via CLI to bypass wizard prompts. | | -y, --yes | Automatically confirm the first synchronization. | | -v, --version | Display the current version of Braidwire. | | -h, --help | Display the help menu. |

Configuration

Braidwire persists your settings in braidwire.config.json. You can modify this file at any time; the next sync will automatically detect the changes and migrate your codebase.

{
  "language": "ts",
  "driver": "axios",
  "specPath": "./openapi.yaml",
  "outputPath": "./src/api",
  "baseClient": true,
  "version": "1.0.0"
}

Advanced Features

Configuration Drift Detection

If you change your configuration (e.g., switching from Fetch to Axios), Braidwire will detect the "drift." It will prompt you for consent before surgically migrating your network layer, ensuring your imports and client instances are updated while keeping your manual code intact.

Type-Safe JavaScript

Using the JavaScript flavor? Braidwire generates comprehensive JSDoc Typedefs and @param annotations. This gives you TypeScript-level IntelliSense and autocomplete without needing a build step.

Maintainer

Rahat Hasan Senior Software Engineer (~5 Years Experience)

Dedicated to building tools that empower junior developers to write stable, professional, and scalable code.

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgements

Braidwire is built with respect for the OpenAPI Initiative and inspired by the architectural standards of Zod, Prettier, and ESLint.