Blog Home

Tutorial: Getting Started With the Starter Kit

 

Understanding the Starter Kit

Over the last year Reaction has changed a lot. As we move toward an event-driven, headless commerce system, one of our first steps was to create a GraphQL API. The main goal for our first iteration of the GQL gateway was to expose all the data & functionality needed to power a retail storefront within the Reaction ecosystem, and as a proof of concept we created the Reaction Next.js Starter Kit, or Starter Kit for short.

While the Starter Kit is currently in active development and is gaining new features every week, it is now stable enough to run within the Reaction ecosystem. We offer a super easy way to get the Reaction ecosystem up and running with Reaction Platform—check out Will Lopez’s how-to post for instructions on setting up the Platform for development on your local machine.

The Starter Kit was built not only to verify the GraphQL API, but also to create a reference storefront using popular frontend technologies. Tools like Next.js, Apollo Client, MobX, and React have created a very approachable starting point for frontend developers new to Reaction, and this reference storefront can serve as an example of the custom frontend possibilities of the Reaction headless commerce ecosystem.


 

Interacting with the Starter Kit

If you’ve followed the steps in Will’s post, you should be up and running with Reaction Platform and have the Reaction Meteor backend available at localhost:3000 and the Starter Kit available at localhost:4000. Since we’re focusing on developing a custom storefront using the Starter Kit, we first need to cover some basic start, stop, test, and build commands.

To interact directly with the Starter Kit using your terminal, you’ll need to change directories from the Platform root into the Starter Kit root by entering cd reaction-next-starterkit.

Now you can check the current state of the Starter Kit container with docker-compose ps and view the server processes in the Docker logs with docker-compose logs -f.

This gives you a quick way to peek into the container and see what’s going on with the Next.js server. (You can easily exit the container logs by pressing the Ctrl+C keys; this should exit out of the logs but not stop any running processes.)

Interacting with the Reaction Next.js Starter Kit

 

Starting & stopping the Starter Kit

Sometimes you may need to stop and restart the Starter Kit without stopping the other pieces of the Platform—for example, after changing an environment configuration or adding a new dependency. To do so, enter docker-compose stop, then follow that with docker-compose ps.

You should see the container is still present, but the state is set to Exit 137, indicating that it’s stopped. To restart in detached mode, simply run docker-compose up -d, then enter another docker-compose ps.

At the end of this sequence, you should see that the container's state is set to Up.

Starting and stopping the Starter Kit

 

Testing the Starter Kit

Many developers like to write tests as they work on features. The Starter Kit comes pre-packaged with Jest & Enzyme for simple unit & component testing. If you run the test command docker-compose run web yarn test, the Starter Kit test should run, and then the test container will exit.

To have your tests watch your codebase, run docker-compose run web yarn test:unit:watch.

This creates a powerful development workflow where you can build Storefront UI against a real API and at the same time run unit and component tests as your code changes. Please check out our testing documentation for more details about common testing patterns used within the Reaction ecosystem.

Unit and component testing for the Starter Kit

     

Building the Starter Kit for production

While developing your storefront, you may need to build the code base for production and run it locally. To do this, you’ll first need to build a Docker production storefront container by running docker build -t reaction-storefront --build-arg BUILD_ENV=production .

Next, you’ll need to stop the development container from earlier in the tutorial, because it’s already using port 4000. Enter docker-compose stop web.

Then start the production container using docker run -d --name storefront -p 4000:4000 --env-file .env --network api.reaction.localhost reaction-storefront.

If the rest of the Platform is still running, then your production container should automatically connect to the ecosystem and start pulling data from GraphQL. (If you need to stop this production container, you can do that with docker stop storefront.)

Building a local production container for your custom Starter Kit build

 

Forking for customization

You’re up and running with the Platform and working with the Starter Kit Docker environment. Now it’s time to create your own fork of the Reaction Starter Kit for your own custom Storefront. Just click the Fork button at the top of the Starter Kit repo to add your own Starter Kit repository under your Github account. Make sure to copy the url of this new repo, and then jump back into the terminal.

From here you’ll need to stop and remove the Docker development container we built back in the first section by entering docker-compose stop && docker-compose rm -f.

This way you won’t have any collisions when trying to run your custom storefront.

Now change directories from the Starter Kit back to the Platform with cd .., then clone your new forked version of the Starter Kit with git clone https://github.com/{github-username}/reaction-next-starterkit.git {myCustomStorefront}.

(Make sure you replace {github-username} with your actual username, and {myCustomStorefront} with the name you want to give the directory where you put your forked version.)

Now change directories into your new custom storefront with cd myCustomStorefront and then run the setup script:bin/setup. The setup script will create the default environment variables needed to integrate your custom storefront with the Reaction Platform.

To start your custom storefront, run docker-compose up -d --build and wait for the storefront to load at localhost:4000.

Forking the Starter Kit repo and cloning it for customization

 

What comes next

Now you’re ready to start creating your own custom storefront. From here the possibilities are endless: You can make use of the existing Reaction frontend tool set, or you can go off on your own, delete the src directory and create your own frontend tooling. If you do choose to go with the Reaction frontend setup, I’ll cover how to customize the design of your new storefront in my next post.

Important note: Since the Starter Kit is still in active development and receiving updates every day, it’s possible that your forked version could have conflicts with upstream changes later added to the Reaction Starter Kit. We’ve come up with a few ways to minimize these problems by utilizing environment variables and specific directories to store customizations, but we can’t promise that your setup won’t be affected down the line. Keep an eye on the Reaction GitHub repos and Gitter chat to stay on top of the latest developments that may affect your installation.

comments powered by Disqus