| name | pui-migrate |
| description | Migrate a Phoenix app from generated UI patterns (core_components and daisyUI class usage) to PUI primitives, theme tokens, and layout shells. Use when replacing `CoreComponents` calls, cleaning daisyUI classes from HEEx templates, adopting `use PUI`, and moving dashboard shells to `PUI.Layout`. |
PUI Migrate
Follow this workflow to migrate safely and keep behavior stable.
1. Map Existing UI Surfaces
Inventory the app before edits:
- Find generated wrappers and daisyUI-heavy templates.
- Identify dashboard shell files (
app.html.heex, layout LiveViews, sidebar wrappers).
- List custom components that can be replaced with PUI equivalents.
Use quick discovery commands:
rg -n "CoreComponents|core_components|daisy|btn-|card-|alert-|input-" lib/*_web
rg -n "<\\.flash|<\\.button|<\\.input|<\\.modal|<\\.table" lib/*_web
2. Apply Baseline PUI Integration
Carry these setup steps before component replacement:
- Add
{:pui, "~> 1.0.0-alpha"} to mix.exs and run mix deps.get.
- In
assets/css/app.css, include PUI source and CSS import:
@source "../../deps/pui";@import "../../deps/pui/assets/css/pui.css";
- In
assets/js/app.js, merge PUI hooks:
import { Hooks as PUIHooks } from "pui";hooks: %{...PUIHooks, ...} in LiveSocket config.
- Enable PUI usage in LiveViews with
use PUI (or import selected modules in *_web.ex).
3. Enable PUI Imports and Base Theme
- Add the dependency and fetch deps.
- Use
use PUI in LiveView modules or import specific modules in *_web.ex.
- Keep project-level theme variables in CSS and use semantic names (
primary, secondary, accent, destructive).
Example:
def live_view do
quote do
use Phoenix.LiveView
use PUI
end
end
4. Replace Generated Components Incrementally
Do replacements in focused slices:
- Forms:
<.input> and helpers -> PUI.Input
- Buttons/actions ->
PUI.Button
- Flash/loading ->
PUI.Flash.flash_group and PUI.Loading.topbar
- Dialog/dropdown/popover wrappers -> PUI modules
Apply one slice, compile, and test before the next slice.
5. Remove DaisyUI and Dead Wrappers
- Replace utility classes that exist only for daisyUI components.
- Delete now-unused wrapper functions in
core_components.ex.
- Remove obsolete imports/usages and references.
6. Move App Shell to PUI.Layout
For dashboard-style apps:
- Use
PUI.Layout.app_layout/1 as the root shell.
- Compose sidebar sections with
PUI.Layout.sidebar/1 and sidebar_menu_item/1.
- Use
PUI.Layout.content_header/1 for header controls.
Keep public/auth surfaces split as needed by the host app.
7. Validate and Clean Up
Run:
mix compile
mix test
mix format
Confirm there are no remaining generated-component hooks:
rg -n "CoreComponents|core_components|daisy|<\\.flash|<\\.modal" lib/*_web
References
