Skip to main content الرئيسية المنشئون orcaqubits agentic-commerce-skills-plugins spree-typescript-sdk
spree-typescript-sdk Build storefronts and integrations using `@spree/sdk` — the official TypeScript SDK for Spree's API v3 (v5.4+). Covers installation, the resource-builder pattern (`spree.products.list`, `spree.checkout.create`, etc.), Zod schema validation, server-only auth (httpOnly JWTs, never exposing API keys), error handling, typing customizations, and pinning SDK versions to backend Spree releases. Use when integrating Spree into a Next.js / Node.js / TypeScript project.
الانتقال إلى التثبيت سوق المهارات اكتشف واستكشف مهارات الذكاء الاصطناعي التي بناها المجتمع.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
عرض تفاصيل Prompt يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/OrcaQubits/agentic-commerce-skills-plugins --skill spree-typescript-sdkيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
تحميل Zip جاري التحميل... المهن ذات الصلة SOC
استنادا إلى تصنيف SOC المهني
name spree-typescript-sdk description Build storefronts and integrations using `@spree/sdk` — the official TypeScript SDK for Spree's API v3 (v5.4+). Covers installation, the resource-builder pattern (`spree.products.list`, `spree.checkout.create`, etc.), Zod schema validation, server-only auth (httpOnly JWTs, never exposing API keys), error handling, typing customizations, and pinning SDK versions to backend Spree releases. Use when integrating Spree into a Next.js / Node.js / TypeScript project.
Spree TypeScript SDK (@spree/sdk)
Before writing code
Fetch live docs :
Fetch https://spreecommerce.org/docs/developer/sdk/quickstart for the SDK's current API surface.
Inspect the SDK's source / README on GitHub (likely under https://github.com/spree/sdk or as part of the storefront repo) for resource names and parameter shapes.
Check the npm registry page for @spree/sdk for the current version aligned to your Spree backend release.
Read the v5.4 announcement (https://spreecommerce.org/announcing-spree-commerce-5-4/ ) for the SDK's release context.
For the Next.js usage pattern, fetch https://spreecommerce.org/docs/developer/storefront/nextjs/quickstart .
Conceptual Architecture
Why an SDK?
Hand-writing API v3 clients works, but @spree/sdk gives you:
TypeScript types generated against the same OpenAPI spec the backend shipsZod validation of responses so runtime drift is caughtResource-builder pattern (spree.products.list(...)) that mirrors the API
Auth handling — token storage, refresh, cookies
Idempotency-key plumbing for safe retries
Error mapping from HTTP responses to typed exceptions
Installation npm install @spree/sdk
pnpm add @spree/sdk
Pin to the version matching your backend Spree release:
{ "dependencies" : { "@spree/sdk" : "5.4.x" } }
When upgrading Spree, bump both together.
Client Initialization import { createSpreeClient } from '@spree/sdk' ;
const spree = createSpreeClient ({
apiUrl : process.env .SPREE_API_URL !,
publishableKey : process.env .NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY !,
});
(Verify the actual factory name and option shape against the live @spree/sdk docs.)
Resource Builder Pattern The SDK exposes resources mirroring the API:
const products = await spree.products .list ({ limit : 20 , expand : ['default_variant' , 'images' ] });
const product = await spree.products .find ('prod_…' , { expand : ['variants' ] });
const taxons = await spree.taxons .list ();
const cart = await spree.cart .create ();
const cart2 = await spree.cart .addItem ({ variantId : 'var_…' , quantity : 1 });
await spree.checkout .update ({ email : 'guest@example.com' , shippingAddress : { ... } });
const session = await spree.checkout .createPaymentSession ({ paymentMethodId : 'pm_…' });
const order = await spree.checkout .complete ();
await spree.auth .signIn ({ email, password });
const me = await spree.account .find ();
await spree.admin .orders .update ('ord_…' , { internalNote : '...' });
Method names are illustrative — verify against live SDK docs.
Zod Schemas Responses are parsed through Zod schemas:
import { ProductSchema } from '@spree/sdk/schemas' ;
const product = await spree.products .find ('prod_…' );
This catches API shape drift (e.g., your backend is on 5.4.1 but the SDK expects 5.4.3 conventions).
Server-Only Auth Pattern Never expose the admin API key to the browser. In Next.js:
import { cookies } from 'next/headers' ;
import { createSpreeClient } from '@spree/sdk' ;
export async function GET (const token = cookies ().get ('spree_jwt' )?.value ;
const spree = createSpreeClient ({
apiUrl : process.env .SPREE_API_URL !,
publishableKey : process.env .NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY !,
userToken : token,
});
const me = await spree.account .find ();
return Response .json (me);
}
User JWTs go in httpOnly cookies set server-side. Cart tokens go in httpOnly cookies. Public publishable key (pk_…) is fine in browser code (that's its purpose).
Idempotency Keys const order = await spree.checkout .complete ({
idempotencyKey : crypto.randomUUID (),
});
Generate per logical operation; resend on transient failure to avoid double-charging.
Error Handling import { SpreeError , ValidationError } from '@spree/sdk' ;
try {
await spree.cart .addItem ({ variantId : 'var_…' , quantity : 99 });
} catch (err) {
if (err instanceof ValidationError ) {
err.fieldErrors ;
} else if (err instanceof SpreeError ) {
err.code ;
err.requestId ;
}
}
Typing Customizations If your Spree backend exposes custom Metafields or extension fields, extend the SDK's types via module augmentation:
declare module '@spree/sdk' {
interface Product {
metafields : {
my_app : {
launch_date ?: string ;
editor_pick ?: boolean ;
};
};
}
}
Version Pinning The SDK is generated against a specific OpenAPI spec version. Mismatches cause Zod validation failures. Strategy:
Pin @spree/sdk to the exact backend Spree minor (5.4.x).
Upgrade in lockstep with backend deploys.
CI: run a smoke test against your staging backend before promoting.
Implementation Guidance
Recommended Project Layout (Next.js) src/
├── lib/
│ ├── spree.server.ts # createSpreeClient with adminApiKey — server-only
│ └── spree.public.ts # createSpreeClient with publishableKey — safe for browser
├── app/
│ ├── (storefront)/ # public pages
│ └── api/ # Server Actions / Route Handlers
└── types/
└── spree.d.ts # type augmentations
Never import spree.server.ts from a Client Component — Next.js will yell, but it's also a credential leak.
Caching API Responses Use Next.js fetch cache or React cache():
import { cache } from 'react' ;
export const getProducts = cache (async () => {
return await spree.products .list ({ limit : 20 });
});
const products = await spree.products .list ({}, { next : { revalidate : 60 } });
(Verify whether @spree/sdk exposes fetch options pass-through.)
Webhook Verification Sidekick The SDK may expose webhook signature verification helpers:
import { verifyWebhookSignature } from '@spree/sdk/webhooks' ;
const event = verifyWebhookSignature ({
payload : rawBody,
signature : request.headers ['x-spree-webhook-signature' ],
secret : process.env .SPREE_WEBHOOK_SECRET !,
});
Verify in the live SDK docs.
Pagination let cursor : string | undefined ;
do {
const page = await spree.products .list ({ limit : 100 , starting_after : cursor });
for (const product of page.data ) { }
cursor = page.has_more ? page.data [page.data .length - 1 ].id : undefined ;
} while (cursor);
Common Pitfalls
Importing the admin client from a Client Component — exposes the admin key.Pinning to ^5.4.0 instead of 5.4.x — minor releases can change generated schema shapes.Storing JWT in localStorage — XSS-vulnerable; use httpOnly cookies.Not awaiting Zod parse errors — silent stringy responses break runtime.Using the SDK in browser code with admin key — Next.js' server-only enforcement is your friend; opt into it.Ignoring Idempotency-Key — duplicate checkouts on retry. Always verify resource names, method signatures, and option shapes against the live @spree/sdk README and the SDK's TypeScript declarations — the SDK is the youngest part of the Spree ecosystem and is iterating fast.
