Back to Arky

Installation

Install and configure the Arky SDK in your project

Install The SDK

npm install arky-sdk

Requirements

  • Node.js 18+ or a modern browser
  • TypeScript 5.0+ is recommended

Storefront Setup

Storefronts should use initialize. It is a framework-agnostic SDK helper that exposes reactive Nano Store state.

import { initialize } from 'arky-sdk/storefront';

export const arky = initialize(import.meta.env.PUBLIC_ARKY_PUBLISHABLE_KEY, {
  locale: 'en',
  market: 'us',
});

Then use the modules the page needs:

arky.setContext({ locale: 'en' });
await arky.eshop.cart.load();

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | publishableKey | string | Yes | First argument. Public arky_pk_... key from the Store’s Developer page | | apiUrl | string | No | API URL override. Defaults to https://api.arky.io; normally set only for local development | | market | string | No | Initial market key used for prices, taxes, payment methods, and cart context | | locale | string | No | Initial storefront locale | | sessionStorage | StorefrontSessionStorage | No | Explicit request-local visitor-session storage adapter for stateful SSR |

Locale and market are independent. If either is omitted, Arky uses the Store’s configured default. Change them explicitly with arky.setContext(); the SDK does not guess a market from the locale.

Framework Setup

React

import { initialize } from 'arky-sdk/storefront';
import { useEffect, useState } from 'react';

export const arky = initialize(process.env.NEXT_PUBLIC_ARKY_PUBLISHABLE_KEY!, {
  market: 'us',
  locale: 'en',
});

export function useCartCount() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    return arky.eshop.cart.item_count.subscribe(setCount);
  }, []);

  return count;
}

Svelte

// src/lib/arky.ts
import { initialize } from 'arky-sdk/storefront';

export const arky = initialize(import.meta.env.PUBLIC_ARKY_PUBLISHABLE_KEY, {
  market: 'us',
  locale: 'en',
});
<script lang="ts">
  import { arky } from '$lib/arky';

  const cartCount = arky.eshop.cart.item_count;
</script>

<span>{$cartCount}</span>

Plain TypeScript

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

await arky.eshop.cart.load();
unsubscribe();

Server-Side Usage

Public SSR and static-build reads use the same publishable-key client. Reading content, products, or Store setup does not create a visitor session. Stateful SSR operations require an explicit request-local sessionStorage adapter so one visitor’s arky_vst_... token can never leak into another request.

Trusted backend jobs use the Admin client and a Personal API Token, not the storefront client:

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

export function createServerAdmin() {
  return createAdmin({
    baseUrl: process.env.ARKY_API_URL!,
    storeId: process.env.ARKY_STORE_ID!,
    market: 'us',
    apiToken: process.env.ARKY_API_TOKEN!,
  });
}
Tip

Keep storefronts module-first. Reach for arky.client only when you are building a lower-level storefront call that the high-level modules do not cover yet. It uses the same publishable key and visitor-session boundary.

TypeScript Support

The SDK exports store helpers and platform types:

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

Next Steps