Skip to content
Malouf Developer Docs

Environment Setup

As you can see from our site list, we have various projects and stacks we use. For this particular setup guide we will be focusing on our BigCommerce stores and the structure of our catalog sites. We currently have the most tasks and feature requests coming in for our ecommerce sites.

Why BigCommerce?

BigCommerce is a commerce solution provider similar to Shopify, but with more APIs and code flexibility. We have developed themes for our Lucid, Linenspa, Malouf VIP, and Malouf Home stores.

The BigCommerce theme stack is HTML, CSS/SCSS, GraphQL, Handlebars.js, and Stencil.

We would like to build a headless store on an alternate stack in the future (2024).

⚠️ Experimental: Setup Your Environment With Flox

This is an experimental section to setup your entire BigCommerce project with Flox. Flox is a tool that hooks up with Nix to setup your development enviornment on any computer with ease. To get started, follow the steps below on any BigCommerce project.

  1. Install Flox. You can do this by navigating to their website here, selecting the ‘Download’ button, and choosing a download option. Alternatively, you can install flox via Homebrew if you have that installed.
brew install flox
  1. Create and navigate to a folder of all Malouf projects. eg. “Projects”
mkdir ~/Projects && cd ~/Projects
  1. Clone the desired project repository from GitHub. (MaloufHome in this example)
git clone https://github.com/MaloufSleep/surfup-maloufhome.git
  1. Navigate to that folder.
cd surfup-maloufhome
  1. If a .flox folder exists, then you can skip to step 6.
# This section is not filled out. Please reach out to John to set up Flox or wait patiently for this section to be filled out.
  1. Run Flox on your project. Every time you want to start a Flox project, you’ll need to run the following commands.
flox activate

# When running this command for the first time, you'll be prompted to enter a
# store url and token. Those can be found in Box. The token input will be hidden
# for improved security.
# After, all you'll have to do is start the stencil server:

stencil start

BigCommerce Local Development

For initial setup, we will be using the cornerstone-vip repo. Using your git client, pull down the repo and open it in VS Code.

Packages

If you haven’t already, please install npm. We will also be using nvm as our node version manager. Homebrew is an easy way to get both packages (and a lot more) on your machine. If you need help with this step, please reach out to any team member.

Setup Steps

With the above packages installed, please follow the steps below:

  1. Open your terminal and run the Stencil CLI install commands for mac.
  2. Inside the Cornerstone VIP root directory, run npm install
  3. Initialize your config by running stencil init (requires store url, access token, and API host which you will need to get from our team Box account)
  4. Run locally with the command stencil start

Now you should be set up to develop locally! For this particular store, you will need to create an account to login. Use access code MALOUFEMP.

Page Builder

What is page builder you ask? Well, it is apart of the BigCommerce contorl panel that our team and content managers use to change how the site looks. As a team, we are heavily focused on providing features that our content team (or even us) can update on the fly with a CMS.

We build dynamic features for page builder mode so our content team has more flexibility on what they can change. However, we work in all parts of the BigCommerce system and pull data for the site with Handlebars Helpers, GraphQL, and Stencil Utils.

Please feel free to take some time to look around and learn more about the BigCommerce control panel.

As a team we have been working with BigCommerce since 2023, so please reach out with any questions you may have. 🧑🏼‍💻 At some point we all have had the same question or ran into a similar bug.

Widget Builder

Ah, another builder. You might be wondering if widget builder is associated with page builder. Ding! Ding! Ding! We have a winner. Widget builder is the repo we use to build custom widgets for page builder. The widgets we have created or are default to BigCommerce can be found on the right-hand side within page builder.

For the VIP store you set up earlier, we have a repo where we only store widgets.

To get started with widget builder, you will need to pull down the cornerstone-vip-widgets repo with your git client.

Please follow the steps outlined here to install widget builder globally. The cornerstone-vip-widgets repo will act as the parent directory for your widgets in this particular case, so please skip that configuration step.

Once you have widget builder installed, run widget-builder init inside the cornerstone-vip-widgets repo in VS Code. This will prompt you to enter several credentials (client id, access token, and API path). These credentials can also be found in our box account.

Now you are ready to create widgets! Please take a look at the existing widgets in the repo to learn more about the structure, and read up on how to add widgets to the main theme.

Catalog Site Structure

Now that you are more familiar with our BigCommerce stores, let’s introduce you to our catalog sites. We have numerous catalog sites. Bloomington Bed, Salt Flat, University Bed, and Brindle Pets — to name a few.

Why don’t these go on BigCommerce, you ask? Well, because they don’t need a cart or checkout flow. They are simply digital catalogs that our wholesale and specialty retail teams use to show customers what products are available. Hosting these on BigCommerce would be expensive and unnecessary. And we try to live by the KISS methodology. Each catalog site is self contained and can be launced or deactivated without any affect on the other sites.

The catalog sites are on a custom stack consisting of Astro, Tailwind, and Strapi as the CMS. All the sites are hosted on Digital Ocean. If you don’t have an account to Digital Ocean, please reach out to Phil.

Any catalog sites not built on this structure are set to be ported in the coming months. We call this Project Flaming Pigeon. 🕊️ If you know, you know.

Strapi = Backend, Astro = Frontend

We are using the Strapi API as the backend of the catalog sites. And within Asto, we set up code fences to call the API and other data needed for the page. For these reasons we have two folders in the catalog projects. Each folder will need to be opened in a separate code window and different commands made to get them running. An easy way to remember is that Strapi uses Yarn and Astro uses npm.

Once launched, most of these sites only require maintenance every few months. For this reason we won’t be setting up a particular catalog site today. We will just have you install a few packages in preparation.

Also, once you have reached this step, please reach out in the team discord so we can get some accounts created for you on our live Strapi instances. This way you can poke around the CMS.

Getting Started?

Already have a task for a catalog site and want to dig in? Great! We have a set up guide here.

Only when we stop stopping our lives, can we begin to start starting them.

— Professor Whitman, Community

Catalog Site Requirements