Brua

The lifecycle of an asset

From a draft to a release and back: versions, change sets, approval, merges, rollback and deletion, and what consumers see when.

An asset's life

  1. Created with an id and a preset: flexible (one source, a width ladder), fixed (a designed width and height, one source per color scheme, scales made from it) or animated (Lottie, Rive or GIF with a still per scheme). Whether it takes dark, per-language files or individual scales belongs to the version, so a later version can add or drop them.
  2. Uploaded: the sources go straight to storage through short-lived signed URLs, one per slot such as any.still.source or dark.still.source. The Figma plugin and the command line do this for you.
  3. Processed: when every slot is in, Brua makes the variants. A source with the wrong proportions for a fixed asset fails with aspect_mismatch, unless the version was made with stillFit: fill.
  4. Submitted into a change set, named or new. A change set is the unit of review: it holds versions of several assets and shows the diff against what is in production, before and after side by side or swiped, per appearance and language, with a warning when a version changes an asset's shape by more than a percent, and when it adds or drops dark, languages or motion. A project that goes straight to review (Settings → Review and release) sends a version submitted on its own, from the Figma plugin, the command line or an upload, to review as it arrives; one added to a named change set waits for the rest.
  5. Reviewed: everyone who can approve gets an email when a change set is sent for review. An approver approves, and someone merges, now or at a scheduled time. A project's policy says whether an author may approve their own change set and who may merge. Until it merges, a change set can be withdrawn back to open or deleted.
  6. Released: the merge makes a new release, numbered, with the versions the change set carried. This is what consumers see. The id stays the same; the edge's pointer for it moves to the new version.
  7. A new version repeats the loop. Version numbers only go up, even after a deletion, because files are cached under their versioned URLs.
  8. Rolled back: restoring an earlier release makes a new release with that release's contents, so a rollback is itself a change you can see and undo.
  9. Deleted: an admin deletes an asset or a version that isn't in production. What is in production is taken out through a change set first; what is under review is sent back first.

What consumers see, and when

  • The JSON pointer, {id}.json, and the versionless URL, {id}, follow the current release. The edge serves them for a minute, and the SDKs keep the JSON for the same minute, so a merge reaches every app within a minute of it, with no release of theirs.
  • Versioned URLs, {id}/{version} and the files under it, never change: a file an app holds keeps working after the next merge, and after a rollback.
  • Nothing reaches an app before an approver has merged. A pipeline or a plugin can only put a version into a change set.
  • A test build can show a change set before it merges: see below.

Preview a change set in a test build

Every change set has a preview URL, on its page in the back office. It answers {id}.json like the edge does, with the change set applied to production: the version the change set carries for the assets it touches, the released one for the rest, and a 404 for an asset it takes out. A test build points the SDK's base at it instead of the edge, and needs no key; the token in the URL is the credential, so keep it to test builds.

TypeScript
const brua = createBrua({
  base: import.meta.env.BRUA_PREVIEW ?? "https://cdn.brua.dev/assets/991ceed8-a70e-4a5f-b3d3-e0b6b3d93e44",
});

The same works in every SDK, since they all read {base}/{id}.json. The change set's page says when a build last read the preview, so an approver knows it has been looked at in the app. Nothing is cached, and once the change set merges its preview serves production.

Versions and releases

A version is one asset's files and settings. A release is the project's whole set of versions at a merge, numbered from one. The JSON carries both: version is the asset's, release the project's, and the Asset-Release header on the pointer says which release served it. A library shared by several projects releases the same way, and a merge in it reaches every project that reads it.

Next