Get started
Export and version your app as a portable file

Engineering

Export and version your app as a portable file

FastYoke Engineering · 5 min read · Sep 15, 2026

  • Tutorial
  • Portability
  • YokeDoc

Audience: power users (Pay-as-you-go and up) · Recipe: Export your whole app as a portable file you can version, diff, and re-import.

What you'll build

By the end of this recipe you'll hold your entire app as a single JSON file — its workflows, its page layouts, its branding, its tier configuration, and any seed data — and you'll be able to check that file into git, diff two versions of it line by line, and re-import it to rebuild the app exactly. The app you author in FastYoke isn't locked inside the platform. Its definition is a portable document, and this recipe is how you get it out, keep a history of it, and put a known-good version back.

The document is called a YokeDoc. It's the same shape whether you authored the app by hand, cloned it from a Marketplace listing, or built it in Yoke Studio. Because it's plain JSON, ordinary tools work on it: git diff shows what changed between two exports, a code review comment can flag a workflow edit, and a tagged commit is a restore point. Nothing about this requires a proprietary backup format — the definition is the backup.

What a YokeDoc contains

One YokeDoc describes a whole app:

  • Metadata — the app's slug, name, tagline, category, and a content version number.
  • Branding and tier — colors, light/dark mode, and the app's pricing/tier configuration.
  • Boards — the FSM workflows, one per entity, that drive the app's states and transitions.
  • Pages — the UI layouts operators actually see.
  • Bridges, seed data, and extensions — cross-app links, any starter records, and referenced add-ons.

That's the complete authored surface. Re-materializing the document rebuilds the workflows and pages in your tenant from exactly those fields.

Before you start

You'll need:

  • A tenant-authored app (a Tenant Yoke). This is any app you author on your own tenant — built in Yoke Studio, cloned from a listing, or edited as JSON directly. You'll need its slug to address it.
  • Admin access. Reading, updating, and re-importing an app definition is an admin-only surface, and every call is scoped to your tenant — a slug in one tenant never reaches another.
  • Somewhere to keep the file. A git repository is ideal, because the whole point is to version and diff the exports over time.

Steps

1. Export the current definition

Ask the platform for your app's current YokeDoc. The Tenant Yoke REST surface returns the live definition for a slug as JSON — the same document Yoke Studio reads and writes. Save that JSON to a file in your repo, say bike-shop.yokedoc.json, and commit it. That commit is your first restore point.

Because the export is the canonical definition rather than a dump of internal tables, it's stable to diff. Export again next week and the only changes in git diff are the edits you actually made — a renamed state, a new page block, a tweaked color.

2. Version and diff it

Every time you change the app and re-import it, the platform bumps the app's revision and appends the new definition to that app's change history — so there's a server-side record of every revision alongside your git history. The history endpoint returns those revisions in ascending order, which means you can walk consecutive revisions and diff them to answer "what changed, and when?"

For most teams the git workflow is enough on its own. Commit each export, and your branch history is a readable log of how the app evolved. A pull request that changes bike-shop.yokedoc.json shows a reviewer precisely which workflow or page moved — the review surface you already use for code now covers your app's structure too.

3. Re-import to rebuild or restore

Re-importing is how you push a definition back. Send a YokeDoc to the create endpoint to stand up a new app, or to the update endpoint for an existing slug to re-materialize it in place. Re-import is idempotent: sending the same document again converges the app to that document rather than duplicating anything, and each update appends a fresh revision to the change history.

The platform guards the import. The slug in the update URL must match the slug in the document, so you can't silently rewrite one app into another. The document's format version is checked, so a file written against a newer format than your server understands is rejected rather than half-applied. And a raw-integration manifest is refused on the tenant path — tenant imports stay in the safe, declarative lane.

To restore a prior version, re-import an older exported file: check out the commit you want, send that JSON to the update endpoint, and the app converges back to that definition. Your file history is your rollback mechanism.

Take it further

  • Promote across tenants. Export from a sandbox tenant, review the diff, then import the same file into production. The file is the unit of promotion, so what you tested is exactly what ships.
  • Author in Studio, version in git. Build visually in Yoke Studio for speed, then export the result to a file for the durable, diffable record. The two aren't in tension — Studio writes the same definition you export.
  • Gate changes behind review. Keep app definitions in the repository that already runs your CI and code review. An app change becomes a pull request, with the same approval and audit trail as any other change.