Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Versioning & Support

View as Markdownllms.txt

This page is the rulebook for Strutvane’s versions: what a version number promises, how long each version gets fixes, where each version lives (its git branch, its npm dist-tag and its docs), and how something is deprecated before it’s removed. The two tables below are generated from one file, versions.json, every time these docs are built, so they’re the same in every version of the docs.

You create an app on the current line and keep it on that line:

Terminal window
npm create strutvane@latest my-app

What you’ll see in the new app’s package.json (something like this; the exact numbers depend on the release):

package.json
{
"dependencies": {
"@strutvane/framework": "^0.2.0",
"@strutvane/auth": "^0.2.0",
"@strutvane/ui": "^0.2.0",
"@strutvane/design-crisp": "^0.2.0"
}
}

^0.2.0 means “any 0.2 release from 0.2.0 on”, and never 0.3. So npm update always stays safe: it only moves you to releases that promise not to break your app.

A version line is a family of releases that never break each other: 0.2.0, 0.2.1 and 0.2.2 are all the 0.2 line.

Before 1.0:

  • A new line (0.2 → 0.3) may contain breaking changes. Each one is listed in the upgrade guide, with how likely it is to affect you.
  • Releases within a line (0.2.3 → 0.2.4) never break your app. They carry bug fixes and backward-compatible features.
  • A new line ships at most once every three months.

From 1.0:

  • One major release a year (around Q1). Only majors may break.
  • Minor and patch releases can ship as often as every week and never break.

The promise covers:

  • everything a package exports;
  • node strut commands and flags;
  • installer questions and flags;
  • config files and .env keys;
  • the migration Schema builder;
  • the shape of generated files (.strutvane/*, resources.json, ui.gen.ts);
  • the HTTP conventions of the generated API (query parameters, error codes, the pagination envelope);
  • the tables the framework owns.

Code that Strutvane generates into your app counts too. If a release would make an app generated by an earlier release of the same line stop compiling or behave differently, that’s a bug.

Not covered (these may change in any release):

  • imports from internal paths, or anything marked @internal;
  • the wording of log lines, error detail text and human-readable CLI output (use --json in scripts);
  • the exact SQL the ORM generates;
  • the order of keys in generated JSON;
  • the HTML of developer pages under /_strutvane/.

Before 1.0:

  • The newest 0.x line gets bug fixes and security fixes.
  • When the next line ships, the previous one gets security fixes for 6 more months, then reaches end of life (no fixes at all).

From 1.0: every major gets bug fixes for 18 months and security fixes for 2 years from its release.

VersionNodeReleaseBug fixes untilSecurity fixes untilStatus
0.2you are reading these docs24.3+Not released yetRelease of the next lineNext line’s release + 6 monthsBug and security fixes
0.124+Pre-releases only——End of life

Legend:Bug and security fixesSecurity fixes onlyEnd of life

What a “bug fix” and a “security fix” are:

  • A security fix fixes a vulnerability published as a GitHub Security Advisory.
  • A bug fix fixes anything that doesn’t work as these docs describe.
  • In a security-only line we may also fix critical bugs, such as data loss or a broken upgrade path, but we don’t promise to.

Each released line gets a permanent branch named after it (0.2.x, later 1.x), created from its first release. main holds the next line. An npm dist-tag is a name npm uses to pick a version when you don’t give one: npm install x installs whatever the latest tag points at.

LineBranchnpm dist-tagCreate an appDocsNodeStatus
0.20.2.xlatestnpm create strutvane@latest my-app/docs/0.2.x/24.3+Bug and security fixes
0.10.1.xnextnpm create strutvane@0.1 my-app -- --allow-eol/docs/0.1.x/24+End of life
Dist-tag What it points at
latest the newest release of the current line
latest-0.2, latest-1, … the newest release of an older line that still gets fixes
next previews of the next line, built from main (not for production)

Where a fix goes:

Change Goes to
Bug fix the oldest line in its bug-fix window that has the bug, then merged up into every newer line and main
Security fix the oldest line in its security window, then merged up
Backward-compatible feature the current line
Breaking change main (the next line)

End-of-life branches are locked, never deleted, and their docs stay online with an “end of life” banner.

Every line stays installable, and its docs stay online at /docs/<branch>/ with the version switcher at the top of the menu:

Terminal window
npm create strutvane@0.2 my-app # the newest 0.2 starter: a 0.2 app
npm install @strutvane/framework@latest-0.2 # the newest release of an older maintained line
npm create strutvane@next my-app # a preview of the next line (not for production)

What you’ll see: the starter prints the line it is creating, and the app’s package.json uses ^0.2.x ranges. The starter refuses an end-of-life line unless you pass --allow-eol.

The core train is the set of packages that always release together, with the same version number:

  • @strutvane/framework
  • @strutvane/auth
  • @strutvane/ui
  • the first-party designs, @strutvane/design-crisp and @strutvane/design-vivid
  • create-strutvane, and the app skeleton it copies

So “Strutvane 0.2.4” means all of them at 0.2.4, and one git tag v0.2.4 marks the release.

Add-ons (@strutvane/log-viewer, @strutvane/files, @strutvane/billing, …) release on their own version numbers. Each declares the framework lines it works with as a peer range, a range npm checks against the framework your app already has:

node_modules/@strutvane/billing/package.json (excerpt)
{
"peerDependencies": {
"@strutvane/framework": "^0.2.0"
}
}

The Package Catalogue records which add-on versions work with which framework line, and the installer only offers add-ons that match the framework it is installing. From 1.0, only an add-on’s newest major gets fixes.

Before anything is removed, it is deprecated (marked as on its way out) for at least one full line:

  • Your editor shows it struck through, with the replacement and the line that removes it (TSDoc @deprecated).
  • At runtime, Strutvane logs one warning per process, with a stable code like STRUTVANE_DEPRECATED_… that tells you what to use instead.
  • STRUTVANE_DEPRECATIONS=throw turns the warnings into errors (handy in tests); off silences them.
  • node strut doctor lists the deprecated config keys and flags your app still uses.
  • The Deprecations page lists everything deprecated in a line, and the release notes’ “What’s new” lists what was deprecated or retired in that line.

Removal happens only in a new breaking line: the next 0.x line before 1.0, the next major from 1.0. A renamed API keeps its old name as an alias for a full line. The only exception is a security fix, which may change behaviour at once; it’s always announced, with an upgrade-guide entry.

A package that is no longer needed is retired the same way: its npm name gets npm deprecate with a pointer to the replacement, and its repository is archived (read-only, never deleted). That happens only after the replacement is released, so nobody is pointed at a version that doesn’t exist yet.

npm warn deprecated @strutvane/core@0.1.0-next.0: Merged into @strutvane/framework. Import from @strutvane/framework/core instead.

That is what npm install prints for a deprecated package (the wording of our message is not final).

Please don’t report security problems in public issues. Use GitHub’s private vulnerability reporting on the Strutvane repository.

When a vulnerability is fixed:

  • every affected line that still gets security fixes is released on the same day;
  • a GitHub Security Advisory lists the fixed version for each line;
  • npm audit reports it to you.

End-of-life lines get no fixes; the advisory tells you which line to move to. Every release is built in CI with npm provenance and approved by a maintainer with two-factor authentication before it goes live.

npm update didn’t move me to the next line

Section titled “npm update didn’t move me to the next line”

Why: ^0.2.4 means “any 0.2 release from 0.2.4 on”, never 0.3. A new line may break things, so you move to it on purpose.

Fix: follow the upgrade guide, then change the ranges of the core packages together:

package.json
"@strutvane/framework": "^0.3.0"

npm says an add-on’s peer dependency doesn’t match

Section titled “npm says an add-on’s peer dependency doesn’t match”
npm error ERESOLVE could not resolve
npm error While resolving: @strutvane/billing@0.4.1
npm error Found: @strutvane/framework@0.2.6

Why: that add-on version supports a different framework line than the one in your app.

Fix: install an add-on version made for your line (the catalogue lists them), or upgrade the core packages first:

Terminal window
npm install @strutvane/billing@^0.3
npm create strutvane@0.1 my-app

Why: 0.1 has reached end of life, so it gets no fixes, not even security fixes.

Fix: use the current line. To reproduce an old bug, pass --allow-eol:

Terminal window
npm create strutvane@0.1 my-app -- --allow-eol

Why: a search engine or an old link took you to another line’s docs.

Fix: use the version switcher at the top of the menu; it keeps you on the same page when it exists. Links that start with /docs/latest/ always go to the current line.