.dev

Appearance

Version control ​

A theme is source code. Track it in Git from the first commit, not after the first thing breaks.

Commit the theme, ignore the workspace ​

The platform serves the theme directory as it is. It doesn't install dependencies and it doesn't run your build, so everything the storefront needs has to be committed.

Commit:

  • layouts/, templates/, sections/, snippets/, locales/, config/
  • assets/, including compiled CSS and JavaScript
  • The style and script sources your build compiles from, such as styles/
  • package.json, lockfile, and build config

Ignore:

bash
node_modules/
dist/
.temp/
.youcan
youcan.theme.json
.env
.DS_Store
*.log

.youcan and youcan.theme.json hold the CLI's local link to a specific store. They're per-developer, and committing them points a teammate's theme:dev at your store.

Commit build output ​

This is the part that surprises people coming from application development. If your workflow compiles styles/*.scss into assets/*.css, the compiled CSS is committed alongside the Sass. The platform serves assets/ directly; nothing regenerates it on deploy.

Keep the intermediate directory out of Git, though. A pipeline like styles/ to .temp/ to assets/ should track the first and last, and ignore the middle.

The tradeoff is that generated files show up in diffs and conflict on merge. Two things keep it manageable: build deterministically, with a pinned toolchain and a lockfile, and regenerate rather than hand-resolve a conflict in a compiled file.

settings_data.json ​

config/settings_data.json is both source and state. You commit it to define the configuration a theme ships with, and the theme editor rewrites it whenever a seller customizes anything.

Treat the committed copy as the theme's default configuration. Pull down and commit editor changes deliberately, when you mean to change the defaults, and don't let a routine sync overwrite them with one store's settings.

Branching ​

Branch per change, review, then merge. The specifics matter less than keeping the default branch in a state you could publish.

Two conventions worth adopting:

  • Develop against a development store rather than a live one. youcan theme:dev pushes as you save, and a live storefront is not the place to find out a section throws.
  • Tag releases. Themes are distributed as versioned packages, so a tag that matches the version in package.json gives you something to roll back to and something to diff against.

Commit messages ​

Say what changed and why, scoped to the part of the theme it touched. fix(cart): keep quantity in sync after coupon removal tells you more six months later than fix cart, and it makes the history readable when you're bisecting a regression a seller reported.

© 2022-2026 YouCan