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.

Introduction

View as Markdownllms.txt

Strutvane is a framework for building business web apps in TypeScript. A framework is a ready-made structure for an app: it decides where files go, gives you tools for the common jobs (database, sign-in, forms, permissions), and lets you spend your time on what makes your app different.

It’s made for apps with sign-in, users and permissions, many tables, and screens to list, search, create and edit records: CRMs, back offices, customer portals, internal tools, B2B products.

This page takes you from nothing to a working feature in about ten minutes, then shows you where everything else is explained.

You need Why Check it with
Node.js 24.3 or newer Strutvane runs on Node, and npm comes with it. Earlier 24.x releases break command-line arguments in PowerShell. node --version
Docker Desktop (recommended, optional) New apps use MySQL. With Docker, MySQL and a test mail inbox run in containers, so you install nothing else. docker --version
Git (optional) Your project starts with a first commit. git --version

What you’ll see (your numbers may be higher):

v24.3.0
Docker version 29.8.2, build 1a2b3c4
git version 2.51.0

No Docker? That’s fine: the installer offers SQLite, a database that lives in one file and needs nothing installed. See Installation for every detail.

Open a terminal (PowerShell or Windows Terminal on Windows, Terminal on macOS and Linux) in the folder where you keep your projects, and run:

Terminal window
npm create strutvane@latest my-app

my-app is the folder the installer creates. The first time, npm asks Ok to proceed? (y): type y and press Enter.

Operating system Anything different?
macOS, Linux No.
Windows (PowerShell) If PowerShell says “running scripts is disabled on this system”, type npm.cmd instead of npm, or allow scripts for your user once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

The installer (the small program npm create downloads and runs) first asks how much you want to decide (something like this):

? How do you want to set up my-app?
❯ Recommended a few quick questions, sensible defaults for the rest
Custom Choose everything (about 35 questions, grouped)

Press Enter for Recommended. You’re asked these questions; press Enter on each to take the default:

Question Default What it means
What are you building? Full app (API + admin UI) An API plus a React app with generated screens. “API only” skips the screens.
Which design should your app use? Crisp The look of the screens. You can switch to Vivid later with one command (Designs).
How do people sign in? Email and password Or an email link only, or no sign-in (then the API needs a token).
Teams / multi-tenancy? No Yes means each customer company sees only its own data (Tenancy).
Which database? MySQL Or PostgreSQL (picked for you with teams) or SQLite.
With Docker or without? With Docker Docker runs the database and a mail inbox for you, like Laravel Sail.
AI coding assistants? Yes Adds an AGENTS.md and helpers so AI tools understand your project.

A question that brings a package is shown only once that package is published and works with your framework version. The AI assistants question brings @strutvane/agent-tools, coming in 0.3, so in 0.2 Recommended mode asks the first six.

Custom asks about 35 questions in groups (sign-in security, roles, cache, storage, mail, tests, CI, deployment, and more). Every question also has a flag, so a whole setup can be one line: npm create strutvane@latest my-app -- --db sqlite --yes. Installation lists every question and flag.

Then you see a review screen with every answer, the defaults included, and three choices: Create it, Change an answer, or Cancel. Choose Create it.

You watch it work, step by step:

  1. writes the project files;
  2. generates secrets (such as APP_KEY, the key that signs and encrypts your app’s data) into .env, never into .env.example;
  3. checks the ports it needs and picks free ones;
  4. starts the database (with Docker);
  5. installs the packages with npm;
  6. creates your tables and the first admin user;
  7. makes a first git commit.

What you’ll see at the end (something like this; the password line appears only in a real terminal):

✔ Files written (33 files in C:\Users\you\projects\my-app) 41ms
✔ Secrets generated in .env (APP_KEY, DB_PASSWORD, DB_ROOT_PASSWORD) 1ms
✔ Ports checked (3000 free; 3306 free; 8025 free) 15ms
✔ Containers running and healthy (app, db, mailpit) 15.3s
✔ Dependencies installed with npm (added 13 packages) 4.8s
✔ Migrations run (3 new, 3 total); Admin created: admin@my-app.test; Database seeded 850ms
✔ Git repository created (main, 1 commit) 1.9s
── Ready ───────────────────────────────────────────────────────
App http://localhost:3000
Database MySQL in Docker, 127.0.0.1:3306/my_app
Design crisp (@strutvane/design-crisp)
Mail inbox http://localhost:8025
Admin admin@my-app.test
Password q7Vd-3kPz-Xm2c-8RtL (shown once; change it at first sign-in)
Every day: cd my-app; npm run dev
Commands: node strut help
Teammates: npm run setup (after git clone)

Copy the password now. It’s shown once and never written to any file. Lost it? node strut user:password admin@my-app.test sets a new one.

If a step fails (Docker isn’t running, a port is taken, the network drops), the installer tells you what happened and offers to retry, fall back to SQLite, or stop. Your project is kept, and npm run setup continues from the step that failed.

Terminal window
cd my-app

Every node strut and npm run command works only from inside this folder, because that’s where strut.js and package.json live.

Terminal window
npm run dev

What you’ll see:

My App development
App + API http://localhost:3000
Press Ctrl+C to stop

npm run dev starts your API (the part that answers /api/... with JSON) and your UI (the React app in the browser) together, on one port, with hot reload: save a file and the browser updates.

Open http://localhost:3000 and sign in with admin@my-app.test and the password from the Ready box. You’re asked to choose a new password, then you land on the dashboard: a sidebar on the left (Dashboard and Users, for now) and a welcome checklist.

Leave this terminal running. Open a second terminal in the same folder for the next steps.

With Docker Without Docker
Where the app runs Inside the app container On your computer
npm run dev Forwarded into the container for you Runs directly
node strut <command> Forwarded into the container for you Runs directly
Database MySQL 8.4 (or PostgreSQL) in a container SQLite file, or your own server
Mail inbox Mailpit at http://localhost:8025 Emails are written to the log
Stop everything Ctrl+C, then node strut services:down Ctrl+C

You type exactly the same commands either way. See Docker.

Your app needs a place to store blog posts. In the second terminal, ask for a new migration: a small file that describes one change to your database.

Terminal window
node strut make:migration create_posts_table --seeder

What you’ll see (something like this):

Created database/migrations/2026_11_14_093000_create_posts_table.ts
Created app/models/post.ts
Created database/seeders/post.seeder.ts
Created database/factories/post.factory.ts
Next: add your columns to the migration, then run `node strut migrate`.

Because the name starts with create_ and ends with _table, Strutvane knows you want a new posts table, so it also writes the model (app/models/post.ts, the class you use in code to read and save posts). --seeder adds a seeder (fills the table with starting data) and the factory it uses (makes fake posts for tests and demos). --factory on its own adds only the factory.

Open the new migration file and list the columns a post has:

database/migrations/2026_11_14_093000_create_posts_table.ts
import { migration } from '@strutvane/framework/schema'
export default migration({
up(schema) {
schema.create('posts', (t) => {
t.id()
t.string('title', 200)
t.slug('slug').from('title')
t.text('body').nullable()
t.enum('status', ['draft', 'published']).default('draft')
t.foreignId('author_id').constrained('users')
t.timestamps()
})
},
down(schema) {
schema.drop('posts')
},
})

Read it line by line:

Line Means
t.id() A whole-number id that counts up by itself
t.string('title', 200) Text up to 200 characters
t.slug('slug').from('title') A readable address made from the title: “Hello World” → hello-world
t.text('body').nullable() Long text that may be empty
t.enum('status', [...]).default('draft') One of a fixed list of values, draft unless you say otherwise
t.foreignId('author_id').constrained('users') Points at a row in users; the database refuses a user that doesn’t exist
t.timestamps() created_at and updated_at, filled in for you

up makes the change; down undoes it (for migrate:rollback).

Columns live only in migrations. You never type them on the command line or repeat them in the model, so the types, the database and the screens can’t drift apart. See Migrations for every column type.

Terminal window
node strut migrate

What you’ll see (something like this; the exact wording isn’t final):

✔ 2026_11_14_093000_create_posts_table 14ms
✔ Types and metadata regenerated (3 tables)
✔ Seeded post.seeder.ts
✔ API: /api/posts · UI: Posts (sidebar)

That one command did five things, in order:

  1. created the posts table in your database;
  2. regenerated your TypeScript types, so Post has title, slug, body, status, author_id, created_at and updated_at;
  3. ran the new seeder once (seeders are remembered, so they never run twice by accident);
  4. generated a CRUD API for posts (CRUD means create, read, update, delete);
  5. generated the screens and a sidebar entry.

Go back to the browser. Without refreshing your code or writing anything else, Posts is in the sidebar:

  • A list with search, sorting by any column, filters (status, author, dates), and numbered pages (25 per page; 10, 50 or 100 if you prefer).
  • A “New post” form with the right field for each column: a text box for the title, a slug that fills itself in from the title, a dropdown for status, a searchable picker for the author.
  • A detail page at a readable address: /posts/hello-world.
  • An edit form, and delete with a confirmation (and Undo).

Try it: create a post called “Hello World”, then open it. The address bar shows /posts/hello-world.

The same data is available as a JSON API for other apps and scripts. It’s protected: try it without signing in.

Terminal window
curl http://localhost:3000/api/posts

What you’ll see:

{
"type": "https://strutvane.dev/problems/unauthenticated",
"title": "Unauthenticated",
"status": 401,
"code": "unauthenticated",
"detail": "Sign in first: send an \"Authorization: Bearer <token>\" header."
}

That’s deny by default: nobody can read or change posts until you say who may. Sign in, or create an API token (API Tokens), and the same request returns your posts:

{
"data": [
{ "id": 1, "title": "Hello World", "slug": "hello-world", "body": null, "status": "draft", "author_id": 1, "created_at": "2026-11-14T09:31:02.000Z", "updated_at": "2026-11-14T09:31:02.000Z" }
],
"meta": { "page": 1, "perPage": 25, "total": 1, "lastPage": 1, "from": 1, "to": 1 }
}

On Windows PowerShell, curl may be an alias for a different command. Use curl.exe instead, exactly as above.

Everything generated is ordinary code in your project, and Strutvane never overwrites a file you’ve changed:

You want to… Edit Read
Choose which columns the list shows resources/ui/posts.ui.ts Customising Screens
Change who may see or edit posts app/policies/post.policy.ts Authorization
Add a scope like published() app/models/post.ts ORM: Scopes
Write your own endpoint routes/api.ts + a controller Routing, Controllers
Add a column later a new migration, then node strut migrate Your First CRUD

When you add a column later, the generated screens pick it up by themselves, and anything you customised stays exactly as you left it.

Most business apps spend their first weeks on the same plumbing: tables, an API per table, checking input, sign-in, “who may see what”, and admin screens. In Strutvane:

  • your migrations are the single source of truth;
  • node strut migrate turns them into TypeScript types, a CRUD API and UI pages;
  • you write only the parts that make your app different.

Nothing is hidden. Models are ordinary classes in app/models, routes are in routes/, and the screen settings you might change are files in resources/ui/. Strutvane never overwrites a file you own.

  • Deny by default: nobody can see or change a record until a policy (a small class with the rules for one model) allows it. New policies allow only admins.
  • No SQL injection by construction: every value goes to the database as a bound parameter, never pasted into SQL text.
  • Secrets stay secret: they’re generated into .env, never into .env.example, and hidden columns like password are never sent to the browser.
  • Protections on by default: CSRF checks, rate limits, security headers and more, each one visible in node strut route:list --security (Security Features).
  • Teams: with teams switched on, each customer company sees only its own data.

Your columns live in migrations, and Strutvane generates the TypeScript types from them. Rename or drop a column and every line of code that still uses the old name becomes a compile error, so you find it in your editor instead of in production:

error TS2339: Property 'body' does not exist on type 'Post'.

Route names (route('posts.show', { post })) and settings (config('app.debug')) are typed the same way.

You want to… Laravel Strutvane
Create a project laravel new my-app npm create strutvane@latest my-app
Run the app composer run dev npm run dev
Run a command php artisan migrate node strut migrate
Make a table php artisan make:migration create_posts_table node strut make:migration create_posts_table
Describe a column $table->string('title') t.string('title')
Write a model class Post extends Model {} class Post extends Model('posts', { fillable: [...] }) {}
Define routes Route::get('/', ...) in routes/web.php Route.get('/', ...) in routes/web.ts
Configure the app bootstrap/app.php bootstrap/app.ts
Admin screens Filament or Nova (add-ons) Built in, generated on migrate
Docker for development Sail “With Docker” in the installer
Package manager Composer + npm npm only

The menu on the left follows Laravel’s order, so you always know where to look:

Section What’s in it Start with
Prologue What’s new, the support table, upgrading Release Notes, Upgrade Guide
Getting Started Installing, configuring, the folder layout, the first feature, the UI, deploying Installation, Directory Structure, Your First CRUD, Frontend, Starter Kits, Deployment
Architecture Concepts How a request flows through the app, and how services are wired Request Lifecycle, Service Container, Service Providers, Helpers, Facades
The Basics Writing your own endpoints Routing, Middleware, CSRF, Controllers, Requests, Validation, Responses, Error Handling, Logging
Digging Deeper Commands, background work and the other everyday tools Strut Console, Prompts, Rate Limiting, HTTP Client, Maintenance Mode, Optimization
Security Sign-in, permissions, teams Security Features, Authentication, Authorization, Tenancy
Database and ORM Tables, queries, models and relationships Migrations, Seeding, ORM, Relationships
Auto CRUD & UI The generated API and screens, and how to change them Resources, Sidebar, Customising, Slugs, Search, Precognition
Testing Feature, database and browser tests Testing
Packages Every first-party package Package Catalogue
CLI Reference Every node strut command CLI Reference
  • Small teams building internal tools and B2B products with many tables and roles.
  • Laravel developers moving to TypeScript who want the same productivity.
  • TypeScript developers who are tired of gluing ten libraries together before the first feature.
  • Beginners: these docs explain every new word, and every example can be copied as it is.
  • It isn’t a website builder or a CMS: you write code.
  • It doesn’t render pages on the server with templates (Laravel’s Blade). The UI is a React app in the same project (Frontend).
  • It isn’t a hosting product. You deploy it to any Node host or as a Docker image (Deployment).

“npm create strutvane” says the package doesn’t exist

Section titled ““npm create strutvane” says the package doesn’t exist”
npm error 404 Not Found - GET https://registry.npmjs.org/create-strutvane - Not found

Why: 0.2 hasn’t been published to npm yet (see the banner at the top of this page). Fix: read along for now; this command works once 0.2 is released.

“node strut” says it can’t find the module

Section titled ““node strut” says it can’t find the module”
Error: Cannot find module 'C:\Users\you\strut'

Why: strut.js lives in your project’s root folder, so node strut only works from inside it. Fix:

Terminal window
cd my-app
node strut list
✖ There is no "migarte" command.
→ Did you mean `node strut migrate`?

Why: a typo. Strutvane suggests the closest command. Fix: run the suggestion, or node strut list to see every command.

Why: sv was the 0.1 command. In 0.2 the command line is node strut (or npx strutvane). sv also clashes with a built-in PowerShell alias. Fix: node strut migrate. The Upgrade Guide lists every rename.

? Docker is installed but not running. What now?
❯ Retry (start Docker Desktop first)
Continue without Docker (SQLite)
Skip this step
Stop

Why: Docker Desktop is installed but closed. Fix: start Docker Desktop, wait until it says it’s running, and choose Retry. Or choose Continue without Docker to use SQLite now; you can move to MySQL later.

Why: another program (often another app you left running) uses port 3000. Fix: stop the other program, or set a different port in .env (APP_PORT=3001) and start again. The installer already picks free ports when it creates the project.

Posts doesn’t appear in the sidebar after migrate

Section titled “Posts doesn’t appear in the sidebar after migrate”

Why: usually one of three things: the migration file has an error (read the migrate output), you’re not signed in as a user whose policy allows viewAny on posts, or the browser shows an old page. Fix: check the migrate output, sign in as the admin, and refresh the page.

  1. Installation: every question, flag and recovery option.
  2. Your First CRUD: the same posts feature, with every step explained in more depth.
  3. Directory Structure: where everything lives.
  4. Routing: your first hand-written endpoint.