Resolving Common Merge Conflicts After an Update

TABLE OF CONTENTS

Overview

Pulling in a new Znode release means reconciling your customizations with Znode's own changes. Most of the repository merges with no input from you, because customizations live in their own packages or in the theme override map. A small, predictable set of files needs manual review. This guide shows which files fall into each group and how to work through the files that need review.

This guide is for implementation partners and developers working on the Znode 10 storefront (an Nx monorepo built on Next.js 15, managed with git). It covers merging a baseline update, not day-to-day feature merges. Values in <angle brackets> are placeholders for your own branch, release and project names.

The six steps below take you from a clean branch to a verified merge.

Step

Name

What you do

1

Branch

Create a merge branch from your main integration branch.

2

Merge

Merge the incoming Znode release into the merge branch.

3

Categorize

Group the conflicts by category before you resolve any of them.

4

Resolve

Resolve each category: // CUSTOM: markers for in-place edits, both sides for shared lists, regeneration for the lockfile.

5

Re-verify

Work through the re-verify checklist by hand.

6

Test

Run the full regression pass and record any unresolved failures.

Low-Conflict and Higher-Conflict Zones

Two patterns keep almost all customization work out of the baseline's way: your own packages, and the theme override map. Everything outside those two patterns is a candidate for a conflict.

Area

Conflict risk

Why

<project>-components and <project>-global-components packages

Low

Znode never ships files into your packages.

Theme override map in page-builder/configs/<project>-config/

Low

Your root config layers overrides on top of the base config and never edits it.

Compose, slot, route swap or widget override (options 1-4 in Keeping the next update small)

Low

No baseline file changes, or only your own route or config file changes.

Theme-name lookup in get-config.ts

Low

It reads your project config without being edited.

Copy and modify (option 5)

Low

No merge conflict, but the copy can drift from the new baseline, so compare it against the baseline on every update.

Files edited in place (option 6)

Higher

Baseline fixes and your changes land on the same lines. These are listed in the next section.

Files That Need Manual Review

Check these files by hand on every update.

File or area

Why it can't be avoided

What usually collides

apps/webstore/src/middleware.ts

One request pipeline for store lookup, locale, session, maintenance and route rules

New restriction branches on both sides

Shared constants (app.ts and your project's page-url.ts)

Flat lists that every route addition appends to

New entries in the same array or object

A widget changed with Edit in place

The team chose to edit the baseline file rather than register an override

Baseline fixes and project changes on the same lines

server.js cache-exclusion list

A single regular expression covering every personalized route

New personalized paths

package-lock.json

Regenerated from every workspace package

Dependency updates from both sides

Do mark every in-place edit with // CUSTOM: <reason>. The marker is what makes the next conflict reviewable in minutes instead of hours.

Don't expect zero manual review. A short, known list of files is the realistic goal.

Merge a Baseline Example

Prerequisites:

☐ A clean working tree on your main integration branch, with no uncommitted changes

☐ The incoming Znode release identified: a tag, a release branch or an upstream remote

☐ The release notes for the update, so you know which areas it changed

☐ A reference .env file to compare environment variables against after the merge

Step 3 is the step most teams skip. Sorting conflicts by category before you resolve any of them keeps you from hand-editing files, like the lockfile, that should simply be regenerated.

STEP 1 - Branch. Create a merge branch from your main integration branch.

git checkout -b merge/<release-or-ticket-id> origin/<your-main-branch>

STEP 2 - Merge. Merge the incoming release into the merge branch.

git merge <znode-release-tag>
# or if your team rebases release branches:
git rebase <znode-release-tag>

Most files resolve with no input: anything in a customization package or a project *-config folder, and any baseline file your project never changes.

If your team rebases instead of merging, run git rebase <znode-release-tag>. During a rebase, git swaps the meaning of "ours" and "theirs", so the lockfile command in Step 4 uses --ours instead of --theirs.

STEP 3 - Sort. Group every conflict into one of these categories before you resolve any of them.

Category

Resolution in Step 4

Pure addition (adjacent new files)

Usually merges automatically. If git still flags it, keep both additions.

Baseline file edited in place

Reconcile by hand, using the // CUSTOM: markers.

Regenerated / Lockfile

Take the incoming version, then reinstall.

Your own copy of a baseline file

No conflict, but compare it against the new baseline anyway.


STEP 4 - Resolve. Work through the categories from Step 3.

Edited-in-place files. Find every // CUSTOM: <reason> block on your side and keep it. Take the incoming baseline version for everything else. If the surrounding baseline code was restructured, re-apply the customization against the new structure rather than pasting the old lines back.

Found an edit with no marker? It predates the marker convention. Resolve the conflict, then add the marker so the next update doesn't repeat the investigation.

Lockfile. Take the incoming lockfile, then reinstall.

git checkout --theirs package-lock.json
npm install

Do commit the regenerated lockfile on its own, separate from logic changes.

Don't hand-edit a lockfile conflict. Regenerate it instead of merging it line by line.

STEP 5 - Re-verify. A clean build does not prove the Page Builder config map still resolves the way it did. Work through the re-verify checklist below before you call the merge done.

STEP 6 - Regression test. Once the re-verify checklist is complete, run the full regression pass. A clean merge alone does not confirm the result, so record any unresolved failures before you merge to your main branch.

Keeping the Next Update Small

When you need to change or extend a baseline component, the option you pick today decides how much work the next merge is. Options higher in the table change no baseline file at all.

  

Option

What you do

Baseline files changed

1. Compose

Build around the baseline component.

None

2. Use a slot

Pass UI through a customComponent or render prop the baseline already offers.

None

3. Swap at the route

Import your component instead of the baseline one.

None. Only your route file changes.

4. Override a widget

Register your widget under the same key in the theme override map.

None. Only your Page Builder config changes.

5. Copy and modify

Copy the component into your package.

None, but compare the copy against the baseline on every update.

6. Edit in place

Change the baseline file directly and mark it with // CUSTOM: <reason>.

The baseline file. This is the option that produces merge conflicts.

Rollback Plan

All merge work happens on the merge branch, so your main integration branch is unchanged until you merge the result into it.

Situation

What to do

The merge or rebase is still in progress

Run git merge --abort or git rebase --abort to return the merge branch to its state before Step 2.

You committed the merge but it fails re-verification or regression testing

Leave your main branch as it is. Delete the merge branch, or fix it and repeat Steps 5 and 6.

Hand-off Checklist

Verify each item before you call the merge done:

☐ Each theme override map still points at real baseline widget keys.

☐ The theme-name lookup still resolves to the right root config for every store.

☐ Any new baseline widget or route that needs a customization has it reapplied.

☐ Shared constants lists (admin-restricted paths, excluded paths, route URLs) contain both sides' entries.

☐ The anonymous-cache exclusion list covers every personalized route

☐ Environment variables compared against the reference .env file: nothing added, renamed or removed without a matching change.

☐ Translation keys your project relies on are still present in every locale file.

☐ Every baseline edit has a // CUSTOM: marker.

☐ npm install completes cleanly and the Nx graph resolves.

Golden Rules

Rule

What it means

Mark every in-place edit

If a baseline file must change, add // CUSTOM: <reason> next to the change, every time.

Unmarked lines belong to the baseline

During a conflict, take the incoming baseline version of anything without a marker.

Merge shared lists, don't choose a side

Admin-restricted paths, excluded paths and route URLs are append-only. Keep both sides' entries.

Regenerate lockfiles, never hand-merge them

Take the incoming version, then run npm install.

A clean merge is not a verified merge

Check the theme override map and environment variables by hand before testing.

Some manual review is unavoidable

The goal is a short, known list of files to check, not zero review.

Troubleshooting

You see

What it usually means

A project widget stopped rendering

The baseline renamed or removed the widget key that the theme override map targets.

A previously blocked route is reachable again

Conflict resolution dropped one side's entries from a shared constants list.

One visitor sees another visitor's cached page

A new personalized route was never added to the cache-exclusion list.

The build fails on a missing environment variable

The release added, renamed or removed a required variable.

A customization from before the merge is missing

Its // CUSTOM: block was dropped when the incoming file was accepted as a whole.

npm install reports unresolved peer dependencies

The lockfile was hand-edited instead of regenerated.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.