Uikit3 Laravel Package

Getting Started

Verify the hook exists before you install anything. This package is a plugin for the php artisan preset command, which shipped in Laravel 5.5 and was removed in Laravel 7. That single fact determines whether this package is usable at all:

php artisan list | grep preset

No output means the command is gone and the package has nothing to attach to. Stop there and use UIKit's npm packages directly — the whole preset is ~6 files of glue you can reproduce in an afternoon.

On Laravel 5.5–6.x, install it as a dev dependency. It is a one-shot scaffold generator, not runtime code; nothing is on the request path after it runs.

composer require laravel-frontend-presets/uikit3 --dev
php artisan preset uikit3
npm install && npm run dev

Look at the stubs before you look at your app. The package's source in vendor/laravel-frontend-presets/uikit3/src/ contains the Preset class and its stub directory — that's the ground truth for exactly which files will be overwritten. Reading it takes two minutes and tells you more than any README about blast radius.

Run it on a committed, clean tree. Then immediately capture what happened:

git checkout -b spike/uikit3-preset
php artisan preset uikit3
git status && git diff --stat

That diff is the actual deliverable of this package. Everything else is bookkeeping.

First use case to validate with: a throwaway internal dashboard — one base layout, a navbar, a login form, a table listing. If that renders and npm run dev succeeds, the scaffold works. Do not attempt it on an app with customized auth views as your first run.

Implementation Patterns

Harvest-and-vendor (the recommended default). Run the preset once on a scratch branch, copy the artifacts you want into your repo, then remove the dependency:

php artisan preset uikit3
git add -A && git commit -m "chore: capture uikit3 preset output"
# cherry-pick what you need onto your working branch
composer remove laravel-frontend-presets/uikit3

Record the provenance in a comment at the top of the vendored app.scss or in a short ADR: "Blade layout and auth views derived from laravel-frontend-presets/uikit3 (46 stars, unmaintained) on YYYY-MM-DD. Package removed from composer.json; we own this code." Future maintainers will otherwise re-add the dependency.

Diff-and-merge when you already have an app. Never run the preset blindly against views you've edited. Instead:

git stash && git checkout -b preset-output main
php artisan preset uikit3 && git add -A && git commit -m "preset output"
git checkout main
git merge --no-commit --no-ff preset-output   # resolve file-by-file

This turns destructive overwrite into a reviewable three-way merge. It works because the preset only writes files — there's no migration or state to reconcile.

Isolate the UIKit surface behind one layout plus partials. The generated resources/views/layouts/app.blade.php uses uk- classes, uk-navbar, @yield/@stack conventions that differ from the Bootstrap preset. Don't leak uk-* markup into feature views ad hoc — create a small set of Blade components or partials (<x-ui.card>, components/navbar.blade.php, components/alert.blade.php) and make that the only contract feature developers use. When UIKit eventually gets replaced, the blast radius is the partials directory, not 80 views.

Import UIKit through a single entry point and trim components. The stock stub imports the full framework. Both CSS and JS are large by default. Customize once:

// resources/sass/app.scss
@import "~uikit/src/scss/variables-theme.scss";
@import "~uikit/src/scss/mixins-theme.scss";
@import "~uikit/src/scss/components/navbar.scss";
@import "~uikit/src/scss/components/card.scss";
@import "~uikit/src/scss/components/form.scss";
// only what you use — the preset's full import ships everything

// resources/js/app.js
import UIkit from 'uikit';
import Icons from 'uikit/dist/js/uikit-icons';
UIkit.use(Icons);          // separate import; icons are NOT bundled
window.UIkit = UIkit;      // needed for inline Blade handlers and Livewire

Bridge UIKit JS to Livewire/Turbo with explicit re-init. UIKit components bind on DOM-ready; partial-page navigation leaves modals and dropdowns dead. Add a hook:

document.addEventListener('livewire:navigated', () => {
    UIkit.update(document.body, 'update');
});

Fork internally if you need repeatability. If more than one app in the org starts from this scaffold, fork it, rewrite the stubs for Vite (vite.config.js, @vite([...]) instead of mix()), pin uikit to an explicit version, and publish under your own Composer namespace. That is a half-day of work and converts an abandoned package into an owned asset. Do not consume the upstream repo at install time in CI.

On Laravel 7+, the manual equivalent is genuinely cheaper than resurrecting the preset:

composer require laravel/ui --dev && php artisan ui bootstrap --auth
npm i uikit

import UIkit from 'uikit';
import Icons from 'uikit/dist/js/uikit-icons';
UIkit.use(Icons);

@import "~uikit/src/scss/variables-theme.scss";
@import "~uikit/src/scss/mixins-theme.scss";
@import "~uikit/src/scss/uikit-theme.scss";

Then paste the harvested Blade layout/auth views on top. You get a maintained dependency for the pipeline and the preset's only durable value (the views) for free.

Gotchas and Tips

The command silently doesn't exist on Laravel 7+. This is the highest-friction onboarding failure — a new developer reads the README, installs, and gets Command "preset" is not defined. It is technically possible to instantiate the Preset class manually from a one-off Artisan command, but you are then calling a static install() written against 5.5 file paths. Don't. Document the version ceiling at the top of your ADR.

Second runs are destructive and lossy. install() copies stubs over package.json, webpack.mix.js, resources/assets/{js,sass}, and every auth view. There is no merge logic, no backup, no prompt. If someone hand-edited resources/views/auth/login.blade.php and then re-runs the preset to "pick up a fix," that work is gone and git status is your only recovery path. Treat the preset as a one-time operation; if you need to re-run, stash first and diff.

The pinned npm versions are stale and will fight modern Node. The stub package.json freezes Mix plugins and a uikit version from 2017–2018. On Node 18+ you'll hit node-sass/node-gyp build failures. Fix by bumping laravel-mix, swapping node-sass for sass (dart-sass), and pinning uikit to a current 3.x yourself — the preset will never surface upstream releases to you.

Mix vs. Vite is the real fork boundary. Everything generated assumes webpack.mix.js and the mix() helper. On Laravel 9+ you must rewrite @yield-adjacent asset includes to @vite([...]), delete webpack.mix.js, and add vite.config.js. Budget this explicitly; it's the largest single chunk of adaptation work if you're targeting a modern Laravel.

Icons missing is not a bug — it's a missing import. import UIkit from 'uikit' alone does not register the icon set. import 'uikit/dist/js/uikit-icons' (or UIkit.use(Icons)) is required. Every "the close button is blank" ticket traces back here.

Bootstrap classes will silently do nothing. UIKit is data-attribute driven (uk-modal, uk-toggle, uk-grid). There's no class-name overlap with Bootstrap. Developers coming from the default preset will paste btn btn-primary and get an unstyled button with no console warning. Put a two-line note in the repo README and consider a lint rule or code review checklist item for uk- markup in new views.

Auth views are scaffolding, not production code. The generated login/register/password reset templates are correct Blade but unowned. Before shipping: verify CSRF, old() repopulation, validation error display through UIKit's uk-form-danger/uk-alert, remember me binding, and that the password reset routes match your Laravel version's controller. Audit them like you wrote them, because from that point on you did.

Debugging checklist when the build "works" but looks wrong:

• git status after the preset run — confirm every expected file was actually written (a permission error leaves partial state).
• npm run dev -- --verbose and inspect public/css/app.css for uk- selectors; if absent, the SCSS import path is wrong for your Mix/Vite resolution config.
• Check public/mix-manifest.json exists and Blade references /css/app.css, not a hardcoded path.
• Modal/dropdown dead after navigation → missing UIkit.update re-init hook.
• Console UIkit is not defined → window.UIkit assignment missing from app.js.

Extension point worth knowing: the preset class's install() method is the only place worth patching in a fork. Add your own stub copies (custom layout, an x-ui.* component set, a trimmed SCSS entry) and your fork stays a one-command scaffold instead of a copy-paste ritual. Pin the UIKit version in the same commit so the scaffold and the shipped CSS never drift.

Assume zero upstream support. 46 stars, zero dependents, no evidenced recent activity. Every bug is yours, every UIKit upgrade is manual, and no security advisory will reach you. That's acceptable for a dev-only scaffold you vendored and deleted — it is not acceptable as a live composer.json entry in an app you intend to maintain for years.