Shopify Theme Development Workflow

• Shopify Theme Development Workflow
  • Overview
  • Dev Tools
  • Setup
    • Store Settings
      • .env vars
  • Connecting to the Stores
    • Login to your Shopify account
    • Login to the Store
    • Verify you're logged into the correct store
  • Workflows
    • The Development Store to Production Store Workflow (recommended for any feature development that could break the live site)
    • Production Store Workflow
    • Content Updates Workflow
  • Workflow Commands
    • Login
    • Dev
    • Pushing and Pulling files from Themes
      • github integration
    • Syncing Themes with the Shopify CLI
      • Theme Pull
      • Theme Push
    • Build
  • Contributing
    • Branches
    • gitflow
    • themes
      • Development themes
    • Pull Requests
  • Naming Conventions / Styleguide
  • File Organization
    • Liquid files
    • Admin Snippets
    • Source files
      • JS, CSS, and SVG working files go in the /source folder
      • SVGs
    • Build Config
    • Entry points
    • Linting
      • Linting Tools
      • CLI AutoFormatting
        • Run all linters
        • eslint
        • stylelint
        • theme check
    • Github Actions
      • Setting up Shopify Lighthouse CI GitHub Action
      • Linting Github Action
  • Resources
    • Shopify Resources
    • esbuild
    • Resources from original theme scaffold
    • postcss

Overview

This workflow is setup to handle a 2 store setup: a development store for feature development & testing and a production store for staging and production. The workflow is using the Shopify CLI V3 and esbuild is the build tool for code bundling.

Dev Tools

• Node 16+

• A Package Manager - NPM & NVM recommended

• Shopify CLI

  • provides commands for creating, publishing, deleting themes as well as launching a development server for local theme development
  • installation guide

• VSCode recommended (but not required) editor for working with this project.

  • recommended VS Code extensions
  • settings

Setup

Once you've installed all the needed dev tools follow these steps to get started

npm install

Store Settings

A post-install script will be automatically run after the install step above. It will create a .env file with variables that are needed to successfully connect to the 2 stores used in this workflow. Once created, open the file and set the the following values.

.env vars

STORE_NAME=storeName-production.myshopify.com
DEV_STORE_NAME=storeName-development.myshopify.com
NODE_ENV=

Connecting to the Stores

Login to your Shopify account

As a first step always make sure you have logged into your Shopify account that has the correct permissions granted to access these stores. If you haven't logged in recently make sure to do so as the secure connection required by the CLI does not currently work unless you have an active login session and there's currently no clear error messages indicating such by the CLI.

Login to the Store

To set the store you want to connect to set the NODE_ENV value to either: development or production

Alternatively you can run the following script to quickly switch between stores:

npm run set-store

This script will prompt you to select the store you want to connect to and then list out the themes connected to that store.

Verify you're logged into the correct store

to verify that you are logged into the correct store you can run the following command at any time

shopify theme info

Workflows

Once you've finished setup for the project, you can begin development.

It is recommended that the following branches be connected to the corresponding themes via the github integration

Branch	Theme
develop	Staging
main	Production

The Development Store to Production Store Workflow (recommended for any feature development that could break the live site)

Note, when using this workflow it's important to keep the stores in sync as much as possible -- menus, files, content, code, apps, scripts, discounts, etc.

1. Login to the Development store
2. Branch off of develop (following branching strategies)
3. PR into develop (needs at least 1 approval from a team lead)
   • Make sure to connect your branch to a theme via the github integration for QA/Review
4. PR from develop to main (to be performed by team lead)

If the development store is is not well suited to what you're working on or changes are time sensitive an alternative approach is to bypass using the development store and use the Production Store Workflow

Production Store Workflow

Follow the same workflow as The Development Store to Production Stores Workflow except in step 1 you login to the production store

Content Updates Workflow

Ideally all content updates will flow in the same order as outlined in The Development Store to Production Stores Workflow or the Production Stores Workflow.

When only updating content i.e. no associated code changes those updates can be made directly to the staging theme and once approved PR'd into production.

IMPORTANT, because the staging theme is connected to the develop branch via the github integration, updates will be auto-committed. Thus, it's important that these changes should be only for updates intended to be moved into production. If someone needs a place to test out content updates a new theme should be created for them and connected to a new branch off of the develop branch.

This is not generally recommended but if/when content updates are made directly to the live theme (most likely by non developers using the Shopify store admin) the content should flow back via PRs from main to develop

Workflow Commands

To connect to the store & start the local dev server run:

npm start

Alternatively, you can also independently run the following commands:

Login

Login to the store using the current NODE_ENV:

npm run login

Dev

Start local development in watch mode:

npm run dev

Pushing and Pulling files from Themes

github integration

It is strongly recommended that all theme dev use the github integration.

Once the github integration has been successfully setup it will allow you to connect branches to themes and sync changes in both directions. So changes made via the Shopify admin in those themes will be auto-committed by a shopify-bot to your branch and pushes from your local development environment to github will trigger an auto sync of files to that theme in shopify. When using this technique it is best to only make code changes in you local dev environment and to make content changes via the Customizer in the Shopify admin

Syncing Themes with the Shopify CLI

IMPORTANT pulling files using the Shopify CLI is not generally recommended when using the github integration. However, if you're working from a development theme and want to incorporate the json updates associated with content changes it can be useful to pull down the changes made to those files which are not automatically synced down

Warning, be careful using shopify theme pull without the --only and no-delete flags as it will delete all local files not matching the theme architecture

Theme Pull

Pull changes made in theme editor:

npm run theme-pull <templates/exampleFile.json>

Note this command is just an alias with set flags for shopify theme pull visit docs see all the available options.

Theme Push

npm run theme-push <ThemeName>

Note this command is just an alias with set flags for shopify theme push visit docs see all the available options.

Build

Build files from source to assets:

npm run build

Contributing

Branches

Branches should aim to be specific to a single task and named accordingly. To keep things organized plz try to follow this naming pattern: <type-of-change>/<task-name>. For example: feature/hp-hero

gitflow

Read Branching Strategies

themes

Development themes

Development themes are temporary, themes used for local development (created automatically when running npm run dev or npm start).

Development themes don't show up in the Shopify admin, are deleted when you log out of a store, and are not tied to the branch you are working on. This is important to remember when it comes time to share preview links ( for example for PR reviews). If you share a link to a development theme and then change branches to work on something else that preview link will now be for the current branch not the branch you were working on when you got the preview link.

If you want a preview link that will be tied to a branch you need to either connect the theme via the admin to the branch you're working on or push your development theme to an unpublished theme on your store.

Pull Requests

If your PR is for theme related work remember to connect your branch to a theme before sharing the preview links. Links to Development themes are problematic and should be avoided.

Please remember to fill out all info as needed found in the pull_request_template

Naming Conventions / Styleguide

• Liquid

  • variables should be named in snake_case
  • refer to theme-check for more info about liquid best practices

• Javascript

  • variables use camelCase
  • Follow these JavaScript Naming Conventions (TODO: add internal js naming conventions file)

• HTML / DOM

  • Do Not use xml style tags (eg. use <hr> not <hr />)

• CSS

  • use kebab case as default and BEM for added clarity
  • try to avoid nesting selectors more than 2 levels deep

File Organization

IMPORTANT The file structure needs to follow these guidelines in order for the shopify/github integration to work File and directories that don't match this structure need to be ignored using .shopifyignore

To keep code better organized and to utilize the best of modern CSS and JS this theme uses transpilation tools for all customized CSS and JS files in the source directory. SVG files in the source directory are also transformed into corresponding liquid snippets for ease of use and auto optimizations.

Liquid files

• Snippets, Sections, Layout, and Template folders are all at the root level of the project folder.

Admin Snippets

Use the admin folder for:

• Dashboard code snippets
• Shopify Scripts

More information can be found in ./admin/README.md

Source files

JS, CSS, and SVG working files go in the /source folder

SVGs

builds will auto optimize & convert svgs in source to .liquid snippet files.

• Icons ./source/svg/icons/ will be output as ./snippets/icon-[filename].liquid, and have two classes added to them: .svg-icon and .svg-icon-[filename]
• Graphics (multi-color, or larger & unique images) should be placed in ./source/svg/graphics/, and will be output as ./snippets/graphic-[filename].liquid, and have two classes added to them: .svg-graphic and .svg-graphic--[filename]

NOTE watch mode doesn't detect changes in the svg directory in source so adding files there will not trigger a rebuild

If you have watch mode running and you have added new svgs to source and need new snippets to be created and you don't want to stop and restart the server or if you simply want to only create new snippets and not run a complete build you can run the following command:

npm run transform-svgs

Build Config

esbuild is the build tool used for compiling JS and CSS files. The config file can be found in: build/build.js

Entry points

Currently there are only 2 entry points in the build workflow. 1 for JS files and 1 for SASS => CSS files. The source files for all entrypoints live in the Source directory and have been separated into directories named legacy. This decision has been made in order to keep clear what is new to this repo vs what is not and also to allow for diff configuration of linting tools which at this time is important due to the number of errors being reported in the files from the old repo with the current linting configurations. Entry points for esbuild are imported into this file build/entryPoints which then gets imported into the build config inbuild/build.js

Linting

Linting Tools

• eslint
  • Config: .eslintrc.js
• stylelint-config-recommended
  • Config:.stylelintrc.json
• Theme Check tool provided by Shopify to validate and lint theme files.
  • Config .theme-check.yml
• prettier
  • Config .prettierrc.json

CLI AutoFormatting

Use these commands with caution. ⚠️ Make sure to review changes before committing them. ⚠️ 3rd party scripts should be ignored to prevent breaking changes.

Run all linters

npm run lint

npm run lint-fix

eslint

npm run eslint

npm run eslint-fix

stylelint

npm run stylelint

npm run stylelint-fix

theme check

npm run theme-check

npm run theme-check-fix

Github Actions

Setting up Shopify Lighthouse CI GitHub Action

Shopify/lighthouse-ci-action runs a series of Google Lighthouse audits for the home, product and collections pages. It's important to keep tabs on how scores change with each PR to help mitigate performance degradation over time.

Shopify official Setup guide

Config found here: /.github/workflows/lighthouse.yml

Linting Github Action

This action is currently setup to run all linting tools on push

Config found here: /.github/workflows/linters.yml

Resources

Shopify Resources

• quick start guide for theme developers
• Shopify GitHub Integration
• Theme Check
• Shopify/lighthouse-ci-action
• Shopify GitHub Integration
• Shopify Code Samples
• Dawn

esbuild

• esbuild Docs

Resources from original theme scaffold

• Cart.js
• Bootstrap for Shopify
• Mastering Shopify Themes
• Gavin Ballard
• Disco

postcss

Note postcss isn't currently used in this project adding these here for future reference if we decide to use later

• postcss API
• Postcss Preset Env features