Horizon

Horizon is an open-source, headless storefront starter built with Next.js v12 and React v17 for the Swell ecommerce platform, serving as a reference implementation for creating fully custom storefronts. Originally published as a GitHub repository, it provides a production-ready frontend that connects to Swell's GraphQL API, includes subscriptions, quizzes, multi-currency, i18n, and a component library organized by atomic design.

What is Horizon?

Horizon is a reference example and starter project for building custom Next.js v12 storefronts powered by Swell.js. It takes Swell store credentials and editor configuration as input, and produces a complete storefront with a purchase flow, subscription handling, blog, customer account portal, and dynamic content pages. The project is distributed as a GitHub repository, with a deprecation notice stating the app will not receive updates or bug fixes after March 1, 2024.

What makes Horizon stand out?

• Complete purchase flow — Includes product browsing, cart, checkout, and order confirmation, all wired to Swell's GraphQL API for transaction processing.
• Subscriptions out of the box — Supports recurring products and a customer portal where shoppers can manage orders and subscription plans.
• Quiz-based personalization — Customizable quizzes let shoppers answer questions and get filtered product recommendations, with editor-integrated navigation.
• Multi-currency and i18n — Price formatting follows the active locale and currency, with language variables translatable inside the Swell editor.
• Dynamic content pages — A large, extendable collection of content blocks compose landing pages defined in the Swell editor's page section.
• Product search and filtering — On-site product search and attribute-based filtering help shoppers narrow category pages.
• Live editor integration — Next.js preview mode synchronizes content and theme edits from the Swell editor to the storefront without a rebuild.
• Engineering tooling — TypeScript, TailwindCSS, Storybook, Zustand, Radix UI, Headless UI, Jest, and testing-library are preconfigured, along with Husky and lint-staged for pre-commit checks.

Who should use Horizon?

• Developers building custom Swell storefronts: use Horizon as a starting point to avoid building a headless commerce frontend from scratch.
• Ecommerce teams seeking a headless solution: Horizon decouples the storefront from Swell's backend, enabling a composable architecture.
• Agencies prototyping storefronts: the atomic-design component library and the scaffold script make it fast to restyle and add new UI pieces.
• Merchants needing advanced commerce features: subscription management, quizzes, multi-currency, and a customer portal are prebuilt rather than requiring custom development.

Use cases

• Sell products worldwide: go live with a fully functional storefront that handles product catalogs, checkout, and international currencies and locales.
• Launch a subscription business: set up recurring billing and let customers manage their subscriptions through the included account portal.
• Personalize the shopping experience: configure quiz flows that recommend products and customize dynamic pages for different shopper segments.
• Extend and brand a storefront: use the component library, Storybook, and theme-generation tooling to quickly create a unique front-end.

How does Horizon work?

Horizon is a standard Next.js app that connects to Swell via environment variables. First, create an .env file with your store's URL, public key, store ID, secret key, storefront ID, and editor flag. Then run yarn install, which also generates end-to-end GraphQL typings and downloads editor content. After that, yarn run dev starts the development server on localhost:3000, and yarn run storybook serves the component library on localhost:6006.

FAQ

Is Horizon still maintained?

No. The project's README states that Horizon is provided as-is and will not receive updates or bug fixes from March 1, 2024. Swell itself remains in active development, and Swell recommends using the Swell.js frontend SDK for building full-stack JS storefronts.

What environment variables does Horizon need?

Horizon requires six variables: NEXT_PUBLIC_SWELL_STORE_URL, NEXT_PUBLIC_SWELL_PUBLIC_KEY, SWELL_STORE_ID, SWELL_SECRET_KEY, SWELL_STOREFRONT_ID, and NEXT_PUBLIC_SWELL_EDITOR. These are used for GraphQL requests and syncing theme data from the editor.

Does Horizon support subscriptions?

Yes. Subscriptions are a first-class feature: it supports subscription products, and the customer portal handles recurring order management. The store also supports automatic discounts and one-click add-to-cart.

What styling and UI libraries does Horizon use?

Horizon uses TailwindCSS for styling, and it uses Radix UI and Headless UI for accessible interactive components. Theme colors and typography are fetched from the Swell editor and exposed as CSS variables in a generated theme.css file.