Spree 5.4 RC 1 with new API, TypeScript SDK, Next.js storefront, new Payments engine, Multi-region Markets, and full-text search with Meilisearch

We're excited to announce the first Release Candidate of Spree 5.4 — a generational release that transforms Spree into a modern, API-first commerce platform accessible to any developer, regardless of their backend language of choice.

This release includes 500+ commits on top of Spree 5.3 and introduces a new API layer, TypeScript SDK, Next.js storefront, and a completely new developer onboarding experience.

Highlights

Store API v3

A brand new REST API designed for building headless storefronts. Key design decisions:

10x performance over API v2 - new API was rebuilt from the ground up to be as fast as possible
Security in mind - rate limiting, publishable keys, allowed origins - all best practices baked in
Prefixed IDs — all resources use human-readable prefixed identifiers (e.g. prod_86Rf07xd4z, or_m3Rp9wXz) instead of sequential integers
Flat JSON — no nested JSON:API compound documents; simple, unwrapped singular responses and { "data": [], "meta": {} } collections
expand parameter — selectively include related resources without over-fetching
Full TypeScript types — auto-generated from API serializers via Typelizer

TypeScript SDK (`@spree/sdk`)

A fully-typed SDK for interacting with the Store API:

import { createClient } from '@spree/sdk'

const client = createClient({
  baseUrl: 'https://api.mystore.com',
  publishableKey: 'pk_xxx',
})

const products = await client.products.list()
const cart = await client.cart.create()

Flat namespace (client.products, client.cart, client.categories), full autocomplete, and generated Zod schemas for runtime validation.

Next.js Storefront

A production-ready storefront template built with Next.js, React 19, and shadcn/ui. Features a one-page checkout and multi-regional support via Markets. Designed as a starting point, you own and customize — not a locked-down theme.

Payment Sessions API

A unified, provider-agnostic payment interface replacing the legacy payment flow. Works with Stripe, Adyen, PayPal, and any gateway that supports session-based payments:

session_required flag on payment methods distinguishes session-based gateways from direct methods (Check, COD, Bank Transfer)
Two-phase flow: create a Payment Session → customer pays via provider's frontend SDK → complete the session
Full 3D Secure and PCI compliance out of the box — card data never touches your server
Webhook-driven completion ensures payments are captured even if the customer closes their browser

Markets

Multi-region commerce is built into the core. Markets bundle geography, currency, and locale into distinct selling regions within a single store — enabling region-specific pricing, shipping, and tax rules without multi-store overhead.

Full-text search support with Meilisearch

Spree now includes provider agnostic Search Providers with database and Meilisearch providers included in core. Meilisearch is the default choice when using create-spree-app.

`create-spree-app`

Zero-to-running in one command:

npx create-spree-app@latest my-store

Interactive CLI that scaffolds a full-stack project (Docker-based Spree backend + Next.js storefront) or backend-only setup. No Ruby installation required for the Docker path. However, you can freely opt-out from docker and run Spree natively.

Docker-First Deployment

Official multi-arch Docker images (linux/amd64 + linux/arm64) are published to GitHub Container Registry on every release. The Spree CLI (@spree/cli) manages the full lifecycle:

spree init          # First-run setup, seed DB, generate API keys
spree start         # Start all services
spree update        # Pull latest image, run migrations

Additional Improvements

@spree/next package — Next.js integration library with server actions, automatic cookie management, and full TypeScript support
Publishable & Secret API keys — clean separation between client-safe storefront keys (pk_live_) and server-only admin keys (sk_live_)

Feedback

This is a Release Candidate — we'd love your feedback before the stable release. Please report any issues on GitHub Issues and join the discussion on Slack

New Contributors

@samuel-sarmah made their first contribution in #13718

Full Changelog: v5.3.5...v5.4.0.rc1

spree 5.4.0.rc1 v5.4.0.rc1 on Ruby Gems