# Adopt Frontfriend

Bring your existing shadcn project into a shared design system.

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](/docs/installation/):

```bash
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:

```bash
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.

```bash
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](/docs/migration-v3-v4/). For the latest delivery state, see [Release status](/docs/release-status/).