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.

Customising Screens

View as Markdownllms.txt

Every generated resource gets a small settings file you own: resources/ui/posts.ui.ts. It decides which columns the list shows, which fields the form has, which filters are offered, and how the sidebar entry looks. Strutvane writes it once, when the table first appears, and never touches it again. Change anything; the next migrate keeps your edits.

After node strut migrate creates the posts table, you’ll find:

resources/ui/posts.ui.ts
import { auto, defineResourceUi } from '@strutvane/ui'
/**
* How posts look in the admin UI. This file is yours: `ui:sync` wrote it once,
* when the `posts` table first appeared, and never touches it again.
*/
export default defineResourceUi('posts', {
columns: auto(),
form: auto(),
filters: auto(),
navigation: { icon: 'file-text' },
})

Hide the long body column from the list:

resources/ui/posts.ui.ts
export default defineResourceUi('posts', {
columns: auto({ except: ['body'] }),
form: auto(),
filters: auto(),
navigation: { icon: 'file-text' },
})

What you’ll see: save the file and the list loses its Body column at once (hot reload). Nothing else changes, and future columns still appear by themselves.

auto() means “whatever the schema says, now and later”. It picks sensible defaults:

Setting auto() shows Never shows
columns listed columns, the title field first the id, hidden and secret columns
form fillable columns that have an input hidden, secret and system columns
filters columns with filter operators long text and JSON, the id, updated_at, deleted_at, hidden and secret columns

Two options adjust it without giving up the “follow the schema” behaviour:

Option Does Example
except leave these fields out auto({ except: ['meta'] })
order put these first, in this order; the rest follow in schema order auto({ order: ['title', 'status'] })
form: auto({ except: ['meta'], order: ['title', 'status'] }),

Replace auto() with an array and you decide exactly what’s shown, in that order:

columns: ['title', 'status', 'author_id', 'created_at'],

From then on, a new column is not added to that list. ui:sync tells you about it instead, so you can decide:

ui:sync:
! New column posts.subtitle (columns) is NOT shown: resources/ui/posts.ui.ts lists columns explicitly. Add 'subtitle' to that list if you want it.
Setting Type Default Means
columns auto(…) or a list auto() The list’s columns
form auto(…) or a list auto() The create and edit form fields
filters auto(…) or a list auto() The filter panel
label { singular, plural } from the table name “Post” / “Posts” in titles, buttons and the sidebar
navigation { icon, group, order, hidden, badge } an icon guessed from the name The sidebar entry; see Sidebar
pageSize 10, 25, 50 or 100 25 Rows per page
defaultSort a field, or -field the table’s default 'title' (A to Z) or '-created_at' (newest first)
actions { export?, bulk? } both off Opt-in “Export CSV” and bulk delete/restore
resources/ui/posts.ui.ts
import { auto, defineResourceUi } from '@strutvane/ui'
export default defineResourceUi('posts', {
label: { singular: 'Article', plural: 'Articles' },
columns: auto({ except: ['body'], order: ['title', 'status'] }),
form: auto({ except: ['meta'], order: ['title', 'status'] }),
filters: ['status', 'author_id', 'created_at'],
navigation: { icon: 'file-text', group: 'Content', order: 1, badge: 'count' },
pageSize: 50,
defaultSort: '-created_at',
})

What you’ll see: “Articles” in the sidebar under Content, with a live row count; the list newest first, 50 per page, Title and Status first; three filters only.

actions: { export: true, bulk: true },

What you’ll see: an “Export CSV” button and row checkboxes with bulk delete and restore. They’re off by default because exporting or deleting many rows at once is a bigger permission than viewing one; the API must also allow them for the user.

Every field name in the file is checked against your schema (.strutvane/ui.gen.ts teaches TypeScript the columns of each table):

columns: ['title', 'subtitel'], // ✖ compile error: no such column
auto({ except: ['nope'] }), // ✖ compile error
defaultSort: '-nope', // ✖ compile error
defineResourceUi('invoices', { … }), // ✖ compile error: no such resource
navigation: { icon: 'reciept' }, // ✖ compile error ("Did you mean 'receipt'?")
columns: ['title', 'password'], // ✖ compile error: secret columns aren't field names

When a migration drops a column you still name

Section titled “When a migration drops a column you still name”

You drop subtitle, run migrate, and ui:sync says:

ui:sync:
x resources/ui/posts.ui.ts still names 'subtitle' in columns, but posts no longer has it. Remove it; until then the file does not type-check.

and the type check fails with exactly one error (the list of allowed names is shortened here):

resources/ui/posts.ui.ts(5,23): error TS2322: Type '"subtitle"' is not assignable to type '"title" | "slug" | "status" | …'.

Fix: remove 'subtitle' from the list. Nothing breaks silently: a dropped column can’t leave an empty column on screen.

node strut ui:sync runs after every migrate (and with sync). Its report:

Line starts with Means
+ New screen: … A new table got its settings file (“yours to edit; ui:sync will not touch it again”)
+ New column … appears automatically A new column joined an auto() list
! New column … is NOT shown A new column, but the list is explicit; add it if you want it
x … still names '…' A dropped column is still named; the file won’t type-check until you remove it
! … is missing You deleted a settings file; that screen uses the defaults (restore it from git to customise again)
! … belongs to a table that no longer exists The table was dropped; delete the file
? … The file couldn’t be read safely (see below)
- … is an internal table No screen, by design
ui:sync: screens are up to date. Nothing to report

ui:sync reads your settings file without running it (no app code runs during migrate). So it understands plain values, auto(…), lists, as const and satisfies. If you build a list with a variable or a spread, it can’t check it, and says so with the line number instead of guessing (something like this):

ui:sync:
? resources/ui/posts.ui.ts:4: columns is built from a variable, so new columns can't be checked. Write the list inline.

The screens still work; only the “new column” report is skipped for that setting.

The settings file only changes how screens look. Anything that changes what the API accepts stays where the API reads it:

You want Change it in
A field people may edit fillable in app/models/post.ts
A column searchable, sortable, unique, or a slug the migration
Who may see or change posts app/policies/post.policy.ts
Validation beyond the column types a form request (Requests)
The look (colours, fonts, density) resources/ui/theme.css (Frontend, Designs)

Why: it can’t have: settings files are created with “create only” writes and never overwritten. Most likely the change was in a generated file (.strutvane/ui.gen.ts), which is regenerated. Fix: put customisations in resources/ui/<table>.ui.ts only.

I deleted posts.ui.ts to reset it, and it didn’t come back

Section titled “I deleted posts.ui.ts to reset it, and it didn’t come back”

Why: ui:sync never recreates a file you deleted, so it can’t undo a deliberate choice; the screen uses the defaults and the report says the file is missing. Fix: restore it from git (git checkout -- resources/ui/posts.ui.ts), or write a fresh one with columns: auto() and friends.

auto().except('body') compiles but does nothing useful

Section titled “auto().except('body') compiles but does nothing useful”

Why: the chained form can’t be type-checked, so it isn’t supported. Fix: use the options form: auto({ except: ['body'] }).

Windows: ui:sync failed with EPERM while the dev server ran

Section titled “Windows: ui:sync failed with EPERM while the dev server ran”

Why: a file watcher briefly held the generated file. The prototype retries the rename with a short back-off; a rare failure is safe (nothing is half-written). Fix: run node strut ui:sync again.