Package Selection

The Bridge is built à la carte. While you can install the entire ecosystem in one go, you probably don’t want to drag a parser and a full GraphQL adapter into a lightweight Cloudflare Worker.

By splitting the engine into modular packages, you can ship exactly what you need—and nothing you don’t—keeping your production bundles small.

Packages

Choose your packages based on where and how you plan to execute your graphs.

Package	Role	When to use it
@stackables/bridge	The All-in-One	Quick starts, monoliths, or when bundle size doesn’t matter.
@stackables/bridge-core	The Engine	Edge workers, serverless functions, and running pre-compiled .bridge files.
@stackables/bridge-compiler	The Parser	Compiling .bridge files to JSON at build time, or parsing on the fly at startup.
@stackables/bridge-graphql	The Adapter	Wiring Bridge instructions directly into an Apollo or Yoga GraphQL schema.

---

Common Workflows

Not sure which ones to pick? Here are the two most common architectural patterns for deploying The Bridge.

Workflow A: The Standard GraphQL Server (JIT)

This is the most common setup and the default in our Getting Started guide.

If you are running a traditional Node.js GraphQL server, you will usually parse your .bridge files “Just-In-Time” (JIT) right when the server starts up, and wire them into your schema. For this, you need the compiler and the GraphQL adapter.

npm install @stackables/bridge-graphql @stackables/bridge-compiler graphql

import { parseBridgeDiagnostics } from "@stackables/bridge-compiler";
import { bridgeTransform } from "@stackables/bridge-graphql";

// Read the files, parse them into AST instructions, and attach them to the schema

(Note: If you don’t mind the slightly larger node_modules folder, you can simply install @stackables/bridge to grab all of these in one import).

Workflow B: The Lean Edge Worker (AOT)

If you are deploying to a constrained environment like a Cloudflare Worker or a Vercel Edge function, you want the absolute smallest bundle possible.

Instead of parsing files on the server, you parse them “Ahead-Of-Time” (AOT) during your CI/CD build step. This means you only ship the compiled JSON instructions and the lightweight execution engine to production.

1. The Build Step (Dev/CI) Install the compiler as a dev dependency so it never touches your production bundle.

   npm install --save-dev @stackables/bridge-compiler

   Write a quick build script to compile your .bridge files into a single bridge.json file.

2. The Production Runtime Install only the core execution engine for your runtime.

   npm install @stackables/bridge-core

   At runtime, simply feed the pre-compiled JSON into the engine!

   import { executeBridge } from "@stackables/bridge-core";
   import instructions from "./bridge.json" assert { type: "json" };
   
   const { data } = await executeBridge({
     instructions,
     operation: "Query.search",
     input: { q: req.query.q },
   });

By using the AOT workflow, the parser, lexer, and GraphQL dependencies are completely stripped from your edge deployment, resulting in lightning-fast cold starts.