Upgrade Guide

Introduction

ReeWeb uses calendar versioning. Breaking changes are expected to be rare but may occur; they are documented in the Release Notes when they do. This page explains how upgrading works at all - which, for ReeWeb, is different from a normal dependency.

You own your copy

ReeWeb is a starting template, not a tracked dependency. When you create a project from it - especially via the bun reeweb:install task, which initialises a fresh git repository - your copy is entirely yours. There is no upstream remote to pull from and no automatic update channel; nothing in your project reaches back to the ReeWeb repo.

That's deliberate. With zero runtime dependencies there's no package to bump and no supply chain to track, so a ReeWeb project doesn't rot when you leave it alone. The trade-off is that improvements to ReeWeb itself don't arrive automatically - you adopt the ones you want, by hand.

Adopting changes from a newer release

When a later ReeWeb release ships a fix or feature you want, bring it in manually. The project is structured to make this clean:

• Framework code lives in lib/ and scripts/ and is meant to stay generic - you don't edit it. To adopt a release, copy the changed files from the new ReeWeb version over your own. Because your customisation stays out of these files (see below), replacing them wholesale is safe.
• Your customisation lives in src/lib/ - project_hooks.ts (behaviour), project_helpers.ts (template helpers), and markdown_styles.ts (markdown CSS). These implement the hooks and seams the framework calls into, so framework files never need your edits.
• config/ files - if the shape of supported_languages.ts, redirects.ts, or pagination.ts changes between releases, update yours to match. The SSG script or dev server will surface a mismatch.

Read the Release Notes for what changed before adopting a release.

What's yours vs. framework

Reporting Issues

Found a bug in ReeWeb itself? Open a GitHub Discussion with:

• Your ReeWeb version (from package.json)
• The error message or unexpected behaviour
• A minimal reproduction if possible