Customers never see your draft

I want a theme author to work without a local copy of Lithium. I also want their half-finished hero to stay off a customer's phone. Draft preview is a second document on the store, so those two things can both be true.

npm run dev in a theme package builds dist/data.json and PUTs it to /stores/:id/template-preview. The handler writes metadata.templatePreview. Live metadata.templateData stays whatever customers already have. I have read that function enough times, after enough scares, that I want it written down somewhere public.

The CLI then opens https://{slug}…/?preview={token}. The token is signed and lasts 24 hours. Middleware sets an httpOnly cookie, feeef_preview, so the next click stays on the draft: home, a product, checkout. The products, prices, and stock are the real store. I want that. A fixture catalog hides the bug where your grid assumes product.media[0].url and the API hands you a string.

Leave the draft with the banner, with /?preview=0, or by stopping the CLI, which clears the blob. Waiting out the token works too. None of those publish.

The hour I lost

Hosted *.feeef.store loads drafts from the production API. My CLI was still pointed at http://127.0.0.1:3333. The PUT succeeded, against my laptop. The shop never heard about it. The preview URL opened. I saw the live theme and decided the watcher was broken.

Two systems were answering. Only one of them had the draft.

feeef config set apiUrl https://api.feeef.org/v1
feeef signin
feeef template dev

The CLI refuses that mismatch now, unless you set FEEEF_ALLOW_LOCAL_API_REMOTE_PREVIEW=1. I added the refusal after that hour. Local Next (feeef template dev --local) is there for people who have the storefront repo on disk. I don't send theme authors down that path.

Publish is a different word

feeef template publish uploads the listing: the template row, the component rows, the locales, and a release. Customers still see the previous install until something installs that release. --apply is the install. It pins the store and writes metadata.templateData.

The install is a separate flag. npm run publish updates the listing and the release, then asks. Enter means no. --apply is the install. --yes skips the question and still does not install. I have published a changelog while the draft was still wrong, more than once, which is why Enter is not allowed to mean yes.

npm run publish -- --apply

In my own notes I keep the words apart. "I published" means the catalog moved. "Customers see it" means the live document moved. The flag table is Develop and publish.

A public or paid release can die in the security scan. The scan reads the custom function bodies. When it fails, the release does not exist. Fix the component it names. I have watched people retry by deleting the honeypot or the draft request to "make it smaller." Those checks are why the scan exists.

Paid themes stay in the merchant app. feeef template init --from will not unpack them, even if a payload happens to include data. Free public themes do unpack, and their library reference nodes are inlined first. A ref id from the source store is a blank hole on yours. I have stared at that hole.

Before I call a preview done

I open the preview URL. Then I open a private window, which has no cookie. The private window has to be the old shop. If both windows match, I am looking at the live theme and telling myself it is a draft.

I place a test order only after --apply, on a store that is allowed to take one. The catalog in a draft is already real, so the phone number you type can become a real lead. That surprises people. It surprised me.

The command table and the API-host fix are in the CLI docs. The walk from an empty directory to --apply is Create a template.