Packages & Bundling

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.

The Packages

Choose your packages based on where and how you plan to deploy your application.

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

Common Deployment Workflows

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

Workflow A: The Monolith (All-in-One)

If you are running a traditional Node.js server (Express, Fastify, Apollo) and don’t have strict bundle size limits, the easiest approach is to use the all-in-one package. It includes the parser, the core engine, the standard library, and the GraphQL adapter.

npm install @stackables/bridge

import { parseBridge, executeBridge } from "@stackables/bridge";

// The parser reads the file at startup, and executeBridge runs it!

Workflow B: The Lean Edge Worker (Pre-Parsed)

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 document and the lightweight execution engine to production.

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

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

   Write a quick build script to convert 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 document from "./bridge.json" assert { type: "json" };
   
   const { data } = await executeBridge({
     document,
     operation: "Query.search",
     input: { q: req.query.q },
   });

Note

Is it practical to compile ahead of time?

Yes! The compiled JSON instructions are incredibly compact. A typical complex .bridge file (e.g. ~100 lines handling multiple API calls and array transformations) compiles down to roughly 10–15 KB of JSON — and under 1.5 KB gzipped.

Even a very large enterprise GraphQL schema with hundreds of resolvers will likely stay well under 1 MB uncompressed, and compress down to under 100 KB over the wire. The highly repetitive key structure of the JSON instructions compresses exceptionally well (~90% reduction with gzip) and parses instantly in V8, making AOT compilation perfect for zero-cold-start Edge deployments.

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