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.

Resources

View as Markdownllms.txt

A resource is one table seen from the outside: its API (list, show, create, update, delete) and its screens (a list, forms, a detail page, a sidebar entry). In Strutvane you don’t build resources: after node strut migrate, every table with a model gets one, behind sign-in and your policies. You then customise what you want, and nothing you customise is overwritten.

Terminal window
node strut make:migration create_tags_table

Add a column to the migration (t.string('name', 50).unique()), then:

Terminal window
node strut migrate

What you’ll see: Tags in the sidebar (for users whose policy allows it), with a list, a “New tag” form, a detail page and edit and delete; and an API:

Terminal window
curl http://localhost:3000/api/tags -H "Authorization: Bearer $TOKEN"
{ "data": [], "meta": { "page": 1, "perPage": 25, "total": 0, "lastPage": 1, "from": null, "to": null } }

Your First CRUD walks through the same flow with a bigger table.

Piece Where Owned by
Types (Tag, NewTag, TagPatch, TagJson) .strutvane/types/models.d.ts Strutvane (regenerated)
Metadata: labels, searchable, sortable and filterable fields, relations, slug source .strutvane/resources.json Strutvane
The API routes routes/resources.gen.ts, imported by routes/api.ts Strutvane
The UI registry .strutvane/ui.gen.ts Strutvane
Screen settings, written once for a new table resources/ui/tags.ui.ts You
The model, written by make:migration app/models/tag.ts You
The policy app/policies/tag.policy.ts You

node strut ui:sync regenerates just the UI part; migrate and sync run it for you.

Method URI Does Policy check Answers
GET /api/posts One page of posts, with search, sort and filters viewAny 200 { data, meta }
POST /api/posts Validate and create create 201 + Location header
GET /api/posts/{post} One post (by id, or by slug for tables with a slug) view 200 { data }
PUT/PATCH /api/posts/{post} Validate and change (PATCH: only the fields sent) view, then update 200 { data }
DELETE /api/posts/{post} Delete (soft delete when the table has deleted_at) view, then delete 204
POST /api/posts/{post}/restore Bring back a soft-deleted post (tables with deleted_at) restore 200 { data }
Query Example Rules
page ?page=2 1 or more
perPage ?perPage=50 1 to 100
search ?search=launch at most 200 characters; see Search & Filters
sort ?sort=-created_at,title up to 3 sortable fields; - means newest/largest first
filter[field] ?filter[status]=draft only filterable fields
filter[field][op] ?filter[price][gte]=10 operators per field type
filter[trashed] ?filter[trashed]=with with or only deleted rows (soft-delete tables)

Every bad option is reported at once in a 422, and the message lists what is allowed:

{
"status": 422,
"code": "validation_failed",
"issues": [
{ "path": ["sort"], "field": "sort", "code": "not_sortable", "message": "\"body\" can't be sorted on. Sortable fields: id, title, slug, price, status, author_id, created_at." },
{ "path": ["perPage"], "field": "perPage", "code": "invalid_integer", "message": "Page size must be a whole number from 1 to 100." }
]
}
Request Answer
Not signed in 401 unauthenticated
A record you may not see 404, exactly like a missing one, so hidden records can’t be discovered by guessing URLs
A record you may see but not change 403 forbidden
A field that isn’t in the model’s fillable list, or isn’t a column 422 unknown_field
A model hook (creating, updating, saving, deleting, restoring) returned false 422 write_cancelled (nothing was saved)
A duplicate value in a unique column 422 with code taken on that field (“That email is already taken.”)
Two saves racing for the same unique value 409 conflict
A body that isn’t JSON 415
  • Hidden and secret columns (password, tokens, keys, and any name the shared redaction matcher catches, such as api_key or remember_token) are never serialised, searched, sorted, filtered or accepted.
  • Internal tables never get an API or screens: migrations, seeders, sessions, cache*, jobs, failed_jobs, job_batches, password_reset_tokens, personal_access_tokens, passkeys, roles and team memberships, invitations, audit logs and outboxes. The app refuses to start if a resource controller would serve one.
Screen Address What’s on it
List /posts Search, sortable columns, a filter panel and filter chips, numbered pages (25 per page; 10, 50 or 100), deleted rows on request
Create /posts/new One field per fillable column, the right widget per type, the slug following the title
Detail /posts/hello-world Every visible field, relation links, a tab per related list (“Posts, 13”), previous/next record
Edit /posts/hello-world/edit The form, sending only what changed

Widgets by column type:

Column Widget
string text box (with a character counter when it has a length)
text multi-line text
decimal, integer number box (the decimal point survives typing)
enum select
boolean switch; “✓ Yes / — No” in lists
date, timestamp date picker; lists show relative time (“3 hours ago”) with the exact time on hover
foreignId a searchable picker (“combobox”) over the related table; lists show the related title as a link
slug follows the title until you edit it, with a live URL preview

Proven in spike 14 (P0 in the UI standard):

  • Back returns to the list with its page, filters, sort and scroll restored (Alt+←).
  • Breadcrumbs on every page; deep links: search, filters, sort, page and size live in the URL, so you can share a view.
  • Ctrl/Cmd+K opens a command palette: jump to a screen, a record by title, or an action (“New post”).
  • Keyboard shortcuts: ? help, / search, n new, e edit, g d dashboard; never while you type.
  • Lists: sticky header, show/hide columns, compact density, filter chips with “Clear all”, “Copy link to this view”, search-term highlight.
  • Forms: “Save and add another”, an unsaved-changes guard, the first error scrolled into view and focused.
  • Safety: Undo after delete (10 seconds), type-to-confirm for permanent deletes, automatic retry of reads on network errors.
  • Detail: previous/next record, related-record counts on tabs, Copy ID.

Everything goes through the model’s policy, found by name: the model Post uses app/policies/post.policy.ts with no registration (an explicitly set policy overrides it):

Policy method Controls
viewAny the sidebar entry, the list, and search in the command palette
view the detail page (and whether a record “exists” for this user at all)
create the “New” button and the create form
update the Edit button and the edit form
delete the Delete button

New policies allow only admins. Hiding a button is a convenience; the API refuses the same action regardless. See Authorization.

Endpoint Does
/api/posts/options { value, label } pairs for select boxes
/api/posts/count A count with the same filters as the list
/api/posts/aggregate Group-by counts and sums, for charts (its own aggregate rate limit)
CSV export Up to 10,000 rows, formula-safe (a cell can’t start a spreadsheet formula); opt-in per resource
Bulk actions Up to 100 ids, each checked against the policy, all or nothing; opt-in per resource
/api/search One search across every resource you may list
ETag / If-Match A 409 when someone else saved the record since you opened it

Turn on the opt-in ones in the resource’s settings file: actions: { export: true, bulk: true }. See Customising Screens.

You want Do
No API and no screens for a model Model('posts', { fillable, api: false, ui: false }) in the model
Screens but no API, or the other way round api: false or ui: false alone
Keep the screens, write the API yourself node strut make:controller PostController --model=Post, route it in routes/api.ts
Every line of the API in your file node strut make:controller PostController --api
Keep the API, change the screens edit resources/ui/posts.ui.ts
Hide only the sidebar entry navigation: { hidden: true } in posts.ui.ts

Your own controller extending ResourceController keeps every safety check (policies, visible(), unique checks, problem+json) and lets you override one step. See Controllers.

With teams switched on, every resource is limited to the current team: lists, details, unique checks and slugs. Cross-team attack tests are generated for every resource. See Tenancy.

Why: one of: it has no model (create_*_table migrations write one; others don’t), it’s an internal table, or your policy denies viewAny. Fix: check node strut model:show tags; it says when a table is internal. Then check the policy.

- sessions is an internal table: no screen, sidebar entry or typed names (by design).

Why: framework and identity tables never get auto screens or APIs. Fix: none needed. For a real admin need, write a purpose-built controller with explicit fields.

“… would serve the internal … table over the API”

Section titled ““… would serve the internal … table over the API””
✖ SessionController would serve the internal "sessions" table over the API.
→ Framework and identity tables (sessions, tokens, roles, jobs, users…) are never auto resources. Write a purpose-built controller with explicit fields instead.

Fix: use a plain Controller and return only the fields you mean to show.

A column I added doesn’t appear in the list

Section titled “A column I added doesn’t appear in the list”

Why: posts.ui.ts lists its columns explicitly, so new ones aren’t added; ui:sync reported it. Fix: add the column to the list, or switch back to columns: auto(). See Customising Screens.

Why: their policy’s view says no, and hidden records answer exactly like missing ones. Fix: that’s intended. If they should see it, change view in the policy.