Horizon

Horizon is an advanced headless e-commerce theme built with the focus on the subscription capabilities offered by Swell.

Horizon has been developed using a standard Next.js framework, making it accessible for anyone familiar with React to modify.

You can enhance the overall functionality and capabilities of the theme to provide an even better experience for your customers.

If you aren't already familiar with React, Next, Storybook, or Swell, these resources will get you up to speed:

Clone this project repository to your local machine.

The first step will be to set up the environment variables. Create an .env file at the root of the project's directory and add the following entries:

NEXT_PUBLIC_SWELL_STORE_URL: This endpoint should have the following format: https://{YOUR_STORE_URL}.swell.store

NEXT_PUBLIC_SWELL_PUBLIC_KEY: This value refers to a store's public key that can be found inside the Developer > API Keys route in the admin dashboard.

SWELL_STORE_ID: The store's ID. It can be found at the top of the Developer > API Keys route in the admin dashboard.

SWELL_SECRET_KEY: A store's secret key. It can be found inside the Developer > API Keys route in the Admin Dashboard, and it's used to sync the store with the local editor configuration.

SWELL_STOREFRONT_ID: The storefront id you are using Horizon with. It can be found at the top of the Storefronts > All storefronts > your storefront > Developer route in the admin Dashboard.

NEXT_PUBLIC_SWELL_EDITOR: This should be set to true to allow for correct functionality when using the swell editor. In a production environment, you can safely set this to false.

The next step will be setting up the development environment. We recommend installing Node.js through nvm. Afterward, run the following commands to match the project's Node and NPM versions and install the project's dependencies:

nvm install 
npm install -g npm@8 
npm install

This will automatically set up the GraphQL client with end-to-end typings and download the content and settings from your store's editor. Check out the graphql:generate and theme:generate commands on the package.json file for more information.

Lastly, you can start the development server with:

npm run dev

Horizon should now be running on http://localhost:3000 by default.

Once you've followed the steps in Deploy to Vercel. Add the storefront URL to the dashboard by selecting: Storefronts > All storefronts > Actions > edit settings > Storefront URL > Save changes.

You can take a look at the available components and the props they accept by running the storybook npm script:

npm run storybook

Storybook should now be running on http://localhost:6006, unless the port is already taken.

You can use the Editor to create new pages, sections, and edit other theme settings. Prior to accessing the Editor, you'll want to follow the steps detailed in Deploy to Vercel.

In order to access the Editor, select Edit theme after clicking the Actions dropdown under Storefronts > All storefronts. The Edit theme selection will only be visible if you've set NEXT_PUBLIC_SWELL_EDITOR=true.

When creating new pages and sections using the editor, changes are not pushed to production by default. You can click the Preview button in the Editor to preview changes, then select Publish. You'll also want to ensure that the page has the Live toggle enabled.

The config/ folder contains JSON files that dictate the editor's schema and default values. The top-level structure is defined inside of the editor.json file, while the content blocks that make up the dynamic pages are located inside of the content/ folder.

In the prepare step these files are pushed upstream to update the store's editor and afterwards the node script builds-utils/generate-theme.mjs is executed. This script will attempt to fetch the theme data that has been set through the editor, and that can be accessed through the endpoint https://{{your store id}}.swell.store/api/settings. This script can also be ran on its own by using the command npm run theme:generate.

Using this theme data, the script will create a theme.css file that exposes these settings as css variables, so that they can then be used by the Tailwind config and throughout the application.

To modify any of the theme settings, first make the change in the Editor and then re-trigger the script to pull them into the store. Alternatively, you can also modify the theme.css file directly to preview how the changes would look before committing to them in the Editor.

In regards to customizing the editor's schema itself, please see here for more information.

The language settings represent a set of variables that can be translated into multiple languages in the editor and used throughout Horizon.

The config/editor.json file has a lang key which holds all the text variables used throughout the app. If you want to add a new setting follow these steps:

Add the object containing the configuration of the language setting inside lang under the namespace you want (ex: products)

{
  "lang": {
    //...
    {
      "id": "lang.products.premium_member_label",
      "label": "Premium member label",
      "default": "Premium",
      "type": "short_text",
      "localized": true
    }
  }
}

Add a default value in the config/defaults.json for the new setting (under the same path as the id)

{
  "lang": {
    //...
    "products": {
      "premium_member_label": "Premium"
    }
  }
}

Push the new settings to the store by running the sync npm script. This will add the new language setting to the editor's schema.

npm run sync

Use the new language setting in the code with the i18n hook

const i18n = useI18n(); 
const premiumLabel = i18n('products.premium_member_label');

Horizon automatically enters Next.js' preview mode when the NEXT_PUBLIC_SWELL_EDITOR environment variable is set to true. This is done through the preview.ts API route, which sets the cookies necessary to alert Next.js that pages should be rendered on-demand instead of statically. This is important when running alongside the editor so that the changes made within it are immediately reflected in the storefront without requiring a new build.

The calls to the preview.ts API route are done through a useEffect in app.tsx.

Before every commit, the following checks are made:

This process will automatically attempt to fix the formatting and some of the eslint errors and warnings.

ESLint and TypeScript errors will prevent commits from being completed. See lint-staged.config.js and eslintrc.json for more information on the checks that are made.

Deploying Horizon on Vercel is simple and can be accomplished in only a handful of steps. Firstly ensure you have a Vercel account, otherwise you can signup for one here.

You should now have Horizon deployed on Vercel and can add the URL to the dashboard by following the Storefronts > All storefronts > Actions > edit settings > route. Once you've added the URL to the Storefront URL field, select Save changes.