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.

Your First CRUD in 5 Minutes

View as Markdownllms.txt

CRUD stands for create, read, update and delete: the four things you do with records in any business app. In this guide you’ll add blog posts to a new app. You’ll write about fifteen lines of code, and at the end you’ll have:

  • a posts table in your database;
  • a JSON API to list, search, create, update and delete posts;
  • admin screens: a list with search, filters and pages, create and edit forms, and a detail page;
  • Posts in the sidebar, for everyone who’s allowed to see it;
  • fake posts to play with.

Before you start: create an app and start it, as shown in Installation:

Terminal window
npm create strutvane@latest my-app
cd my-app
npm run dev

Leave npm run dev running, and open a second terminal in the my-app folder for the commands below. (With Docker, type the commands exactly the same way: node strut forwards them into the app container.)

A migration is a small file that describes one change to your database, like “create a posts table”. Ask Strutvane to write one:

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`.

Strutvane reads the name create_posts_table the way Laravel does: it means “create a table called posts”. Because it creates a table, it also writes the model. --seeder adds a seeder (code that fills the table) and the factory it uses (a recipe for one fake post); --factory alone adds only the factory. The date at the start of the file name is the current time in UTC; it keeps migrations in order.

Open the new migration. It already has an id and timestamps. Add the columns a post needs:

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.decimal('price', 12, 2).default(0)
t.enum('status', ['draft', 'published']).default('draft')
t.foreignId('author_id').constrained('users')
t.timestamps()
t.softDeletes()
})
},
down(schema) {
schema.drop('posts')
},
})

Line by line:

Line What it makes
t.id() An auto-increment primary key called id.
t.string('title', 200) Required text, at most 200 characters. Columns are required unless you add .nullable().
t.slug('slug').from('title') A URL-friendly copy of the title, filled in for you: “Hello World” becomes hello-world.
t.text('body').nullable() Long text that may be empty.
t.decimal('price', 12, 2).default(0) An exact number with 2 decimals, 0 when not given.
t.enum('status', ['draft', 'published']).default('draft') One value from a fixed list. The form shows a select.
t.foreignId('author_id').constrained('users') A link to a user. The form shows a user picker.
t.timestamps() created_at and updated_at, kept up to date automatically.
t.softDeletes() deleted_at: “delete” hides a post instead of erasing it, so it can be restored.

down() says how to undo up(), so node strut migrate:rollback can take the change back.

Now open app/models/post.ts and list the columns people may fill in through forms and the API. Anything not on this list (like id, created_at, or a column you add later and forget) is refused, so nobody can set a field you didn’t mean to expose:

app/models/post.ts
import { Model } from '@strutvane/framework'
export class Post extends Model('posts', { fillable: ['title', 'body', 'price', 'status', 'author_id'] }) {}

A factory describes one fake post. Open it and return the columns of one row (faker makes realistic text, sequence counts up so every row is different):

database/factories/post.factory.ts
import { defineFactory } from '@strutvane/framework'
import { Post } from '../../app/models/post.ts'
export default defineFactory(Post, ({ faker, sequence }) => ({
title: `${faker.lorem.words(3)} ${sequence}`,
body: faker.lorem.paragraph(),
price: '9.99',
status: sequence % 2 === 0 ? 'published' : 'draft',
}))

A seeder puts rows in the table. This one says it runs after the users seeder (a post needs an author), and uses the factory to make ten posts by the first user:

database/seeders/post.seeder.ts
import { defineSeeder } from '@strutvane/framework'
import { Post } from '../../app/models/post.ts'
import { User } from '../../app/models/user.ts'
/** Seeds the `posts` table. */
export default defineSeeder({
after: ['users'],
async run() {
const author = await User.query().orderBy('id').firstOrFail()
await Post.factory().count(10).for(author, 'author').create()
},
})

Factories write through forceCreate(), which is for trusted code: it may set columns that aren’t in fillable (such as author_id). You don’t edit database/seeders/database.seeder.ts: every seeder is registered there automatically, in the order their after lists require. See Seeding and ORM: Factories.

Terminal window
node strut migrate

This one command does five things, in order:

  1. Creates the posts table. On PostgreSQL and SQLite, a failing migration leaves nothing half-done.
  2. Regenerates your TypeScript types. Post, NewPost, PostPatch and PostJson now exist, with every column typed: post.title is a string and post.status is 'draft' | 'published'.
  3. Seeds the new post.seeder.ts once, so you get fake posts. It remembers that it ran, so it won’t add more next time.
  4. Generates the API for posts.
  5. Generates the UI for posts and adds Posts to the sidebar.

What you’ll see (something like this):

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

Go back to the browser at http://localhost:3000. Posts is in the sidebar. You’re signed in as the admin, who may do everything; other users see Posts only once a policy or their role allows it (see Authorization). Click it and try:

  • Search for a word: it looks in the title and other text columns.
  • Sort by clicking a column header.
  • Filter by status.
  • Create a post. Leave the title empty and you’ll see a friendly validation message.
  • Open a post: the address uses its slug, like /posts/hello-world.
  • Delete a post, then show deleted posts and restore it.

The same data is available as JSON. While signed in:

Terminal window
curl "http://localhost:3000/api/posts?search=hello&sort=-created_at&page=1"

What you’ll see:

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

Errors come back in one standard shape (RFC 9457 “problem details”) with a stable code, and validation errors list every problem field at once. See Validation.

Scripts, mobile apps and other servers use the API with an API token instead of a browser session. Create one as shown in Authentication: API tokens, then keep it in a variable so the commands below stay short:

Shell Set the variable
macOS / Linux (bash, zsh) TOKEN=svp_your_token_here
Windows PowerShell $TOKEN = 'svp_your_token_here'

In PowerShell, type curl.exe instead of curl (plain curl is a different PowerShell command), and use $TOKEN exactly as below.

Terminal window
curl -X POST http://localhost:3000/api/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Hello World","body":"My first post.","status":"draft"}'

What you’ll see: status 201 Created, a Location header pointing at the new post, and the post itself, with the slug filled in from the title:

{
"data": { "id": 11, "title": "Hello World", "slug": "hello-world", "body": "My first post.", "price": "0.00", "status": "draft", "author_id": 1,
"created_at": "2026-11-14T09:40:00.000Z", "updated_at": "2026-11-14T09:40:00.000Z", "deleted_at": null }
}

Leave out the title and pick a status that doesn’t exist:

Terminal window
curl -X POST http://localhost:3000/api/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"status":"archived"}'

What you’ll see: status 422, with every problem at once, each on its field:

{
"type": "https://strutvane.dev/problems/validation_failed",
"title": "Some fields need attention",
"status": 422,
"code": "validation_failed",
"detail": "Fix the fields listed in `issues` and try again.",
"issues": [
{ "path": ["title"], "field": "title", "code": "invalid_type", "message": "Title is required." },
{ "path": ["status"], "field": "status", "code": "invalid_value", "message": "Status must be one of: draft, published." }
]
}

Now send a valid post with one extra field the API doesn’t accept:

Terminal window
curl -X POST http://localhost:3000/api/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"title":"Sneaky","is_admin":true}'

What you’ll see: 422 again, this time for the unknown field:

{ "path": ["is_admin"], "field": "is_admin", "code": "unknown_field", "message": "\"is_admin\" is not a field you can send here. Remove it from the request body." }

Unknown fields are refused on purpose: a typo or an attempt to set is_admin never passes silently. They’re reported once the other fields are valid. (The exact wording of each message may still change.)

Terminal window
# change only the status (PATCH sends just the fields you change)
curl -X PATCH http://localhost:3000/api/posts/hello-world \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status":"published"}'
# soft-delete it (it can be restored from the Deleted filter in the UI)
curl -X DELETE http://localhost:3000/api/posts/hello-world -H "Authorization: Bearer $TOKEN"

What you’ll see: 200 with the updated post, then 204 No Content (an empty answer that means “done”). Notice the address uses the slug, hello-world, not the id.

You want Add to /api/posts
Page 2, 50 per page ?page=2&perPage=50 (at most 100)
Posts mentioning “launch” ?search=launch
Newest first, then by title ?sort=-created_at,title
Only drafts ?filter[status]=draft
Drafts or published ?filter[status][in]=draft,published
Price of at least 10 ?filter[price][gte]=10

A field that can’t be sorted or filtered is a 422 that lists the ones that can. See Search & Filters.

The first migrate also wrote a small file you own, resources/ui/posts.ui.ts. It starts with columns: auto() and form: auto(), so the screens follow your migrations automatically: a column you add later shows up by itself. Change it whenever you want, for example to choose which columns the list shows. Strutvane never overwrites this file. See Customising Screens.

The generated policy, app/policies/post.policy.ts, lets admins do everything and denies everyone else. That’s on purpose: a new feature is never open by accident. Open it and decide, method by method. For example, “members may list and read posts, and change their own”:

app/policies/post.policy.ts
import { hasAdminRole, type AuthUser, type Policy } from '@strutvane/framework'
import type { Post } from '../models/post.ts'
export class PostPolicy implements Policy<Post> {
/** Admins may do everything. */
before(user: AuthUser | null): boolean | undefined {
return hasAdminRole(user) ? true : undefined
}
viewAny(user: AuthUser | null): boolean {
return user !== null
}
view(user: AuthUser | null, _post: Post): boolean {
return user !== null
}
create(user: AuthUser | null): boolean {
return user !== null
}
update(user: AuthUser | null, post: Post): boolean {
return user !== null && post.author_id === user.id
}
delete(user: AuthUser | null, post: Post): boolean {
return user !== null && post.author_id === user.id
}
}

What you’ll see: a member now finds Posts in the sidebar and can create posts. Edit and Delete appear only on their own posts, and the API answers 403 if they try someone else’s. A method you delete also denies. See Authorization for rules that also filter lists in SQL.

Need a subtitle? Never edit an old migration that has already run. Add a new one:

Terminal window
node strut make:migration add_subtitle_to_posts_table

The name means “change the posts table”, so the new file starts with schema.table('posts', …). Add the column:

database/migrations/2026_11_14_101500_add_subtitle_to_posts_table.ts
import { migration } from '@strutvane/framework/schema'
export default migration({
up(schema) {
schema.table('posts', (t) => {
t.string('subtitle').nullable()
})
},
down(schema) {
schema.table('posts', (t) => {
t.dropColumn('subtitle')
})
},
})
Terminal window
node strut migrate

What you’ll see: the new column in the detail page and the API. To let people edit it, add 'subtitle' to fillable in app/models/post.ts; until then it’s read-only, on purpose. If you had removed a column instead, every line of TypeScript that still used it would now be a compile error, so nothing breaks silently.

Made a mistake in a migration you just ran (and nobody else has it yet)? Roll it back, fix the file, and migrate again:

Terminal window
node strut migrate:rollback # runs down() of the last batch
node strut migrate # runs your corrected up()

Once a migration is shared with teammates or deployed, never edit it: write a new one instead, as above.

While you’re experimenting, you can drop every table, migrate and seed again in one go (development only, it deletes all your data):

Terminal window
node strut migrate:fresh --seed

Nothing changes in what you type. With Docker, node strut make:migration writes files on your computer (the project folder is shared with the container), and node strut migrate runs inside the app container, against the MySQL container. Without Docker, both run on your computer against your database. See Docker.

✖ "CreatePosts" is not a valid migration name.
→ Use snake_case letters, digits and underscores, for example: node strut make:migration create_posts

Why: migration names are snake_case, so Strutvane can read what you mean (create_posts_table → create posts). Fix:

Terminal window
node strut make:migration create_posts_table
[INVALID_COLUMN] in 2026_11_14_101500_add_subtitle_to_posts_table.ts: The new column "posts.subtitle" is required but has no default, so existing rows would have no value. Hint: Make it .nullable(), or give it a .default(…).

Why: the table already has rows, and they need a value for the new column. Fix: t.string('subtitle').nullable() or t.string('subtitle').default('').

Saving the form fails with MASS_ASSIGNMENT

Section titled “Saving the form fails with MASS_ASSIGNMENT”
"subtitle" can't be mass-assigned on "posts". If users may set it, add it to `fillable` in Model('posts', { fillable: [...] }). If your own code sets it, assign it directly (model.subtitle = value) or use forceCreate().

Why: columns are read-only through forms and the API until you list them in fillable. Fix: add the column to fillable in app/models/post.ts. See Mass Assignment.

Why: the sidebar only shows resources you may viewAny. If you’re not the admin, the generated policy denies everything until you edit it. Fix: sign in as the admin from the installer’s summary, or open app/policies/post.policy.ts and allow viewAny (Step 5b). See Authorization.

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

Why: the request carried no session and no token, and the API is deny by default. Fix: send -H "Authorization: Bearer $TOKEN" with a token you created (Step 4b).

{"type":"https://strutvane.dev/problems/unsupported_media_type","title":"Unsupported media type","status":415,"code":"unsupported_media_type","detail":"Send the body as JSON with \"Content-Type: application/json\"."}

Why: the body was sent without Content-Type: application/json (curl’s -d sends a form type by default). Fix: add -H "Content-Type: application/json".

PowerShell says “A parameter cannot be found that matches parameter name ‘X’”

Section titled “PowerShell says “A parameter cannot be found that matches parameter name ‘X’””

Why: in Windows PowerShell, curl is a different command (Invoke-WebRequest) with other options. Fix: type curl.exe instead of curl. Everything else stays the same.

Why: it doesn’t, in development: each seeder runs once and is remembered in a seeders table. You see duplicates only if you ran node strut migrate --seed or node strut db:seed on purpose. Fix: node strut migrate:fresh --seed starts clean (development only).

“The new column … is required but has no default” when I add a column

Section titled ““The new column … is required but has no default” when I add a column”

See “is required but has no default” above: give the column .nullable() or a .default(…).

  • node strut make:migration create_x_table --seeder writes the migration, model, seeder and factory.
  • Columns go in the migration, and only there; fillable in the model says which ones people may set.
  • node strut migrate updates the database, the types, the API and the screens in one go.
  • Files you own (resources/ui/*.ui.ts, models, migrations) are never overwritten.