Shopify-starter-kit

Shopify starter kit is the starter theme and development environment for the largest Shopify stores. Repository makes it easier to work with the distribution of files in the project and automates some tasks. Shopify starter kit based on Shopify Themekit and inspired by Shopify Slate and popular front-end frameworks like a React and Vue.

Shopify starter kit was builded with using technologies and tools:

• Node.js ^14.15.0
• NPM ^7.0.0
• Webpack
• SASS
• Eslint, Stylelint
• Git hooks with prettier + lint-staged
• Shopify Themekit
• Github CI / Gitlab CI

Table of contents

• General info
  • Shopify starter kit in Basic mode
  • Shopify starter kit in Advanced mode
• Getting Started
• Shopify Themekit
  • Configuration for themekit
• File Structure Contract
  • Folders descriptions
• Commands

General info

Shopify starter kit is a tool for comfortable team development of Shopify stores. The main goal of our team was to facilitate the start of new projects. For us, this means a quick start, the use of latest js standards and the use of teamwork tools. We tried to collect the most important things in one place - this is how the Shopify starter kit turned out.

Shopify starter kit support 2 ways to use: basic and advanced modes.

Basic mode

Basic Mode allows to use a Shopify starter kit for existing Shopify repositories. For using this mode, you need to follow a few simple steps:

1. Clone this repo to own project folder
2. Install dependencies
3. Clean out src folder, only scripts folder needs to be keep.
4. Set actual data to the config.yml file
5. Download current shopify store with the command npm run download:theme Then all your store files will be placed into the ./theme folder and everything is ready to go.

All new functionality (scripts and styles) you can add directly to ./src folder. After the build they must be processed and placed in ./dist/assets as build artifacts. We are using webpack: mini-css-extract-plugin for build style files, and it should work at this point.

❗NOTE: If you need to build only js scripts for theme, you don't need to clean up the whole src folder. You should keep a src/scripts. The files in this folder were processed by linters and builders.

Advanced mode

Advanced Mode provides a powerful set for building Shopify stores. This mode makes it easier to work with store pages. An advanced file structure allows you to separate the code between pages and load only the necessary functionality on the page, which increases the speed of the site. The structure also makes it easier to find and fix problems in the code, which speeds up the work of developers.

The advanced mode allows you to use all features of the Shopify starter kit:

• Using the latest JS standard in script files
• Fixed component structure support
• CLI for generating components of this structure
• Separation of styles between pages, which allows optimization loading of styles and scripts, code splitting
• Placing page styles directly in templates to speed up page loading
• Using linting and code styling tools
• Customized auto-corrections style code at the time of commit creation
• Prepared CI/CD for github and gitlab repos

All templates in ./src folder are based on shopify starter theme and provide BEM naming methodology (Block, Element, Modificator). Advanced mode supports partial relocation to the new structure and all files in ./theme folder will work fine.

❗NOTE: This mod is only suitable for those stores where no code changes are expected in the admin panel. In advanced mode, at the moment there is no way to do full syncing with the existing store. All files downloaded from the existing store will be placed in the ./theme folder and there will be no replacement in the structure

Getting Started

For starting core of project you need to do few simple steps:

1. Clone this repo,
2. Install dependencies using npm or yarn. npm install,
3. Create config file: config.yml with correct settings. Can use the config.example.yml as example,
4. Start you project using npm or yarn npm run start or npm run start:prod.

After build all changes will be applied into you selected Shopify theme. Additional information you can find in the Shopify Themekit block.

Shopify Themekit

Don't forget to check theme ids before launching theme kit watcher❗ The command watch starts a process that will watch the directory for changes and upload them to Shopify.

Configuration for Themekit

After cloning the repo, copy config.example.yml and rename the copy to config.yml. The file config.yml should contain development credentials (the current feature theme). The production credentials (the current live theme) is optional.

The current feature theme is the developers's own theme. Starting to work on a new feature the developer must change the development theme_id to the corresponding one every time.

development:
  store: [your-store].myshopify.com
  password: [your-api-password]
  theme_id: "[your-theme-id]"
  ignore_files:
    - config/settings_data.json

Commands

The Shopify starter kit contains many commands for working on a project. Most theme commands are short names for the Shopify Themekit. However, most of it allows you to work with the project itself. Just a few basic commands are described below. A complete list of commands can be found in the package.json file.

Commands short list:

• Download
• Start
• Build
• Deploy
• Creating components
• Analyze

Download

The commands to download the existed shopify stores. We have 2 commands to download theme:

npm run theme:download

or

npm run theme:download:prod

theme:download related to development environment part of your config.yml file,

theme:download:prod related to production environment.

Start

Start command will run a webpack watcher, the Themekit deploy watcher and open a development store in new browser window. By default, this command runs only for development environment.

npm run start

Build

The build command prepare all files for deploy. All files will be processed and placed into ./dist folder. There are supported development and production modes.

npm run build

or

npm run build:prod

The build command is shorthand for webpack run script. By default, it starts with a --progress flag.

Deploy

Command for uploading all files from ./dist folder to your shopify store. Based on Themekit.

npm run deploy

or

npm run deploy:prod

Deploy command it is shorthand of few base commands: lint, build, and Themekit deploy.

Creating components

The Shopify starter kit provides the CLI to creating new entities in own structures. CLI is based on yeoman generator and can be started with the yo command. CLI is supported to creating style, script and liquid files for templates, section, snippets. All templates already used scripts and styles inside the liquid files. You can expand or change it in the generator folder after cloning shopify starter kit.

npm run gen

Analyze

It is CLI command for profiling js assets. Analyze is the shortcut for two commands: webpack --profile and run webpack-bundle-analyzer. You can find more details about profiling in webpack docs webpack profile.

npm run analyze

or

npm run analyze:prod

File Structure Contract

The file structure contract is the main feature of Shopify starter kit. ❗This structure only supports with advanced mode The synchronization between shopify store and file structure doesn't work yet.

/src
 ├── assets
 |    └── index.js
 ├── customers
 |    └── customer-template
 |         ├── section-name
 |         |    ├── section-name.js
 |         |    ├── section-name.liquid
 |         |    └── section-name.scss
 |         ├── customer-template.js
 |         ├── customer-template.liquid
 |         └── customer-template.scss
 ├── templates
 |    ├── common
 |    |    └── common-section-name
 |    |         ├── common-section-name.js
 |    |         ├── common-section-name.liquid
 |    |         └── common-section-name.scss
 |    └── template-name
 |         ├── section-name
 |         |    ├── section-name.js
 |         |    ├── section-name.liquid
 |         |    └── section-name.scss
 |         ├── template-name.js
 |         ├── template-name.liquid
 |         └── template-name.scss
 ├── scripts
 └── snippets
      └── snippet-name
           ├── snippet-name.js
           ├── snippet-name.luqiid
           └── snippet-name.scss
/theme

Js files is optional for sections and template. Please remove this files (and import them into the template) after generation for make you codebase smaller.

Folders descriptions:

./src/assets - folder for assets. They might be images, fonts, any necessary files for shopify store. The same as default Shopify assets folder. By default, files from this folder will be copied to dist without modification. In production mode images will be compressed.

./src/customers - folders for customer templates. Optional.

./src/templates - include all store pages with necessary styles and scripts. Each page should include its own sections. By default, all templates use scripts and styles as webpack entry points.

./src/snippets - are regular snippets with own styles. The styles of each snippet can be included in section, template or theme. By default, snippets styles or scripts are unwatched.

./src/scripts - the main folder functionality. All js files in this folder will be processed with wabpack and placed in ./dist/assets. Can't be empty.

./theme - folder for all shopify files, used in base mode. All files from this folder will be copied to dist without changes. It is recommended to use the npm run gen command to add new components.

Contributing

For help on setting up the repo locally, building, testing, and contributing please see CONTRIBUTING.md.

Code of Conduct

All developers who wish to contribute through code or issues, take a look at the CODE_OF_CONDUCT.md.

License

Copyright (c) 2021 SpiralScout. See LICENSE for further details.