--- title: Adding WireKit to the Livewire Starter Kit description: Step-by-step recipe for fitting WireKit into an existing Livewire Starter Kit project — the four touchpoints where Starter-Kit defaults differ from a clean-room install visibility: guest draft: false related: - /getting-started - /integration --- # Adding WireKit to the Livewire Starter Kit The [Livewire Starter Kit](https://laravel.com/docs/starter-kits#livewire) 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. ::: tip 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](/getting-started) instead — it walks the clean-room install which is simpler than retrofitting. ## Step 1 — Composer install ```bash # 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 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: ```css @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: ```css @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: ```text resources/views/components/layouts/app.blade.php ``` Open it. You'll see something close to: ```blade {{ $title ?? config('app.name') }} @vite(['resources/css/app.css', 'resources/js/app.js']) @livewireStyles {{ $slot }} @livewireScripts ``` You need to add `@wirekitStyles` in the `` and `@wirekitScripts` in the `` BEFORE `@livewireScripts`. The order matters — `@livewireScripts` boots Alpine, and WireKit's Alpine factories must register first. ```blade {{-- resources/views/components/layouts/app.blade.php --}} {{ $title ?? config('app.name') }} @vite(['resources/css/app.css', 'resources/js/app.js']) @wirekitStyles @livewireStyles {{ $slot }} {{-- Critical order: @wirekitScripts BEFORE @livewireScripts --}} @wirekitScripts @livewireScripts ``` 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: ```bash php artisan wirekit:doctor ``` Expected output (formatted slightly differently in your terminal): ```text ✓ 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: ```blade Hello from WireKit ``` Now `wirekit:install` has added the `@source` line, rebuild so Tailwind picks up WireKit's classes: ```bash # 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 ``, `@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 `` and your existing `