Some of the scripts are influenced by friends at the Stable, I do not take credit for this extremely well-documented readme, although I have modified it.
here is some info about this project:
This theme uses Dawn - 12.0.0 as its base theme.
- Liquid / HTML
- Tailwind + SCSS
- Web Components
- React (3.x)
- Webpack
- Yarn
./
- .browserslistrc: Config file for Browserlist
- .editorconfig: Config file for EditorConfig
- .eslintrc.js: Config file for ESLint
- .gitignore: Config file for gitignore
- .nvmrc: Used to set the NPM version using NVM
- .shopifyignore: Config for Shopify CLI Ignores
- .stylelintrc.js: Config for StyleLint
- package.json: Project metadata & scripts and NPM package dependencies (ref)
- webpack.common.js: Shared config for Webpack
- webpack.dev.js: Local development config for Webpack
- webpack.prod.js: Production config for Webpack
.github/
GitHub utilities like pull-request templates and actions (ref)
shopify/
Shopify theme files get's pushed to Shopify, uses Shopify Theme Architecture
src/
All un-compiled static assets like SCSS (not currently set up) & JS, gets compiled by Webpack which outputs to shopify/assets
- react/: Project React files
Theme Assets
shopify/assets/ is managed by Webpack and can be set to be ignored by .gitignore
It is possible to whitelist files in this directory, see the # [Unignore] Theme and Other Asset Files
section of the .gitignore
Theme Merchandising Files
The following files are ignored in .gitignore to decouple merchandising data from the theme repository and can be pulled in via commands in package.json:
Optionally, you can also ignore:
Ensure the following is installed on your machine (click the links to find install instructions).
- NVM (recommended)
- Shopify CLI (latest)
Run these commands to set the repository up locally.
# Set correct node version.
# - If not installed try: `nvm install $(cat .nvmrc)`
# otherwise install manually using nvm install [VERSION].
# - See nvm --help
# - See .nvmrc
nvm use
# Install deps from the package.json
yarn
# Log into the storefront.
# yarn run login:[dev|prod]
# ex.
yarn run login:prod
# Clean
# - Optional
# - Only needed if you previously had this project cloned
# before this README was updated.
yarn run clean-merch
# Pull down latest merchandising into the repo:
# - See: Appendix: Pulling Theme Merchandising Files
yarn run pull-merch
# Start the Webpack watch and create a Shopify development theme.
yarn run start
# Deploy to an existing preview (or live) theme.
# - Select the theme from the list displayed after running this command.
yarn run deploy
# Deploy to a new Shopify preview theme.
# Name the theme something clear & useful, ex.
# - [PROJ-123] Fix Header on Mobile (Bob)
# - [DEV] Testing (Bob)
yarn run deploy:new
See: package.json for all available commands.
This project uses several tools to ensure code consistency & quality:
- EditorConfig - Editor formatting rules
- Prettier – Javascript, CSS, SCSS formatting
- Prettier VSCode Extension - Editor on demand formatting
- ESLint – Javascript linting (integrated with Prettier)
- StyleLint – CSS, SCSS linting (integrated with Prettier)
- Theme Check – Shopify theme Liquid and JSON linting
Install the following extensions to setup formatting & linting in real time (when applicable, these extensions will autoload local config):
Setting this project up for the first time? Need to add a theme? Review the following information.
# NOTE: Assumes you've already created the repo in GitHub or Bitbucket.
cd path/to/project/folder
git init
git add .
git commit -m "Initial commit"
git remote add origin [REPO_URL]
git push -u
- Find & replace
{client_name}
in the project with the actual client name - Find & replace
client_name
in package.json with the actual client name - Find & replace
{base_theme_name_and_version}
in the README.md with the Base theme name and version: Ex. Dawn 5.0.0 - Find & replace
{base_theme_link}
in the README.md with a link to the base theme
Commit changes to the repo
git add .
git commit -m "Update repo info"
3.1 Prep
- Add the theme to the storefront(s) using Shopify admin (if it hasn't been added already)
- Replace the value of
login:prod
in package.json with the prod storefront URL (excludehttps://
)- For example
"login:prod": "shopify login --store [STOREFRONT_URL]"
- If there is no prod store, do not update it
- For example
- Replace the value of
login:dev
in package.json with the dev storefront URL (excludehttps://
)- For example
"login:dev": "shopify login --store [STOREFRONT_URL]"
- If there is no dev store, do not update it
- For example
Commit changes to the repo
git add .
git commit -m "Update login scripts"
3.2 Pull the theme files from Shopify
Pull theme files using Shopify CLI
nvm use
# NOTE: If using the dev store, run login:dev.
yarn run login:prod
yarn run pull-theme
Commit changes to the repo
git add .
git commit -m "Add theme to repo"
3.3 Add files in shopify/assets to .gitignore
- Add any files in shopify/assets to the "Asset Unignores" section of .gitignore.
Get list of theme files
# NOTE: The `find` command will give us relative paths.
find shopify/assets/*
- Copy and paste the list into .gitignore
- Add a literal
!
character in front of every path
Commit the changes to the repo
git add .
git commit -m "Add theme assets to the repo"
3.4 Update shopify/config/schema_settings.json
- Change the "theme_name" value to
{client_name} Shopify Theme
(max 25 chars) - Change the "theme_version" value to
0.0.1
- Change the "theme_author" value to
The Stable
- Change the "theme_documentation_url" value to the repo URL
- Change the "theme_support_url" value to the repo URL
Commit the changes to the repo
git add .
git commit -m "Update theme schema settings"
Install yarn dependencies
yarn
Commit changes to the repo
git add .
git commit -m "Add yarn.lock"
Depending on your setup, you will need to include compiled assets into the theme. The simplest version of this is adding files like main.js and main.css to theme.liquid
, like so:
<script src="{{ 'script.js' | asset_url }}" defer="defer"></script>
Test webpack:build command
yarn run webpack:build
- Ensure command runs without error
- Ensure theme files in
shopify/assets
are still there - Ensure webpack bundles (main.js|css, checkout.js|css) are in
shopify/assets
Test shopify:serve & webpack:watch
yarn run start
- Ensure theme appears as expected
Test deploy:new command
yarn run deploy:new
- Ensure theme deploys and appears as expected
When the Shopify CLI errors, it can be a bit cryptic:
✗ An unexpected error occurred.
You can get more useful error output from the CLI if you set this env. setting in your terminal and running the failing command again:
export SHOPIFY_CLI_STACKTRACE=1
You can pull the files above into your local project using one or more of the following commands:
Macro Commands
# Pull all merch (templates/*.json, config/settings_data.json, & locales/*.json)
yarn run pull-merch
# Pull all merch from your dev theme (templates/*.json, config/settings_data.json, & locales/*.json)
yarn run pull-dev-merch
# Clean all merch (templates/*.json, config/settings_data.json, & locales/*.json)
yarn run clean-merch
Granular Commands
# Pull templates from the selected theme
yarn run pull:templates
# Pull templates from your development theme.
# - This is useful if you've setup some merchandising on your dev theme
yarn run pull-dev:templates
# Pull config/settings_data.json
# from the selected theme
yarn run pull:config
# Pull config/settings_data.json
# from the your development theme.
# - This is useful if you've setup some merchandising on your dev theme
yarn run pull-dev:config
# Pull locales/*.json from the selected theme.
yarn run pull:locales
# Pull locales/*.json from your development theme.
# - This is useful if you've setup some merchandising on your dev theme
yarn run pull-dev:locales
# Remove these files with the following
yarn run clean:templates
yarn run clean:config
Pulling down other theme files is useful when trying to pull in changes made in Shopify into the repository (for example when an app injects snippets and changes).
It's best to pull the files down into a clean working directory and then use git to inspect changes.
# Check for a clean working directory
# - This should output: nothing to commit, working tree clean.
# - If not, then commit your changes.
git status
# Pull down all theme files from Shopify.
yarn run pull-theme
# Check for changes, additions, and deletions.
git status
# Inspect changes to all files.
git diff
# Inspect changes to one file.
git diff path/to/file.json
Certain conditions may cause the CLI to miss some files in the remote Shopify theme. So far this has been observed when two template/_.json files shared the same _.json name with an additional *.liquid extension.
For example, the CLI may not pull down the *.json version in the following case:
- cart.json
- cart.json.liquid
There isn't an obvious way to get the CLI to pull down the *.json
file.
Workarounds
- Avoid naming files this way (if possible)
- Add the
*.json
file to version control (by adding an explicit unignore to .gitignore) and manually update it regularly (i.e. pulling file contents directly from Shopify and making a commit) - When deploying to a new theme, go to the storefront and manually duplicate a theme and then deploy to it(as opposed to using
deploy:new
)
See: package.json for all available commands.
# Linting
yarn run lint:js
yarn run lint:css
yarn run lint:shopify
# Auto-fix
yarn run fix:js
yarn run fix:css
yarn run fix:shopify
git rm --cached [FILE_PATH]
# This will result in an "untracked" file until you update the .gitignore
git commit -m "Removing [FILE_NAME] from repo"
Then, add the path in .gitignore file and commit your changes.
UNLICENSED