Adopt Frontfriend — Frontfriend

Frontfriend v4 is designed as an addon for teams already building with shadcn. Adoption starts with your existing codebase and target, then connects tokens and component configuration.

Start with an inventory

Create a branch and commit your current UI. Record the framework, primitive library, Tailwind version, UI directory, local modifications and installed components. Identify any custom composition that differs from current upstream APIs.

Connect a Design System using Installation. Set its framework and primitive explicitly. Existing Radix code should stay on the Radix target unless you deliberately plan a primitive migration.

Extract your component styling

The CLI has a migration path for existing shadcn component styling:

npx frontfriend migrate --help
npx frontfriend migrate --component button --no-push

Use a single component first. --no-push keeps the generated configuration local for review. Check the output, semantic token mappings and remaining local classes before accepting a cloud write.

npx frontfriend migrate --component button

The v4 server migration implementation uses snapshots for recovery. Confirm the behavior supported by the package version you installed; do not assume a migration is complete just because a command exits successfully.

Adopt deliberately

Download the same canonical target only after reviewing the existing source and generated configuration. An overwrite can replace local modifications. Test loading, disabled states, focus rings, nested overlays and responsive layouts in your actual application.

What migration does not promise

The planned shadcn ingest feature is deferred until after v4 GA. Do not confuse it with the existing migrate command. Universal API equivalence, arbitrary component conversion and switching primitives without source changes are not guarantees.

Validate the result

Check your source diff and configuration diff.
Verify light and dark mode and semantic color contrast.
Exercise the component with mouse and keyboard.
Run typechecking, application tests and a production build.
Repeat with the next component after the first one is accepted.

For existing Frontfriend v3 projects, use v3 to v4 migration instead. For the latest delivery state, see Release status.