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:
npx frontfriend upgrade-config --help
npx frontfriend codemod v4 --helpValidate 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. The legacy guides remain available for reference during the transition.