Skip to main content
WireKit
Copy for LLM

Adding WireKit to the Livewire Starter Kit

The Livewire Starter Kit ships with its own pre-configured layout, Vite configuration, and Tailwind v4 setup. Adding WireKit on top requires touching four files; this page walks each one in order.

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 already ran laravel new my-app --livewire-starter-kit (or equivalent), the Starter Kit's auth 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 + the canonical icon packages.
#    The Livewire Starter Kit doesn't ship blade-icons; both the renderer
#    and a preset are required for WireKit's <x-wirekit::icon> component.
composer require pushery/wirekit blade-ui-kit/blade-icons blade-ui-kit/blade-heroicons

# 2. Run the WireKit installer. On the Starter Kit it will:
#    - publish config/wirekit.php
#    - copy dist/* assets to public/vendor/wirekit/
#    - append the Tailwind @source directive for WireKit's Blade templates
#      to resources/css/app.css (see Step 2)
#    - add /public/vendor/wirekit to .gitignore (Filament-style; flip with
#      --no-gitignore if you commit published assets to git)
php artisan wirekit:install

After this step php artisan wirekit:doctor should report green for "Assets published" and "Tailwind @source includes WireKit templates".

Step 2 — Tailwind @source (verify the install wrote it)

The Starter Kit ships resources/css/app.css with content like:

@import 'tailwindcss';

@source '../../vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php';
@source '../../storage/framework/views/*.php';
@source '../**/*.blade.php';
@source '../**/*.js';

wirekit:install appended one line for the WireKit vendor directory. Open resources/css/app.css and confirm this line is present:

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

If the install command couldn't write to app.css (filesystem permissions, locked file), add the line manually. Without it, Tailwind's content-scan ignores WireKit's Blade templates and every component renders unstyled.

Step 3 — Layout integration

The Starter Kit uses Livewire v4's anonymous-component layout pattern. The default file is at:

resources/views/components/layouts/app.blade.php

Open it. You'll see something close to:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{{ $title ?? config('app.name') }}</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @livewireStyles
</head>
<body>
    {{ $slot }}
    @livewireScripts
</body>
</html>

You need to add @wirekitStyles in the <head> and @wirekitScripts in the <body> BEFORE @livewireScripts. The order matters — @livewireScripts boots Alpine, and WireKit's Alpine factories must register first.

{{-- resources/views/components/layouts/app.blade.php --}}
<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{{ $title ?? config('app.name') }}</title>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
    @wirekitStyles
    @livewireStyles
</head>
<body>
    {{ $slot }}

    {{-- Critical order: @wirekitScripts BEFORE @livewireScripts --}}
    @wirekitScripts
    @livewireScripts
</body>
</html>

If the Starter Kit also ships a guest layout (typically resources/views/components/layouts/auth.blade.php for login / register / password-reset pages), repeat the same insertions there. Anywhere @livewireScripts appears, @wirekitScripts must appear immediately above it.

Step 4 — Verify

Run the doctor and look for green across the board:

php artisan wirekit:doctor

Expected output (formatted slightly differently in your terminal):

✓ Assets published
✓ Tailwind @source includes WireKit templates
✓ Config file published
✓ @wirekitStyles directive present in layout
✓ @wirekitScripts directive present in layout
✓ @wirekitScripts before @livewireScripts (correct order)
✓ Bundle config valid (full)
i  Alpine.js: skipped (Livewire 4 bundles Alpine)

If any check fails, the doctor prints the literal fix snippet. Re-run the failing step and re-run the doctor.

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.
  • Multiple layout files. The Starter Kit may ship both components/layouts/app.blade.php AND a layouts/app.blade.php (older path). Some pages reference one, some the other. Search your codebase for every <x-layouts.app>, @extends('layouts.app'), and #[Layout(...)] reference, then add the WireKit directives to every layout that's actually rendered.
  • 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 component classes work exactly as before. WireKit is purely UI primitives — no service-provider takeovers, no middleware injection, no auth-flow rewrites.
  • The Starter Kit's Tailwind classes still work. WireKit components emit Tailwind utilities and use the same theme tokens; you can mix <x-wirekit::button> and your existing <button class="bg-indigo-600 ..."> markup on the same page without conflict.

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 --verbose and paste the output into a new issue on the package repository.