This is a Shopify starter MadeByShape use internally for projects. It is intended to be used on top of an existing Shopify theme.
Before running any commands first install node (v20+) and shopify cli globally on your computer.
If you use nvm or fnm, run nvm use / fnm use in the project root to automatically switch to the correct Node version (pinned in .nvmrc).
- Create a new repository for your new Shopify project.
- Add your theme files into the repository.
- Download a copy of this repository to your computer using the Code button above.
- Move these files into your repository.
- Login to your Shopify store and go to Online Store > Themes.
- Connect your new repository as a new theme.
Copy .env.example to .env and update it with your Shopify store ID.
cp .env.example .env
SHOPIFY_STORE=xxxxxx-xx
The .env file is gitignored so each developer can have their own store ID without it being committed.
Run the setup command to install dependencies and copy .env.example to .env in one step:
make setup
Or manually:
npm install
This step will vary per theme, but typically you will need to add the following lines to your layout/theme.liquid file:
Add your custom.css stylesheet link within the <head> tags.
<link rel="stylesheet" href="{{ 'custom.css' | asset_url }}">
Add your custom.js script tag at the bottom of the <body> tag.
<script src="{{ 'custom.js' | asset_url }}" defer="defer"></script>
Once you've completed these steps, you should be ready to start working on your theme!
Commands are available as both make shortcuts and npm run equivalents.
| Make | npm | Description |
|---|---|---|
make setup |
— | First-time setup: copies .env.example → .env and runs npm install. |
make dev |
npm run dev |
Starts Shopify theme dev and Vite watch mode together in one terminal. |
make build |
npm run build |
One-off production build of assets/custom.js and assets/custom.css. |
make shopify |
npm run shopify |
Runs the Shopify site locally only (without the asset watcher). |
make pull |
npm run shopify-pull |
Pulls any CMS changes from your local dev environment into the repository. |
make check |
npm run theme-check |
Runs Shopify's Liquid linter against your theme files. |
By default, the TailwindCSS config is set to prefix all classes with tw-. This is to prevent any issues with the theme's existing CSS classes.
For JS that only needs to load on certain page types, add a file to src/pages/. Vite automatically picks up any .js file in that directory and outputs it as assets/custom-[name].js.
For example, src/pages/product.js becomes assets/custom-product.js. Load it conditionally in layout/theme.liquid:
{% if template == 'product' %}
<script src="{{ 'custom-product.js' | asset_url }}" defer></script>
{% endif %}An example src/pages/product.js is included to get you started.
Source maps are enabled automatically when running in watch/development mode (npm run dev), so browser DevTools will point at your original src/ files. They are disabled in production builds (npm run build).
Some Shopify theme files come with custom.css and custom.js included out the box, so be sure to check this.
You can either overwrite these files if that is possible, OR you can update the naming of them in your setup. To rename the outputs, update the entryFileNames and assetFileNames values in vite.config.js.
Vite is configured to output directly into the assets/ folder without clearing it first (emptyOutDir: false), so existing Shopify theme asset files are never deleted. CSS and JS are both compiled from src/ in a single Vite pass.