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.

Upgrade Guide

View as Markdownllms.txt

This guide lists every change that can break an app when you move from Strutvane 0.1 to 0.2, how likely each one is to affect you, and exactly what to do.

We try to document every breaking change. Work from the top: high impact first.

Before you start:

  1. Commit your work, so git diff shows exactly what the upgrade changed.
  2. Make sure you have Node.js 24.3 or newer (node --version).
  3. Read What’s new in Strutvane 0.2 for the big picture.

Click Copy as Markdown at the top of this page and paste the guide into your coding agent, together with your app’s package.json and its app/models folder. Ask it to go through the changes below one at a time.


Likelihood of impact: High

What changed. Strutvane apps use npm only. The pnpm-lock.yaml, pnpm-workspace.yaml and corepack pnpm commands are gone.

Why. pnpm’s build-script blocking stopped new 0.1 apps from installing (esbuild was blocked), and every extra tool is one more thing to set up. npm comes with Node.

Who is affected. Every 0.1 app.

Terminal window
# 0.1
corepack pnpm install
corepack pnpm sv migrate
# 0.2
npm install
node strut migrate

What to do. Delete pnpm-lock.yaml and node_modules, then run npm install to create package-lock.json.

Likelihood of impact: High

What changed. 0.1 was published only under the next tag; 0.2 is published on latest. Several packages were merged (see below).

What to do. In package.json, set:

  • @strutvane/framework to ^0.2.0
  • @strutvane/auth to ^0.2.0
  • @strutvane/ui to ^0.2.0

and remove @strutvane/core, @strutvane/contracts, @strutvane/cli, @strutvane/devkit and @strutvane/logs. Then:

Terminal window
npm install
node strut migrate # applies framework tables and regenerates types, API and UI
node strut doctor # reports anything still on 0.1 conventions

Likelihood of impact: High

What changed. In 0.1, app/models/*.model.ts declared every field with defineModel() and field.*, and migrations were generated from it. In 0.2, migrations are the source of truth: you write columns with the Schema builder, and the model holds only behaviour.

Why. Real projects need to rename, backfill and reshape tables, which a model file can’t describe. Laravel’s flow (columns in migrations) handles all of it, and Strutvane now generates the types from the migrations, so you lose no type safety.

Who is affected. Every 0.1 app.

app/models/post.model.ts
export const Post = defineModel('Post', {
title: field.string(200),
status: field.enum(['draft', 'published']),
})
// 0.2: database/migrations/2026_11_14_093000_create_posts_table.ts
schema.create('posts', (t) => {
t.id()
t.string('title', 200)
t.enum('status', ['draft', 'published']).default('draft')
t.timestamps()
})
// 0.2: app/models/post.ts
export class Post extends Model('posts', { fillable: ['title', 'status'] }) {}

What to do. For each 0.1 model, write a create_<table>_table migration with the same columns (node strut make:migration create_posts_table also writes the new model), then delete the old model file. If your database already has the tables, point the 0.2 app at a copy first and compare. See Migrations.

Likelihood of impact: Medium

What changed. Seeders are registered in database/seeders/database-seeder.ts and tracked in a seeders table. In development, node strut migrate runs each new seeder once; production seeds only with --seed --force.

Why. In 0.1, seeders weren’t registered automatically, so they silently never ran.

What to do. Move seed code into database/seeders/ (one file per table) and register it. See Seeding.

Likelihood of impact: High

What changed. The project CLI is node strut <command> (or npx strutvane <command>). The sv script is gone. Column definitions on the command line (make:model Post title:string) are gone too, because columns live in migrations.

Why. sv clashes with a built-in PowerShell alias, and field specs broke on Windows quoting. node strut works identically in every shell.

Terminal window
# 0.1
pnpm sv make:model Post title:string status:enum:draft,published
# 0.2
node strut make:migration create_posts_table --seeder

Likelihood of impact: Low

What changed. The 0.1 levels L0–L3, eject and the upgrade command with three-way merges are gone.

Why. In 0.2, files you own are simply never overwritten, and generated files (.strutvane/, *.gen.ts) are always regenerated, so there’s nothing to merge.

What to do. Nothing, unless you ejected files: keep them as your own code.

Likelihood of impact: Medium

What changed. Better Auth is no longer the default engine. Sign-in follows Laravel’s Fortify + Sanctum model: a features list in config/auth.ts, standard /login and /register routes, and the auth tables as ordinary migrations in your app, with a real users model.

Why. In 0.1, identity lived in a separate store and could be lost on restart, and auth needed its own migration step.

What to do. Recreate your sign-in settings in config/auth.ts, and move existing users across with a one-off script. (A migration helper is planned; it isn’t built yet.)

Likelihood of impact: Medium

What changed. UI customisations live in resources/ui/ (for example resources/ui/posts.ui.ts), written once by node strut migrate and never overwritten.

What to do. Move each override from your 0.1 web/ folder into the matching resources/ui/<resource>.ui.ts. See Customising Screens.

Likelihood of impact: Low

@strutvane/core, @strutvane/contracts, @strutvane/cli, @strutvane/devkit and the logging pipeline from @strutvane/logs are now part of @strutvane/framework, like laravel/framework. The log viewer is the separate @strutvane/log-viewer package. If you imported from the old packages, import from @strutvane/framework instead.

Likelihood of impact: Low

What changed. Logging is now part of @strutvane/framework and works like Laravel’s: you pick channels (single, daily, stack, stderr, slack, …) in config/logging.ts and .env (LOG_CHANNEL, LOG_STACK, LOG_LEVEL, LOG_DAILY_DAYS, LOG_FORMAT). Three things look different from 0.1:

0.1 (@strutvane/logs) 0.2
Level names six pino-style names (trace, debug, info, warn, error, fatal) the eight RFC 5424 names, as in Laravel: emergency, alert, critical, error, warning, notice, info, debug
File names storage/logs/YYYY-MM-DD.w<id>.ndjson storage/logs/strutvane-YYYY-MM-DD.log (daily) or strutvane.log (single)
File format NDJSON (one JSON object per line) readable lines by default; LOG_FORMAT=json keeps NDJSON

What to do. Usually nothing: the old names warn, fatal and trace still work as aliases for warning, critical and debug. If a log shipper reads the old .ndjson files, point it at the new names and set LOG_FORMAT=json. See Logging.

The full list of changes in 0.2 is in the release notes.

npm install fails with “No matching version found for @strutvane/core”

Section titled “npm install fails with “No matching version found for @strutvane/core””
npm error notarget No matching version found for @strutvane/core@^0.2.0.

Why: @strutvane/core (and contracts, cli, devkit, logs) don’t exist in 0.2: they were merged into @strutvane/framework. Fix: remove them from package.json, keep @strutvane/framework, and change imports from the old packages to @strutvane/framework.

pnpm sv migrate says “command not found”

Section titled “pnpm sv migrate says “command not found””

Why: 0.2 apps use npm only, and the sv script is gone. Fix:

Terminal window
node strut migrate

My 0.1 model file still compiles, but nothing uses it

Section titled “My 0.1 model file still compiles, but nothing uses it”

Why: defineModel() files aren’t read in 0.2; columns come from migrations. Fix: write a create_…_table migration with the same columns, move any behaviour into the new class … extends Model('…') file, then delete the old model.