Getting started
How Ulika works
How the Ulika connector, the editor and the publish pipeline fit together, and what Ulika does and does not change in your repository.
Last updated
Ulika sits between your website's code and the people who edit its content. It does that with three parts: a small connector that lives in your repository, an editor that opens your real website, and a publish pipeline that gets your changes onto the live site. This page explains each part and where the boundaries are.
The big picture#
Your GitHub repository <---- connector (added by a pull request you review)
|
| your host (Vercel, Netlify, ...) builds the site on every push
v
Your live website <-----> Ulika editor (opens the site in a frame)
|
| Publish
v
content committed to your repository
-> host rebuilds -> live site updatedUlika owns the content of the site: the text, images, links and looks that the connector found. You own everything else: the code, the repository and the hosting.
Part 1: the connector#
The connector is a small set of files that Ulika adds to your repository so the site can be edited. It is added through an ordinary pull request. Nothing reaches your live site until that pull request is merged and your host has built it.
What Ulika reads first#
Before it writes anything, Ulika reads your repository (through the GitHub App you installed) and looks for content that can be edited: headings, paragraphs, button labels, images, links and page titles. Your code is read in memory and is never stored, and nothing in it is run. For each editable value Ulika remembers where it came from: the file, the line and the component name. Ulika then imports those values as editable fields in your project.
What the connector adds#
What you see in the pull request depends on your framework. The pull request always shows the exact diff first, so you can read every line.
Vite and React sites (the build adapter):
| File | What it is |
|---|---|
.ulika/connector.json | Settings: version, how content is delivered, your original build command. No secrets. |
.ulika/bindings.json | The list of editable values and where each one lives in your source, each source file pinned by a checksum. |
.ulika/defaults.json | A copy of your current content, used as a safe fallback. |
.ulika/build.mjs | The build step that applies published content while your site builds. |
.ulika/bridge.js | The editor bridge (see part 2). |
.ulika/live.js | A tiny script that shows a publish immediately (see part 3). |
ulika.config.json | A record of the link between the site and Ulika. No secrets. |
| One build entry | A single edit to vercel.json, netlify.toml or package.json, so your host runs the Ulika build step. |
Next.js App Router sites (the generated runtime connector) get a small ulika/ folder next to the app/ folder (for example src/ulika/), two static routes that publish cms/content.json and cms/code-build.json into your build output, and one line each in your root layout to mount the editor bridge.
In both cases:
No dependency is added and no secret is committed.
Your original build command keeps working. It is wrapped, not replaced.
Ulika writes to a new branch named
ulika/setup(with a suffix if that name is taken). It never writes the connector to your default branch.
Build-time markers#
When your site builds with the Ulika build step, Ulika applies your published content to the matching places in the source, runs your normal build, and then restores the source. In the built pages, each editable element carries a small marker attribute (data-ulika, data-ulika-href or data-ulika-el). The markers are how the editor and the instant-publish script know which element is which. They exist only in the built pages. Nothing in your Git history is rewritten.
If a bound source file changes after Ulika read it, Ulika does not guess. The build stops with a clear message instead of publishing the wrong text, and Ulika asks you to scan the site again. See Failed builds.
Part 2: the editor and its bridge#
The editor opens your real, live website inside a frame and lets you click the things you want to change. To make that safe, the connector ships the editor bridge:
It does nothing for normal visitors. It only wakes up when the page is inside the Ulika editor frame and was opened with the
ulikaPreview=1parameter.It only accepts messages from the Ulika address pinned in the connector settings. Messages are sent to that address only, never broadcast.
It does not run code or create HTML from content. Text goes into existing text nodes. Only a short list of attributes (such as
href,srcandalt) can be set, and never ajavascript:ordata:address.Inside the editor, link clicks and form submissions are cancelled so you cannot accidentally leave the editor.
The editor sends your draft changes to the bridge, which shows them on the page as you type. Drafts stay inside Ulika until you publish. Read more in The editor.
Part 3: the publish pipeline#
When you click Publish, Ulika freezes your drafts into a release and gets it onto your site in two layers.
Content is committed to your repository. For Vite and React sites connected today (connector 1.1 and later, called Git delivery), Ulika commits one file,
.ulika/content.json, to your default branch. It is the only file written there, and the commit is a fast-forward only (never a force push). If your branch is protected, Ulika opens a pull request on a branch namedulika/content-<release>instead, and asks GitHub to merge it automatically when the repository allows that. If it cannot, the release waits for you to merge it.Your host rebuilds. The push triggers your host's normal build, which reads
.ulika/content.json. Connectors that use the older delivery do it differently: the Next.js App Router connector and Vite connectors installed before version 1.1 fetch published content during the build with a build token (ULIKA_BUILD_TOKEN), and Ulika rebuilds the site through a deploy hook on your host.
A rebuild takes a while; how long depends on your host and your site, and Ulika cannot promise a time. To close that gap, the live.js script on your published site asks Ulika once per page load for the newest published content. If it is newer than the build the visitor is looking at, the script patches the marked text, images, links and styles in place. When the rebuilt site arrives, it already carries the same values and the script does nothing.
Finally, Ulika treats a release as complete only after your live site actually serves that release. A deploy request that returned "ok" is not enough on its own.
The full details are on Publish.
What Ulika changes in your repository#
| When | What is written | Where |
|---|---|---|
| You turn on live editing | The connector files, one commit | A new branch (ulika/setup) and a pull request |
| You activate the connector | The pull request is merged | Your default branch |
| You publish (Git delivery) | .ulika/content.json, one commit | Your default branch (or a pull request on a protected branch) |
| You publish (older delivery) | Nothing in your repository; Ulika asks your host to rebuild | Your host's deploy hook |
| A live build fails after Ulika merged the connector | A revert of the connector's own files | A pull request (ulika/revert) that Ulika merges |
Ulika never force-pushes, never rewrites history and never deletes a branch. See Security and privacy for the full list of rules.
What Ulika does not do#
It does not host your site.
It does not store your source code.
It does not run your code.
It does not change layout or structure. It changes the content and looks that the connector bound.
Next steps#
Check Requirements.
Follow the Quickstart.
Was this page helpful?