Updates

How new versions reach you, how to apply one, and how to customise your store so updates stay easy.

Most updates are a git merge · Estimated time: 5–10 min, plus a redeploy

How updates are delivered

Updates are delivered through the GitHub repository. There is no auto-updater and nothing phones home — a new version is a new commit and a new release tag on the ShipCommerce repository, and you pull it into your own copy when you choose to.

That means your store has to be a git repository. If you deployed by uploading a folder rather than by cloning, there is nothing for git to merge into and there is nothing to merge. Getting your store into git first is the prerequisite for everything below.

Applying an update

Updates are applied with git. To review the incoming changes before merging, or to merge on a branch, these are the steps:

# once: point an 'upstream' remote at ShipCommerce
git remote add upstream https://github.com/ShipCommerce/ShipCommerce.git

# every update
git status                    # must be clean
git fetch upstream --tags
git tag --list --sort=-v:refname --merged upstream/main | head -n 5

# review what is coming before you take it
git diff HEAD..<tag>

git merge <tag>
npm install
npm run db:setup

Replace <tag> with the newest release tag from the list. Merging onto a throwaway branch first is a good habit on a busy store: you get to see the conflicts without touching the branch you deploy from.

If the merge conflicts

This can happen, and it is worth being straightforward about it: if you have edited files that the new release also changed, git cannot combine both versions on its own. Git stops rather than guessing, leaving the conflict markers in place for you to resolve.

Resolve the conflicted files, then finish by hand:

git add . && git commit
npm install
npm run db:setup

Those last two steps matter: after a conflicted merge, dependencies and database changes are still outstanding, even once the conflict is resolved and committed.

After updating

1. Build locally. Catch problems on your machine, not in production.

   npm run build

2. Push and redeploy. Pushing to the branch your host builds from is enough on Vercel. Remember that any new NEXT_PUBLIC_ variable introduced by a release has to be added to your host before the deployment that needs it — those values are baked in at build time.
3. Make sure the database is up to date. If you are unsure whether the database changes were applied — or you skipped a step — run the setup again:

   npm run db:setup

4. Click through the critical path. Load the storefront, open a product, place a test order with card 4242 4242 4242 4242, and confirm it appears in the admin panel.

If something is broken after an update, the Troubleshooting page covers the usual suspects.

Customising without pain

You have the source code and you are meant to change it. The cost of changing it is felt at update time, when git has to reconcile your edits with the new release. A few habits keep that cost low.

Commit before every update

This is the highest-value habit by a wide margin, and git will refuse to merge over uncommitted changes. With your work committed, a merge conflict is a reviewable diff between two known states rather than a tangle of your uncommitted edits and incoming changes — and git merge --abort always gets you back to safety.

Prefer configuration over code changes

Anything you can achieve with an environment variable or a setting in the admin panel costs nothing at update time. Store name, site URL, analytics, anti-bot, admin IP restrictions, the order webhook and email settings are all configuration — see the Configuration page before you reach for the editor.

Add rather than edit, where you can

A new file you introduce yourself will never conflict, because no release touches it. Rewriting a core file guarantees you will meet it again at every future update. When you do need to modify shipped code, prefer the smallest possible edit at the point where it is needed over a broad reorganisation.

Keep your customisations legible

Small, well-described commits that touch one thing each are far easier to reapply after a conflict than one large commit that changed twenty files. When you edit a core file, a brief comment saying why makes the decision reviewable months later, by you or by whoever resolves the next merge.

What your plan includes

Every plan ships the same complete platform — the full source code and every feature in the release you bought. What the plan decides is how long you keep receiving new releases and whether support is included.

Updates are delivered through the repository on every plan that includes them. The full and binding terms — including what support does and does not cover — are on the Purchase Plans page.

Questions

Email hello@shipcommerce.io. For a failed update, include the command you ran and the full output — a conflicted merge is usually a two-minute answer once someone can see which files git stopped on.