Troubleshooting
Common symptoms, their causes, and fixes.
Renderers look unstyled
Symptom: inputs and selects render without their Tailwind styles.
Cause: your shadcn theme tokens aren't set up — the renderers use token utilities
(border-input, bg-background, text-muted-foreground, …) that resolve to nothing
without them.
Fix: run npx shadcn@latest init (it writes the theme tokens + Tailwind setup), then
npx shadcn@latest add @easy-forms/easy-form. Tailwind scans your components/ directory
automatically. See Installation.
The form chrome looks unstyled
Symptom: the container, footer, and buttons have no styling.
Cause: your Tailwind build is not scanning components/easy-forms/, or your shadcn theme
tokens (--primary, --border, --card, …) are not defined.
Fix: run npx shadcn@latest init if you have not — it writes the tokens and Tailwind
setup. The chrome is plain Tailwind utilities in files you own, so if the rest of your app is
styled and this is not, the cause is almost always content-scanning configuration.
My chrome broke after upgrading to 0.2
Symptom: chrome that used to render correctly is now unstyled, or you have a dangling
import of easy-forms.css.
Cause: 0.2 deleted easy-forms.css and moved all chrome into ejectable components.
Fix: re-run npx shadcn@latest add @easy-forms/easy-form to pull the current files, and
delete any leftover easy-forms.css import. See Upgrading.
The old stylesheet used bare var(--token) references, which are only valid for Tailwind
v4-style full-colour tokens. Consumers on Tailwind v3 with HSL-triplet tokens got silently
broken chrome. Utilities route through your own Tailwind wiring, so that mismatch is gone.
A group's fields are misaligned
Symptom: in a grid group, the title occupies the first cell and every field shifts.
Cause: the grid class is on the <section> instead of the inner content <div>.
Fix: put the layout/grid class on the inner content <div> in your group renderer.
"Group with dependents is missing an id"
Symptom: a thrown error in development when a group has dependents.
Cause: group-level dependencies need a stable address.
Fix: add an id to the group.
A dependency cycle error
Symptom: DependencyCycleError with a path like a → b → a.
Cause: two fields derive from each other.
Fix: make one field the source of truth and derive the other in a single direction. See Cycle detection.
Edits to the library don't show up
Symptom: in a monorepo, changes to the packages aren't reflected in your app.
Cause: your app imports the built dist, not the source.
Fix: rebuild the packages (or run them in watch mode). For Next.js consuming source, add
the packages to transpilePackages.