Basekit Laravel Ui Laravel Package

Getting Started

Install the package and publish only what you intend to override:

composer require basekit-laravel/basekit-laravel-ui
php artisan vendor:publish --tag=basekit-ui-config
php artisan vendor:publish --tag=basekit-ui-assets   # CSS/JS entrypoints

Look here first, in this order:

1. config/basekit-ui.php — theme tokens, component namespace/prefix, asset paths.
2. resources/views/vendor/basekit-ui/ — the Blade component source you'll be composing with (read it before overriding it).
3. README.md → AGENTS.md (new in v1.11.0) — the package now ships agent/skill definitions for OpenCode, Claude Code, and GitHub Copilot; this is the fastest way to learn the intended composition patterns.

First use case: build one page end-to-end — a layout shell plus a form — before touching theming:

<x-basekit::layout title="Dashboard">
    <x-slot:header>Dashboard</x-slot:header>

    <x-basekit::card>
        <x-basekit::form :action="route('projects.store')" method="POST">
            <x-basekit::input name="name" label="Project name" />
            <x-basekit::button type="submit">Create</x-basekit::button>
        </x-basekit::form>
    </x-basekit::card>
</x-basekit::layout>

If you use an AI assistant, the v1.11.0 agents/skills are the second thing to wire up (see below) — they encode component names and slot conventions more accurately than most blog posts.

Implementation Patterns

Layout shell + page views. Keep a single x-basekit::layout in resources/views/layouts/app.blade.php and have pages extend it via <x-basekit::layout> or @extends. This keeps the theme swap in one place when you upgrade.

Compose, don't fork. Prefer wrapping package components in your own app-level components (resources/views/components/ui/button.blade.php wrapping x-basekit::button) rather than editing published vendor views. Upgrades then become composer update instead of a three-way merge.

Publish-then-diff workflow. Publish views to a scratch directory, diff against the new vendor version on each upgrade, and copy only the deltas you actually need:

php artisan vendor:publish --tag=basekit-ui-views --force
git diff resources/views/vendor/basekit-ui

Theming via tokens, not class overrides. Set CSS custom properties in resources/css/app.css and map them in config/basekit-ui.php. Reach for class="..." merges only when a token doesn't exist.

Tailwind content configuration. Vendor Blade files must be in your Tailwind content globs or all package classes get purged:

content: [
    './resources/**/*.blade.php',
    './vendor/basekit-laravel/basekit-laravel-ui/resources/views/**/*.blade.php',
],

AI-assisted development (v1.11.0). The package now ships agent and skill definitions with first-class OpenCode, Claude Code, and Copilot support. A workable setup:

• Copy or symlink the package's AGENTS.md guidance into your repo root so Claude Code and OpenCode pick it up automatically.
• For Copilot, mirror the relevant rules into .github/copilot-instructions.md (Copilot does not read AGENTS.md).
• Put package-specific skills where your tool expects them (.opencode/skills/, .claude/skills/) and vendor them under a basekit/ namespace so they don't collide with your own skills.
• Treat these files as code: commit them, review diffs on upgrade, and keep them pinned to the installed package version.

Feature tests around components. Because these are presentation components, assert on rendered markup contract rather than exact classes:

$this->blade('<x-basekit::button variant="danger">Delete</x-basekit::button>')
    ->assertSee('Delete')
    ->assertSee('data-variant="danger"', false);

Gotchas and Tips

• vendor:publish --force is destructive. It overwrites your customizations with no warning. Publish to a scratch tag first, diff, then merge. Consider a CI check that fails if resources/views/vendor/basekit-ui diverges unexpectedly from the installed version.
• View cache after publishing. php artisan view:clear after any publish or config change, otherwise you'll debug a component that "isn't updating."
• config:cache in production. Reading config('basekit-ui.*') inside a service provider's register() captures stale values. Read config in boot() or in the component itself.
• Component name collisions. If the package registers a button component and your app also has x-button, resolution order depends on registration. Use the package prefix (x-basekit::button) explicitly rather than relying on the unprefixed alias.
• Slot vs. attribute confusion. Most "my content disappeared" reports come from passing content as an attribute when the component expects a named slot (<x-slot:header>). Check the component's $slot/named-slot usage in the vendor source — it's the definitive answer.
• AI instruction drift is the new documentation drift. The v1.11.0 agents/skills describe the API as of that release. After upgrading, re-copy them rather than assuming your local copies are current, and never let generated agent output override a failing test — the skills are a productivity aid, not a source of truth.
• Copilot coverage is partial. Copilot support means instruction files, not the same tool-calling surface as Claude Code or OpenCode. Expect the Copilot path to be advisory only; verify component APIs against the vendor views.
• Asset pipeline. If styles look unstyled in production but fine locally, you're almost certainly missing the vendor path in the Tailwind content glob or haven't rebuilt assets (npm run build) after publishing.
• Extension points worth knowing: the config's component prefix and theme token map are the supported seams. Anything else (subclassing components, editing vendor providers) is unsupported and will break on minor releases.