Back to Arky

Installation

Install and configure the Arky SDK in your project

Install The SDK

npm install arky-sdk

Requirements

  • Node.js 22 or a modern browser
  • TypeScript 5 is recommended

Storefront Setup

Storefronts use initialize, a framework-agnostic helper with reactive nanostores state:

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

export const arky = initialize(import.meta.env.PUBLIC_ARKY_PUBLISHABLE_KEY, {
	locale: "en",
	createVisitorIdentity: () => ({
		customer_id: crypto.randomUUID(),
		session_id: crypto.randomUUID(),
	}),
	createSessionId: () => crypto.randomUUID(),
	createId: () => crypto.randomUUID(),
	createOrderToken,
});

Configuration Options

OptionTypeRequiredDescription
publishableKeystringYesFirst argument: the store’s publishable arky_pk_... key, which also decides the sales channel
apiUrlstringNoAPI URL override; defaults to https://api.arky.io
localestringFor text and ordersThe language, sent as X-Arky-Locale; one of the store’s languages
marketstringUnless the key’s channel has one marketThe market key, sent as X-Arky-Market
sessionStorageStorefrontSessionStorageFor stateful SSRA request-local store for the visitor’s session
createVisitorIdentity() => { customer_id: string; session_id: string }YesPicks the ids of a new visitor customer and its session
createSessionId() => stringYesPicks the id of each new signed-in session: a code sign-in or a refresh
createId() => stringYesPicks the id of every record a call creates when you leave its id out: carts, cart lines, deliveries, orders, form submissions, sign-in emails, support conversations and messages
createOrderToken() => stringYesMakes each new order token; pass createOrderToken from arky-sdk/utils
visitorIdentity{ customer_id: string; session_id: string }NoRestores a visitor pair your code picked earlier

There is no default language: the SDK sends exactly what you set, and Arky refuses a language the store doesn’t have. The sales channel is the publishable key’s own, so there is no channel option. Change the context with setContext. A market change clears every cart view; each market keeps its own carts, and switching back reads them again.

arky.setContext({ locale: "hr" });

For one request in another language, pass { locale } as its request options. It runs on the same session, and only that request changes:

const croatian = await arky.content.load({ collection: { key: "website" } }, { locale: "hr" });

Cart calls refuse a per-call market, because a cart keeps the market it was filled in. The cart store’s quote, shipTo and quoteFutureDeliveries refuse a per-call locale too, so a quote always matches the store’s own context.

Framework Setup

Svelte

<script lang="ts">
  import { arky, catalog_id } from "$lib/arky";

  const cartCount = arky.eshop.cart({ buyer: { type: "customer" }, catalog_id }).item_count;
</script>

<span>{$cartCount}</span>

React

import { useEffect, useState } from "react";
import { arky, catalog_id } from "./arky";

export function useCartCount() {
	const [count, setCount] = useState(0);
	useEffect(
		() => arky.eshop.cart({ buyer: { type: "customer" }, catalog_id }).item_count.subscribe(setCount),
		[],
	);
	return count;
}

Server-Side Usage

Public reads during SSR or a static build (content, products, store setup) use the same publishable-key client and create no visitor session. Stateful SSR calls need an explicit request-local sessionStorage, so one visitor’s session never leaks into another request.

Trusted jobs, such as seed scripts and imports, use the Admin client with one of the store’s secret keys (arky_sk_...), which carries its own permissions:

import { createAdmin } from "arky-sdk/admin";

export const sdk = createAdmin({
	apiUrl: process.env.ARKY_API_URL!,
	secretKey: process.env.ARKY_SECRET_KEY!,
});

const store = await sdk.store.get({ id: process.env.ARKY_STORE_ID! });

Admin calls always name the store: every store-scoped call takes store_id. See Storefront and secret keys for creating one.

Tip

Never put a secret key in browser code. A storefront only ever holds the public key and the visitor’s own session, which the SDK keeps.

TypeScript

import { initialize, type ArkyStore } from "arky-sdk/storefront";
import type { BookingService, Cart, Order, Product } from "arky-sdk";

Next Steps