Step 1: Set up required tools

Ensure the required tools are correctly set up:

1. GitHub account
2. GitHub Desktop
3. Shopify CLI
4. Shopify GitHub app (see instructions below)
5. Visual Studio Code

Step 2: Download Shopify theme code

Get the theme files locally to set up with GitHub.

1. Go to folder where you want to store your theme, e.g. /Users/<username>/GitHub
2. Shopify recommends the use the Skeleton theme for custom themes, which can be found at https://github.com/Shopify/skeleton-theme or by running:
   
   shopify theme init

Name of the new theme:
shopify-theme

Include LLM instructions in the theme?
VS Code (GitHub Copilot)

Alternatively, if you want to adjust an existing theme:

1. Log in to your Shopify admin at https://admin.shopify.com/ (or your store's URL).
2. Go to Online Store > Themes.
3. Locate your theme, click the ... (actions) menu, and select Download theme file.
4. Shopify emails you a ZIP file—download it.
5. Unzip to a new folder.

This folder has your theme files (e.g., layout/theme.liquid).

Step 3: Set up Git repository using GitHub Desktop

Use GitHub Desktop for an easier workflow than command line.

1. Open GitHub Desktop.
2. Click File > New Repository (or the "+" button).
3. In the dialog:
   • Name: e.g., "shopify-theme-repo".
   • Local path: Choose your unzipped theme folder.
   • Git ignore: Select "None" or "Liquid" if available (optional).
   • License: None.
4. Click Create Repository. This initializes Git in your folder.
5. Move all theme folders and files into the newly created Git repository.
6. In GitHub Desktop, you'll see all files listed as changes. Enter a commit message like "Initial commit of Shopify theme" in the bottom left, then click Commit to main.
7. To push to GitHub: Click Publish repository (top right). Confirm the repo name, keep it public or private, and publish.
   • This creates the repo on GitHub and uploads your files.
   • Verify on github.com—your repo should show the theme files.

Step 4: Install and connect the Shopify GitHub app

This links Shopify to your GitHub repo for automatic syncing.

1. Install the Shopify GitHub app.
   For more information, check out: https://shopify.dev/docs/api/github-app
2. In Shopify admin, go to Online Store > Themes.
3. In Theme library, click Add theme > Connect from GitHub.
   Add theme can also be called Import theme.
4. Authenticate with GitHub if prompted—log in and grant access to your repo.
5. In the Connect theme panel:
   • Select your GitHub account.
   • Repository: Choose "shopify-theme-repo".
   • Branch: "main".
6. Click Connect. A new theme appears in your library, linked to GitHub.
7. If replacing your current theme, click Publish on the new one (your old theme unpublishes automatically). Remove the old one if unnecessary.

Edits in Shopify now auto-commit to GitHub, and pushes from GitHub update Shopify.

Step 5: Set up Visual Studio Code for editing

Integrate VS Code with your local repo.

1. Open VS Code from Applications.
2. Install extensions:
   • Click the Extensions icon (squares) on the left.
   • Search and install:
     • "Shopify Liquid" by Shopify (for .liquid file support).
     • "Prettier - Code formatter" (for auto-formatting).
     • "GitHub Pull Requests and Issues" by GitHub (for GitHub integration in VS Code—optional but useful).
   • Reload VS Code if asked.
3. Open your theme folder: File > Open Folder, select ~/Documents/my-shopify-theme.
4. VS Code detects the Git repo—see the branch (main) in the bottom left status bar.
5. For GitHub Desktop integration: You can edit in VS Code, then switch to GitHub Desktop to commit/push, or use VS Code's built-in Git (Source Control sidebar) if preferred.

Step 6: Workflow for editing and syncing

A simple routine to make changes safely.

1. Pull Updates: In GitHub Desktop, open your repo and click Fetch origin (or Pull if changes exist) to sync from GitHub/Shopify.
2. Edit Files: In VS Code, modify files (e.g., add code to theme.liquid). Save changes (Cmd + S).
3. Commit and Push:
   • Switch to GitHub Desktop—it shows your changes.
   • Select files, add a message (e.g., "Updated navigation"), and commit.
   • Click Push origin to upload to GitHub.
4. Check in Shopify: Refresh admin > Themes. Changes should appear; preview before going live.
5. Resolve Conflicts: If simultaneous edits cause issues, use GitHub Desktop's merge tools or Shopify's "Reset to last commit" on the theme card.
6. Testing: Use Shopify's theme preview to test edits. For collaboration, invite others via GitHub.