Common mistakes
Common mistakes
1. Hand-editing auto-generated columns
Problem: You edit schema.ts or accept every column in a crouton update diff without reviewing, then later run crouton update again and lose your changes.
Rule: crouton update fully regenerates schema.ts. Never edit it by hand.
What you own: Everything in resource.json β fieldInput, label, searchable, sortable, hiddenInTable, enum refs, relations. These are never overwritten.
Fix: Move any customisation into resource.json. If you find yourself wanting to change schema.ts, you probably want a column override in resource.json instead.
2. kind: "custom" when you only need an adapter
Problem: Your data comes from a non-Prisma backend (e.g. Elasticsearch). You set kind: "custom" on every resource and write a repository.ts for each one β which is a lot of boilerplate.
Fix: Set adapter: "custom" on the datasource in data-source.json. The adapter handles CRUD for all resources on that datasource. Resources stay kind: "prisma" (the default) and declare a model; the adapter uses the model name as the key.
Use kind: "custom" only when one resource has genuinely different data access than the others.
See Decision tables β kind vs adapter.
3. Wrong fieldInput.type spelling
Problem: A column with fieldInput.type: "autocompleet" or "Textarea" silently falls back to the default renderer. The form looks wrong but no error appears.
Fix: Run crouton validate β it checks fieldInput.type against the registered renderer list and reports unknown types.
npx crouton validate resources resources/book/resource.jsonValid built-in types: autocomplete, textarea, select, multiSelect, boolean, toggle, date, dateTime, dateRange, number, integer, markdown, array, string.
4. Skipping crouton validate after editing resource.json
Problem: A typo in resource.json causes a silent load failure β the resource disappears from the sidebar with no obvious error message.
Fix: Always run crouton validate after any manual edit:
npx crouton validate resources resources/book/resource.jsonFor a whole directory:
npx crouton validate resourcesCheck the status page in the running app β it shows load errors for every resource.
5. Wrong relation direction
Problem: The manyToOne column (with the FK) is declared on the parent resource, or the oneToMany side is declared on the child. The autocomplete appears on the wrong form and saves nothing.
Rule: The manyToOne column goes on the model that holds the foreign key. The oneToMany side goes on the other end (the parent, in the UI sense).
Example: Book has authorId β book's resource.json gets the manyToOne autocomplete. Author has many books β author's resource.json gets the oneToMany embedded table.
Fix: Check which table has the FK column in the Prisma schema. That model's resource.json gets manyToOne; the other gets oneToMany.
See Add relations for a complete example.
6. Missing $schema in resource.json
Problem: Your editor does not autocomplete resource.json fields, and you do not discover typos until runtime.
Fix: Add the $schema line to every resource.json:
{
"$schema": "https://ghentcdh.github.io/crouton/schema/v1/resource.schema.json",
"schemaVersion": 1,
"name": "book",
...
}VS Code and other editors with JSON Schema support will validate and autocomplete all fields inline.
7. Missing model for a Prisma resource
Problem: You copy a kind: "custom" example and forget to add model. Crouton rejects the resource at load time with a message about a missing model.
Fix: Every kind: "prisma" resource (the default) must declare model β the exact Prisma model name, case-sensitive.
{
"name": "book",
"model": "Book",
...
}8. Editing resource.json columns that match Prisma field names but not the right case
Problem: The Prisma model has publishedYear but you write published_year in resource.json. The column shows in the table but filtering and sorting break.
Fix: Column keys in resource.json must match the Prisma field name exactly (camelCase, as Prisma emits it). Run crouton update to generate the canonical names, then configure display on top.