Skip to content

Working on a site locally ​

Change a template on your machine and see it in the panel — with the client's real text in it — without pushing, building or importing.


What this is, and the part everybody skips ​

Pushing a change feeds four things: the built artifact the preview reads, the schema the panel draws forms from, the schema the server validates every edit against, and the content that becomes the draft.

The third one is why pointing an iframe at a dev server is only half a feature. You would see your new block immediately and be unable to type a word into it, because the server checks every field against the schema pinned to the last build, and that schema has no such field.

A dev session answers both halves: the page comes from your machine, and the server accepts the shape your working copy declares.

What a session is ​

A copy of the site — its draft as it stands right now, so you are working against the client's real text rather than lorem ipsum — that lives for as long as you are using it and is then thrown away.

  • It is not the client's site. Nothing you do in it is visible to them.
  • It cannot publish. A session shares the site's repository, and publishing from one would push your working copy over what the client has been editing.
  • It expires if nobody touches it for two hours. Your dev server holds it open by saying hello; a laptop closed on Friday is not still holding one on Monday.
  • The way anything leaves it is a commit you make (below).

Opening one ​

Your agent does this. In its own words: open a dev session on natali-nails, serving from http://localhost:4321.

A session is opened on a site, because what it frames your page with is that site's real text. For a template that has no site yet — a new client, a fixture, a scaffold you are trying out — make one: create_site is a row, a site that is not live costs nothing and draws on no plan, and it can be archived when the template is done. Do not borrow another client's site as the frame; the text in it is theirs.

The address is not free-form. It is http://localhost:<port> or http://127.0.0.1:<port> and nothing else — whatever the panel is told to frame is a page embedded in a signed-in browser, so the set is exactly what the feature is for.

Leave the address out and the session shows a candidate build instead: slower by a build, and the only option if your browser will not frame a local address.

What your dev server has to do ​

One script tag, in dev only:

html
<script src="https://preview.jtakeit.com/_fl/bridge.js"></script>

That is the editor: it is what makes a heading tappable in the panel and what carries the text you type into the page. It is the same file the hosted preview gets — served from one place on purpose, because the page and the panel agree a version number between them and two copies of a protocol are two versions of it.

The host is the preview's, and it has to be: the file is served by the edge Worker, which holds preview.jtakeit.com (preview.stg.jtakeit.com on staging) and no route on the bare domain. A tag pointing anywhere else fails the quietest way this feature can fail — the page renders, the panel frames it, and nothing is editable, with no error anywhere to say why.

Nothing else changes. Your components already carry data-jtk-path; that is what the annotation lint checks on every build.

The page says where it is ​

The session's answer carries a watch_key, shown once. In the working tree:

npx jtkit session <session_id> <watch_key>          # --api https://api.stg.jtakeit.com on staging

It writes jtk/session.json (ignored by git), and from then on every page the dev server serves carries a small card, bottom right: where the site is — the brief, the layout, the writing, read off the files — and the platform's half through the session: the judge's word, the repository, the build, the preview, and the steps of the panel's Setting up the developer can take meanwhile, with the way there. The same seven phases the panel's «What the agent is doing» shows; the card is in the dev server only and never in a build. The key reads this one session's progress and nothing else, and dies with the session. jtkit progress prints the card's list in the terminal; run it before saying a phase is done.

Telling the session what the site is made of ​

When you change the schema, jtk/schema.json (jtk/catalogue.json on a contract-2 site), the session has to be told, or the panel draws yesterday's forms and refuses today's fields. Under astro dev the scaffold writes the schema again on every save of src/content/blocks.ts; run npx @jtakeit/astro schema before a commit, which also mints the ids and _keys the files lack.

Your agent sends the file with send_dev_schema. The session then draws its forms from your working copy — and the client's site keeps drawing forms from the template it is actually built from, because a working copy's schema only ever reaches a session. There is no state to clean up and nothing to switch back.

The file goes through the same validator the repository's own copy does, so a schema that would fail a build fails here, in front of you, in seconds — and it is the same judge validate_schema is, with the same findings, so under a session there is no reason to validate first and send second. One paste.

A session takes the file of the contract its site is written in. Before the site's first push it has none, and the session takes whichever the file says — jtk/schema.json for contract 3. When an import moves the site to contract 3, its first or a later one, every open session follows it: the site's schema and its pages are copied in again, and what was typed into the session before the move goes with the old shape. Keep the session; there is no need to close it and open another.

A shop on localhost ​

A session frames your page, and the page's shop is not the session's: astro dev answers the shop's four addresses (/api/stock, /api/shipping, /api/checkout, /api/order) from the site's own files — the scaffold's jtakeit-meta.mjs mounts devShop beside the diary's stand-in, and reads the products and jtk/modules/shop.json fresh on every request. A storefront can be walked end to end while it is written, the payment on a page of the dev server's own that charges nothing. It is a stand-in: every variant on sale is in stock with no count, there is no VAT and no own currency, and nothing reaches Stripe or the platform. The platform's twin of a session answers those four addresses 404; only the site itself or a preview takes an order, and preflight with try_order is the test of that one (the shop on the site).

Seeing what the panel drew ​

A session is a site with its own id, and the reading tools work on it: ask your agent to read the content of the session (get_content with the session's id) and the answer is the pages, and per page the blocks and the fields the panel draws forms for — which is how an agent that cannot see the panel checks that the block it just declared is there, rather than inferring it from the dev server's markup.

Getting your work back out ​

Anything you type into a session's content lives in the session. To keep it, ask your agent for the session's files: it writes them into your working copy at the paths a publish would have used — jtk/pages/<path>.json, jtk/entries/<collection>/<slug>.json, the translations beside them, jtk/shared.json, jtk/site.json (jtk/content/ on a contract-2 site) — and you read the diff and commit.

That is deliberate rather than a limitation. The way out of the panel's database and into a repository is a commit, everywhere in this product; a session is not allowed a shortcut past the one place a person sees what they are about to change before it changes.

Closing one ​

Ask your agent to close it, or leave it and let it expire. Either way the copy is deleted and the site is untouched — it never knew the session existed.

When it does not work ​

The panel shows an empty rectangle where the page should be. Your browser is refusing to embed a plain-http address in an https page. Chrome and Firefox allow localhost; Safari is stricter. Either use one of the first two, or run your dev server over https with a locally trusted certificate, or open the session without an address and work against a candidate build.

You can see the block and cannot type into it. The session has not been told about your schema yet. Ask your agent to send it.

The panel says the session is gone. It expired. Open another one — it takes the client's draft as it stands now, which is what you wanted anyway.