Create a theme
You're ready to create a new theme. You might be asking yourself: How can I quickly set up my development environment and start coding?
In this tutorial, you'll use Shopify CLI, Dawn, and the Shopify GitHub integration to create a new theme and upload it to Shopify.
What you'll learn
After you've finished this tutorial, you'll have accomplished the following:
- Set up your local development environment
- Cloned Dawn, Shopify's reference theme
- Previewed changes made to your local code
- Integrated version control into your theme development process
- Pushed theme code to your Shopify store and published your theme
Before you start
Before you start developing themes, do the following:
- If you want to use a development store to build a theme, create or log in to a Shopify Partner account, and then create a development store. We recommend using a development store for this tutorial.
- Note the URL of the store that you want to work on, such as
- Note the GitHub organization or account that you want to connect to your store.
- Make sure that you have a collaborator account or staff account with the the Manage themes permission or Themes permission for the store that you want to work on.
Step 1: Install Shopify CLI
Shopify CLI is a command-line tool that helps you to build Shopify themes. It lets you preview, test, and share changes to themes while developing locally. Follow the instructions below to install Shopify CLI on macOS or Windows. For other platforms, refer to Install Shopify CLI.
To install and run Shopify CLI, you need to have the following installed on your computer:
Review the full requirements for interacting with Shopify CLI in Getting started with Shopify CLI.
Step 2: Initialize a new theme using Dawn
shopify theme init to clone the Dawn Git repository to your local machine.
Dawn is Shopify's reference theme, built for performance, flexibility, and ease of use. You can use Dawn as the starting point for building a theme.
- In a terminal, navigate to the working directory where you want to clone Dawn.
Enter the following command:
You're prompted to enter a name for your theme, such as
my-new-theme-project. The theme is cloned into a folder with the same name.
After the theme is cloned, navigate to the folder:
Step 3: Authenticate with Shopify CLI
shopify login to connect Shopify CLI with the store that you want to work on.
In a terminal, type
shopify login --store <DOMAIN>, where
<DOMAIN>is the store that you want to log into:
In your browser window, log into the account that's attached to the store that you want to use for development.
Step 4: Preview your theme
The command returns a URL that hot reloads local changes to CSS and sections, allowing you to preview changes in real time using the store's data. This preview is only available in Google Chrome.
To serve your theme, run the following command:
In Google Chrome, navigate to
http://127.0.0.1:9292to open the theme preview.
Step 5: Push your theme to a new GitHub repo
Step 6: Install the Shopify GitHub integration and connect your branch to your store
The Shopify GitHub integration lets you connect one or more GitHub accounts and organizations to your Shopify admin, and connect Git branches to themes in your store. This connection helps you to make and track changes to theme code. It also helps you to collaborate with other developers and share progress in real time.
After you commit the initialized theme, you can connect a branch in your repository to your store. The contents of the branch are added as a new, unpublished theme in your theme library.
If you're using a new development store for this tutorial, then you can't set up the GitHub integration on the initial login after the store is created. To connect to GitHub successfully, you need to log out of the store, then log in to it again through the Partner Dashboard.
- From your Shopify admin, go to Online Store > Themes.
- In the Theme library section, click Add theme > Connect from GitHub.
- Log into GitHub.
You're prompted to authorize and install the Shopify Online Store GitHub app. Select whether you want to install the app on your personal account or for your organization.
If you're connecting a repository that belongs to an organization, then select the organization that the repository belongs to.
Select the repository that you want to connect, and then select the branch that you want to connect.
The theme appears in your theme library. Themes connected to GitHub list the repository, branch name, and time of the last commit on the theme card.
After the initial connection is made, all commits to the branch that you selected are pulled into the theme, and all changes you make through the Shopify admin are pushed to the branch.
Step 7: Test your connection
You can test your theme's connection to your GitHub branch by making a small change to your theme code. In this example, we'll update the name of the theme and then verify it in the theme editor.
- Open your repository in an editor. Make sure that you're on the branch that's connected to your theme in the Shopify admin.
- Navigate to the
configfolder, and then open
- In the
theme_infonode, update the theme name to match the name that you gave to your theme using Shopify CLI.
- Save and commit your changes, and then push them to GitHub.
- From your Shopify admin, open the Themes page.
- In the theme library, find the theme that's connected to your branch. The Last saved date should match the time that you pushed your commit to the branch.
- Click Customize to open the theme editor. Beside the repository and branch name, click the menu button
⋯. In the menu, the theme name should match the value that you entered in
Step 8: Publish your theme
If you want to make your theme live on your store, then you can publish it. Because the theme in this example is connected to a GitHub branch, you need to publish it through the Shopify admin or Shopify CLI. This is because GitHub branches can only be connected as unpublished themes.
When you publish a theme that's connected to a GitHub branch, the connection between the branch and the theme is maintained. You can push changes to the GitHub branch to alter the published theme. For example, you might publish a theme that's connected to your
main branch, and then merge changes into it to roll out new theme features. Learn more about branching strategies for the Shopify GitHub integration.
- From your Shopify admin, go to Online Store > Themes.
- In the Theme library section, find the theme that you want to publish, and then click Actions > Publish.
- In the Publish... window, click Publish.
Creating your first theme with our tools is only the first step in building your theme. Consider the following next steps:
Explore the architecture of a theme. Learn more about the structure of a theme, and the role of each file and folder, in our architecture documentation.
Learn how to lint your theme code. Use Theme Check, a linter for Liquid and JSON, to detect errors and enforce Shopify theme and Liquid best practices.
Review our general theme best practices. Shopify themes are powerful and flexible. To use themes to their full potential, and to create great ecommerce experiences, you should build your theme with a set of principles in mind. Our best practices cover topics like performance, accessibility, and design.
Review our workflow best practices. If you're building a theme with a team of developers, or if you want to use build tools or advanced version control strategies, then review our best practices to identify how these strategies can be applied to your Shopify theme development processes.
Consider submitting your theme to the Shopify Theme Store. As a theme partner, you can create themes for the Shopify Theme Store and reach an international audience of millions of entrepreneurs. Learn about the requirements for themes in the Shopify Theme Store, and how to submit your theme.
Prepare to hand off your store to a client. If you're building your theme for a client, then review our best practices for working with merchants.
Learn how to implement features in your theme. You can enable certain Shopify features or add functionality to your theme. Features fall into the following categories:
- Product merchandising
- Pricing and payments
- Delivery and fulfillment
- Customer engagement
- Site navigation and search
- Search engine optimization
- Trust and security
If you're building a theme for a client, or for your own store, then you can pick and choose from these features. If you're building a theme for the Shopify Theme Store, then some of these features need to be included in your theme.