This guide explains how to update your s:CMS installation to the latest version while preserving your customizations.

TL;DR - Quick Update

1
npm run update-core

This automated script will:

1. Create a backup branch
2. Fetch latest changes from upstream
3. Merge updates while protecting your usr/ folder
4. Install new dependencies if needed

First Time Setup

If you haven’t set up the update system yet:

1
npm run setup-upstream

This configures the connection to the s:CMS repository for receiving updates.

What Gets Updated vs. What Stays Yours

✅ Always Updated (Framework Code)

• core/** - All framework components, layouts, and utilities
• Core package dependencies

🛡️ Always Protected (Your Content)

• usr/** - All your content, components, and customizations
• usr/user.config.mjs - Your site configuration
• usr/scripts/local-packages.yml - Your site-specific npm packages (see below)

⚠️ May Need Review (Shared Files)

• package.json - Dependencies may need merging
• astro.config.mjs - Usually auto-merges correctly
• .github/workflows/** - Deployment configurations
• tsconfig.json, tailwind.config.js - Build configurations

Update Process Details

Step 1: Prepare Your Environment

Before updating, ensure:

• All changes are committed: git status
• Your site builds successfully: npm run build
• (Optional) Test your site: npm run dev

Step 2: Run Update Script

1
npm run update-core

The script will:

1. Create backup - Saves current state to a dated branch
2. Fetch changes - Downloads latest s:CMS updates
3. Show preview - Lists what will change
4. Ask confirmation - You decide whether to proceed
5. Merge updates - Integrates changes while protecting usr/
6. Install dependencies - Updates packages if needed

Site-Specific Packages

Because npm run update-scms replaces package.json with the upstream (core) version, any packages you added manually to package.json would be wiped on every update.

The solution is usr/scripts/local-packages.yml — a YAML list of npm packages specific to your implementation. This file lives inside usr/, so it is always preserved across updates. The update script reads it and runs npm install for those packages automatically at the end of every update.

Setup

Create or edit usr/scripts/local-packages.yml:

1
- gsap
2
- d3
3
- @types/d3      # inline comments are supported
4
- swiper@11      # pin to a specific version

You can also install them manually at any time without running the full update:

1
# parse and install local packages directly
2
grep -E '^\s*-\s+[^#]' usr/scripts/local-packages.yml \
3
  | sed 's/^\s*-\s*//' | sed 's/\s*#.*//' \
4
  | xargs npm install

How It Works

During npm run update-scms the script:

1. Replaces package.json with the upstream version and runs npm install
2. Reads usr/scripts/local-packages.yml
3. Runs npm install <packages> for every package listed there

If the file does not exist or contains no uncommented entries, this step is silently skipped.

Step 3: Review and Test

After a successful update:

1
# Review what changed
2
git log HEAD~1..HEAD
3

4
# Test your site
5
npm run dev
6

7
# Check the production build
8
npm run build

Step 4: Cleanup

If everything works:

1
# Delete the backup branch (replace with actual branch name from script output)
2
git branch -d backup-before-update-20260202-123456

If something went wrong:

1
# Restore from backup
2
git reset --hard backup-before-update-20260202-123456

Handling Merge Conflicts

If the update script reports conflicts, don’t panic! Here’s how to resolve them:

package.json Conflicts

Strategy: Keep your dependencies + add new framework dependencies

1
# 1. Open package.json
2
# 2. Look for conflict markers: <<<<<<<, =======, >>>>>>>
3
# 3. Merge dependencies from both sections
4
# 4. Remove conflict markers
5
# 5. Save and run:
6
git add package.json
7
npm install
8
git commit

Example:

1
<<<<<<< HEAD (your version)
2
{
3
  "dependencies": {
4
    "astro": "^5.0.0",
5
    "my-custom-package": "^1.0.0"
6
  }
7
}
8
=======
9
{
10
  "dependencies": {
11
    "astro": "^5.1.0",
12
    "photoswipe": "^5.4.4"
13
  }
14
}
15
>>>>>>> upstream/scms
16

17
// Resolve to:
18
{
19
  "dependencies": {
20
    "astro": "^5.1.0",           // Use newer version
21
    "my-custom-package": "^1.0.0", // Keep your addition
22
    "photoswipe": "^5.4.4"         // Add new framework dep
23
  }
24
}

astro.config.mjs Conflicts

Usually auto-merges due to the coreConfig + userConfig pattern. If not:

1. Keep the merge structure
2. Ensure your usr/user.config.mjs imports are preserved
3. Verify the merge function is intact

Other Config Files

Review changes and decide case-by-case:

• .github/workflows/** - Keep your deployment setup, review new features
• tsconfig.json - Usually safe to accept upstream version
• tailwind.config.js - Merge your customizations with new settings

Release Notes & Migration Guides

Always check the CHANGELOG.md after updating for:

• Breaking changes
• New features
• Manual migration steps
• Deprecated APIs

Manual Update (Alternative)

If you prefer manual control:

1
# 1. Create backup
2
git checkout -b backup-before-update
3

4
# 2. Fetch upstream
5
git fetch upstream main
6

7
# 3. Merge (protecting usr/)
8
git merge upstream/main
9

10
# 4. Resolve any conflicts
11
# ... edit files ...
12
git add .
13
git commit
14

15
# 5. Install dependencies
16
npm install
17

18
# 6. Test
19
npm run dev

Troubleshooting

”Upstream remote not configured”

Run: npm run setup-upstream

”You have uncommitted changes”

Commit your work first:

1
git add .
2
git commit -m "Save work before update"

Update fails but you want to retry

Reset and try again:

1
git merge --abort
2
npm run update-core

Completely undo an update

Restore from backup:

1
git reset --hard backup-before-update-YYYYMMDD-HHMMSS

Best Practices

1. Update regularly - Smaller, frequent updates are easier than large jumps
2. Read changelogs - Know what’s changing before you update
3. Test locally first - Always test after updating before deploying
4. Keep backups - The script creates them automatically
5. Don’t edit core/ - Make customizations in usr/ only

File Ownership Reference

1
.
2
├── core/                    # ❌ Never edit (framework code)
3
│   ├── components/          # Framework components
4
│   ├── layouts/             # Base layouts
5
│   └── utils/               # Framework utilities
6
├── usr/                     # ✅ Your code (always protected)
7
│   ├── content/             # Your content
8
│   ├── pages/               # Your pages
9
│   ├── components/          # Your components
10
│   ├── layouts/             # Your custom layouts
11
│   └── user.config.mjs      # Your settings
12
├── astro.config.mjs         # ⚠️ Merges automatically
13
├── package.json             # ⚠️ May need manual merge
14
├── tsconfig.json            # ⚠️ Review on update
15
└── .github/workflows/       # ⚠️ Your deployment (review updates)

Getting Help

If you encounter issues:

1. Check Discussions
2. Review Issues
3. Ask in the community

Remember: The core/usr separation is designed to make updates safe and painless. Your customizations in usr/ are always protected! 🛡️