Adding WireKit to the Livewire Starter Kit

The Livewire Starter Kit ships with its own layouts, Vite configuration, and Tailwind v4 setup. php artisan wirekit:install knows how the kit is put together and wires WireKit into it. This page walks through what the installer changes, so you can check the result, and finish by hand if your project has moved away from the kit's defaults.

Want to skip all of this? A standalone WireKit-flavored starter kit (pushery/wirekit-starter-kit) is on the roadmap. Once shipped it will replace this entire walk-through with a single composer create-project pushery/wirekit-starter-kit my-app. Until then, follow the steps below for an existing Livewire Starter Kit project.

Prerequisites

You created the project with laravel new my-app --livewire (or chose Livewire when the Laravel installer asked for a starter kit), the kit's login and dashboard pages render, and npm run dev works without errors. If you don't have a project yet, start with the main Getting Started recipe instead — it walks the clean-room install, which is simpler than retrofitting.

Step 1 — Composer install

# 1. Add WireKit plus the icon renderer and one icon set.
#    The Starter Kit doesn't ship blade-icons; WireKit's <x-wirekit::icon>
#    needs both the renderer and a preset.
composer require pushery/wirekit blade-ui-kit/blade-icons blade-ui-kit/blade-heroicons

# 2. Run the WireKit installer. On the Starter Kit it:
#    - publishes config/wirekit.php
#    - copies the compiled assets to public/vendor/wirekit/
#    - adds WireKit's @source line to resources/css/app.css (Step 2)
#    - adds @wirekitStyles and @wirekitScripts to the kit's layouts (Step 3)
#    - adds /public/vendor/wirekit to .gitignore (skip with --no-gitignore)
php artisan wirekit:install

The installer prints a line for every file it changed. To see that list before anything is written, run php artisan wirekit:install --diff. To undo the install, php artisan wirekit:install --rollback puts every file it touched back the way it was.

Step 2 — Tailwind `@source`

The Starter Kit's resources/css/app.css begins like this:

@import 'tailwindcss';
@import '../../vendor/livewire/flux/dist/flux.css';

@source '../views';

wirekit:install adds one line directly under @import 'tailwindcss';:

@source '../../vendor/pushery/wirekit/resources/views/**/*.blade.php';

Without it, Tailwind never scans WireKit's templates and every component renders unstyled. If the installer couldn't write to app.css (filesystem permissions, a locked file), add the line by hand.

Step 3 — Layouts

The kit's layout files don't contain the page's <head> and <body>. resources/views/layouts/app.blade.php is a short wrapper that hands the page to a shell:

{{-- resources/views/layouts/app.blade.php, as the Starter Kit ships it --}}
<x-layouts::app.sidebar :title="$title ?? null">
    <flux:main>
        {{ $slot }}
    </flux:main>
</x-layouts::app.sidebar>

The shell is resources/views/layouts/app/sidebar.blade.php. It holds the <html>, the <head> and the </body>, and it takes the contents of its <head> from resources/views/partials/head.blade.php. The login and registration pages work the same way: resources/views/layouts/auth.blade.php hands them to resources/views/layouts/auth/simple.blade.php.

wirekit:install follows both wrappers to their shells and adds the two directives there: @wirekitStyles at the end of the <head>, @wirekitScripts at the end of the <body>. It also wires the alternative shells the kit keeps beside them — app/header next to app/sidebar, auth/card and auth/split next to auth/simple. Switching between them is a one-word edit to the wrapper, and a shell without the directives would drop WireKit from every page the day you make it.

After the install, each shell looks like this:

{{-- resources/views/layouts/app/sidebar.blade.php, excerpt --}}
<head>
    @include('partials.head')
    @wirekitStyles
</head>
<body class="min-h-screen bg-white dark:bg-zinc-800">
    {{-- the kit's sidebar and your page --}}
    @fluxScripts
    @wirekitScripts
</body>

The kit's layouts contain no @livewireScripts: Livewire adds its script to the end of the page by itself, after everything the template renders. That puts @wirekitScripts ahead of it, which is the order that matters — Livewire starts Alpine, and WireKit's Alpine components have to be registered first. If you add @livewireScripts to a layout yourself, put @wirekitScripts directly above it.

When the installer can't find the shell

If your project has moved away from the kit's structure, the installer says so instead of guessing: it reports that a layout "renders no <head> or </body> this install can find". Open the file your pages actually render — the one with </head> and </body> in it — and add @wirekitStyles inside its <head> and @wirekitScripts just before its </body>.

Step 4 — Verify

Run the doctor:

# 1. Check the install end to end.
php artisan wirekit:doctor

These are the lines that matter for the Starter Kit. Your report has more, and which ones appear depends on your configuration:

  ✓ Tailwind @source includes WireKit templates
  ✓ config/wirekit.php published
  ✓ @wirekitStyles directive found
  ✓ @wirekitScripts directive found
  ✓ @wirekitScripts is before @livewireScripts (or no explicit @livewireScripts)
  ✓ Every page shell your layouts render loads WireKit
  ✓ Alpine.js provided by Livewire v4+

The page-shell line follows the app and auth layouts to the shells they render right now. If one of them doesn't load WireKit, it names the file; run php artisan wirekit:install again, or add the directive to that file by hand. For any other failing line, the doctor prints the fix underneath it.

Then drop a single component into one of your Livewire views to confirm it renders:

<x-wirekit::button intent="primary">Hello from WireKit</x-wirekit::button>

Now wirekit:install has added the @source line, rebuild so Tailwind picks up WireKit's classes:

# 1. Production build — bakes WireKit's `@source` classes into your compiled CSS.
#    Required before any deploy; run it once now to confirm the retrofit compiles.
npm run build

For local development, restart npm run dev instead so Vite re-reads the new @source directive, then reload — the button renders with full styling. If it still looks unstyled under npm run dev, a one-shot npm run build clears the cached incremental-compile state the dev server holds onto, then npm run dev again.

Common pitfalls when retrofitting

npm run dev was running while wirekit:install ran. Vite's dev server caches the compiled CSS in memory; wirekit:install writes the @source line to app.css after Vite has already compiled it. Stop npm run dev (Ctrl+C), run wirekit:install, restart npm run dev.
A layout of your own. The installer wires the app and auth layouts and the shells they hand pages to. A layout you add yourself — say, a marketing layout at resources/views/layouts/marketing.blade.php — needs the two directives added by hand.
A project created before the kit's Livewire v4 release. It keeps the same files under resources/views/components/layouts/ instead of resources/views/layouts/. The installer follows those in the same way.
Inertia / non-Livewire pages. If your Starter Kit project mixes Livewire pages with Inertia pages, the Inertia layout file ALSO needs @wirekitStyles + @wirekitScripts. The directives are layout-level, not Livewire-specific.
wirekit:install already ran but assets aren't visible. Run php artisan vendor:publish --tag=wirekit-assets --force to overwrite stale published copies. The --force flag is required because Laravel's vendor:publish is non-overwriting by default.

What didn't change in your Starter Kit project

Your existing auth flows (Login, Register, ForgotPassword, ResetPassword) are untouched. WireKit doesn't replace any Starter Kit views.
Your existing route definitions, middleware stack, and Livewire components work exactly as before. WireKit is purely UI primitives — no service-provider takeovers, no middleware injection, no auth-flow rewrites.
The Starter Kit's own Tailwind classes still work. WireKit components emit Tailwind utilities too, so you can mix <x-wirekit::button> and your existing markup on the same page.

Next step

Once the doctor reports green and the smoke-test button renders, follow the main integration guide for the optional setup steps (font presets, icon-preset stacks, chart adapter selection). Those steps are identical for clean-room and Starter Kit projects — the four steps above cover everything Starter-Kit-specific.

If you hit a friction point not listed here, open the diagnostics with php artisan wirekit:doctor — add --fail-on=warning to see the warnings too — and paste the output into a new issue on the package repository.

Adding WireKit to the Livewire Starter Kit

Was this page helpful?