# Migrate from v3

Plan the Tailwind and component transition together.

Frontfriend v3 and v4 use different token/build integrations and different component contracts. An existing v3 customer migration needs coordinated configuration conversion, source updates and custom-component review.

## Plan the transition

A v3-to-v4 migration covers component-config conversion, standard API compatibility, custom promotion and application validation. Do not treat the v4 new-project installation guide as a safe one-command upgrade for an existing customer.

## Prepare a baseline

Commit the current application, record dependency versions and export or retain a known-good Design System version. Inventory standard and custom components, local edits, build plugins, token usage and key user journeys.

## Separate the changes

Move from Tailwind v3’s plugin setup to the v4 CSS-first integration deliberately. Convert editable component configuration through the supported converter for your release. Update source using the canonical framework/primitive target and review renamed or structurally different APIs.

Inspect available tooling before use:

```bash
npx frontfriend upgrade-config --help
npx frontfriend codemod v4 --help
```

Validate the generated changes against your application’s own tests.

## Custom components

Private v3 components remain part of the managed workflow until the separate migration. Review each custom component for whether it can become a canonical component, needs explicit promotion, or remains client-specific. Preserve ownership and installation paths.

## Validate before cutover

Run typechecks, application tests and production builds. Compare representative screens in light/dark modes and check focus, overlays, forms and responsive layouts. Keep rollback evidence and known-good versions until the real application journey is accepted.

Existing v3 customers should coordinate with [Frontfriend](https://www.donux.com/contact-us). The [legacy guides](/docs/legacy/) remain available for reference during the transition.