Skip to main content

Installation

This page provides detailed instructions on how to seamlessly get started with Gesso. It outlines the necessary steps to successfully install and set up Gesso for your use. By following this guide, you will be able to quickly and effectively begin using Gesso for your project.

Prerequisites​

Before proceeding with the installation, it is crucial to review and fulfill the prerequisites outlined in the previous section. This will ensure a smooth and successful installation process of Gesso. Take the time to carefully go through the prerequisites and ensure that all requirements are met before proceeding with the installation steps.

Requirements​

danger

If you are using pnpm make sure you are using v8.11.x or higher. Some issues have been flagged using lower versions

  • Node
  • A node package manager
    • npm
    • yarn
    • pnpm (prefered) v8.11.x or higher
  • An .npmrc file in place.

(optional)​

Design system​

If you plan to create a Design System project and want to sync theme tokens from Figma you will need to have the following.

  • Figma token (access token)
  • Figma ID
info

Figma Token: Generate this by going to https://www.figma.com, login with your acromedia email, go to settings > personal access tokens > generate new token.

Figma ID: This corresponds to the second argument within the Figma space of your designated project. If your are unsure where to get this reach out to someone from UX assigned to your project.

BigCommerce​

If you plan to integrate with BigCommerce you will need to have the following information.

  • X-Auth-Token
  • Store hash
  • Storefront URL
info

Store hash: Login to your BigCommerce Store -> Go to Advanced Settings -> Click API Accounts -> Create API Account (V2/V3 Token) You can find a field named "API Path", with the following structure: https://api.bigcommerce.com/stores/<storehash>/v3.

X-Auth-Token: The X-Auth-Token header uses access tokens to authenticate requests. Create an OAuth API account to generate access tokens. Pass the access token as the value of the X-Auth-Token header of the request you want to authenticate.

Storefront URL: This will be your .mybigcommerce.com address.

Shopify​

If you plan to integrate with Shopify you will need to have the following information.

  • Storefront API token
  • Storefront URL
info

Storefront API token: Login to your Shopify Admin dashboard -> Settings -> Apps and sales channels -> Develop apps. If you already have an app installed and configured, you can simply click into it and find the token under API credentials. Otherwise: Create an app, follow the instructions on your screen to set the Admin and Storefront API scopes, then find your token under API credentials.

Storefront URL: This will be your .myshopify.com address.

Drupal​

If you already have a Drupal instance all you will need is the url. If you do not have one you can choose to create a Drupal project via the script or continue without Drupal.

Creating the project​

We recommend creating a new project using @acromedia/create-gesso, which sets up everything automatically for you.

To create a project, run:

pnpm create @acromedia/gesso
info

If this command fails it's either you're missing a global .npmrc or a local .npmrc (in your current dir). If the problem still exists check your access token.

During the script execution you will be prompted to enter some information specific to your project. Most of the information exists in 1password, your Figma id can be found in the URI of your project's Figma page. If you're unsure of your Figma ID ask your UX lead. Your Figma token should be your Figma access token.

On installation, you'll see the following prompts:

? Enter project name: my-project
? Do you want to create a design system project? Yes
? Enter Figma token: [hidden]
? Enter Figma id: 123abc321cba
? Do you want to create a frontend project? Yes
? Which CMS do you want? Drupal
? Would you like to setup a Drupal backend: No
? Which Commerce platform do you want? BigCommerce
? Enter BigCommerce X-Auth-Token: [hidden]
? Enter BigCommerce Store Hash: 123abc321cba
? Enter BigCommerce Storefront URL: https://my-site.mybigcommerce.com

Once complete two/three new directories will be created under the directory from which you ran the script.

my-project-frontend        my-project-design-system           my-project-backend
  • Frontend (always)
  • Design System (if selected)
  • Backend (if selected)

From here if all the information entered is correct you should have a working frontend with the selected integrations running.

cd my-project-frontend && pnpm dev

Our frontend's leverage the NextJS framework if you are not familiar with NextJS I would start by brushing up on their docs.

Our Design System is based off Material UI, their docs are a good supplement to understanding what components you have access to outside of what's listed in storybook.

Setup lagoon environments​

Once created each project will contain the necessary lagoon Dockerfiles for hosting.

Located under .lagoon/Dockerfile which contains required args listed as

ARG NAME_OF_ARG

As of writing this there is only one required arg to be created in lagoon which is the GITLAB_API_TOKEN.

In order for the frontend / design system to successfully deploy you must ensure you have created build scoped environment variable containing:

See deployments/lagoon on how you can create environment variables.

Congratulations​

☆ 彡(ノ^ ^)ノ Congratulations your ready to get rocking! ヘ(^ ^ヘ)☆ 彡

Next Steps​

  • Checkout the getting started with Drupal guide.
  • Take a look at Integrations for more detail on how integrations work and how you configure / use them.