This document describes how we maintain our custom Dawn boilerplate while staying synced with Shopify's upstream Dawn theme.
main (origin/main)
βββ Clean mirror of Shopify/dawn upstream
βββ Syncs with upstream/main for easy updates
βββ NO custom modifications
develop (origin/develop) [DEFAULT BRANCH]
βββ Your custom boilerplate base
βββ Has frontend tooling (pnpm, Vite, Tailwind, TypeScript)
βββ Has src/theme/ restructured directory
βββ Has custom GitHub Actions workflows
βββ Target for all PRs and deployments
boilerplate/X.X.X (e.g., boilerplate/15.4.1)
βββ Version-specific customizations
βββ Based on upstream tags (v15.4.1)
release/X.X.X
βββ Mirror of upstream release branches (for reference)
.
βββ .github/
β βββ actions/ # Composite actions
β β βββ install-dependencies/
β β βββ push-to-preview-theme/
β β βββ stats/
β β βββ preview-summary/
β βββ workflows/ # CI/CD workflows
β βββ on-pr.yml
β βββ on-push-main.yml
β βββ on-close.yml
β βββ deploy-*.yml
βββ src/
β βββ frontend/ # Custom frontend code
β β βββ entrypoints/
β β βββ app.css
β β βββ app.js
β β βββ product-sticky-atc.js
β βββ theme/ # Dawn theme files
β βββ assets/
β βββ config/
β βββ layout/
β βββ locales/
β βββ sections/
β βββ snippets/
β βββ templates/
βββ package.json # pnpm dependencies
βββ pnpm-lock.yaml
βββ vite.config.mts # Build configuration
βββ tailwind.config.js
βββ postcss.config.js
βββ tsconfig.json
βββ shopify.theme.toml # Shopify CLI config
# Fetch latest from upstream
git fetch upstream --tags
# Switch to main and sync
git checkout main
git merge --ff-only upstream/main
# Push to your fork
git push origin main# Pull all upstream tags
git fetch upstream --tags
# Push all tags to your fork
git push origin --tags# For each new upstream release
git checkout -b release/15.4.1 upstream/release/15.4.1
git push origin release/15.4.1When Shopify releases a new Dawn version (e.g., v15.4.1 β v15.5.0):
# Create from your current boilerplate
git checkout -b boilerplate/15.5.0 boilerplate/15.4.1# See what changed between versions
git diff --name-status v15.4.1..v15.5.0
# View commit log
git log --oneline v15.4.1..v15.5.0Since we use src/theme/ instead of root-level theme files, we need to apply changes carefully:
# For modified files in assets/
git show v15.5.0:assets/cart.js > src/theme/assets/cart.js
git show v15.5.0:assets/global.js > src/theme/assets/global.js
# For modified files in sections/
git show v15.5.0:sections/main-product.liquid > src/theme/sections/main-product.liquid
# For modified files in snippets/
git show v15.5.0:snippets/price.liquid > src/theme/snippets/price.liquid
# For new files
git show v15.5.0:snippets/unit-price.liquid > src/theme/snippets/unit-price.liquid# Update all locale files
for locale in bg cs da de el en es fi fr hr hu id it ja ko lt nb nl pl pt-BR pt-PT ro ru sk sl sv th tr vi zh-CN zh-TW; do
git show v15.5.0:locales/${locale}.json > src/theme/locales/${locale}.json 2>/dev/null || true
git show v15.5.0:locales/${locale}.schema.json > src/theme/locales/${locale}.schema.json 2>/dev/null || true
done
# Update config
git show v15.5.0:config/settings_schema.json > src/theme/config/settings_schema.json# Check for new workflow files
git diff --name-only v15.4.1..v15.5.0 .github/
# Review and selectively apply changes
# Note: Keep our custom workflows, only update if necessarygit add -A
git commit -m "Upgrade boilerplate to v15.5.0
Applied upstream changes from v15.4.1 to v15.5.0:
- Fixed cart performance measurement
- Updated nested cart lines support
- Improved unit price display
- Updated translations across all locales
- [Add other key changes]
Changes applied to src/theme/ structure."
git push origin boilerplate/15.5.0git checkout develop
git merge boilerplate/15.5.0
# Resolve any conflicts if needed
git push origin develop| Workflow | Trigger | Purpose |
|---|---|---|
| on-pr.yml | PR to develop |
Deploy preview theme |
| on-push-main.yml | Push to develop |
Deploy to live & tagged themes |
| on-close.yml | PR merged/closed | Clean up preview themes |
| deploy-to-preview-theme.yml | Reusable | Preview deployment logic |
| deploy-to-published-theme.yml | Reusable | Live theme deployment |
| deploy-to-tagged-themes.yml | Reusable | Tagged themes deployment |
| remove-preview-theme.yml | Reusable | Preview cleanup logic |
| Action | Purpose |
|---|---|
| install-dependencies | Install pnpm, Node.js, Shopify CLI, build assets |
| push-to-preview-theme | Deploy preview theme, return URLs |
| stats | Generate metadata (date, time, branch name) |
| preview-summary | Comment PR with preview URLs |
Go to Settings β General and set develop as the default branch.
Go to Settings β Environments and create: production
In the production environment:
Secrets:
SHOPIFY_CLI_THEME_TOKEN
- Get from: Shopify Admin β Apps β Theme Access
- Generate a password token
- Paste into GitHub secret
Variables:
SHOPIFY_FLAG_STORE = your-store-name
NODE_VERSION = 20
- PR created to
developbranch - Workflow triggers:
on-pr.yml - Actions run:
- Install pnpm dependencies
- Build Vite assets (
pnpm run build) - Pull live theme settings (templates, locales, config, sections)
- Deploy to preview theme (named after branch)
- Comment on PR with preview URLs
- PR merged to
developbranch - Workflow triggers:
on-push-main.yml - Actions run:
- Install dependencies & build
- Deploy to live theme
- Deploy to all tagged
[main]themes (excluding[live])
- PR closed or merged
- Workflow triggers:
on-close.yml - Actions run:
- Find preview theme by branch name
- Delete preview theme
# Create feature branch from develop
git checkout develop
git pull origin develop
git checkout -b feature/test-something
# Make changes
echo "Test change" >> README.md
git add README.md
git commit -m "Test: workflow validation"
# Push to GitHub
git push -u origin feature/test-something# Option A: Using GitHub CLI
gh pr create --base develop --title "Test workflow" --body "Testing preview deployment"
# Option B: Via GitHub Web UI
# Go to: https://github.com/benjaminv/dawn/compare/develop...feature/test-something# Check workflow runs
gh run list --branch feature/test-something
# Watch specific run
gh run watch
# View logs
gh run view --logThe workflow will comment on your PR with:
- Preview URL: Public preview link
- Editor URL: Theme editor link
- Store info: Store URL and theme name
When merged:
- Preview theme automatically deleted
- Code deployed to live theme
- Branch can be deleted
# 1. Sync develop branch
git checkout develop
git pull origin develop
# 2. Create feature branch
git checkout -b feature/my-feature
# 3. Make changes and commit
# ... do your work ...
git add .
git commit -m "feat: add new feature"
# 4. Push and create PR
git push -u origin feature/my-feature
gh pr create --base develop- Your PR triggers the workflow
- Preview theme created with name:
feature/my-feature - Comment appears on PR with URLs
# After review, merge PR
gh pr merge --squash
# Automatic actions:
# - Preview theme deleted
# - Code deployed to live theme
# - Tagged themes updatedIssue: pnpm is installed after setup-node tries to use it.
Fix: Already resolved - pnpm is installed before setup-node in our workflows.
Issue: Incorrect Shopify CLI syntax.
Fix: Already resolved - using --live --store instead of --theme --live.
Check:
- GitHub secrets are set correctly (
SHOPIFY_CLI_THEME_TOKEN) - Store variable is correct (
SHOPIFY_FLAG_STORE) - Theme Access app is installed in Shopify
Optimization:
- Caching is enabled for pnpm and node_modules
- First build: ~2-3 minutes
- Subsequent builds: ~30-60 seconds
- Keep main clean: Never commit directly to main
- Develop is your base: All feature branches from develop
- One feature per branch: Keep changes focused
- Delete merged branches: Clean up after merging
Use conventional commits:
feat: add new product card component
fix: resolve cart drawer layout issue
chore: update dependencies
docs: update README with new workflow
style: format code with prettier
- Keep PRs small and focused
- Write clear descriptions
- Reference related issues
- Request reviews when needed
- Test preview theme before merging
- Sync weekly or after major Dawn releases
- Review changes before applying to boilerplate
- Test thoroughly after upgrades
- Document breaking changes
- Shopify Dawn: https://github.com/Shopify/dawn
- Shopify CLI: https://shopify.dev/themes/tools/cli
- Theme Access: https://shopify.dev/themes/tools/theme-access
- GitHub Actions: https://docs.github.com/actions
- Vite: https://vitejs.dev
- Tailwind CSS: https://tailwindcss.com
- Create feature branch from
develop - Make changes
- Test locally with
pnpm run dev - Push and create PR
- Review preview deployment
- Merge after approval
This boilerplate extends Shopify Dawn which is licensed under MIT.
Last Updated: December 16, 2025