Install and setup the storefront web-app

To test the Unchained Engine we setup the test frontend project Storefront created with React.js and Next.js locally.


This tutorial helps you:

  • Install the storefront web app locally
  • Conntect to the local Unchained Engine via graphQL


The storefront installation requires a Node version > 14.

node --version

Step 1: Installation

The Storefront project is a Next.js based web app and connects to your Unchained Engine through graphQL queries.

  1. First create a new folder for your project to be installed.
mkdir my-storefront-webapp
cd my-storefront-webapp
  1. Use the Unchained initialisation script to download the code.
npm init @unchainedshop
  1. A message prompts you to select the installation template. Choose storefront by using the down key and press enter
? What type of template do you want ›
Full stack e-commerce
Storefront <--
Unchained engine
  1. Next two steps are to select the directory, as we already created a new empty directory you can simply press enter, and whether you want to initialise git which is up to you.
? Directory name relative to current directory
 (press Enter to use current directory) ›
? Do you want Initialize git? no / yes
  1. Install the npm packages
npm install

The installation script downloads, installs and initialises all files and packages required to build and run the storefront web app.

Step 2: Setup connection

Before running the web app, you need to create an .env file in the root directory of my-storefront-webapp and add the graphql API endpoint of your local Unchained Engine to the settings.

printf "UNCHAINED_ENDPOINT=http://localhost:4010/graphql" > .env

Step 3: Start the app

Now, start the app by using the following command. Make sure that the engine runs that you set the UNCHAINED_ENDPOINT environment variable to.

npm run dev

Open localhost:3000 to check your storefront webapp is running correctly.

And that's it!

Your Unchained E-Commerce environment is fully setup and running locally.

(Connect to a remote test Unchained Engine)

If you skipped the step of adding new products and categories as described in the Getting Started - Add Product guide, your store is empty.
With a little update of our .env settings we can change that by connecting to Unchained's remote test engine which contains some prefilled product data.

  • Stop the app: ctrl+c
  • Open the file in the my-storefront-webapp
  • Update the endpoint in the .env file to: UNCHAINED_ENDPOINT=https://engine.swag.unchained.shop/graphql
  • Restart the app:
npm run dev
  • Open localhost:3000 again to see some swaggy products popping up in your store. 😎


Edit on GitHub