Setting Up a Local Shopify Theme Development Environment

I recently had the opportunity to customize a Shopify theme.
Since it was my first time working with Shopify, I looked into it and found that I could edit code directly in the Shopify code editor.

However, I felt that working in a familiar editor would be more efficient, so I decided to set up a local development environment.

In this article, partly as a memo for myself, I will introduce how to set up the local environment and the essential Shopify commands.

My environment is Mac, so I haven't checked the operation on Windows.
Since Homebrew and Xcode are required, the process will go smoother if you install both beforehand.

■ Requirements

• Shopify account
• Homebrew: https://brew.sh/
• Xcode: https://apps.apple.com/jp/app/xcode/id497799835?mt=12

What is Shopify?

It is a service that allows you to easily create an e-commerce site.

"Manage everything from SNS integration and SEO to global sales with ease. Make your shop even more user-friendly."

As the description says, it's truly easy to use.
You can easily configure design customizations and create pages like the Top Page directly from the admin panel.

You need to create a Shopify account and a store in advance.
(A 14-day free trial is available.)

Pre-configuration in Shopify Admin and Note Down Required Information

First, we will configure settings in the Shopify admin panel to obtain the following two pieces of information:

• API password
• Theme ID

① Create a Private App

Click on "Apps → Manage private apps".

Initially, there will be no private apps, so click "Create a new private app" to create one.

Enter the "Private app name" and "Emergency developer email".
Then, click to expand "Show inactive Admin API permissions".

Within the expanded list, change the setting for "Themes: View or manage theme templates and assets" to "Read and write".
Note: Without this step, you won't be able to download or upload themes.

Once finished, click "Save" → "Create app" to complete the process.

② Note Down the API Password

Once the private app creation is complete, you will be automatically redirected to a screen displaying various information like "API key" and "password." From this list, please make a note of the "password."

Please be careful not to leak the password to others.

Now that you have obtained the API password, let's move on to the next step.

③ Duplicate the Default Theme "Debut"

By default, the "Debut" theme is active. We will duplicate this theme and proceed with development based on the copy.

If the store is already open, editing the active theme directly is risky. (It's scary to think that the site might stop working due to an error.)
To avoid such issues, we will duplicate the existing theme before starting development.

Select "Online Store → Themes" from the left sidebar, then choose "Current theme → Debut → Actions" and select "Duplicate."
A theme named "Copy of Debut" will then be created in your "Theme library."

If you want to change the theme name, you can do so from "Actions → Rename."
In this case, I named it Debut-copy.

Once the theme has been duplicated, click the "Customize" button to navigate to the next page.

④ Note Down the Theme ID

Once the page has changed, please pay attention to the URL displayed at the top of your browser.
It should look something like https://xxx.myshopify.com/admin/themes/115540426945/editor, so make a note of the numbers between "/themes/" and "/editor" in this URL.
This will be your Theme ID (in the example above, 115540426945 is the Theme ID).

This completes the configuration in the Shopify admin panel. Now that we have obtained the necessary information such as the API password and Theme ID, let's proceed with operations in the terminal.

Install Shopify Theme Kit

Launch the terminal and enter the following commands.
This will begin the installation of Shopify Theme Kit via Homebrew.

brew tap shopify/shopify
brew install themekit // For reinstallation, use: brew reinstall themekit

Shopify Theme Kit is a command-line tool that assists with Shopify theme development.

Depending on your environment, you may be prompted to install Xcode during the process.
You can install it with the following command, but in my case, an error occurred because the previously installed version of Xcode was outdated.

xcode-select --install

To resolve this, I completely uninstalled Xcode once and then reinstalled the latest version of Xcode (12.1) from the App Store.

Get the Duplicated Theme

Once the installation of Shopify Theme Kit is complete, we will retrieve all the template files within the "Copy of Debut" theme we duplicated earlier.

There are two ways to retrieve the theme.

① Retrieve using theme get

theme get -p=[your-password] -s=[you-store.myshopify.com] -t=[your-theme-id]

In the above command, replace [your-password] with the API password you obtained earlier, and [you-store.myshopify.com] with your store's address.
Replace [your-theme-id] with the theme ID you noted down, and then run the command.
Note: Brackets [] are not required.

/*
  Example settings:
  API password: shppa_xxxyyyzzz
  Store URL: hoge.myshopify.com
  Theme ID: 115540426945
*/
theme get -p=shppa_xxxyyyzzz -s=hoge.myshopify.com -t=11554042694

With this, the files for theme ID "11554042694" on Shopify will be downloaded locally,
and the connection between Shopify and your local environment will also be established.

② Create config.yml and Retrieve using theme download

While retrieving the theme with theme get automatically generates config.yml (detailed later), you can also manually create config.yml and download the theme.

Create a config.yml file within the directory where you want to download the theme and describe the following:

config.yml

development:
  password: shppa_xxxyyyzzz
  theme_id: "115540426945" # Debut-copy
  store: hoge.myshopify.com

Next, in the terminal, navigate to the directory where you placed the config.yml and enter the following command:

theme download

This command alone will download the theme (ID: 115540426945).
Since the API password and Theme ID are already defined in config.yml, you don't need to enter -p=shppa_xxxyyyzzz or -s=hoge.myshopify.com like you do with theme get.

There are two ways like this, so use the method that suits you best.

About Config.yml

Before introducing the commands, let me briefly explain Config.yml.
Once you have completed the steps up to "Get the Duplicated Theme", a config.yml will be automatically generated in the following state in your local environment.

config.yml

development:
  password: shppa_xxxyyyzzz
  theme_id: "115540426945" # Debut-copy
  store: hoge.myshopify.com

Initially, "development" (development environment) is the target of the command, but with Shopify Theme Kit, you can reflect changes not only to the development environment but also to the production environment simultaneously.

Although I use the term "environment," you can think of it as "Development Environment = Development Theme" and "Production Environment = Production Theme."

You can also specify excluded files (ignore_files) and more.

Change your config.yml as follows:

config.yml

development: # Development Environment
  password: shppa_xxxyyyzzz
  theme_id: "115540426945" # Debut-copy01
  store: hoge.myshopify.com
  ignore_files: # Specify files to be excluded
    - "*.gif"
    - "*.jpg"
    - config/settings_data.json

production: # Production Environment
  password: shppa_xxxyyyzzz
  theme_id: "115587654678" # Debut-copy02
  store: hoge.myshopify.com

Some of the commands introduced below allow you to specify environments other than "development" using options, which is why I explained config.yml first.
If you are checking operations, it will be smoother to set up config.yml like this beforehand.

Note: If no option is specified, "development" (development environment) is targeted by default.

Various other settings are possible in config.yml. For details, please refer to the official page.
https://shopify.github.io/themekit/configuration/

List of Commands

Now that you've successfully copied the theme to your local environment, I'll introduce the main topic of this article: a list of commands.

Preview the Theme

theme open

Entering the command above will launch your browser and open the preview screen.
Note that it does not support live reloading, so when you change a file, you'll need to refresh the browser to see the changes.
Refer to the table below for options:

Option Flag	Description
--env	Execute by specifying the environment defined in config.yml (--env=production)
-b	Specify the browser to open the URL by name
-E	Display the theme customization screen

In the official documentation, the command option is listed as "-a" instead of "--env," but when I used it, I received the following message and only the "development environment" was previewed:
more than one environment specified for a single environment command
(Translation: More than one environment is specified for a single environment command)

Watch Files

theme watch

Entering the command above starts file monitoring, and any edited files will be automatically uploaded to the server continuously. The log will be displayed in the terminal as follows.
To stop watching, press 「Control + C」.

/* Start Watch (Theme Name: Debut-copy, Theme ID: 11554042694) */
15:41:59 [development] debut-copy watching for file changes to theme 11554042694

// Example of updating assets/theme.css
15:43:00 [development] processing assets/theme.css
15:43:02 [development] Updated assets/theme.css
15:43:26 [development] processing assets/theme.css
15:43:28 [development] Updated assets/theme.css

/* When starting watch for all environments */
theme watch -a

15:41:59 [development] Debut-copy watching for file changes to theme 11554042694

// Example of updating assets/theme.css
15:43:00 [development] processing assets/theme.css
15:43:00 [production] processing assets/theme.css
15:43:02 [development] Updated assets/theme.css
15:43:02 [production] Updated assets/theme.css
15:43:26 [development] processing assets/theme.css
15:43:26 [production] processing assets/theme.css
15:43:28 [development] Updated assets/theme.css
15:43:28 [production] Updated assets/theme.css

Refer to the table below for options:

Option Flag	Description
-a	Execute watch for all environments defined in config.yml
-n	File path or URL. Necessary when combining with tools like live reload
--allow-live	Required when you want to watch files of the live theme (the theme currently applied)

Deploy the Theme

If you deploy without specifying files, all theme files on the Shopify server will be replaced by your local files. Be careful, as any changes made directly in the Shopify code editor will be deleted.

// Deploy all theme files
theme deploy

// Deploy only a specific file
theme deploy assets/theme.css

Refer to the table below for options:

Option Flag	Description
-a	Execute deployment for all environments defined in config.yml
-n	Execute deployment without deleting files added from the admin panel
--allow-live	Required when deploying to the live theme (the theme currently applied)

Download the Theme

When developing with multiple people, some may work in the Shopify admin panel (code editor) instead of locally.
In such cases, if you deploy your local work as is, files might be overwritten, and changes made in the admin panel will be replaced by your local environment's state.

To prevent such situations, it's safer to download the remote theme files once to absorb any differences before starting work locally (similar to Git).

If the development environment setup is complete, re-downloading the theme is easy.
You can download all theme files with the following command:

// Download all theme files
theme download

// Download only specific files
theme download assets/theme.css templates/article.liquid

Remove

Using this command deletes files both locally and remotely.
To avoid accidentally deleting the entire theme, specifying a filename is required with this command.

// Delete assets/theme.css
theme remove assets/theme.css

Option Flag	Description
-a	Execute removal for all environments defined in config.yml
--allow-live	Required if the target file is in the live theme (the theme currently applied)

If you try to delete a file essential to the theme, a message like the following will appear:
" this file is critical and removing it would cause your theme to become non-functional "
This notifies you that the theme might break, but the deletion will still be executed after the notification, so be very careful when deleting files.

Create a New Theme

Use the following command when creating an original theme from scratch.

/*
  Example settings:
  API password: shppa_xxxyyyzzz
  Store URL: hoge.myshopify.com
  Theme name: myTheme
*/
theme new -p=shppa_xxxyyyzzz --store=hoge.myshopify.com --name=myTheme

When the command above is executed, files are generated locally as shown below and simultaneously uploaded to the Shopify server.

[hoge.myshopify.com] theme created
[hoge.myshopify.com] config created
Created assets.
  Created assets/application.js.
  Created assets/application.scss.liquid.
Created config.
  Created config/settings_data.json.
  Created config/settings_schema.json.
Created layout.
  Created layout/theme.liquid.
Created locales.
  Created locales/en.default.json.
Created templates.
  Created templates/page.contact.liquid.
  Created templates/search.liquid.
  Created templates/article.liquid.
  Created templates/blog.liquid.
  ・
  ・
[hoge.myshopify.com] uploading new files to shopify

*Notes on Creating a New Theme

If you execute the "Create a New Theme" command while no theme has been downloaded, new files are simply created, so there's nothing special to worry about.

However, executing "theme new ..." while a theme is already downloaded will duplicate the downloaded theme (and upload it simultaneously).

The logs appearing in the terminal will also be different as shown below.
After executing the command, I was confused for a while because only the theme_id in config.yml changed while other .liquid files remained the same.

// When the command "theme new ..." is executed while the "Debut" theme is already downloaded locally

[hoge.myshopify.com] theme created
[hoge.myshopify.com] config created
Exists templates/customers.
  Exists templates/customers/register.liquid.
  Exists templates/customers/reset_password.liquid.
  Exists templates/customers/account.liquid.
  Exists templates/customers/activate_account.liquid.
  Exists templates/customers/addresses.liquid.
  Exists templates/customers/login.liquid.
  Exists templates/customers/order.liquid.
Exists assets.
  Exists assets/application.js.
  Exists assets/application.scss.liquid.
  ・
  ・

Get Information for All Available Themes

Earlier, I introduced a method to find the theme ID from the URL displayed in the browser, but you can also find it using a command.
By typing the following command, you can retrieve information about themes available in your store (the production theme and the list of themes in the theme library).

theme get --list -p=shppa_xxxyyyzzz -s=hoge.myshopify.com

Running the command above displays the available themes and their associated theme IDs as follows:

Available theme versions:
  [115518406849][live] Debut
  [115540426945] Debut-copy01
  [115587654678] Debut-copy02

The one marked as [live] is the theme currently applied.

This is useful when you want to check a theme ID without opening a browser.

View Help

You can view help for the commands used in Shopify Theme Kit.
Display help with the following command:

// Get a list of all commands and flags
theme help

// Get a list of all flags for a specific command
// e.g., theme open --help or theme deploy --help
theme [command] --help

Conclusion

That's all.
I've explained the Shopify Theme Kit commands while actually running them, and personally, I think it's very similar to Git.
(In fact, maybe they've incorporated Git's logic?)

Unlike WordPress, Shopify doesn't (yet) allow for creating a local environment easily, so as someone accustomed to WordPress, I was initially confused.
However, because the commands are so robust, development work feels very manageable.