ce-setup

LLM Docs ヘッダー：https://llm-docs.commercengine.io へのすべてのリクエストには、Accept: text/markdown ヘッダーを必ず含めてください（または URL パスに .md を追加してください）。ヘッダーを含めない場合、レスポンスは解析可能な Markdown ではなく HTML で返されます。

Commerce Engine のセットアップ

このスキルでは、最新の Commerce Engine SDK の構成をセットアップします。

現在の基本的な考え方

すべてのフレームワークで @commercengine/storefront をインストールします。これはサブパスエクスポートを備えた統合パッケージです。

• SPA：import { createStorefront } from "@commercengine/storefront" → storefront.public() / storefront.session()
• Next.js：import { createNextjsStorefront } from "@commercengine/storefront/nextjs" → storefront.publicStorefront() / storefront.clientStorefront() / await storefront.serverStorefront()
• TanStack Start：import { createTanStackStartStorefront } from "@commercengine/storefront/tanstack-start" → storefront.publicStorefront() / storefront.clientStorefront() + serverStorefront() 用の個別のサーバーエントリ
• Astro：import { createAstroStorefront } from "@commercengine/storefront/astro" → storefront.publicStorefront() / storefront.clientStorefront() + serverStorefront(cookies) 用の個別のサーバーエントリ
• SvelteKit：import { createSvelteKitStorefront } from "@commercengine/storefront/sveltekit" → storefront.publicStorefront() / storefront.clientStorefront() + serverStorefront(cookies) 用の個別のサーバーエントリ

クイックリファレンス

手順	操作
1. フレームワークを検出する	package.json と設定ファイルを確認します
2. SDK をインストールする	@commercengine/storefront（すべてのフレームワーク）
3. ストアフロントを初期化する	SPA：createStorefront(...)、Next.js：createNextjsStorefront(...)、TanStack Start：createTanStackStartStorefront(...)、Astro：createAstroStorefront(...)、SvelteKit：createSvelteKitStorefront(...)
4. 環境変数を設定する	Next.js：NEXT_PUBLIC_*、TanStack Start / SPA：VITE_*、Astro / SvelteKit：PUBLIC_*
5. セッションを初期化する	SPA：セッションを起動時に事前設定する場合は、sdk.ensureAccessToken() を一度呼び出します。SSR フレームワーク：クライアントコンポーネントで storefront.bootstrap() を呼び出します
6. 適切なアクセサーを使う	公開データの読み取り：publicStorefront() / public()、セッションフロー：clientStorefront() / serverStorefront() / session()
7. Hosted Checkout（使用する場合）	必須：双方向のトークン同期を伴う authMode: "provided"（Storefront SDK を使うすべてのアプリ）

標準的なセットアップ（Storefront + Hosted Checkout）

アプリが Storefront SDK と併せて Hosted Checkout を使用する場合、双方向のトークン同期を伴う authMode: "provided" は必須であり、任意ではありません。SDK は API 呼び出し用に独自のセッションを管理します。provided モードを使わないと、チェックアウトによって独立した 2 つ目のセッションが作成されます。以下が標準的なセットアップです。

• Storefront SDK がセッション状態を管理します。
• Hosted Checkout は authMode: "provided" で動作します。
• チェックアウトはルートやコンポーネントのレンダーごとではなく、アプリの起動時に一度だけ初期化します。
• トークンの同期は、両方向で必須です。
  • SDK → チェックアウト：updateTokens(...) 経由
  • チェックアウト → SDK：onTokensUpdated 経由

import {
  BrowserTokenStorage,
  createStorefront,
} from "@commercengine/storefront";
import { getCheckout, initCheckout } from "@commercengine/checkout";

const tokenStorage = new BrowserTokenStorage("myapp_");

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  session: {
    tokenStorage,
    // Note: in SPA (createStorefront), onTokensUpdated is nested inside `session`.
    // In SSR wrappers (createNextjsStorefront / createTanStackStartStorefront),
    // it is a top-level config property — do not nest it under `session` there.
    onTokensUpdated: (accessToken, refreshToken) => {
      getCheckout().updateTokens(accessToken, refreshToken);
    },
  },
});

const sessionSdk = storefront.session();
const accessToken = await sessionSdk.ensureAccessToken();
const refreshToken = await tokenStorage.getRefreshToken();

initCheckout({
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  authMode: "provided",
  accessToken: accessToken ?? undefined,
  refreshToken: refreshToken ?? undefined,
  onTokensUpdated: ({ accessToken, refreshToken }) => {
    void sessionSdk.setTokens(accessToken, refreshToken);
  },
});

フレームワークの検出

package.json と設定ファイルを確認して、フレームワークを特定します。

判定基準	フレームワーク	インポートパス	セッションストレージ
依存関係に next があり、next.config.* がある	Next.js	@commercengine/storefront/nextjs	組み込み（Cookie ベース）
依存関係に @tanstack/react-start がある	TanStack Start	@commercengine/storefront/tanstack-start	組み込み（Cookie ベース）
依存関係に astro がある	Astro	@commercengine/storefront/astro	組み込み（Cookie ベース）
依存関係に @sveltejs/kit がある	SvelteKit	@commercengine/storefront/sveltekit	組み込み（Cookie ベース）
依存関係に nuxt がある	Nuxt	@commercengine/storefront + @commercengine/ssr-utils	ServerTokenStorage
vite.config.* があり、ブラウザーアプリである	React / Vue / Svelte / Solid SPA	@commercengine/storefront	BrowserTokenStorage
依存関係に express がある	Express / Node.js	@commercengine/storefront	MemoryTokenStorage またはカスタムの TokenStorage
上記のいずれにも該当しない	Vanilla JS	@commercengine/storefront	BrowserTokenStorage

判断フロー

User Request: "Set up Commerce Engine" / "Add e-commerce"
    │
    ├─ Read package.json + config files
    │
    ├─ Next.js detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createNextjsStorefront() from @commercengine/storefront/nextjs
    │   │        → Root layout uses storefront.publicStorefront() + StorefrontBootstrap
    │   │        → See ce-ssr-patterns for request-bound usage
    │   └─ NO ↓
    │
    ├─ TanStack Start detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createTanStackStartStorefront() from @commercengine/storefront/tanstack-start
    │   │        → Server-only: createTanStackStartServerStorefront() from .../tanstack-start/server
    │   └─ NO ↓
    │
    ├─ Astro detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createAstroStorefront() from @commercengine/storefront/astro
    │   │        → Server-only: createAstroServerStorefront() from .../astro/server
    │   └─ NO ↓
    │
    ├─ SvelteKit detected?
    │   ├─ YES → Install @commercengine/storefront
    │   │        → Use createSvelteKitStorefront() from @commercengine/storefront/sveltekit
    │   │        → Server-only: createSvelteKitServerStorefront() from .../sveltekit/server
    │   └─ NO ↓
    │
    ├─ Other SSR framework (Nuxt)?
    │   ├─ YES → Install @commercengine/storefront + @commercengine/ssr-utils
    │   │        → Use ServerTokenStorage with CookieAdapter
    │   └─ NO  → Install @commercengine/storefront
    │            → Use BrowserTokenStorage (SPA) or MemoryTokenStorage (Node)
    │
    ├─ Using Hosted Checkout?
    │   ├─ YES → Install @commercengine/checkout
    │   │        → authMode: "provided"
    │   │        → Two-way token sync (SDK ↔ checkout)
    │   └─ NO → SDK-only setup
    │
    └─ Create one storefront factory and use the framework-appropriate accessors

フレームワーク別のセットアップ

Next.js（App Router）

npm install @commercengine/storefront

// lib/storefront.ts
import { Environment } from "@commercengine/storefront";
import { createNextjsStorefront } from "@commercengine/storefront/nextjs";

export const storefront = createNextjsStorefront({
  storeId: process.env.NEXT_PUBLIC_STORE_ID!,
  apiKey: process.env.NEXT_PUBLIC_API_KEY!,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
});

// components/storefront-bootstrap.tsx
"use client";

import { useEffect } from "react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    storefront.bootstrap().catch(console.error);
  }, []);
  return null;
}

ルートレイアウトは Server Component ですが、子として StorefrontBootstrap（Client Component）をレンダリングできます。これは Next.js の標準的なコンポジションです。ブートストラップコンポーネントは、ツリーのできるだけ上位に配置してください。

// app/layout.tsx (Server Component — this is fine)
import { storefront } from "@/lib/storefront";
import { StorefrontBootstrap } from "@/components/storefront-bootstrap";

const { data: storeConfig } = await storefront.publicStorefront().store.getStoreConfig();

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <StorefrontBootstrap />
        <header>{storeConfig?.store_config?.brand.name}</header>
        {children}
      </body>
    </html>
  );
}

Next.js のリクエストモデルの詳細については、ce-ssr-patterns を参照してください。

ホスト型チェックアウトを使用していますか？ トークン同期のパターンについては、ce-cart-checkout と references/hosted-checkout.md を参照してください。

# .env.local
NEXT_PUBLIC_STORE_ID=your-store-id
NEXT_PUBLIC_API_KEY=your-api-key

TanStack Start

npm install @commercengine/storefront

// lib/storefront.ts
import { Environment } from "@commercengine/storefront";
import { createTanStackStartStorefront } from "@commercengine/storefront/tanstack-start";

export const storefrontConfig = {
  storeId: import.meta.env.VITE_STORE_ID,
  apiKey: import.meta.env.VITE_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

export const storefront = createTanStackStartStorefront(storefrontConfig);

// lib/storefront.server.ts (server-only module)
import { createTanStackStartServerStorefront } from "@commercengine/storefront/tanstack-start/server";
import { storefrontConfig } from "./storefront";

const serverStorefrontFactory = createTanStackStartServerStorefront(storefrontConfig);

export function serverStorefront() {
  return serverStorefrontFactory.serverStorefront();
}

// components/storefront-bootstrap.tsx
import { useEffect } from "react";
import { storefront } from "@/lib/storefront";

export function StorefrontBootstrap() {
  useEffect(() => {
    storefront.bootstrap().catch(console.error);
  }, []);
  return null;
}

ルートレイアウト（__root.tsx）に StorefrontBootstrap をマウントします。

# .env
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key

Astro

npm install @commercengine/storefront

// src/lib/storefront-config.ts
import { Environment } from "@commercengine/storefront";
import type { AstroStorefrontConfig } from "@commercengine/storefront/astro";

export const storefrontConfig: AstroStorefrontConfig = {
  storeId: import.meta.env.PUBLIC_STORE_ID,
  apiKey: import.meta.env.PUBLIC_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

// src/lib/storefront.ts
import { createAstroStorefront } from "@commercengine/storefront/astro";
import { storefrontConfig } from "./storefront-config";

export const storefront = createAstroStorefront(storefrontConfig);

// src/lib/server-storefront.ts (server-only)
import { createAstroServerStorefront } from "@commercengine/storefront/astro/server";
import { storefrontConfig } from "./storefront-config";

export const serverStorefront = createAstroServerStorefront(storefrontConfig);

ルートレイアウトのスクリプトでブートストラップし、SSR ページや API ルートでは serverStorefront.serverStorefront(Astro.cookies) を使用します。

Astro のリクエストモデルの詳細については、ce-ssr-patterns を参照してください。

# .env
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key

SvelteKit

npm install @commercengine/storefront

// src/lib/storefront-config.ts
import { Environment } from "@commercengine/storefront";
import type { SvelteKitStorefrontConfig } from "@commercengine/storefront/sveltekit";
import { env } from "$env/static/public";

export const storefrontConfig: SvelteKitStorefrontConfig = {
  storeId: env.PUBLIC_STORE_ID,
  apiKey: env.PUBLIC_API_KEY,
  environment: Environment.Staging,
  tokenStorageOptions: { prefix: "myapp_" },
};

// src/lib/storefront.ts
import { createSvelteKitStorefront } from "@commercengine/storefront/sveltekit";
import { storefrontConfig } from "./storefront-config";

export const storefront = createSvelteKitStorefront(storefrontConfig);

// src/lib/server/storefront.ts (server-only — $lib/server/ is enforced by SvelteKit)
import { createSvelteKitServerStorefront } from "@commercengine/storefront/sveltekit/server";
import { storefrontConfig } from "$lib/storefront-config";

export const serverStorefront = createSvelteKitServerStorefront(storefrontConfig);

ルートの +layout.svelte で onMount を使ってブートストラップし、サーバーの load 関数、フック、アクションでは serverStorefront.serverStorefront(cookies) を使用します。

SvelteKit のリクエストモデルの詳細については、ce-ssr-patterns を参照してください。

# .env
PUBLIC_STORE_ID=your-store-id
PUBLIC_API_KEY=your-api-key

React / Vue / Svelte / Solid（SPA）

npm install @commercengine/storefront

// lib/storefront.ts
import {
  BrowserTokenStorage,
  Environment,
  createStorefront,
} from "@commercengine/storefront";

export const storefront = createStorefront({
  storeId: import.meta.env.VITE_STORE_ID,
  environment: import.meta.env.PROD ? Environment.Production : Environment.Staging,
  apiKey: import.meta.env.VITE_API_KEY,
  session: {
    tokenStorage: new BrowserTokenStorage("myapp_"),
  },
});

// Public reads
const { data: products } = await storefront.public().catalog.listProducts();

// Live session flows
const sessionSdk = storefront.session();
await sessionSdk.ensureAccessToken();

# .env
VITE_STORE_ID=your-store-id
VITE_API_KEY=your-api-key

Node.js / Express

npm install @commercengine/storefront

import {
  Environment,
  MemoryTokenStorage,
  createStorefront,
} from "@commercengine/storefront";

export const storefront = createStorefront({
  storeId: process.env.CE_STORE_ID!,
  environment: process.env.NODE_ENV === "production" ? Environment.Production : Environment.Staging,
  apiKey: process.env.CE_API_KEY!,
  session: {
    tokenStorage: new MemoryTokenStorage(),
  },
});

セッションストレージガイド

ストレージ	用途	永続性	SSR 対応
BrowserTokenStorage	ブラウザー SPA	localStorage	いいえ
CookieTokenStorage	ブラウザーの Cookie / タブ間の Cookie 同期	Cookie	ブラウザーのみ
MemoryTokenStorage	サーバーサイドまたは一時的なストレージ	メモリ内	はい
ServerTokenStorage	リクエスト Cookie を扱う SSR フレームワーク	フレームワークアダプター経由の Cookie	はい

実際の SSR リクエストフローでは、@commercengine/ssr-utils の ServerTokenStorage を使用してください。SSR サーバーの主要なストレージ層として CookieTokenStorage を使用しないでください。

最初の API 呼び出し

公開読み取りはすぐに実行できます。

const { data: products } = await storefront.public().catalog.listProducts();

アプリでライブの匿名／ログイン済みセッションを起動時にすぐ確立したい場合は、起動時に一度だけ実行します。

const sessionSdk = storefront.session();
await sessionSdk.ensureAccessToken();
const { data: wishlist } = await sessionSdk.cart.getWishlist();

sdk.cart.getWishlist()、sdk.cart.addToWishlist()、sdk.cart.getUserCart()、sdk.customer.listAddresses() など、通常のセッション対応 SDK メソッドでは、ensureAccessToken() を手動で呼び出す必要はありません。ミドルウェアとオーバーロードが、セッションの作成と ID の解決を自動的に処理します。アプリで起動時のブートストラップを行う場合は、機能コードのあちこちに ensureAccessToken() を記述するのではなく、起動時に一度だけ呼び出してください。

セッションヘルパー

user_id または customer_id が必要なセッション SDK メソッドの多くには、現在のセッションから自動的に値を解決する引数なしのオーバーロードがあります。ID を手動で取得して渡す必要はありません。たとえば、次のとおりです。

// Preferred — SDK auto-resolves user_id from session
const { data } = await sdk.cart.getUserCart();
const { data: wishlist } = await sdk.cart.getWishlist();
const { data: orders } = await sdk.order.listOrders();
const { data: addresses } = await sdk.customer.listAddresses();

// Only pass IDs explicitly when operating on behalf of a different user (admin scenarios)
const { data } = await sdk.cart.getUserCart({ user_id: "other_user_id" });

引数なしのオーバーロードがあるメソッド（user_id または customer_id を自動的に解決します）：

• カート：getUserCart()、deleteUserCart()、getWishlist()、addToWishlist()、removeFromWishlist()
• 注文：listOrders()
• 顧客：listAddresses()、createAddress()、getAddress()、updateAddress()、deleteAddress()、getLoyaltyDetails()、listLoyaltyPointsActivity()、listCustomerReviews()、listSavedPaymentMethods()、listCustomerCards()

認証クライアントのメソッドでは、引き続き明示的な ID が必要です — getUserDetails({ id })、updateUserDetails({ id }) など。これらの呼び出しで現在のユーザーの ID を取得するには、sdk.getUserId() を使用してください。

セッションヘルパーが引き続き必要な場合

ヘルパー	使用する場面
ensureAccessToken()	セッションを早期に確立したい場合、起動時に一度呼び出します
getAccessToken()	現在のトークンを受動的に読み取ります（Hosted Checkout の初期化に渡す場合）
sdk.session.peekRefreshToken()	現在のリフレッシュトークンを受動的に読み取ります（Hosted Checkout の初期化に渡す場合）
setTokens(accessToken, refreshToken?)	Hosted Checkout から SDK にトークンを同期します
getUserId()	{ id } を明示的に指定する必要がある認証クライアントメソッドに渡します
getUserInfo()	API を呼び出さずに、UI 表示用のユーザー情報（名前、メールアドレス）を読み取ります — JWT からデコードされます
isLoggedIn() / isAnonymous()	条件付きの UI 表示に使用します（ログインボタンとアカウントメニューの切り替え）

sdk.session — Peek と Ensure

session プロパティでは、2 つのモードで細かくアクセスできます。

Peek — 受動的に読み取り、セッションの作成やトークンの更新は行わず、失敗した場合は null を返します：

• sdk.session.peekAccessToken() / peekRefreshToken() / peekUserInfo() / peekUserId() / peekCustomerId()

Ensure — 匿名セッションを作成したり、期限切れのトークンを更新したりする場合があります。失敗した場合は例外をスローします：

• sdk.session.ensureAccessToken() / ensureUserInfo() / ensureUserId() / ensureCustomerId()

副作用なしで現在の状態を取得したい場合（例：トークンを Hosted Checkout の初期化に渡す場合）は、peek を使用してください。他のセッション呼び出しの前に有効なトークンや ID が明示的に必要な場合は、ensure を使用してください。ほとんどのカート、注文、顧客関連メソッドは、すでに内部でセッションを管理します。

環境変数

変数	必須	説明
CE_STORE_ID / NEXT_PUBLIC_STORE_ID	はい	ストアの識別子
CE_API_KEY / NEXT_PUBLIC_API_KEY	はい	ストアフロント API キー
CE_ENVIRONMENT / NEXT_PUBLIC_ENVIRONMENT	いいえ	staging または production

デフォルトヘッダー

SDK は設定で defaultHeaders をサポートしています。これは、顧客グループによって価格やプロモーションが異なる B2B ストアフロントに便利です。

const storefront = createStorefront({
  storeId: "...",
  apiKey: "...",
  defaultHeaders: {
    customer_group_id: "01JHS28V83KDWTRBXXJQRTEKA0",
  },
  session: {
    tokenStorage: new BrowserTokenStorage("myapp_"),
  },
});

ログイン後、ユーザープロフィールまたは認証レスポンスから customer_group_id を設定してください。関連するカタログメソッドには自動的に反映されます。

アナリティクス

アナリティクスはサーバー側で自動的に処理されます。Commerce Engine は Segment の仕様に沿って e コマースイベントを収集します。マーチャントは Admin のインテグレーションを通じて、これらのイベントを Segment、Rudderstack、または類似のツールにルーティングします。ストアフロントのコードでアナリティクスを手動で設定する必要はありません。

よくある落とし穴

レベル	問題	解決策
HIGH	カート／認証／顧客／注文のフローで public() を使用する	実際のユーザーまたは匿名セッションに関する処理には、session() を使用してください
HIGH	SSR サーバーのストレージとして CookieTokenStorage を使用する	@commercengine/ssr-utils の ServerTokenStorage を使用するか、Next.js／TanStack Start 用の組み込みラッパーを使用してください
HIGH	SSR アプリで StorefrontBootstrap を省略する	ルートレイアウトで、storefront.bootstrap() を一度呼び出すクライアントコンポーネントをマウントしてください
MEDIUM	ビルド／プリレンダーのコードで匿名認証を初期化する	代わりに public() を使用してください
MEDIUM	public クライアントと session クライアントで設定を重複させる	1 つの createStorefront(...) ファクトリーを使用してください

関連項目

• ssr-patterns/ - Next.js と TanStack Start の publicStorefront()／clientStorefront()／serverStorefront() パターン
• ssr/ - @commercengine/ssr-utils を使ったカスタム SSR バインディング（Nuxt およびその他の未対応フレームワーク）
• auth/ - 認証フロー
• cart-checkout/ - Hosted Checkout の同期パターン

ドキュメント

• コア SDK: https://www.commercengine.io/docs/sdk
• Next.js インテグレーション: https://www.commercengine.io/docs/sdk/nextjs-integration
• LLM リファレンス: https://llm-docs.commercengine.io/sdk/