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 johns-apparel.myshopify.com.
  • 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.

macOS (Homebrew)

Windows (RubyGems.org)

Step 2: Initialize a new theme using Dawn

Use 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.

  1. In a terminal, navigate to the working directory where you want to clone Dawn.
  2. Enter the following command:

  3. 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.

  4. After the theme is cloned, navigate to the folder:

Step 3: Authenticate with Shopify CLI

Use shopify login to connect Shopify CLI with the store that you want to work on.

  1. In a terminal, type shopify login --store <DOMAIN>, where <DOMAIN> is the store that you want to log into:

  2. 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

After you initialize your theme, you can run shopify theme serve to interact with the theme in a browser. Shopify CLI uploads the theme as a development theme on the store that you're connected to.

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.

  1. To serve your theme, run the following command:

  2. In Google Chrome, navigate to http://127.0.0.1:9292 to open the theme preview.

Step 5: Push your theme to a new GitHub repo

You can create an empty GitHub repository, and then add your theme code to it.

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.

  1. From your Shopify admin, go to Online Store > Themes.
  2. In the Theme library section, click Add theme > Connect from GitHub.
  3. Log into GitHub.
  4. 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.

  5. If you're connecting a repository that belongs to an organization, then select the organization that the repository belongs to.

  6. 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.

The card for a theme that's connected to GitHub

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.

  1. Open your repository in an editor. Make sure that you're on the branch that's connected to your theme in the Shopify admin.
  2. Navigate to the config folder, and then open settings_schema.json.
  3. In the theme_info node, update the theme name to match the name that you gave to your theme using Shopify CLI.
  4. Save and commit your changes, and then push them to GitHub.
  5. From your Shopify admin, open the Themes page.
  6. 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.
  7. 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 settings_schema.json.

The name of the  theme is updated in the theme editor

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.

  1. From your Shopify admin, go to Online Store > Themes.
  2. In the Theme library section, find the theme that you want to publish, and then click Actions > Publish.
  3. In the Publish... window, click Publish.

Next steps

Creating your first theme with our tools is only the first step in building your theme. Consider the following next steps: