DOCSEARCHbyAlgolia
Submit Docs

BlatUI Component Library

repository·main·Indexed 41 days ago

https://github.com/anousss007/blatui

A shadcn/ui-like component library for the BLAT stack (Blade, Laravel, Alpine, Tailwind). BlatUI provides accessible, themeable UI components that developers copy-paste directly into Laravel projects for full ownership and customization. Requires Laravel 11+, PHP 8.2+, Tailwind CSS v4, and Alpine.js 3.

Tokens
15.8K
Snippets
61
Records
79
Agent score
54%

What's inside BlatUI

  1. Understand the BlatUI Starter architecture

    main

    The BlatUI Starter kit provides a fully owned set of components and foundations within a Laravel environment. Key architectural details include:

    • Component Ownership: All components are copied directly into resources/views/components/. You can modify them freely.
      • ui/: 180 component families (376 files) rendered via <x-ui.*>.
      • block/: 8 dashboard/sidebar building blocks (e.g., nav-main, team-switcher) rendered via <x-block.*>.
    • Foundations:
      • CSS: resources/css/app.css imports ./blatui.css, which contains Tailwind CSS v4, theme tokens (OKLCH), and light/dark presets.
      • JS: resources/js/app.js imports ./blatui.js, which boots Alpine.js and the BlatUI engine (components + calendar).
    • Layouts: The base HTML structure is provided by <x-layouts.app> (defined in layouts/app.blade.php).
    • Theming: Theme tokens are CSS variables. You can customize the look by using the BlatUI theme editor and pasting the output into resources/css/blatui.css.

  2. Component Design Principles for BlatUI

    main

    When building or extending components in BlatUI, follow these core principles to ensure library consistency and maintainability:

    1. Composition over Re-declaration: Never copy-paste a primitive's styling, class strings, or logic. If a component needs a button, input, or textarea, it must compose the existing <x-ui.button>, <x-ui.input>, etc.
    2. Single Source of Truth: Base classes (e.g., field classes, menu-item classes) and structural scaffolds (e.g., overlay teleport/anchor/transition logic) must exist in exactly one place.
    3. Shared API Vocabulary: Use consistent prop names and types across all components:
      • size: sm | default | lg (plus xs, icon* where applicable).
      • color: Local-token brand overrides.
      • disabled: bool, defaulting to false.
      • name, id, placeholder, value: Follow a consistent passthrough vs. declared-prop policy.
      • rows / maxRows: Unified sizing contract for textareas.
    4. Variants over New Components: Instead of creating separate components for similar controls with different skins, collapse them into a single component and expose the differences via variants and props.
    5. Semantic Integrity: Do not merge components just because they look similar if their WAI-ARIA roles differ. For example, meter (role="meter") and progress (role="progressbar") must remain separate components.

  3. BlatUI MCP Server Capabilities

    main

    The BlatUI MCP server provides the following interfaces to AI agents:

    • Tools: Enables searching, retrieving, and installing components. Key tools include search_registry, get_component, get_example, and install_command.
    • Resources: Provides access to component, block, and chart data via the blatui:// protocol (e.g., blatui://component|block|chart/{name}).
    • Prompts: Pre-defined prompts for common tasks like use-component and scaffold-page.

  4. Understand the BlatUI repository layout

    main

    BlatUI uses a monorepo structure where the published Composer package is located at the repository root. This means that while the repository contains development tools and demo applications, the distributed package remains lightweight.

    Key directories include:

    • Root (composer.json, src/, stubs/): This is the actual published package. When you run composer require anousss007/blatui, you are installing the contents of this root directory.
    • apps/demo/: The source of truth for components. This directory contains the live documentation site and the actual Blade component implementations.
    • apps/starter/: The Laravel starter kit.
    • scripts/build-package.sh: A script used to regenerate the stubs/ directory from the components defined in the demo app.
    • tests/: Package-level tests.

    Note that apps/, scripts/, docs/, .github/, and tests/ are excluded from the distributed Composer tarball via .gitattributes export-ignore, so consumers only receive the core package files.

  5. Understand the BlatUI core model

    main

    BlatUI follows a copy-paste, own-the-code philosophy. Unlike traditional component libraries that provide a runtime package, BlatUI components are Blade files that you copy directly into your project's resources/views/components/ui/ directory.

    Once added, they are used under the x-ui. namespace. Because you own the source files, the supported way to customize a component's appearance or behavior is to edit the Blade file directly. Components are styled using Tailwind v4 tokens and use Alpine.js for interactivity.

  6. Manage component deprecations in BlatUI

    main

    When merging or removing a component, follow this deprecation policy to avoid breaking user implementations:

    1. Alias Wrapper: Instead of immediate removal, ship the merged-away component as a thin alias wrapper for one minor version.
    2. Documentation: Add a @deprecated note to the component's documentation page.
    3. Changelog: Include a Deprecated entry in the CHANGELOG.
    4. Removal: Remove the component entirely in the following minor version.

    Note: Users who have already used blatui:add to pull a component into their local project will keep their local file; this policy only affects the central library.

  7. Configure DNS-AID for AI Discovery

    main

    To enable AI discovery via DNS (DNS-AID), you must manually add a TXT record at your DNS provider. This allows agents to discover the BlatUI MCP registry and server card via the domain.

    Note: It is recommended to enable DNSSEC on the zone if available, as DNS-AID uses it for verification.

    Record Details:

    • Host: _blatui._mcp._agents.blatui.remix-it.com
    • Type: TXT
    • Value: v=mcp1; registry=https://blatui.remix-it.com/registry.json; card=https://blatui.remix-it.com/.well-known/mcp/server-card.json; endpoint=https://blatui.remix-it.com/mcp; public=true; version=2025-06-18
    Host:  _blatui._mcp._agents.blatui.remix-it.com
Type:  TXT
Value: v=mcp1; registry=https://blatui.remix-it.com/registry.json; card=https://blatui.remix-it.com/.well-known/mcp/server-card.json; endpoint=https://blatui.remix-it.com/mcp; public=true; version=2025-06-18

  8. Install BlatUI blocks and charts

    main

    Full-page blocks (e.g., dashboards, auth, marketing) and charts (ApexCharts) are not included in the standard CLI bundle but can be installed from the remote registry.

    1. Fetch the JSON definition for the block or chart using curl.
    2. Manually write the files[].content to the specified files[].target.
    3. Run php artisan blatui:add for any registryDependencies listed in the JSON to ensure the block's required components are present.
    # Example: Fetching a dashboard block
curl https://blatui.remix-it.com/r/blocks/dashboard-01.json

# Example: Fetching a default area chart
curl https://blatui.remix-it.com/r/charts/chart-area-default.json

  9. Configure BlatUI MCP server in AI editors

    main

    You can connect your AI editor (Claude Code, Cursor, or VS Code) to the BlatUI MCP server using either the hosted HTTP endpoint or a local installation via Laravel Artisan.

    Option 1: Hosted HTTP (Streamable HTTP)

    Use this for a stateless, zero-setup connection to the live hosted server.

    Option 2: Local stdio (Laravel Artisan)

    Use this if you have already installed the package in your Laravel project via composer require anousss007/blatui. This runs the server locally using your project's environment.

    // Option 1: Hosted HTTP
{
  "mcpServers": {
    "blatui": { "type": "streamable-http", "url": "https://blatui.remix-it.com/mcp" }
  }
}

// Option 2: Local stdio (requires composer package)
{
  "mcpServers": {
    "blatui": { "command": "php", "args": ["artisan", "blatui:mcp"] }
  }
}

  10. Add and use BlatUI components

    main

    Use the BlatUI CLI to copy components directly into your project. Components are stored in resources/views/components/ui/ as Blade components.

    Adding Components

    # Add specific components (dependencies are resolved automatically)
php artisan blatui:add button card input

# Add everything at once
php artisan blatui:add --all

    To see a list of available components, blocks, and charts:

    # List all families
php artisan blatui:list

# View details for a specific component
php artisan blatui:list select

    Usage Example

    Once added, use them as standard Blade components:

    <x-ui.card class="max-w-sm">
    <x-ui.card-header>
        <x-ui.card-title>Welcome back</x-ui.card-title>
        <x-ui.card-description>Sign in to continue.</x-ui.card-description>
    </x-ui.card-header>
    <x-ui.card-content class="space-y-3">
        <x-ui.input type="email" placeholder="m@example.com" />
        <x-ui.button class="w-full">Sign in</x-ui.button>
    </x-ui.card-content>
</x-ui.card>
    php artisan blatui:add button card input

  11. Run the BlatUI morph testbed

    main

    The BlatUI morph testbed is a Laravel + Livewire 4 application designed to verify that BlatUI components' DOM-based wiring survives Livewire's DOM morphing during re-renders. Use this to reproduce specific issues related to component state loss or broken wiring after server round-trips.

    Setup and Execution

    1. Install dependencies and build assets:

      composer install && npm ci && npm run build

    2. Configure environment:

      cp .env.example .env && php artisan key:generate

    3. Start the server:

      php artisan serve --port=8124

    Note: No database migration is required as sessions, cache, and queue use file/sync drivers.

    Running Browser Tests

    Once the server is running, execute the Playwright browser suite:

    npm run test:browser                      # against http://127.0.0.1:8124
npm run test:browser -- http://host:port

    If Playwright is not installed, you can install the version required by the demo package:

    cd ../demo && npm i --no-save playwright@$(node -p "require('./package.json').blatui.playwright")
    composer install && npm ci && npm run build
cp .env.example .env && php artisan key:generate
php artisan serve --port=8124