Upgrade Guide
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.
Upgrading to 0.2 from 0.1
Section titled “Upgrading to 0.2 from 0.1”Estimated upgrade time: not measured yet
Section titled “Estimated upgrade time: not measured yet”We try to document every breaking change. Work from the top: high impact first.
Before you start:
- Commit your work, so
git diffshows exactly what the upgrade changed. - Make sure you have Node.js 24.3 or newer (
node --version). - Read What’s new in Strutvane 0.2 for the big picture.
Upgrading with an AI agent
Section titled “Upgrading with an AI agent”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.
High impact changes
Section titled “High impact changes”- npm instead of pnpm
- Updating dependencies
- Columns move from models to migrations
pnpm svbecomesnode strut
Medium impact changes
Section titled “Medium impact changes”- Auth is built in (Better Auth is no longer the default)
- UI customisations move to
resources/ui/ - Seeders run once and are tracked
Low impact changes
Section titled “Low impact changes”upgradeand three-way merges are retired- Packages merged into
@strutvane/framework - Logging uses Laravel-style channels
Dependencies
Section titled “Dependencies”npm instead of pnpm
Section titled “npm instead of pnpm”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.
# 0.1corepack pnpm installcorepack pnpm sv migrate
# 0.2npm installnode strut migrateWhat to do. Delete pnpm-lock.yaml and node_modules, then run npm install to create package-lock.json.
Updating dependencies
Section titled “Updating dependencies”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/frameworkto^0.2.0@strutvane/authto^0.2.0@strutvane/uito^0.2.0
and remove @strutvane/core, @strutvane/contracts, @strutvane/cli, @strutvane/devkit and @strutvane/logs. Then:
npm installnode strut migrate # applies framework tables and regenerates types, API and UInode strut doctor # reports anything still on 0.1 conventionsDatabase & migrations
Section titled “Database & migrations”Columns move from models to migrations
Section titled “Columns move from models to migrations”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.
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.tsschema.create('posts', (t) => { t.id() t.string('title', 200) t.enum('status', ['draft', 'published']).default('draft') t.timestamps()})
// 0.2: app/models/post.tsexport 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.
Seeders run once and are tracked
Section titled “Seeders run once and are tracked”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.
Command line
Section titled “Command line”pnpm sv becomes node strut
Section titled “pnpm sv becomes node strut”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.
# 0.1pnpm sv make:model Post title:string status:enum:draft,published
# 0.2node strut make:migration create_posts_table --seederupgrade and three-way merges are retired
Section titled “upgrade and three-way merges are retired”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.
Auth is built in
Section titled “Auth is built in”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.)
UI customisations move to resources/ui/
Section titled “UI customisations move to resources/ui/”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.
Miscellaneous
Section titled “Miscellaneous”Packages merged into @strutvane/framework
Section titled “Packages merged into @strutvane/framework”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.
Logging uses Laravel-style channels
Section titled “Logging uses Laravel-style channels”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.
Common mistakes
Section titled “Common mistakes”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:
node strut migrateMy 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.