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({
  baseUrl: import.meta.env.PUBLIC_ARKY_API_URL,
  storeId: import.meta.env.PUBLIC_ARKY_STORE_ID,
  locale: 'en',
  market: 'us',
  marketForLocale: (locale) => (locale === 'it' ? 'ita' : 'us'),
  navigate: (path) => window.location.assign(path),
});

Then use the modules the page needs:

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

Configuration Options

Option	Type	Required	Description
`baseUrl`	`string`	Yes	API base URL
`storeId`	`string`	Yes	Store ID
`market`	`string`	No	Initial market key used for prices, taxes, payment methods, and cart context
`locale`	`string`	No	Initial storefront locale
`marketForLocale`	`(locale: string) => string \| null`	No	Maps locale changes to a market key
`apiToken`	`string`	No	API token for trusted server-side use
`navigate`	`(path: string) => void`	No	Optional navigation hook for auth and checkout flows
`loginFallbackPath`	`string`	No	Path used when auth-required actions need a login fallback

Framework Setup

React

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

export const arky = initialize({
  baseUrl: process.env.NEXT_PUBLIC_ARKY_API_URL!,
  storeId: process.env.NEXT_PUBLIC_ARKY_STORE_ID!,
  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({
  baseUrl: import.meta.env.PUBLIC_ARKY_API_URL,
  storeId: import.meta.env.PUBLIC_ARKY_STORE_ID,
  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

For trusted backend jobs or custom server routes, use apiToken or the lower-level client. Browser storefronts should not ship private API tokens.

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

export function createServerClient() {
  return createStorefront({
    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 or createStorefront only when you are building a lower-level API connection that the storefront modules do not cover yet.

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

Quick Start - Initialize Arky
E-commerce Store - Build a cart-first storefront
Scheduled Services - Schedule services through the cart
API Reference - Explore lower-level methods