BigCommerce Project Configuration Guide

Introduction

This documentation provides a comprehensive guide for configuring new projects using BigCommerce. Our organization has developed a template containing all the essential components to kickstart a new project. When embarking on a new project, there are three possible scenarios:

• Starting a Project from Scratch
• Incorporating Template Files into the Cornerstone Theme
• Integrating Template Files into an Existing Project

In the following sections, we will explore both of these scenarios in detail, offering step-by-step instructions for each case to ensure a smooth and efficient project setup.

Prerequisites

Before you can integrate template files into an existing project, you need to ensure that certain prerequisites are met. Here's a list of the prerequisites:

1. Node.js 16+ : we recommend using NVM. Some existing projects may require oldest version of Node.
2. Stencil CLI : You must have Stencil CLI installed. If it's not already installed, you can set it up using the following command:

   npm install -g @bigcommerce/stencil-cli

Starting a Project from Scratch

Coming soon...

Incorporating Template Files into the Cornerstone Theme

Coming soon...

Integrating Template Files into an Existing Project

Downloading the Current Theme

1. Create a Repository : Begin by creating a new repository for your project. At Minnek we use GitHub as our main repository platform.

2. Update Repository Pull Request: Go to Repository Settings > General > Pull Requests and uncheck "Allow squash merging" and "Allow rebase merging". By following these steps, you will configure your repository settings to align with the project's requirements and ensure that merge strategies do not conflict with your development process.

3. Update Collaborator and Teams : Ensure that the right team or members give access to the repository, the permission should be “maintainers“.

4. Clone the Empty Repository : You can do this with the following commands:

   git clone <repository-url>

   Replace <repository-url> with the URL of your Git repository.

5. Initialize Stencil : Inside the project folder, with Stencil CLI installed, run the following command:

   stencil init

   During the stencil init process, you will be prompted for specific credentials. These credentials are typically obtained from the client or can be sourced from the BigCommerce admin panel. The project managers always give this information in the right place.

6. Download the Current Theme : Once you have initialized Stencil, you can download the current theme that is applied to the store using the following command:

   stencil download

   This will retrieve the current theme files, which you can later modify to incorporate your template files. During the download process, you may encounter a prompt asking if you want to overwrite existing files. In such cases, make sure to select "Yes" or "Y" to ensure that any conflicting files are updated.

   After the download process is complete, it's important to note that in certain situations, the config.stencil.json and secrets.stencil.json files might be deleted. If this happens, you'll need to reinitialize Stencil just like in Step 3. To do this, run:

   stencil init

With these preliminary steps completed, you are ready to integrate your template files into the existing project.

Please refrain from making any commits at this stage. The .gitignore file has not been added yet, and committing without it may include unwanted files. It's crucial to configure the .gitignore file properly to exclude unnecessary files and directories from version control. Once the .gitignore is in place, you can proceed with your commits.

Incorporating Template Files into the Downloaded Theme

1. Clone the Template Repository : Begin by cloning the repository for the template that you want to incorporate into your project. Note: don't clone this repo into your project, must be on external folder. You can use Git to do this. For example: git clone https://github.com/minnek-digital-studio/bigcommerce-template

2. Copy the Following Directories and Files : After cloning the template repository, you will need to copy the following directories and files into your existing project:

   • .cm
   • .github
   • .husky
   • .vscode
   • assets
   • cypress
   • grunt
   • templates
   • .editorconfig
   • .eslintignore
   • .eslintrc
   • .gitignore
   • .minnekrc.json
   • .nvmrc
   • .release-it.json
   • .stylelintrc
   • babel.config.js
   • commitlint.config.js
   • cypress.config.js
   • Gruntfile.js

3. Merge Files with Existing Ones : When copying the files and directories listed above, be mindful of existing files in your project. If there are conflicts between files in your project and the template files, it's important to merge them carefully. Prioritize the files from the template, but ensure that the merge does not negatively affect the current theme or the downloaded theme.

4. Install Dependencies : After successfully merging the files, it's essential to install the required dependencies. Run the following command to install the necessary dependencies: npm install -DE husky @commitlint/config-conventional @commitlint/cli cypress eslint-plugin-cypress cli-color release-it @release-it/bumper @release-it/conventional-changelog release-it jit-grunt stylelint grunt-stylelint stylelint-config-sass-guidelines stylelint-scss

5. Set Up Husky Scripts : To configure Husky for your project, run the following commands to initialize and install Husky scripts: npx husky install.

   This step is essential for enabling Husky to enforce pre-commit and pre-push hooks, ensuring that your code meets the defined quality standards before being committed or pushed to the repository.

6. Add linter script: To include a linter script in your project, open your package.json file, and within the "scripts" section, add the following line: "theme-check": "npx grunt check".

   This command allows you to run the linters in your project by executing npx grunt check. It's a crucial part of ensuring the code quality and functionality of your project.

By following these steps, you will successfully incorporate the template files into your existing project, ensuring that all the required dependencies are in place for a smooth development experience.

This setup assumes that the project is using JavaScript. In the case of TypeScript, additional steps may be required. It's worth noting that adding TypeScript to existing projects is not a common practice and might involve further adjustments and configurations beyond the scope of this documentation.