Fix A
Make it one big app.
Now nobody ships alone. One team's broken build breaks everyone, and updating a library means getting every team to agree first.
What breaks: your release schedule.
<fragment-slot name="problem" adapter="contract">
its own sealed space · started from blob:https://this-page/3c1a…
01
Why this
is hard
Four teams, one website. The usual fixes all go wrong somewhere.
Fix B
Put each app in an iframe.
Nicely separated, but each one is stuck in a box. It can't flow with the page, its pop-ups can't cover the page, and screen readers treat it as a different page.
What breaks: layout and accessibility.
Fix C
Load every app into one page.
It looks right, but the apps now share everything. Two versions of React collide, or one team's code quietly changes something another team relies on.
What breaks: something, on a Tuesday, with no clue why.
Fix D, the one Braid is built on
Keep each app's code apart. Put what it shows together.
<fragment-slot name="glossary" adapter="contract">
its own sealed space · started from blob:https://this-page/9e07…
02
How it works,
one word at a time
Words you'll hear a lot, in plain English.
Some of these sound like a fantasy novel. They're simpler than they sound.
YOUR PAGE · what the browser shows HIDDEN REALMS · display:none
┌──────────────────────────────────────────────────────────────┐
│ ● ● ● acme.example/billing/invoices │
├──────────────────────────────────────────────────────────────┤
│ ╔══ HOST SHELL · your app, owns the page ══════════════════╗ │
│ ║ ║ │
│ ║ ┌─ <nav> · part of the host ───────────────────────────┐ ║ │
│ ║ │ acme Home Billing Orders Reports │ ║ │
│ ║ └──────────────────────────────────────────────────────┘ ║ │
│ ║ ║ │
│ ║ ┌─ <fragment-slot name="billing"> ─────────────────────┐ ║ │
│ ║ │ #shadow-root ← its DOM lives here, in your page │ ║ │ ┌┄ <iframe hidden> ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
│ ║ │ Invoices │ ║ │ its code ┆ realm · billing ┆
│ ║ │ INV-101 $450.00 Pending ├┄╫┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄▶┆ Angular · its own window ┆
│ ║ │ INV-102 $1,200.00 Paid │ ║ │ ┆ own globals, own modules ┆
│ ║ └──────────────────────────────────────────────────────┘ ║ │ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
│ ║ ║ │
│ ║ ┌─ <fragment-slot name="payments"> ────────────────────┐ ║ │ ┌┄ <iframe hidden> ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
│ ║ │ #shadow-root │ ║ │ its code ┆ realm · payments ┆
│ ║ │ Balance due $1,650.00 [ Pay now ] ├┄╫┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄▶┆ React 19 · next door to 18 ┆
│ ║ └──────────────────────────────────────────────────────┘ ║ │ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
│ ║ ║ │
│ ║ ┌─ <fragment-slot name="notifications"> ───────────────┐ ║ │ ┌┄ <iframe hidden> ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
│ ║ │ #shadow-root │ ║ │ its code ┆ realm · notifications ┆
│ ║ │ ● 3 new · INV-102 was paid ├┄╫┄┼┄┄┄┄┄┄┄┄┄┄┄┄┄▶┆ a widget on every page ┆
│ ║ └──────────────────────────────────────────────────────┘ ║ │ └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘
│ ║ ║ │
│ ║ ┌─ <footer> · part of the host ────────────────────────┐ ║ │
│ ║ │ © Acme · Privacy · Status │ ║ │
│ ║ └──────────────────────────────────────────────────────┘ ║ │
│ ╚══════════════════════════════════════════════════════════╝ │
└──────────────────────────────────────────────────────────────┘
│ ▲
GET /billing/ │ │ one HTML response,
invoices ▼ │ every app already in it
┌─ BRAID GATEWAY ──────────────────────────────────────────────┐ fragment servers
│ middleware in your server, or at the edge │
│ 1 fetches the shell and every app at once ├─────────────▶ host app :3000
│ 2 stitches each app into its slot as it streams ├─────────────▶ billing :4201
│ 3 makes app scripts inert, re-arms them in a realm ├─────────────▶ payments :4202
│ 4 forwards /__braid/frag/:id/* to each server ├─────────────▶ notifications :4203
└──────────────────────────────────────────────────────────────┘
── host markup ══ host shell ── <fragment-slot> ┄┄ hidden realm, where the code runs
- frag·ment noun
- One of the apps on the page. It's a normal web app with its own team and its own deploys. Often it has no Braid code in it at all.
- host noun
- The app that owns the page. It draws the layout and the menu, and it leaves spaces for the other apps.
- slot noun
- One of those spaces. You write <fragment-slot name="billing"> and the billing app shows up there. That's all the host has to do.
- realm noun
- The sealed-off space where an app's code runs. It's invisible, and nothing inside it can reach out and change your page.
- de·pend·en·cy graph noun
- Every library your apps use, and every library those use. When apps share one, they have to agree on versions. With Braid, each app keeps its own.
- con·tract skew noun
- When two apps were built at different times and now disagree on what their shared data looks like. Braid spots it, upgrades the data when it can, and says so clearly when it can't.
- pierc·ing noun
- The server adds each app's content to the page before sending it, so people see it right away instead of watching an empty box.
- born in·ert adjective
- An app's content arrives switched off. Any scripts in it can't run on your page. They only run inside that app's own realm.
- ad·apt·er noun
- How Braid starts an app. compat works with apps you can't change. contract is for apps written to work with Braid, and needs no server.
<fragment-slot name="braided" adapter="contract">
its own sealed space · you're reading it right now
03
No server.
Yes, really.
This page is braided.
And there's no server behind it.
Each section you've scrolled past is its own little app. The page itself is just files on a CDN. When each app started, your browser built its sealed space from memory, using a blob: URL. Nothing had to be downloaded first, and your back button wasn't touched.
What happened while you read that
- 1The page finds a slot and reads which app goes there.
- 2Braid writes a tiny blank page for that app, in memory.
- 3It gives that page a blob: address, so no download is needed.
- 4A hidden frame opens it. That's the app's sealed space.
- 5The app's code loads and runs in there, away from everyone else.
- 6What it draws shows up here, on this page.
| With a server · compat | From memory · contract | |
|---|---|---|
| Where its blank page comes from | /__braid/realm/billing/… | blob:https://this-page/8f3e… |
| Waiting time | one trip to the server | none, it's already there |
| Touches your back button | yes, carefully | never |
| Needs a server | yes, the Braid gateway | no, any static host works |
<fragment-slot name="promises" adapter="contract">
its own sealed space · started from blob:https://this-page/c4b8…
04
What we
promise
Safe, untangled, and honest about the rest.
Your page stays yours.
Braid never changes anything global on your page. We have a whole set of tests whose only job is to fail if it ever does.
No more version standoffs.
Each app keeps its own libraries. One team can upgrade React this week without waiting on, or breaking, anyone else.
Mismatches get caught, not shipped.
When apps meet, they check that they agree on their data. Older data gets upgraded step by step. If it can't be, you get a clear reason instead of a quietly wrong screen.
"Safe" means what it says.
By default, apps your company owns are kept apart from each other. For code from outside your company, trust="untrusted" walls it off completely, cookies and storage included.
<fragment-slot name="start" adapter="contract">
its own sealed space · started from blob:https://this-page/0a7f…
05
Start in
ten minutes
Pick a path. Each one takes about ten minutes.
<fragment-slot name="parts" adapter="contract">
its own sealed space · started from blob:https://this-page/e612…
06
The parts bin
Take what you need. Leave the rest.
Every piece is a separate package under @braidlabs/*. Use one, or use them all.
Putting apps together
- core<fragment-slot>
- Runs in the browser. Starts each app in its own space.
- gatewaycreateGateway
- Runs on your server. Adds each app to the page before it's sent.
- clibraid dev
- Run everything on your laptop with one command.
- registrycreateRegistry
- A record of which apps exist and where, that never gets overwritten.
- swbraidServiceWorker
- Keeps open tabs working while you deploy.
- consolemountConsole
- See all your apps and how they fit together, at a glance.
For React and Angular
- react<BraidFragment>
- Show other apps inside your React app.
- angularprovideBraid()
- The same, for your Angular app.
Is your app the one being shown, not the one showing?
Then you don't need to install anything. Braid handles it.
Keeping data in agreement
- skewversioned()
- Labels data with its version and upgrades old data safely.
- datacreateRecordStore
- Saves data in the browser and sends changes when it's back online.
- contractresolveContract
- Your API explains its newer data shapes, so older apps can still read them.
- buildskew-stamp
- Stamps each build, so an out-of-date one gets noticed.
- studio<SkewStudio>
- Look inside versioned data and try out upgrades.