Next.js: editable source, clean boundaries.

Install

npx shadcn@latest add https://gummyui.dev/r/gummy-base.json https://gummyui.dev/r/gummy-button.json

Import @/components/gummy-theme.css and @/components/gummy-button.css from the root layout or global stylesheet. Import the component from @/components/ui/gummy-button.

App Router behavior

Interactive registry source declares its own client boundary where needed. Keep Server Components as the default in your application and move only stateful composition behind a client boundary.

Prepare the consumer project

Check components.json before installing. Its component and utility aliases must resolve inside the application, and its CSS entry should identify the stylesheet that owns application-wide styles. If your project uses a src directory, keep the alias and registry destination aligned with that layout rather than moving generated files after every install.

The shared Gummy theme defines material tokens and environmental behavior; the component stylesheet defines only that component's presentation. Load each generated stylesheet once in a stable global entry. Do not import CSS from gummyui.dev at runtime, because the installed files are the versioned source your project owns.

Compose across server and client boundaries

A Server Component may render a client component and pass serialisable content or configuration into it. Keep data fetching, authentication checks and sensitive server work outside the installed UI source. If you wrap a Gummy component, preserve its label relationships, keyboard behavior, forwarded ref and focus handling rather than replacing them with click-only containers.

After composition, exercise the real route—not only an isolated preview. Check loading, empty, error and disabled states, then navigate away and back to catch hydration, focus-restoration or layout problems.

Update safely

Registry installation writes editable files, so a later install can conflict with changes you made locally. Review the proposed diff before accepting an overwrite. Carry intentional local changes forward, re-run the component's behavior contract, and commit the installed source with the application so production does not depend on a network fetch.

Verify

Run your project's TypeScript, lint, behavior, accessibility, and production-build checks after installation. Gummy UI's release gate performs the independent typecheck and build in a fresh temporary Next.js consumer.