Quick Start Guide

Quick Start

Blaze Commerce is how WooCommerce stores go headless with ease. Our open-source platform covers everything from seamless integration and blazing-fast performance to exceptional user experience and SEO optimization for thriving in today’s competitive market.

The following quick start guide is intended to get a headless instance of your Woo store up-and-running in about 15 minutes. It won't look too pretty, but it'll showcase the key elements of Blaze Commerce.

The following guide is broken into the following steps:

  1. Setup a Typesense instance for where all the data necessary for creating your headless store will reside
  2. Install the Blaze Commerce plugin and dependent plugins on your WP/Woo store
  3. Configure the Blaze Commerce plugin
  4. Deploy Blaze Commerce locally
  5. Deploy Blaze Commerce with Vercel

Watch: Deploy a Headless WooCommerce Store in 15 Minutes

Prefer to watch instead of read?

Check out this step-by-step video tutorial where I walk through deploying a headless WooCommerce store using Blaze Commerce in around 15 minutes.

More info about this video guide at Headless WooCommerce: A Comprehensive Guide to Supercharging Your Store (opens in a new tab)

Prerequisites

Software Requirements

  • Node.js (Latest Version) (opens in a new tab) - Ensure that Node.js is installed on your local machine. This is required for running the frontend locally.
  • Running WP/Woo site - This will serve as the backend and where we host the data and user checkout.

Required Accounts

Site Domain Configuration

We’ve chosen to prioritize the front-end development of Blaze Commerce. Since both the 'front-end' and checkout require significant work, we've decided to focus on perfecting the user experience on the front-end first. Checkout-related features are on our roadmap, and we'll tackle them in future updates.

Blaze Commerce requires a separate subdomain for checkout. This allows for more efficient management of the purchasing flow until we roll out those improvements.

If your main site domain is example.com, set the WordPress domain to cart.example.com.

Note: While "cart" is a common choice, you're free to use any subdomain that fits your needs (e.g., checkout.example.com or shop.example.com). Just remember to update any references to cart.example.com in this guide if you use a different subdomain.

Typesense

Typesense is a brilliant open source alternative to Algolia, and is used to deliver the search functionality, providing an instant search experience with typo-tolerance and fast auto-complete suggestions. It's also used for generating the category views and filtering, and is also the repository for all data and configuration options for the headless frontend.

You can use their 14 day free trial with their cloud offering or use their open source project.

Typesense Cloud

The following steps have you create a free trial with Typesense Cloud and grab the necessary credentials for using it with Blaze Commerce.

Create an account on Typesense Cloud

Creatin a new Cluster and API keys

  • Login to your Typesense Cloud using GitHub if you are not logged in. If you have followed the steps above you should be in https://cloud.typesense.org/clusters/new (opens in a new tab)
  • Click Launch
  • After the creation of new cluster you will be in a screen with a pink button "Generate API Keys". So click it after the cluster is created and initialized
  • Once you click "Generate API Keys". it will download a text file containing the following
    • Admin API Key: we use this as the API Key in Blaze Commerce
    • Search Only API Key: we use this in our frontend repo
    • Nodes: we use this as the Typesense host in Blaze Commerce

Creating api key

If for some reason you can't continue the process from above then just create the API Key manually by following the steps below

Typesense Open Source

If you prefer to use their open source project and/or use one of their preconfigured containers, their Typesense Guide (opens in a new tab) is the place to start.

Note: Our Blaze Commerce WP plugin requires an SSL connection with Typesense, so be sure to add a cert (opens in a new tab) to your Typesense instance.

Install WP Theme & Plugins

Now we need to install the handful of plugins necessary to support your new headless frontend.

Theme

Plugins

Install and configure (where necessary) the following plugins.

Step 1. WPGraphQL

WPGraphQL is a free, open-source WordPress plugin that adds a GraphQL API to your WordPress site. This allows developers to query WordPress data in a more flexible, efficient way, compared to traditional REST APIs. It's ideal for headless WordPress setups and works seamlessly with WordPress content structures.

Project Link: https://www.wpgraphql.com/ (opens in a new tab)

Installation: Install and activate via the the WordPress plugin installer by searching wpgraphql.

Step 2. WPGraphQL CORS

WPGraphQL CORS is a WordPress plugin that provides Cross-Origin Resource Sharing (CORS) support for WPGraphQL. It ensures that your WPGraphQL queries can be securely accessed from external domains, which is essential for headless WordPress and third-party integrations.

Project Link: https://github.com/funkhaus/wp-graphql-cors (opens in a new tab)

Installation: Download the WPGraphQL CORS (opens in a new tab) plugin from GitHub, then Install and activate it on your site.

Configure WPGraphQL CORS

Go to GraphQl ➝ Settings ➝ CORS Settings

  1. Enable Add Site Address to "Access-Control-Allow-Origin" header
  2. Extend Access-Control-Allow-Origin” header and add the following, replace example.com with your domain 
     *
 https://example.com
  3. For Extend "Access-Control-Allow-Headers” add 
    set-cookie
woocommerce-session
  4. Enable Send site credentials.
  5. For Samesite cookie mode select LAX
  6. For Cookie domain add localhost or your domain with the dot. See example below 
     .example.com

Step 3. WPGraphQL JWT Authentication

WPGraphQL JWT Authentication is a WordPress plugin that adds JSON Web Token (JWT) authentication capabilities to WPGraphQL. It allows secure authentication for GraphQL queries by issuing and validating JWT tokens, providing a robust and scalable way to authenticate users in headless WordPress environments.

Project Link: https://github.com/wp-graphql/wp-graphql-jwt-authentication (opens in a new tab)

Installation: Download the WPGraphQL JWT Authentication (opens in a new tab) plugin from GitHub, then Install and activate it on your site.

Step 4. WooGraphQL

WooGraphQL is an extension of WPGraphQL that brings WooCommerce functionality into the GraphQL API. It enables developers to query and mutate WooCommerce data, such as products, orders, and customers, through GraphQL, making it a key tool for headless WooCommerce stores.

Project Link: https://woographql.com/ (opens in a new tab)

Installation: Download and activate WPGraphQL WooCommerce (WooGraphQL) from one of the following options:

Step 5. GenerateBlocks

GenerateBlocks is a lightweight WordPress plugin that gives you four powerful blocks to build almost any type of content layout. It's used by Blaze Commerce for composing header, footer and homepage elements with blocks.

Project Link: https://wordpress.org/plugins/generateblocks/ (opens in a new tab)

Installation: Install and activate via the the WordPress plugin installer by searching generateblocks.

Step 6. Rename Plugin Folders

When installing WPGraphQL CORS, WPGraphQL JWT Authentication and WPGraphQL WooCommerce (WooGraphQL) the version number is included in the folder name:

You need to rename those folders to remove the version numbers:

Once this step is completed you should then proceed to the next step.

Step 7. Blaze Commerce WP Plugin

The Blaze Commerce WordPress plugin ensures seamless synchronization between WordPress and your Headless WooCommerce instance.

Project Link: https://github.com/blaze-commerce/blazecommerce-wp-plugin (opens in a new tab)

Installation: Download the Blaze Commerce WP Plugin (opens in a new tab) plugin from GitHub, then Install and activate it on your site.

Note: if you're getting a This plugin cannot be activated because required plugins are missing or inactive. or similar, make sure you've completed the previous step and renamed plugin folders.

Configuring Blaze Commerce Plugin

  1. Go to Blaze Commerce ➝ General Settings in the WordPress admin sidebar
    1. Enable Enable System
    2. API Key is the Admin API Key from Typesense from above steps
    3. Typesense Host is the Typesense node's domain name - This is a naked URL without https://. Note that we only support https connections, so if you're using Typesense Open Source you'll need to add an ssl cert.
    4. Set Store ID to 1 - We use store id to identify a store collection in your Typesense cluster. This allows you to use one cluster for different websites. If you have used store id 1 from another site then use another number to avoid conflict.
    5. Shop domain - this is the frontend domain for your site. Please check Site Domain configuration above. It should exclude https and slashes. eg example.com
    6. Click Save Changes
  2. Go to Regional settings tab
    1. Add your region (this should have zero impact on visitors to your stie - it's for multicurrency, but must be configured for single currency sites for now)
    2. After entering a region, you'll be presented with a Map Regions option - add your country here.
    3. Click Save Changes
  3. Return to the General tab and click Sync All - this link will only show after saving valid Typesense credentials from the above step.

Running Blaze Commerce Frontend Locally

Follow this step if you want to install the headless frontend in your local.

Clone repository

Configure environment variables

  • Go to where you saved the cloned files

  • Create a new file name within the root directory called .env.local

    • The .env.local file must have the following variables
    • IMPORTANT: Change example.com to your wp url.
    NEXT_PUBLIC_WORDPRESS_SITE_URL="https://cart.example.com"
NEXT_PUBLIC_GRAPHQL_URL="https://cart.example.com/graphql"
NEXT_PUBLIC_CHECKOUT_URL="https://cart.example.com/checkout"
NEXT_PUBLIC_LIVE_URL="https://example.com"
NEXT_PUBLIC_COOKIE_DOMAIN=".example.com"
NEXT_PUBLIC_TYPESENSE_PUBLIC_KEY="BYkmODoUgE12mCQEsW1LlzTClMR9UZBt"
NEXT_PUBLIC_STORE_ID="1"
NEXT_PUBLIC_TYPESENSE_HOST="k0ao6lubzq75gpw1p-1.a1.typesense.net"

  • NEXT_PUBLIC_WORDPRESS_SITE_URL - this is the WordPress site url.

  • NEXT_PUBLIC_GRAPHQL_URL - this is the graphql url found in wp-admin ➝ GraphQL ➝ Settings ➝ GraphQL Endpoint

  • NEXT_PUBLIC_CHECKOUT_URL - this is the checkout url of WooCommerce

  • NEXT_PUBLIC_LIVE_URL - this is the frontend URL you choose for the frontend when deployed publicly. Usually we just remove https://cart. from NEXT_PUBLIC_WORDPRESS_SITE_URL

  • NEXT_PUBLIC_TYPESENSE_PUBLIC_KEY - This is the Typesense 'Search Only API Key'.

  • NEXT_PUBLIC_STORE_ID - this is what you set from Blaze Commerce ➝ General Settings ➝ Store Id

  • NEXT_PUBLIC_TYPESENSE_HOST - This is the Typesense Node URL. the same information you entered from Blaze Commerce ➝ General Settings ➝ Typesense Host

  • NEXT_PUBLIC_COOKIE_DOMAIN - this is your wp url without https://cart

    • if your wp url is https://cart.example.com then NEXT_PUBLIC_COOKIE_DOMAIN is .example.com

Commands to run the frontend locally

  1. If you haven't install node.js https://nodejs.org/en/download/package-manager/current (opens in a new tab) please download and install it in your local machine
  2. Once you have node.js installed. Install yarn by opening a command promp and execute the command npm install --global yarn . Click here (opens in a new tab) for details about installing yarn
  3. Go to where you save the files and open command prompt and run the following commands
    1. yarn install - this will install all the dependencies we had for the frontend.
    2. yarn prebuild - this will gather the data needed from wp site to the run the site.
    3. yarn dev - this will run the project locally

Running Blaze Commerce on Vercel

The following steps are required to deploy Blaze Commerce on Vercel and be publicly accessible.

Requires the following account

  1. Login to your GitHub account
  2. Fork our headless-woocommerce (opens in a new tab) repo https://github.com/blaze-commerce/headless-woocommerce/fork (opens in a new tab)
  3. Sign up/ Login to Vercel using your GitHub account
  4. Add a new project - see
  5. Click install so that your repository can be connected to Vercel
  6. Click Import for headless-woocommerce
  7. Open the the .env.local file from the previous step above.
  8. Paste the values into the 'Environment Variables' in the Vercel project.
  9. Click Deploy - This will start the deployment process
  10. Go to Settings > Domains and configure the Vercel project to use your own domain.

You should now be able to access your headless Woo store via your chosen URL.

Who is using Blaze Commerce?

Gourmet Baseket (opens in a new tab), Jackie Mack Designs (opens in a new tab), Admerch (opens in a new tab)

Need help?

If you have any problems with this guide, please reach out to us on our Slack channel (opens in a new tab) and we'll do anything we can to help.

IntroductionWP & Woo features