Appearance
The shop on the site
What a site that turns the shop module on has to lay, write and draw. The rules — what a price comes to, whether the last item is still there, what Stripe is asked — live in one place and it is not the page: four addresses on the site's own host answer everything a buyer needs, and the page renders what they say. Those addresses, their answers and their refusals are the shop protocol; what the module reads of a product and of the settings is modules; this page is what to do with them, in the order an agent does it. The brief comes first: a shop says what to ask the developer and what the kit takes by default.
A shop is one of the kit's, and the kit does most of it: the platform's shop kit is laid over the site by jtk add shop, the storefront is a base to copy whose behaviour is @jtakeit/kit's five elements, and jtk import products brings a catalogue in from a spreadsheet. The commands and the components to copy are in @jtakeit/astro, from the release that has add shop — npx @jtakeit/astro units lists shop among what a site can add when it does — and the elements are @jtakeit/kit's, which the site depends on. The kit's own page for all of it, the one to read beside the site's files, is docs/shop.md in the package (node_modules/@jtakeit/astro/docs/shop.md; on GitHub).
Turning it on
npx @jtakeit/astro add shop [--kit <file>] [--country <XX>] [--api <url>] [--root <dir>] [--dry-run]
npx @jtakeit/astro remove shop [--force]The shop is added to a site and never copied into every one: jtk create makes none. It works on a contract-3 site that jtk create laid out, with a booking kit or without one — a salon may sell beside its diary. The kit is the platform's, asked of it (GET /v1/kits/shop, at https://api.jtakeit.com, or at the --api or JTK_API_URL given where the site lives on another platform — staging, for one) or read from a file with --kit. It lays:
- the declaration, in
src/content/blocks.tsunder a line that says The shop kit: yours from here on: theproducttype, theproductscollection (a product's page at/shop/<slug>, the listing at/shop) and the module's binding,modules: { "shop": { "products": "products" } }in the schema.npx @jtakeit/astro schemawritesjtk/schema.jsonfrom it, andjtk import productsreads the collection from there; - the settings,
jtk/modules/shop.json: one zone,home, whose country is the business's (--country CH, else the region of the site's locale —de-CHisCH— else the shared contacts' country), and two methods in it,postandpickup.posthas no price: what the business charges to send is a fact only the business has — ask it, never make it up. A method with no price is a draft, whichpreflightnames; a pick-up ("pickup": true) is nothing sent and nothing priced.kitandkit_versionrecord which kit the settings came from, as the booking kit's do; - the storefront: five components under
src/components/shop/and three pages, the cart, the page after payment and the listing, written where the site has none, and Shop and Cart in the header's menu; - no product, no stock. The products are the business's, by hand or by
jtk import products, and a counted product is sold out untilset_stockhas its count.
jtk add shop changes no file the scaffold owns. A site laid out before the release that has it is told the lines to add instead — devShop in jtakeit-meta.mjs (on localhost) and the lines of src/pages/[...entry].astro that hand a product to Product.astro, which jtk add shop prints — and a component or page the site already has is left as it is. remove shop takes out what the kit added and refuses while jtk/entries/products/ holds a product: the products are the business's.
The settings are the business's to price, and the owner changes them later in the panel (Shop → Shipping). Zones are a name and their countries (a country is in one zone); a method is a flat price, or prices by weight for each size class (letter, parcel, bulky, each band up_to a number of grams, rising), not both, and may be free above an amount — say the business's own, in whole minor units of the site's currency. The business's country is the zone the kit starts with; another country it sends to is another zone with its own methods. A country no zone names is one the business does not send to (sends is false in the shipping answer), and a pick-up is offered whatever the country. Modules has every key.
A fix to the kit reaches a site as advice. kit and kit_version in jtk/modules/shop.json — a string, "1" — are read as the bookings' are: when the platform's kit has changed since, the judge says JTK_W_KIT_BEHIND, naming what changed, and nothing is refused or changed for you. (The contract card's one line for that code names the bookings; the shop's settings are judged for it the same.) Carry over what the business needs, then set kit_version to the version the finding gives.
Then npx @jtakeit/astro schema, and validate_schema with the schema, the jtk/ files and the site, before anything is pushed.
The products
A product is an entry of the collection products, jtk/entries/products/<slug>.json (a translation beside it, <slug>.<locale>.json). Its prices are whole minor units of the site's one currency, { "minor": 2990 } for 29.90 in francs, and the currency is the site's, never the page's. What the module reads, key by key, is modules; the shape an agent writes:
| field | holds |
|---|---|
title, description | the words, in each language the site has |
cover, pictures | the library's pictures, never a file in git (the pictures) |
options | the axes a product varies along — Size: S, M — each with a name and its values, each value a label |
variants | required. What is sold: a sku, a price, a weight in whole grams and, with options, picks and on_sale |
customizations | what the buyer is asked besides the variant (below) |
tracked | whether stock is counted; false is made to order and is never sold out. Counted unless it says otherwise |
size_class | letter, parcel or bulky: what a shipping method's bands go by. A parcel unless it says otherwise |
tax_code | Stripe's tax code, below |
tariff_number, made_in | where it is made and its customs number, below |
A simple product is one variant and no option:
json
{
"id": "0193a5c3-6b1c-7d20-9a31-5e4d3c2b1a01",
"collection": "products",
"slug": "becher",
"visible": true,
"fields": {
"title": "Becher",
"variants": [{ "_key": "v1", "sku": "MUG-1", "price": { "minor": 1450 }, "weight": 350 }]
}
}One with options is a variant for each combination, and each variant's picks names an option and its value by _key:
json
"options": [
{ "_key": "size", "name": "Size", "values": [{ "_key": "s", "label": "S" }, { "_key": "m", "label": "M" }] },
{ "_key": "colour", "name": "Colour", "values": [{ "_key": "red", "label": "Red" }, { "_key": "blue", "label": "Blue" }] }
],
"variants": [
{ "_key": "v1", "sku": "FOX-S-RED", "price": { "minor": 2990 }, "weight": 180, "picks": { "size": "s", "colour": "red" } }
]A minted _key is valid and means nothing, and picks is the one place that depends on one: an option or a value whose key changes leaves every variant that picks it picking nothing — JTK_E_PICKS_INVALID. Keep the keys. A product has at most 2,000 variants and any number of options. picks is the same in every language; a translation gives the words of an option or a value by its _key.
- A SKU is the business's own, unique to the site in any case (
MugandMUGare one) —JTK_E_SKU_TAKENotherwise — and immutable once an order names it: a variant with history is taken off sale ("on_sale": false), never reused (JTK_E_SKU_ORDERED). A variant added in the panel, or left without one by a sheet, is given the SKU the platform makes from the product's slug and its values' keys (T-SHIRT-FOX-M-BLUE). - The weight is whole grams. A variant without one counts as 0 g and is named by the panel, which matters the moment a method prices by weight.
- A product hidden (
"visible": false) is not served and may be unfinished, but its SKUs are still the stock's and the orders': one hidden product does not free them, and a copy made in the panel is given new ones. - A product sold until a date — a ticket for a night, a seasonal box — is a products collection with
ends_byon its date. Once that moment passes the shop sells it no more: withthen: hideit leaves the site as any entry over by its date does; withthen: keep, the default, the page stays and every variant answersoff_sale. - Stock is never content. It is the platform's ledger, by SKU: no field, no file, no page says a count (
set_stock, and the owner in the panel). A count written into a page is a lie by the next minute.
Customizations
What the buyer is asked, changing the line and never the product: a choice (a select; each choice may add to the price), a yes or no (a checkbox that adds an amount, and is never required) and a text (with the most characters it takes, 1 to 500). A required one the buyer leaves unanswered is said beside its field and nothing is sent. The panel keeps Advanced, where they are written, folded on every product, and opens it by itself only when a value in it is refused; the brief asks about customizations only where the business's products have them.
The tax code
A product's tax_code is Stripe's, txcd_ and eight digits, and decides the VAT only where the business charges it (a switch of the owner's, in the panel). Ordinary goods unless the brief says otherwise: a product with none is taxed as txcd_99999999, and Stripe applies each country's rate — no rate is kept anywhere. The panel offers a short list, by name, and Another code, typed:
| the panel offers | tax_code |
|---|---|
| Ordinary goods | txcd_99999999 |
| Printed books | txcd_35010000 |
| Children's books | txcd_35010001 |
| Newspapers | txcd_35020100 |
| Magazines | txcd_35020200 |
| Food and groceries, not eaten on the premises | txcd_40040000 |
| Clothing and footwear | txcd_30011000 |
| Children's clothing and footwear | txcd_30011200 |
Another shape is refused with JTK_E_PRODUCT_INVALID. The tax code is the owner's fact for Stripe and is drawn nowhere for a buyer (no_tap_target).
The customs fields
tariff_number and made_in are needed only when the shop ships abroad, and they are not alike. tariff_number is the owner's fact for customs, like the tax code: edited on the product's card and drawn nowhere for a buyer (no_tap_target). made_in, where the product is made, is drawn on the product's page under its label, so write it as the business wants it read: Portugal, not a code for customs.
The storefront: a base to copy
Five pieces — a product's page, the cart, the checkout step, the page after payment and a listing — are components in src/components/shop/, each with its markup written out, every hook of it, and the scaffold's look in a <style> beside it. The behaviour is @jtakeit/kit's five elements, imported at the bottom of each component. The markup, its classes, its order and its look are the site's; the behaviour is the platform's protocol and is the kit's to keep, not the site's to rewrite — as the booking form's are (bookings on the site).
| piece | component | element | its root | it asks shop/1 |
|---|---|---|---|---|
| a product's page | Product.astro | <jtk-product> | form[data-product] | what is left |
| the cart | Cart.astro | <jtk-cart> | [data-cart] | the cart priced |
| the checkout step | Checkout.astro | <jtk-checkout> | form[data-checkout] | the cart priced, then the checkout |
| the page after payment | OrderAfter.astro | <jtk-order> | [data-order] | the order |
| a listing | ProductListing.astro | <jtk-listing> | [data-listing] | what is left, for the tiles |
The entry page, src/pages/[...entry].astro, draws a product with src/components/shop/Product.astro; the cart and the checkout step are two elements on one page, /cart, the checkout hidden until the cart's To checkout hands on; the page after payment is /order, the return Stripe sends the buyer back to; the listing is /shop.
Copy it, keep the hooks, design the rest
An element finds everything in its piece by a hook — a data-* attribute or a control's name, never a class. So a storefront can be rebuilt in any design: rename every class, draw the options as swatches or a select, put the address beside the buyer, move the price. Keep the hooks and it sells. Two kinds, the list of which is @jtakeit/kit/shop/hooks:
- Always — the piece cannot work without them. An element says in the browser's console which is missing when it wires one, and the part the hook stands for does nothing.
- Said — where the element writes what happened: the price from, the customs notice, the order's number. Left out, that line is not said and nothing else changes.
| piece | always | said |
|---|---|---|
| product | form[data-product] (with data-api, data-locale, data-facts, data-words, data-jtk-fixed), [name^="option:"], [data-price], [data-stock], [name=qty], [data-add], [data-product-error], a hidden [data-added] | [name^="answer:"], [data-from] |
| cart | [data-cart], [data-cart-lines], a hidden [data-cart-empty], [name=country], [data-methods], [data-subtotal], [data-cart-error], [data-to-checkout] | [data-abroad], [data-vat], [data-cannot-send], [data-cart-retry] |
| checkout | form[data-checkout] (hidden until the cart hands on), [name=name], [name=email], [name=phone], [data-address] around [name=line1], [name=line2], [name=postal_code], [name=city], [data-total], [data-challenge], [data-checkout-error], [data-pay] | [data-abroad], [data-vat], [data-own-currency] |
| page after payment | [data-order], [data-order-state], [data-order-lines], [data-order-total], [data-pay-again] | [data-order-number], [data-order-method], [data-back-to-cart] |
| listing | [data-listing] around each [data-product-tile] | [data-listing-group], [data-listing-empty] |
data-jtk-fixed on a piece's root (the product's form, the cart, the checkout, the page after payment) says that the words drawn inside it — the labels, the buttons, the sentences the element writes — are the site's design, the same for everyone and changed by the studio, and not content the owner edits: a tap on one in the panel says so, where it would otherwise open nothing. A copy keeps it on the root; only a field the owner edits (a product's title, its description, a price) carries its own annotation inside.
Each root says what it is drawing in data-state, for the site's CSS to show a part by and for a walk to wait on:
| root | data-state |
|---|---|
| cart | pricing, priced, stale (the shop could not be asked again: the last rows, held), empty, failed |
| checkout | pricing, priced, stale, failed, refused, empty, paying |
| order | loading, waiting, stopped (still waiting after two minutes of asking), paid, lapsed, cancelled, unknown |
What an element draws itself carries a data attribute, never a class (data-cart-line, data-line-title, data-method-choice…); reach it from Astro's scoped style as .cart :global([data-cart-line]). The rules the behaviour cannot work without — [hidden] means hidden, a focus ring where the site draws none — the element puts on the page itself.
X-Jtk-Shop: 1 is on every request an element makes, with cache: "no-store": what is left, and what a cart comes to, change with every checkout, and a count a minute old sends a buyer to pay for the last item somebody else is holding. A page that sends no header is read as version 1, and jtk a11y fails one that sent a request without it.
The words are @jtakeit/kit/shop/words, in the kit's eight languages (uk, de, en, ru, es, it, pt, fr), English for any other; a regional tag reads its language's (de-CH is German). A component draws its labels from them and hands the same words to its element as data-words. They are plain on purpose: have a native speaker read them before a site goes live. A sentence has no full stop at the end, so the markup may add its own.
The look is the site's to give. The components' <style> is the scaffold's: neutral, legible, in the site's tokens, with no stylesheet of the kit's behind it. A storefront in the scaffold's clothes on a page designed otherwise is the first thing a studio sees: restyle it before it goes out. A price, and the stock beside it, are what the shop says; the design decides how they are drawn, never what they are.
What not to do
- Do not work out a price on the page — not a discount, not shipping, not a sum of lines. The shop prices every line, and the cart again each time it is shown; the checkout holds the buyer to the
totalit priced. The one sum a page makes is thetotal: the shipping answer'ssubtotalplus the chosen method'sprice, which the shop checks (409 total) — nothing else. - Do not keep a price or a title in the cart. The cart holds the protocol's line (
product,variant,qty,answers) in the browser and nothing else, so a cart kept for a week can say nothing stale: what it shows is the lastPOST /api/shippinganswer. - Do not show a count as content, nor cache one: it is read live from
/api/stockand is never in a page or an entry. - Do not leave out a hook, and do not hide a sold-out product from the built page: that is the listing's element, once the page has loaded, and only where the site chose it.
- Do not put a Turnstile key or a Stripe key in the repository. The challenge's key is asked of the platform when the checkout step opens.
On another generator
A site on Eleventy, a Next export, Nuxt or SvelteKit takes the same elements and writes the markup itself. There is no renderProduct, as there is a renderBookingForm: the hooks above are the whole contract between a piece and its element.
html
<script type="module">
import '@jtakeit/kit/elements/shop-product'; // and shop-cart, shop-checkout, shop-order, shop-listing
</script>once on each page that has the piece; importing a module defines its element and wires every root of its piece on the page, at load and again on the panel's fl:placed. @jtakeit/kit/shop gives productFacts(entry, currency) to read a product through the door, @jtakeit/kit/shop/words the words, @jtakeit/kit/money a price as the page says it, and @jtakeit/kit/devshop the dev server's stand-in. jtk add shop is Astro's — it edits blocks.ts — so the kit is laid by hand: the platform's page for it, jtakeit:///kits/shop.md, gives it whole. jtk import products is not Astro's: it reads jtk/schema.json and writes entries on any contract-3 site.
The cart and the checkout, as shop/1 speaks them
The storefront does all this, and what it does is the platform's, so a page that is not the kit's elements does the same. The shop protocol has the wire; the rules an agent builds against:
- The price is the platform's, every time. The cart is priced by
POST /api/shippingwhenever it is shown; a line the shop refuses is said with its reason and taken out by the buyer, and To checkout is held until none is. The checkout step asks again with the stored cart, so thetotalit says and sends is what the shop prices at that moment, and a price that changed in between is refused with the new one. - One press is one order — the
attempt. Pay is for one body: the lines, the country and method, the buyer, the address and the total. The same body pressed again — the answer was lost, the button pressed twice — is the sameattemptand the same order, with one hold; any other body is a new press with a new one, and a press answered201is over. The press is kept in the tab as a digest, none of the buyer's details. - A buyer back from Stripe's page without paying is offered it again (
pay_url) and keeps the cart. abroad— the parcel leaves the business's customs area (Switzerland and Liechtenstein are one, the European Union's with Monaco and San Marino is another, any other country its own): the checkout says before payment that customs duties are paid at the door by the buyer, never for a pick-up.vat_included— the business's VAT switch is on: incl. VAT stands beside a price. It is the switch, not Stripe's word on a sale; a buyer abroad may be charged none.own_currency— Stripe's page may show a buyer from abroad the price in their own currency: You can pay in your own currency beside the pay button.422 address— Stripe cannot work out the VAT for the delivery's address. The order is given up and its hold given back: the buyer checks the address and starts again.locale— the language the page is in goes on the shipping and the checkout bodies ("locale": "en"). The lines are frozen in it where the product has that language and the site's own words otherwise, and the buyer's letters speak it. They go out in the business's name («<the site's name> via jtakeit»), and an answer goes to the business's own email — the shared text'semailfield or the business factemail; none given, none to answer to. A language the site has not got is the site's own, never a refusal, and the language chooses the words, never what is sold.- The last item goes to the first buyer who goes on to pay: a stock hold is 31 minutes, and a line short of stock is refused with what is available (
409 short,short: [{ sku, wanted, available }]). A page says each such line, or the buyer must guess which to cut: by the title and labels the answer's quote gives that SKU and what is left — «Fox T-shirt, M, Blue: 1 left», «Mug: none left». The kit's checkout says it in[data-checkout-error]and tells the cart, which says it on the row and gives its box the focus.
The page after payment is the checkout's return. It reads the order from the token on its address, so it needs no cart and may be opened on another device: the lines as they were frozen, the number once it is paid, never the buyer's contact or address. While the order waits it asks every three seconds for two minutes, offers Stripe's page again (pay_url), and then says it is still waiting; once the order is paid it empties the cart — only for the order this tab's press sent to Stripe. A token that is nobody's says so rather than waiting.
A listing that hides what is sold out is the site's choice (HIDE_SOLD_OUT, false as the kit lays it, data-hide-sold-out on the root): once the page has loaded the element asks what is left of its tiles and hides each whose product nobody can buy. The built page lists every product either way — a crawler and a reader whose script never ran see all of them.
On localhost
astro dev answers the shop's four addresses itself: jtakeit-meta.mjs mounts @jtakeit/kit/devshop at /api, beside the diary's stand-in, and reads the products (the collection the schema binds to the role) and jtk/modules/shop.json fresh on every request, so an edit shows at once. A storefront can be walked end to end while it is written: a product chosen and added, the cart priced, a country and a method chosen, the checkout filled in, a payment made on a page of the dev server's own (/api/dev-pay, which says nothing is charged) and the page after payment.
It is a stand-in, close to the platform's and not the same: every variant on sale of a counted product is in stock and none says how many are left; there is no VAT and no own currency (read incl. VAT on the preview); nothing is asked of Stripe or the platform; no hold, no challenge, and an order never lapses. preflight with try_order is still the test of the real shop, which proving it says the extent of. The platform's own twin of a dev session answers the four addresses 404: only the site itself, or a preview of it, takes orders.
The catalogue: jtk import products
In this order, because each step writes what the next reads:
npx @jtakeit/astro add shoplays the declaration and the settings;npx @jtakeit/astro schema --emit-only(orschema, which also builds) writes the product block and the module's binding intojtk/schema.json, which the import reads the products collection from and refuses without;npx @jtakeit/astro import products, below.
npx @jtakeit/astro import products <file.csv> --map <mapping.json>
[--root <dir>] [--currency <xxx>] [--words] [--media '<link>'] [--dry-run]A catalogue is a spreadsheet — a WooCommerce or a Shopify export, or any CSV — and the command reads it through a mapping that says which column is which field of a product. It writes what the door reads, jtk/entries/products/<slug>.json and, for the words the sheet has in another language, <slug>.<locale>.json. It is for a contract-3 site with the shop on, after jtk schema.
Everything is read and judged before anything is written or fetched. A sheet with one fault leaves the tree as it was, and each fault names its row (the line of the sheet, the header being line 1) and its column. The sheet is CSV in UTF-8; the prices are read in the minor unit of the site's currency (jtk/site.json's, or --currency where the site has none, and one that contradicts the site's is refused). Run it with --dry-run first: it says what it would make, update and skip, every SKU it would make, every change of a second import as before → after, the pictures it would fetch and the stock file it would write, and does none of it.
The whole mapping — every key, every field, what a row is, how slugs and keys are made — is the kit's page, docs/shop.md (node_modules/@jtakeit/astro/docs/shop.md), and is not repeated here. Nothing in a mapping is guessed, and a key the import does not read is refused. The two layouts the kit shows, as the files its tests read:
json
{
"v": 1,
"decimal": ".",
"group": { "parent": "Parent", "of": ["ID", "SKU"] },
"skip": { "column": "Type", "values": ["grouped", "external"] },
"fields": {
"title": { "de-CH": "Name", "en": "Name (EN)" },
"description": "Description",
"sku": "SKU",
"price": "Regular price",
"weight": { "column": "Weight (kg)", "unit": "kg" },
"stock": "Stock",
"visible": { "column": "Published", "yes": ["1"] },
"options": [
{ "name": "Attribute 1 name", "value": "Attribute 1 value(s)" },
{ "name": "Attribute 2 name", "value": "Attribute 2 value(s)" }
]
}
}That is a WooCommerce export: a variable product's variations name their parent as id:20, so they are grouped by Parent and looked up in ID or SKU, the weight is in kilograms, and the site is in German with English beside it. And a Shopify export, one product the rows of one Handle:
json
{
"v": 1,
"decimal": ".",
"group": { "by": "Handle" },
"fields": {
"title": "Title",
"description": "Body (HTML)",
"slug": "Handle",
"sku": "Variant SKU",
"price": "Variant Price",
"weight": "Variant Grams",
"stock": "Variant Inventory Qty",
"visible": { "column": "Status", "yes": ["active"] },
"options": [
{ "name": "Option1 Name", "value": "Option1 Value", "none": ["Default Title"] },
{ "name": "Option2 Name", "value": "Option2 Value" }
]
}
}Neither names pictures; see the pictures. The rules an agent acts on:
skip—{ "column", "values" }: a row whose cell in that column is one of the values (compared without regard to case or the spaces round it) is left out, and each is said. WooCommerce's grouped and external products are not products of this shop, and one of them would otherwise stop a whole export. A variation that names a skipped row as its parent is refused.none— on an option, the words that say a variant has no value of it: Shopify's"Default Title"on the only variant of a product with no options.- A variant is a row with a price. A row with a SKU or an option value and no price is refused: a variant is sold at a price or not at all.
- An amount is digits and the mapping's decimal — no sign, no thousands separator, no currency — and more digits after the separator than the currency has is refused, zeros included:
12.500is no 12.50, and1,250under","is neither 1.25 nor 1250.12,50under","is 1250, and without it is refused with the hint. Nothing is rounded. - A weight is whole grams.
0.18kg is 180 g; at most three decimals in kilograms and none in grams, zeros included (0.1800kg and180.0g are refused). - SKUs and keys. The business's SKUs are kept; a variant the sheet leaves without one is given the SKU the platform would make. An option and a value get the key the panel would give from their names (Size is
size; a value 42 isv42, an optiono42), and the keys are kept:picksdepends on them. Two rows with one SKU, in any case, are refused naming both. - A second import of the same file, or an updated one, matches by SKU and updates what the sheet says — the numbers and the switches: prices, weights,
on_sale,visible,tracked, the size class, the tax code, the customs fields — and keeps the owner's words: a title, a description, an option's name or a value's label the entry holds that differs from the sheet's stays, and each is said, so an owner who renamed a product in the panel does not have it renamed back.--wordstakes the sheet's. The ids, the keys, the rank, every variant the sheet does not name and every product the file does not name are left alone; an empty cell erases nothing. Tell the owner this before a second import of a catalogue they have edited.
Pictures
A pictures column names a product's photographs by address or by path — a bare column string splits a cell on ,, and { "column": "Images", "split": ";" } says another separator. They are fetched on the developer's machine, never by the platform, into src/assets/products/<slug>-<n>.<ext> (git-ignored before the first file is written), named in the entry as slots — the first is the cover — and jtk media push then sends them to the site's library and writes its keys in their place. A picture never reaches git. What is taken:
- A picture is taken by what its first bytes are, never by its name or the type an address says: a JPEG, a PNG, a WebP or an AVIF, at most 8 MB. No SVG — a drawing from a stranger's sheet may carry script the library would serve, so it is added by hand. A HEIC photograph is said as one: export it as a JPEG.
- An address is fetched over
http:orhttps:only, for at most 20 seconds, and a path only inside the sheet's folder: no absolute path, no..out of it, no link out of it. - What cannot be had — a 404, a page, a file over the most, a slow address — is said with its row and its address, and the product is written without that picture.
--media '<link>' — media_link's URL, quoted, good for fifteen minutes — runs jtk media push in the same run:
npx @jtakeit/astro import products catalogue.csv --map mapping.json --media '<media_link url>'It is refused where the mapping names no pictures column, before anything is written. And two things to say plainly, to the developer and to yourself:
--mediaruns the wholejtk media push, not only the import's pictures: everything the content names that is not a key of this site goes with them — a fresh site's example photographs are sent with the import's — at the site's hourly budget of 300 files and 250 MB.npx @jtakeit/astro media push --dry-runshows the plan.- A stranger's sheet — a supplier's catalogue — can make the developer's machine ask any address it names,
localhostand link-local addresses included, and it follows redirects, so an address the sheet names can send this machine on to one it does not. Only an image is ever kept, but the request has been made: read a stranger's sheet before importing it.
When the push is stopped by the link or the budget, what reached the library has its key written, and the import says how many pictures are still files on this machine only and exits 1: a commit before they are pushed builds the site without them, since the platform builds from git. Run the same command again with a new media_link; nothing is fetched again.
Stock
Stock is never content, so the sheet's stock column goes to a file for set_stock, never a field of the site: .jtakeit/stock.txt, one SKU and its count a line (FOX-S-RED 5), at most 5,000 lines a file (the next is stock-2.txt), added to .gitignore — a count committed is a stale one. Send the text of each file to set_stock with the site's id: it sets how many are on hand for the SKUs that have not sold yet, and a SKU that has sold is the owner's, corrected in the panel — set_stock leaves it as it is and names it. A counted product is sold out until its stock is set, so set it before the site is looked at. With no stock column, set_stock sets it SKU by SKU.
Then npx @jtakeit/astro schema --judge, or validate_schema by site and ref, judges the site with its products, and set_stock stocks them. A catalogue of hundreds of products is judged by site and ref, never sent with the call: the call takes at most 500 files and 8 MB.
Proving it
preflightwithtry_orderwalks the four addresses as a buyer does, on the preview before the launch or on the site's address after it, under your own session: the cart priced, Stripe's test page opened on the sandbox, and the order lapsed and its stock given back by Stripe's own message. It is a test order the business never sees, and on a launched site never takes the last of a SKU. It needs what a buyer needs: a build served, the business's country, a product in stock (set_stockfirst) and a method priced for that country. A check that fails says which step, and what the run left behind. It reads none of the storefront's hooks: it walks the shop's addresses, not the page, so a greentry_orderdoes not prove that a page still draws every hook. A page that lost one is found by its element, which says in the browser's console which is missing, and bynpx @jtakeit/astro a11yon the build — not by the platform.get_sitesays what a stranger's shop page sent that the platform does not read, inshop_drops: each name, the address it was sent to, how many times this month. A stranger's cart is read without it and goes through, so whatever the field meant was lost on every buyer; a test session is refused it (JTK_E_SHOP_FIELD_UNKNOWN) — which is why the checkout is tried on the preview before anybody else uses it. Fix the page.validate_schemajudges products too — SKUs unique per site, every variant priced, picks that name the product's options, at most 2,000 variants.
What is a person's
An agent does none of these, and the brief says so to the developer:
- Connecting the business's Stripe account — nothing is paid before it is.
- Linking where new orders go — the Telegram chat or the email, in the panel; every kind a site collects, orders among them, must be heard by a verified channel before it launches.
- Switching VAT on, and the buyer's own currency, on the site's Payments screen: no tool, file or commit sets either.
- Launching on the business's own domain, and handing the site over. A site that sells needs a shop line on the studio's plan as well as its site line, bought under Reselling by the studio's owner or admin; without one the launch is refused, a live site's publish that turns the shop on is refused too, and a launched shop whose line lapsed takes no new order until a line is bought and the site's next publish takes it.
- Running the shop — the orders, fulfilled with a tracking number or refunded with the items put back, the stock counts after the first sale, the shipping. No tool reads an order, and none is added: orders are the business's customers.
What an agent does is the files and the checks: the kit, the products, the storefront, the settings the business gave it prices for, the starting stock, and preflight with try_order before it says the shop is done.