Admin panel
customizeTable
If you use the CMS, every table the backend serves already has a collection in
the panel, derived from the table itself (see
how tables become collections). customizeTable states
what should differ, and nothing else. It lives in the frontend, next to the rest
of your React code, so a custom field is a component you import like any other.
// frontend/src/cms/posts.tsximport { customizeTable, updateRecord } from "@rebasepro/cms";import type { posts } from "../../../backend/schema/posts";import { CustomMarkdownEditor } from "../components/CustomMarkdownEditor";
export const postsCms = customizeTable<typeof posts>("posts", { name: "Blog Posts", singularName: "Blog Post", icon: "FileText", group: "Content",
defaultViewMode: "cards", enabledViews: ["table", "cards", "kanban"], kanban: { columnField: "status", orderField: "__order" },
display: { title: "title", image: "heroImage", status: "status", date: "publishDate", },
fields: { status: { enumLabels: { draft: { label: "Draft", color: "gray" }, needs_review: { label: "Needs Review", color: "orange" }, published: { label: "Published", color: "green" }, archived: { label: "Archived", color: "red" }, }, }, title: { multiline: true }, content: { Field: CustomMarkdownEditor }, orgId: { hidden: true }, __order: { hidden: true, disabled: true }, },
entityActions: [ { key: "publish", name: "Publish", icon: "Send", collapsed: false, isEnabled: ({ row }) => row?.status !== "published", onClick: ({ id, context }) => updateRecord(context, "posts", id, { status: "published", publishDate: new Date().toISOString() }, "Published"), }, ],});Pass the result to <RebaseCMS tableCustomizations={[postsCms]}/>; see
the frontend overview.
Where the files live
Section titled “Where the files live”frontend/src/cms/├── index.ts # export const tableCustomizations = [postsCms, …]├── posts.tsx # customizeTable("posts", …)└── events.ts # defineFirestoreCollection(…), for FirestoreThe names are a convention. What matters is that the results reach
<RebaseCMS tableCustomizations>. A table without a file is shown as derived.
The frontend imports the table’s type only: import type { posts }. A type
import is erased when the bundle is built, so hooks and server code in
backend/schema never reach the browser. A value import from backend/ in
frontend code is the one thing not to write. The backend never imports anything
from the frontend.
The slug and the type
Section titled “The slug and the type”The first argument is the table’s slug: the name it was defined under, or the
slug it was given. With the table as the type argument, the slug, every key
that names a field and every enum value is checked against the table:
Checked against typeof posts |
A mistake is |
|---|---|
| the first argument | a type error unless it is the table’s slug |
fields keys |
a column key or a relation name |
fieldOrder, listFields, form entries |
a field, a dotted path into one ("seo.title"), subcollection:<relation>, or an additional field’s key |
display, sort, fixedFilter, defaultFilter, filterPresets |
a field or a path into one |
kanban.columnField |
a column holding one closed set of strings (col.enum([...]), or .oneOf([...])) |
kanban.orderField |
a text column |
enumLabels, enumOrder |
values the column can hold; a column with no closed set accepts neither |
| field options | those of the column’s type: multiline on a text column, format on a number |
entityActions[].onClick and friends |
row is the table’s InferRow |
defineTable("blog_posts", { slug: "posts", … }) is customized as
customizeTable<typeof posts>("posts", …): still one type argument. Without the
type argument, customizeTable("posts", { … }) accepts the same options,
loosely typed.
What is refused, and what is skipped
Section titled “What is refused, and what is skipped”customizeTable checks what the compiler cannot see when the module loads, and
throws with what to write instead:
- an unknown option, with the nearest known one, or with the new name of an old
adminoption; - a component given as a string path, a lazy
() => import(…)thunk or anything that is not a React component; - an entity action without
nameoronClick, a custom view withoutBuilder, akanbanwithoutcolumnField, areferenceTothat is not a slug; fieldsinside a relation’soverrides: restyle the target table with its owncustomizeTable.
customizeTable("posts"): unknown options: - `propertiesOrder` — it is `fieldOrder` now - `iconn` — did you mean `icon`?The result is frozen. Passing two customizations of the same slug to
<RebaseCMS> throws: which one wins would depend on import order.
What the server serves can differ from what you wrote against. A column may be withheld from this caller (see field access), or the table may have changed since. That is not an error at runtime. In development the panel prints one warning per mismatch, and skips it:
- a customization whose slug matches no served table is ignored;
- a field, column entry, display slot, form entry or kanban field the table does not serve is dropped;
- an option that does not apply to the field’s type (
formaton a text column,enumLabelson a field without a closed set) is ignored.
The rest of the customization still applies.
Table options
Section titled “Table options”Every key is optional. A key you leave out keeps what the panel derived.
Identity and navigation
Section titled “Identity and navigation”| Option | Type | Effect |
|---|---|---|
name |
string |
The plural label: drawer, page heading. Derived from the table name otherwise. |
singularName |
string |
The label of one record. |
description |
string |
Shown under the heading and on the home card. |
metadata |
Record<string, unknown> |
Your own data, merged over the table’s metadata. |
icon |
string | ReactNode |
A Lucide icon name ("FileText") or an element. |
group |
string |
The navigation group. |
hideFromNavigation |
boolean |
Not in the drawer. Still reachable by URL and as a reference target. |
hideFromEntityViews |
boolean |
Not offered as a tab on the records of tables that relate to it. |
| Option | Type | Effect |
|---|---|---|
defaultViewMode |
ViewMode |
The view a visitor lands on: "list", "table", "cards", "kanban" or a custom view’s key. "list" otherwise. |
enabledViews |
ViewMode[] |
The views offered in the switcher. |
kanban |
{ columnField, orderField? } |
The board: the column it groups by and the text column it stores order keys in. See View modes. |
customViews |
(string | TableCustomView)[] |
More ways to render the rows: { key, name, Builder }, or the key of one registered on <RebaseCMS collectionViews>. |
defaultSize |
"xs" | "s" | "m" | "l" | "xl" |
The default row height. |
kanban takes two keys:
| Key | Type | Effect |
|---|---|---|
columnField |
column key | The column the board’s columns come from: a col.enum([...]) or .oneOf([...]) of strings. |
orderField |
text column key | Where a card’s position within its column is stored, as a fractional order key. Without it the order resets on every read. |
Columns and slots
Section titled “Columns and slots”| Option | Type | Effect |
|---|---|---|
fieldOrder |
TableColumnId[] |
The order fields are drawn in. Fields it leaves out follow, so nothing disappears. |
listFields |
TableColumnId[] |
The columns of the list view. |
previewFields |
TableFieldKey[] |
The fields shown when a record of this table is referenced from another. |
display |
TableDisplay |
What fills a record’s title, subtitle, image, status, date and tags: a field path or a resolver. See display slots. |
additionalFields |
TableAdditionalField[] |
Computed columns. See Additional columns. |
hideIdFromCollection |
boolean |
Hide the id column. |
A computed column takes:
| Key | Type | Effect |
|---|---|---|
key |
string |
Identifies the column. Name it in fieldOrder as "total" as AdditionalFieldKey. |
name |
string |
The header. |
width |
number |
The width, in pixels. |
Builder |
(props) => ReactNode |
Renders the cell from { row, id, context }. |
dependencies |
field path or paths | The fields whose change re-renders the cell. |
value |
(props) => string | number |
The cell’s value, for export. May be async. |
Query defaults
Section titled “Query defaults”| Option | Type | Effect |
|---|---|---|
sort |
OrderBySpec |
The default sort: ["publishDate", "desc"], or several keys in order. |
fixedFilter |
FilterValues |
A filter the visitor cannot change. |
defaultFilter |
FilterValues |
The filter a visitor starts from. |
filterPresets |
FilterPreset[] |
One-click filters in the toolbar: { label?, filterValues, sort? }. |
pagination |
boolean | number |
Load in pages (true, or the page size), or everything at once (false). |
See Filters and sort.
Behaviour
Section titled “Behaviour”| Option | Type | Effect |
|---|---|---|
inlineEditing |
boolean |
Edit cells in place in the table. |
selectionEnabled |
boolean |
Rows can be selected. |
selectionController |
SelectionController |
A selection you hold outside the view (useSelectionController). |
exportable |
boolean | ExportConfig |
Whether the toolbar offers Export, and extra columns for it. See Import and export. |
openEntityMode |
"side_panel" | "full_screen" | "split" | "dialog" |
How a record opens. |
defaultEntityAction |
"view" | "edit" |
Whether clicking a record opens it to read or to edit. |
sideDialogWidth |
number | string |
The width of the side panel a record opens in. |
defaultSelectedView |
string | DefaultSelectedViewBuilder |
The tab a record opens on. |
| Option | Type | Effect |
|---|---|---|
form |
{ sidebar?, sections?, showRecordMeta? } |
Sections, and the rail beside the form. See Form layout. |
formView |
{ Builder, includeActions? } |
A component that replaces the generated form. includeActions keeps Save and Discard in the record’s bar. |
formAutoSave |
boolean |
Save as the visitor types. |
alwaysApplyDefaultValues |
boolean |
Fill declared defaults into a stored record’s empty fields when it is opened. |
includeJsonView |
boolean |
Add a tab with the record as JSON. |
localChangesBackup |
"manual_apply" | "auto_apply" | false |
Keep unsaved edits in local storage. |
hideIdFromForm |
boolean |
Hide the id from the form. |
form takes:
| Key | Type | Effect |
|---|---|---|
sidebar |
field ids | The fields pulled out into the rail beside the form. |
sections |
sections | The sections of the main column, below. |
showRecordMeta |
boolean |
Show the record’s id and timestamps in the rail. |
Each section takes:
| Key | Type | Effect |
|---|---|---|
key |
string |
Identifies the section; also the id of its anchor. |
title |
string |
The heading. None when omitted. |
fields |
field ids | The fields in the section, in order. |
collapsed |
boolean |
Starts collapsed. |
collapsible |
boolean |
Can be collapsed. |
readVariant |
"grid" | "summary" |
How the section reads when the record is shown rather than edited. |
Actions, views and overrides
Section titled “Actions, views and overrides”| Option | Type | Effect |
|---|---|---|
entityActions |
(string | TableEntityAction)[] |
Actions on a record. An object, or the key of one registered on <RebaseCMS entityActions>. See Entity actions. |
disableDefaultActions |
("edit" | "copy" | "delete")[] |
Built-in actions this table does not offer. |
resetPasswordAction |
false | TableEntityAction |
The auth table only (defineAuthTable): false removes the built-in reset-password action, an action replaces it (offered whatever the auth adapter supports: its backend is yours). Ignored, with a warning, on any other table. |
entityViews |
(string | TableEntityView)[] |
Extra tabs on a record. See Entity views. |
Actions |
Component[] |
Components rendered in the collection’s toolbar. |
components |
TableComponentOverrides |
Collection-scoped component overrides, each { Component, wrap? }. See Component overrides. |
browserCallbacks |
CollectionCallbacks |
Callbacks that run in the panel after the server’s hooks. Presentation only: they ship to every visitor and secure nothing. See React hooks. |
fields |
TableFields |
Per-field options, keyed by column or relation. Below. |
Field options
Section titled “Field options”fields.<key> takes the options every field takes, plus those of its column
type. Fields shows each with the widget it
changes.
Every field
Section titled “Every field”| Option | Type | Effect |
|---|---|---|
name |
string |
The label. Derived from the key otherwise (publishDate → “Publish Date”). |
description |
string |
Help text under the field. |
hidden |
boolean |
Kept out of the table and card views. Still on the form, and still read and written by the API. |
hiddenInForm |
boolean |
Kept off the form. Still in the views. |
disabled |
boolean | { disabledMessage?, clearOnDisabled? } |
The control is greyed out. disabledMessage says why, beside it; clearOnDisabled clears the value when it becomes disabled. |
readOnly |
boolean |
The value is drawn as text, with no control. |
Field |
Component |
Replaces the form control. The component itself. See Custom fields. |
Preview |
Component |
Replaces how the value is drawn outside the form. |
Filter |
Component |
Replaces the filter control for this field. |
columnWidth |
number |
The column width in the table, in pixels. |
filledByServer |
boolean |
A server hook fills it on create: the form lets a record be created without it. |
span |
1 | 2 | 3 | 4 |
How many of the form grid’s four columns it spans. |
customProps |
unknown |
Passed untouched to your Field and Preview. |
filterOperators |
WhereFilterOp[] |
Narrows the filter operators offered. [] turns filtering off for it. |
propertyConfig |
string |
The key of a field type registered on <Rebase propertyConfigs>. |
conditions |
PropertyConditions |
JSON-logic rules that hide, disable or require the field from the record’s values. Form only. See conditions. |
dynamicProps |
(props) => options | undefined |
Returns the field options that apply now, from the record being edited. Form only. |
metadata |
Record<string, unknown> |
Your own data. |
Text and uuid columns
Section titled “Text and uuid columns”| Option | Type | Effect |
|---|---|---|
multiline |
boolean |
A multi-line input, growing with its content. |
markdown |
boolean |
A markdown editor with a preview. |
previewAsTag |
boolean |
Drawn as a chip rather than text. |
clearable |
boolean |
Adds a control that sets the value to null. |
urlPreview |
PreviewType | boolean |
How a URL in the value is previewed: "image", "video", "audio", "file", or true for a link. |
referenceTo |
string |
The column holds the key of a record in another collection, on any data source: it is drawn and picked as a reference to that collection’s slug. See Firestore. |
Columns with a closed set of values
Section titled “Columns with a closed set of values”A col.enum([...]), a .oneOf([...]), or an array of either:
| Option | Type | Effect |
|---|---|---|
enumLabels |
{ [value]?: string | EnumLabel } |
Labels for some of the values. Values left out keep their derived label and colour. |
enumOrder |
value[] |
The order values are offered, and kanban columns drawn, in. The column’s own order otherwise. |
previewAsTag |
boolean |
On a col.enum(): drawn as a chip. |
clearable |
boolean |
On a col.enum(): adds a control that sets the value to null. |
An EnumLabel takes:
| Key | Type | Effect |
|---|---|---|
label |
string |
The text on the chip and in the select. |
color |
ColorKey | ColorScheme |
A chip colour key ("green", "orangeDark") or a { color, text } scheme. A value without one keeps its seeded colour. |
disabled |
boolean |
Shown, but not offered for selection. |
Number columns
Section titled “Number columns”| Option | Type | Effect |
|---|---|---|
clearable |
boolean |
Adds a control that sets the value to null. |
format |
NumberFormatOptions |
Writes the number out as currency, a percentage, or with fixed decimals. |
format takes style ("decimal", "currency", "percent"), currency (an
ISO code, required with "currency"), locale (the viewer’s otherwise),
minimumFractionDigits, maximumFractionDigits and notation
("standard" or "compact", which writes 12000 as 12K). It changes what is
drawn, never what is stored.
Date, timestamp and time columns
Section titled “Date, timestamp and time columns”| Option | Type | Effect |
|---|---|---|
clearable |
boolean |
Adds a control that sets the value to null. |
mode |
"date" | "date_time" |
Pick and show a day only, or a day and a time. Derived from the column type otherwise. |
timezone |
string |
The IANA time zone the value is shown and picked in ("Europe/Madrid"). The viewer’s otherwise. |
Vector columns
Section titled “Vector columns”| Option | Type | Effect |
|---|---|---|
clearable |
boolean |
Adds a control that sets the value to null. |
Storage columns
Section titled “Storage columns”| Option | Type | Effect |
|---|---|---|
storage |
StorageCustomization |
The upload functions that run in the browser. |
clearable |
boolean |
Adds a control that sets the value to null. |
urlPreview |
PreviewType | boolean |
How the stored URL is previewed. |
storage takes functions only; the serializable options stay on
col.storage({ … }) (see File uploads):
| Key | Signature | Effect |
|---|---|---|
path |
(context) => string |
The folder a file is uploaded to, replacing the column’s path template. |
fileName |
(context) => string | Promise<string> |
The stored file name, replacing the column’s fileName template. |
processFile |
(file) => Promise<File> |
Transforms a file before it is uploaded. |
postProcess |
(pathOrUrl) => Promise<string> |
Transforms the stored path or URL before it is written to the column. |
previewUrl |
(fileName) => string |
The URL to preview a stored file at. |
Array columns
Section titled “Array columns”| Option | Type | Effect |
|---|---|---|
expanded |
boolean |
Every item open on load. |
minimalistView |
boolean |
Items without their frame and header. |
sortable |
boolean |
Items can be reordered by dragging. |
canAddElements |
boolean |
Items can be added. |
of |
field options | The options of each item. |
storage |
StorageCustomization |
The upload functions, for col.storage().multiple(). |
enumLabels and enumOrder written on an array apply to its items.
JSON columns
Section titled “JSON columns”| Option | Type | Effect |
|---|---|---|
expanded |
boolean |
The document’s fields open on load. |
minimalistView |
boolean |
The document’s fields without their frame. |
spreadChildren |
boolean |
The document’s fields laid out as if they were the record’s own. |
keyValue |
boolean |
Edited as free key/value pairs. |
previewFields |
string[] |
The document’s keys shown in its preview. |
fields |
{ [key]: field options } |
The options of each key of the document. |
fieldOrder |
string[] |
The order the document’s keys are shown in. |
of |
field options | The options of each item, for a document that is a list. |
oneOf |
{ [variant]: field options } |
The options of each variant of a typed block (json.oneOf). |
With col.jsonb().$type<T>() or a json.object({…}) shape, fields and fieldOrder
are typed by the document’s keys. See Arrays and JSON.
Relations
Section titled “Relations”| Option | Type | Effect |
|---|---|---|
previewFields |
string[] |
The target’s fields shown in the chip for a related row. At most three fit. |
defaultValue |
EntityRelation | EntityRelation[] |
The related row(s) a new record’s form starts with: new EntityRelation(id, "<target slug>") (EntityRelation from @rebasepro/cms-types), or a list for a to-many relation. Written only when the form is saved. A column’s own default is .default() on the column. |
widget |
"select" | "dialog" |
How a related row is picked. |
fixedFilter |
FilterValues |
Offer only rows that pass this filter. |
includeId |
boolean |
Show the related row’s id in previews. |
includeEntityLink |
boolean |
Show a link that opens the related row. |
renderInForm |
boolean |
Also draw a to-many relation as a picker in the form, beside its tab. |
overrides |
table options without fields |
How the target is presented in this relation’s tab. |
Customizations, ui-config.json and preferences
Section titled “Customizations, ui-config.json and preferences”What the panel shows for a table is composed in a fixed order, each layer over the one before it:
- The derived collection: what the panel reads off the table the server serves.
- Code: the
customizeTableresults you pass astableCustomizations. frontend/src/cms/ui-config.json: the workspace’s presentation as the collection editor saved it in development, passed asuiConfig. It is a file in the frontend, so it is reviewed and deployed with it.- Workspace preferences: what an admin saves on a deployment, in the
rebase.ui_preferencestable through/api/admin/ui-config. Writing them needsschema:write. - User preferences: one person’s own column widths, view switches and hidden columns. Kept in the browser while signed out.
A scaffolded App.tsx already wires the file:
import { RebaseCMS } from "@rebasepro/cms";import { tableCustomizations } from "./cms";import uiConfig from "./cms/ui-config.json";
export const Admin = () => <RebaseCMS tableCustomizations={tableCustomizations} uiConfig={uiConfig} />;Preferences hold presentation only: labels, icon, view modes, column order,
hidden columns, enum labels and colours, kanban and query defaults. A schema
fact never lands there; the collection editor writes those to
backend/schema instead.
rebase build carries frontend/src/cms/ui-config.json into the bundle
(entry.uiConfig), so a deployed backend knows it too: GET /api/admin/ui-config
serves it as shipped beside the workspace and user layers, and the MCP views
and describe_table fold the same three layers — the file, the workspace, and
the caller’s own (none for an API key) — so an agent sees the labels, order,
hidden columns and enum labels a person sees in the panel.
rebase verify reads every customizeTable call in frontend/src/cms against
the tables, without running it: it catches a customization for a table or a
field that does not exist, a required column the form hides, a table
customized twice, a ui-config.json no <RebaseCMS> is passed, and a Vite
config without rebaseBackendGuard(). See rebase verify.
Next steps
Section titled “Next steps”- How tables become collections: what the panel derives before any of this
- Fields: each column type’s widget and options
- View modes: table, cards, kanban, display slots, filters
- Entity actions:
entityActionsandupdateRecord - Firestore beside Postgres:
externalCollectionsand references across engines