Quick Start

Get Arky running under a custom website. The storefront helper initialize wraps the SDK, keeps the visitor’s customer session, holds the cart, and exposes the modules a frontend needs.

Install

npm install arky-sdk

Initialize

import { initialize } from "arky-sdk/storefront";
import { createOrderToken } from "arky-sdk/utils";

export const arky = initialize("arky_pk_...", {
	locale: "en",
	market: "eu",
	createVisitorIdentity: () => ({
		customer_id: crypto.randomUUID(),
		session_id: crypto.randomUUID(),
	}),
	createSessionId: () => crypto.randomUUID(),
	createId: () => crypto.randomUUID(),
	createOrderToken,
});

• arky_pk_... is the store’s publishable key, safe in browser code. Each key belongs to one sales channel, so carts, prices and checkout use that channel.
• locale is the language of every text the site reads and of every order it places. It must be one of the store’s languages; Arky never falls back to another one.
• market names the market; it is implied when the key’s channel sells in one market.
• createVisitorIdentity, createSessionId, createId and createOrderToken are required. Your code picks every customer, session and record id and every order token: the SDK calls them when it needs a new visitor, a new signed-in session, a new record or a new checkout, and a client without them throws when it is created. createOrderToken from arky-sdk/utils makes a token in the shape Arky accepts.

Read Content

const website = await arky.content.load({ collection: { key: "website" } });
const title = website.text("title");
const hero = website.media("hero");

content.load reads the collection with its media and answers its blocks in the client’s locale: text is null when the block has no value in that language, and a failed read throws.

Count A Page View

arky.pageViews.send({ path: location.pathname, referrer: document.referrer });

The view is counted and nothing is stored, in Arky or in the browser. See Page Views.

Track An Action

await arky.actions.track({ key: "lead.submitted", data: { source: "homepage" } });

Sell A Product

const { items: [catalog] } = await arky.eshop.catalog.find();
const { items: products } = await arky.eshop.product.find({ catalog_id: catalog.id, limit: 20 });
const variants = await arky.eshop.productVariant.find({ catalog_id: catalog.id, product_id: products[0].id, limit: 20 });

const cart = arky.eshop.cart({ buyer: { type: "customer" }, catalog_id: catalog.id });
await cart.ensure();
await cart.addProduct({
	variant_id: variants.items[0].id,
	quantity: 1,
	purchase: { type: "catalog" },
});

const quote = await cart.quote();
console.log(quote.totals.total, quote.currency);

catalog.find lists the catalogs the buyer may use in this market; every product read and cart names one, and Arky never picks it for you. eshop.cart({ buyer, catalog_id }) answers the cart store of that buyer and catalog, the same one on every call. ensure loads the cart this browser selected for them, or creates one. The cart and line ids come from your createId; pass an id yourself when you want to pick it. See Core Concepts.

React To Cart State

const unsubscribe = cart.item_count.subscribe((count) => {
	document.querySelector("[data-cart-count]")!.textContent = String(count);
});

The cart store exposes nanostores atoms (cart, item_count, quote_result, status) that any framework can subscribe to.

Submit A Form

const contact = await arky.forms.getByKey({ key: "contact-form" });

await arky.forms.submit({
	form: contact,
	language: "en",
	values: { email: "ana@example.com", message: "Hello" },
});

The submission id comes from createId. When the answer is lost, sending the same answers again reuses that id, so the message arrives once.

Next Steps

• E-commerce Store: a cart-first storefront
• Scheduled Services: bookings through the cart
• Store Email: the store’s Resend account, sending addresses and the emails of each moment
• Authentication: sign-in codes for customers and operators
• API Reference: every module and its rules