Adopt Frontfriend

Frontfriend 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 first

Every project starts from a Design System. Connect one before you migrate, using Installation:

npx frontfriend login
npx frontfriend setup --ff-id YOUR_DESIGN_SYSTEM_ID --framework react --primitive radix

Set the framework and primitive explicitly. Existing Radix code should stay on the Radix target unless you deliberately plan a primitive migration.

Without an ff-id, migrate and init stop before any other check with No Design System connected to this project, and they do not change the project. If the ff-id does not match a Design System, or your account cannot access it, the CLI reports that separately.

Extract your component styling

The migration runs on the Frontfriend platform. It sends your shadcn component styling to the connected Design System as a new version and keeps a snapshot for recovery:

npx frontfriend migrate --help
npx frontfriend migrate --component button

Use a single component first. The migration runs on the Frontfriend platform: the CLI uploads the component source, and the platform saves a restore snapshot and writes a new Design System version. The command requires an ff-id and there is no local-only mode, so every run is a cloud write. Check the reported components, semantic token mappings and remaining local classes after each run.

npx frontfriend restore

The v4 server migration implementation uses snapshots for recovery. restore without an id lists the snapshots; with an id it restores the original shadcn sources. Confirm the behavior supported by the package version you installed; do not assume a migration is complete just because a command exits successfully.

Until the project is migrated, init stops with a reminder to run migrate. Run npx frontfriend init --force only if you want the Design System styling as-is.

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 general availability. 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

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

This guide is not for existing Frontfriend v3 projects. The Frontfriend team runs that migration with you, see Migrate from v3. For the latest delivery state, see Release status.