We've released the Enterprise CLI for seamless deployments of Next.js projects on the AWS with complete IaC (Terraform) setup. Learn more
Blazity Logo

Setup & Configuration

Technical setup guide for Enterprise Commerce starter

Introduction

This guide covers the technical configuration steps for Enterprise Commerce starter by Blazity. Follow these instructions to properly set up search, redirects, and make the codebase ready to launch.

Environment variables

As you will see throughout this guide, the .env.local file is used to configure the environment variables, which are the source of truth for the features and settings. If something happens to be not working, it is very likely that the environment variables are not set correctly

Clone the repository

Using Git via HTTPS:

git clone https://github.com/blazity/enterprise-commerce.git && cd enterprise-commerce/starters/shopify-algolia

or using GitHub CLI:

gh repo clone blazity/enterprise-commerce && cd enterprise-commerce/starters/shopify-algolia

Install the dependencies

yarn

Shopify

Shopify is our source for all the product data and e-commerce platform of our choice.

Shopify environment variables

SHOPIFY_STORE_DOMAIN
SHOPIFY_STOREFRONT_ACCESS_TOKEN
SHOPIFY_ADMIN_ACCESS_TOKEN
SHOPIFY_APP_API_SECRET_KEY

Below you will see steps to find the environment variables for your Shopify store that are crucial for the starter to work.

Shopify Store Domain

  • Variable required: SHOPIFY_STORE_DOMAIN
  • How to obtain it: Your Shopify store domain is the URL of your Shopify store. You can obtain it in Shopify dashboard, it should be without https and / at the end of the string. Example: cool-socks.myshopify.com

Headless App

  • Variable Required: SHOPIFY_STOREFRONT_ACCESS_TOKEN
  • Installation and Configuration:
    1. Visit the Shopify Marketplace and search for the Headless commerce application or navigate directly to https://apps.shopify.com/headless.
    2. Install the application, open it, and create a new Storefront within the app.
    3. In the "Manage API Access" section, click on the Manage button next to Storefront API.
    4. Make sure you have enabled unauthenticated_read_product_inventory and unauthenticated_read_customer_tags scopes
    5. Copy the Private access token displayed and place it in your .env file under SHOPIFY_STOREFRONT_ACCESS_TOKEN.

Private Admin App

  • Variables Required: SHOPIFY_ADMIN_ACCESS_TOKEN, SHOPIFY_APP_API_SECRET_KEY
  • Application Setup and Scopes Configuration:
    1. Go to the Shopify admin dashboard, navigate to Settings > Apps and sales channels > Develop Apps, and click on Create app.
    2. After naming and creating your app, move to the Configuration tab.
    3. In the "Admin API access scopes" section, click Edit and select the following scopes:
    • write_product_listings
    • read_product_listings
    • read_products
    • write_products
    1. Under Webhook subscriptions, choose the 2024-01 API version.
    2. Lastly, navigate to the API Credentials section.
    • Copy the Admin API access token and place it in your .env.local file under SHOPIFY_ADMIN_ACCESS_TOKEN

Shopify App API Secret Key

  • Variable required: SHOPIFY_APP_API_SECRET_KEY
  • How to obtain it:
    1. Launch the Terminal of your choice (e.g. Ghostty or iTerm or MacOS built-in Terminal)
    2. Run the following command to generate the API secret key
    node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
    1. Copy the generated key and place it in your .env.local file under SHOPIFY_APP_API_SECRET_KEY

Shopify Webhooks

As Shopify serves as a source of truth for the product data but the direct requests are not made to its API from the storefront, you need to set up webhooks to correctly update and sync the data in the Algolia indices each time the product/category is updated in the Shopify.

Webhooks configuration

In order for the webhooks creation scripts to work, all Shopify-related environment variables need to be set in the root level of the shopify-algolia starter.

Prepare your URL that project's API will be accessible publicly. It can be URL of a deployment from the Vercel dashboard. The script will handle appending the path of an sync endpoint to the domain

If you're on localhost, we recommend using ngrok to expose your local server to the public internet.

The URL will be passed to the webhooks creation script's --domain= argument.

Run the webhooks creation script (assuming you've already cloned the repository and you're in the starters/shopify-algolia directory)

yarn build:scripts && node scripts/dist/webhooks/setup-webhooks.mjs --domain=https://your-domain.com

and replace https://your-domain.com with your actual domain.

Algolia

Algolia environment variables

ALGOLIA_APP_ID
ALGOLIA_WRITE_API_KEY
ALGOLIA_PRODUCTS_INDEX
ALGOLIA_CATEGORIES_INDEX
ALGOLIA_REVIEWS_INDEX

Algolia App ID

  • Variable required: ALGOLIA_APP_ID
  • How to obtain it:
    • Go to your Algolia dashboard
    • Click on "API Keys"
    • Copy the "Application ID"

Algolia Write API Key

  • Variable required: ALGOLIA_WRITE_API_KEY
  • How to obtain it:
    • Go to your Algolia dashboard
    • Click on "API Keys"
    • Copy the "Write API Key"

Algolia Indices

  • Variable required: ALGOLIA_PRODUCTS_INDEX, ALGOLIA_CATEGORIES_INDEX, ALGOLIA_REVIEWS_INDEX (optional)

  • How to setup and obtain them:

    • Products index

      1. Go to your Algolia dashboard to the "Search" section
      2. Click on "Index" dropdown and select "Create Index" at the bottom
      3. Name it products
      4. Copy the name of the index to your .env.local file under ALGOLIA_PRODUCTS_INDEX
      5. Click on "Create"
      6. Navigate to the "Configuration" tab of newly created index
      7. Search for "Searchable attributes" (or searchableAttributes)
      8. Add handle, title, description, id to the list of searchable attributes (it does not matter if they are marked as "ordered" or "unordered")
      9. Search for "Attributes for faceting" (or attributesForFaceting)
      10. Add every single attribute from this list to the Algolia
      [
  "collections.handle",
  "collections.id",
  "flatOptions.color",
  "handle",
  "minPrice",
  "tags",
  "variants.availableForSale",
  "vendor",
  "hierarchicalCategories.lvl0",
  "hierarchicalCategories.lvl1",
  "hierarchicalCategories.lvl2",
  "avgRating"
]

      and mark all of them as "searchable"

      1. Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else)

    • Categories index

      1. Go to your Algolia dashboard to the "Search" section
      2. Click on "Index" dropdown and select "Create Index" at the bottom
      3. Name it categories
      4. Copy the name of the index to your .env.local file under ALGOLIA_CATEGORIES_INDEX
      5. Click on "Create"
      6. Navigate to the "Configuration" tab of newly created index
      7. Search for "Attributes for faceting" (or attributesForFaceting)
      8. Add handle to the list of attributes for faceting (it does not mean if its marked as "searchable" or "not searchable")
      9. Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else)

    • Reviews index (optional)

      • Go to your Algolia dashboard to the "Search" section
      • Click on "Index" dropdown and select "Create Index" at the bottom
      • Name it reviews
      • Copy the name of the index to your .env.local file under ALGOLIA_REVIEWS_INDEX
      • Click on "Create"
      • Navigate to the "Configuration" tab of newly created index
      • Search for "Searchable attributes" (or searchableAttributes)
      • Add product_handle, body, to the list of searchable attributes (it does not matter if they are marked as "ordered" or "unordered")
      • Search for "Attributes for faceting" (or attributesForFaceting)
      • Add product_handle, body, hidden, published to the list of attributes for faceting (it does not matter if they are marked as "searchable" or "not searchable")
      • Click on "Review and Save Settings", then click "Save Settings" in the modal (do not click anything else)

Algolia Sorting Replicas

If you followed the steps above, you should have 3 indices created in Algolia and all the environment variables set. Apart from that, you need to create 5 sorting replicas indices for products

{indexName}_price_desc
{indexName}_price_asc
{indexName}_rating_desc
{indexName}_updated_asc
{indexName}_updated_desc

Sorting Replicas

Sorting replicas are not affecting the .env.local environment variables file. This lives only inside the Algolia dashboard.

  1. Go to your Algolia dashboard to the "Search" section

  2. Click on "Index" dropdown and select previously created products index

  3. Go to the Replicas tab (near Configuration tab)

  4. Click on + Create Replica index

  5. Name it the names from the list, e.g. products_price_desc (since our indexName is products)

  6. Repeat adding the rest of the sorting replicas (you will see them marked as "Draft" in the UI)

  7. Click on Review and Save Settings

  8. Click on Save Settings in the modal (do not click anything else)

  9. Go back to the Algolia dashboard to the "Search" section

  10. Click on "Index" dropdown and select previously created products index

  11. Go to each replica index from the list to theirs corresponding Configuration tab

  12. Search for Ranking and Sorting

  13. Add corresponding sorting rules and fields to each of the replicas (basing on their names), e.g. products_price_desc should have minPrice field and Descending sorting rule.

    Apart from minPrice field for this particular replica index from the example, the remaining fields of your interest for other replicas are: avgRating, updatedAtTimestamp

Initial data sources synchronization

After setting up the crucial environment variables and webhooks (everything from Algolia and Shopify sections), you can start the initial data sources synchronization.

Run the data synchronization script (assuming you've already cloned the repository and you're in the starters/shopify-algolia directory)

yarn build:scripts && node scripts/dist/sync/sync.mjs

The script may run for a while, depending on the size of your Shopify store. It will create the Algolia data inside the indices and sync the products & categories from Shopify to Algolia basing on calculated differences between the datasets.

This script can also be used periodically in development environments if needed.

Enterprise-grade redirects

Inside of the middleware.ts in the starter, there's an import of a file (bloom-filter.json) that contains the output of the bloom filter algorithm. On the other hand, the actual redirects are stored in the lib/redirects/redirects.json file.

In production cases, this probably should not be a file, but a query to some edge storage with extremely low latency, e.g. Vercel Edge Config.

However, in development / less sophisticated cases, this file is good enough and we provide a straightforward way to generate the bloom filter or seed the filter with example redirects for testing purposes.

Generating the filter and redirects

Run the redirects seeding script (assuming you've already cloned the repository and you're in the starters/shopify-algolia directory)

yarn build:scripts && node scripts/dist/redirects/generate-test-redirects.mjs --count=10000 --output=lib/redirects/redirects.json

After successfull execution, you will have 10k redirects inside the lib/redirects/redirects.json directory. This file is automatically used by the /api/redirects/ endpoint to check the redirect's details.

After seeding the redirects, you actually need to generate the bloom filter.

yarn build:scripts && node scripts/dist/redirects/generate-bloom-filter.mjs --input=lib/redirects/redirects.json --output=lib/redirects/bloom-filter.json

After successfull execution, you will have the bloom filter inside the lib/redirects/bloom-filter.json directory. This file is automatically used by the middleware.ts file to check if the redirect exists.

Bloom filter

Quick note: After each modification of the redirects, you need to regenerate the bloom filter.

Launch the development server and test if the redirects are working.

Analytics

Vercel analytics are enabled by default. However, you may want to disable it by settings the IS_VERCEL_ANALYTICS_ENABLED environment variable to false in your .env.local file.

Google Analytics

Enterprise Commerce also supports Google Analytics integration through the official Next.js module. While it is disabled by default, you can easily enable it by setting the feature flag IS_GTM_ENABLED in your .env.local file:

IS_GTM_ENABLED=true

Once enabled, the Google Analytics tracking code will be automatically added to your website, allowing you to track and analyze user behavior and traffic data.

Reviews

We use Judge.me as a reviews provider.

JudgeMe environment variables

JUDGE_BASE_URL
JUDGE_API_TOKEN
SHOPIFY_STORE_DOMAIN

You can obtain these by setting up an account on the provider's website and traversing through the dashboard.

Getting started

Introduction to open source enterprise-grade e-commerce platform with Headless Next.js, Algolia middle layer and Shopify backend

Hierarchical Categories

Narrow results for large subset of products

On this page