BlatUI

https://github.com/anousss007/blatui
Admin
BlatUI is a CLI tool that copies open-source, copy-paste UI components for the BLAT stack (Blade,...
Tokens:76,922
Snippets:511
Trust Score:7.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### install() usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Example usage of install() with a namespaced spec, showing how to iterate over written paths and errors, and how to handle Composer/npm packages.

```php
$result = $installer->install('@acme/fancy-button', base_path(), (bool) $force);

foreach ($result['written'] as $path) { /* echo "+ path" */ }
foreach ($result['errors'] as $error) { /* report */ }
if ($result['composer'] || $result['npm']) {
    // "composer require …" / "npm install -D …"
}
```

--------------------------------

### Boot the starter app

Source: https://github.com/anousss007/blatui/blob/main/apps/starter/README.md

Boots the starter app: installs PHP and JS dependencies, sets up the environment, generates an app key, runs migrations (creates the SQLite database and session/cache tables), builds assets (or runs the dev server), and starts the Laravel development server. After this, open http://localhost:8000.

```bash
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate          # creates the sqlite db + session/cache tables
npm install && npm run build # or: npm run dev
php artisan serve
```

--------------------------------

### install() failure example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Shows how to call install() with an unknown widget and an invalid URL, and how to check the returned errors array. The first error message is 'Unknown registry for "@unknown/widget" (configure config/blatui.php → registries).' and the second is 'Could not fetch a valid registry item from https://acme.test/r/missing.json.'

```php
$result = $installer->install('@unknown/widget', base_path());

if ($result['errors']) {
    // errors[0] === 'Unknown registry for "@unknown/widget" (configure config/blatui.php → registries).'
}

$result = $installer->install('https://acme.test/r/missing.json', base_path());
// HTTP failure or non-JSON body
// errors[0] === 'Could not fetch a valid registry item from https://acme.test/r/missing.json.'
```

--------------------------------

### Set up and run the Livewire morph testbed

Source: https://github.com/anousss007/blatui/blob/main/apps/livewire/README.md

Install dependencies, build assets, set up the environment, and start the Laravel development server on port 8124. No database is needed because sessions, cache, and queue use file/sync drivers.

```bash
composer install && npm ci && npm run build
cp .env.example .env && php artisan key:generate
php artisan serve --port=8124
```

--------------------------------

### Setup and register blatui-charts

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/js-charts.md

Install the chart engine and register it with Alpine. Run the artisan command to publish the charts file, then install ApexCharts as a dev dependency. The JavaScript imports both core and charts modules, registers them with the Alpine instance, and starts Alpine.

```bash
php artisan blatui:add chart
npm install -D apexcharts
```

```javascript
import { registerBlatUI } from './blatui-core.js';
import { registerCharts } from './blatui-charts.js';

registerBlatUI(Alpine);
registerCharts(Alpine);
Alpine.start();
```

--------------------------------

### Build and cache the demo with deploy.sh

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/deploy/README.md

Run the deployment script that performs Composer install, npm build, key generation, and cache setup. This is the standard build step for the demo.

```bash
bash deploy/deploy.sh                 # composer + npm build + key:generate + caches
```

--------------------------------

### Install BlatUI and add components

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/README.md

Install BlatUI and its peer dependencies, publish the foundations, verify the setup, add components, and list available components. Requires Laravel 11+, PHP 8.2+, Tailwind CSS v4, Alpine.js 3, and Node 18+.

```bash
composer require anousss007/blatui

composer require gehrisandro/tailwind-merge-laravel mallardduck/blade-lucide-icons
npm install -D alpinejs @alpinejs/anchor @alpinejs/collapse @alpinejs/focus

php artisan vendor:publish --tag=blatui-foundations

php artisan blatui:init

php artisan blatui:add button card input

php artisan blatui:list
```

--------------------------------

### example(string $kind, string $name): ?array

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-registry-client.md

Documentation for the `example` method of the `RegistryClient` class, which fetches remote block or chart examples.

```APIDOC
## `example(string $kind, string $name): ?array`

### Description
Fetches a remote block or chart example from the registry. Blocks and charts are not bundled in the package, so this method is remote-only.

### Method
`example`

### Signature
`public function example(string $kind, string $name): ?array`

### Parameters
- `$kind` (string) - Required - `'chart'` or anything else (treated as block).
- `$name` (string) - Required - Example slug.

### Returns
- `?array` - Normalized remote item from `{base}/r/{charts|blocks}/{name}.json`, or `null` (unreachable/unknown).

### Example
```php
$dash = $client->example('block', 'dashboard-01');   // remote only
$area = $client->example('chart', 'chart-area-default'); // remote only
```
```

--------------------------------

### Run BlatUI demo site locally

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/README.md

Commands to run the BlatUI demo site locally. Install dependencies, build assets (or run dev server), and start the Laravel development server.

```bash
composer install && npm install
npm run build      # or: npm run dev
php artisan serve
```

--------------------------------

### Livewire test setup and run commands

Source: https://github.com/anousss007/blatui/blob/main/CONTRIBUTING.md

Commands to install dependencies, build assets, configure the environment, and run browser tests for the Livewire app. Requires PHP and Composer, and uses file/sync drivers (no database). The server runs on port 8124.

```bash
cd apps/livewire
composer install && npm ci && npm run build
cp .env.example .env && php artisan key:generate     # no database — file/sync drivers
php artisan serve --port=8124 &
npm run test:browser
```

--------------------------------

### Registry instantiation examples

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Instantiation examples for the Registry class. The first uses default paths; the second passes custom manifest and stubs directory paths.

```php
$registry = new Registry;
$registry = new Registry('/custom/registry.json', '/custom/stubs/ui');
```

--------------------------------

### Full usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Full usage example of the BlatUI Registry class.

```APIDOC
## Full usage example

### Description
Example of using the BlatUI Registry to install a family and its dependencies.

### Code
```php
use BlatUI\Registry;

$registry = new Registry;

// Install "sidebar" + everything it needs, into the family's own namespace.
$families = [];
foreach (['sidebar'] as $family) {
    $registry->resolve($family, $families);
}
$families = array_unique($families); // resolved incl. transitive deps

foreach ($families as $family) {
    $dest = base_path(trim($registry->targetFor($family), '/'));
    if (! is_dir($dest)) {
        mkdir($dest, 0755, true);
    }
    foreach ($registry->filesFor($family) as $src) {
        copy($src, $dest.'/'.basename($src));
    }
    $packages = $registry->packagesFor($family);
    // $packages['composer'] ?? [], $packages['npm'] ?? [] → suggest to the user
}
```
```

--------------------------------

### Install server prerequisites (nginx, PHP 8.3, Composer, Node 20)

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/deploy/README.md

Install required system packages (nginx, PHP 8.3 with extensions, unzip, git), Composer, and Node.js 20 on a fresh Ubuntu/Debian server. Run once before deploying the demo.

```bash
sudo apt update
sudo apt install -y nginx php8.3-fpm php8.3-cli php8.3-mbstring php8.3-xml \
                    php8.3-curl php8.3-zip php8.3-sqlite3 unzip git
# Composer
php -r "copy('https://getcomposer.org/installer','composer-setup.php');"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
# Node 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
```

--------------------------------

### Full example: instantiate Server and handle a tools/call frame

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-server.md

Complete PHP example showing how to create a Server with a RegistryClient and Registry, emulate a stdio JSON-RPC frame for the get_component tool, and extract the resulting text from the response. The response text contains the component content and a Blade file path.

```php
use BlatUI\Mcp\RegistryClient;
use BlatUI\Mcp\Server;
use BlatUI\Registry;

$server = new Server(new RegistryClient(new Registry), '1.34.0');

// emulate one stdio frame
$frame = json_decode('{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_component","arguments":{"name":"button"}}}', true);
$response = $server->handle($frame);

if (isset($response['error'])) {
    // error envelope
}
$text = $response['result']['content'][0]['text']; // "# Button\n…\n## resources/views/components/ui/button.blade.php\n```blade…"
```

--------------------------------

### Server usage example with handle calls

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-server.md

Shows how to instantiate the server and call handle with a tools/list request and an initialized notification, with expected responses.

```php
$server = new Server(new RegistryClient($registry), '1.34.0');

$resp = $server->handle(['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/list']);
// ['jsonrpc' => '2.0', 'id' => 1, 'result' => ['tools' => [ ... 5 tool defs ... ]]]

$resp = $server->handle(['jsonrpc' => '2.0', 'method' => 'initialized']); // notification
// null — never answered
```

--------------------------------

### install() method signature with docblock

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Signature and docblock for the install method. It fetches and writes a remote item and all its dependencies, returning arrays of written/skipped/error paths and Composer/npm packages. Failures are collected into 'errors' rather than thrown.

```php
/**
 * Fetch + write a remote item and all its dependencies.
 *
 * @return array{written: list<string>, skipped: list<string>, errors: list<string>, composer: list<string>, npm: list<string>}
 */
public function install(string $spec, string $basePath, bool $force = false): array
```

--------------------------------

### Full usage example of Registry

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Full usage example showing how to resolve a family, create its target directory, copy its files, and retrieve its package requirements. It uses the Registry class and assumes a Laravel-like base_path helper.

```php
use BlatUI\Registry;

$registry = new Registry;

// Install "sidebar" + everything it needs, into the family's own namespace.
$families = [];
foreach (['sidebar'] as $family) {
    $registry->resolve($family, $families);
}
$families = array_unique($families); // resolved incl. transitive deps

foreach ($families as $family) {
    $dest = base_path(trim($registry->targetFor($family), '/'));
    if (! is_dir($dest)) {
        mkdir($dest, 0755, true);
    }
    foreach ($registry->filesFor($family) as $src) {
        copy($src, $dest.'/'.basename($src));
    }
    $packages = $registry->packagesFor($family);
    // $packages['composer'] ?? [], $packages['npm'] ?? [] → suggest to the user
}
```

--------------------------------

### Scaffold a new BlatUI app with laravel new --using

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/STARTER-KIT.md

Command to create a new Laravel application using the BlatUI starter kit from GitHub. The `--using` flag installs the repository as the app skeleton.

```bash
laravel new my-app --using=anousss007/blatui-starter
```

--------------------------------

### resolveUrl() usage examples

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Example calls showing the resolved URL for a known namespace and null for an unconfigured one.

```php
$installer->resolveUrl('@blatui/button');
// "https://blatui.remix-it.com/r/button.json"
$installer->resolveUrl('@acme/thing'); // null unless 'acme' is configured
```

--------------------------------

### Install remote registry items with blatui:add

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Install a component from a remote registry by namespace or direct URL. Namespaces resolve through config('blatui.registries'); the built-in @blatui points to the official registry.

```bash
php artisan blatui:add @acme/fancy-button
php artisan blatui:add https://acme.test/r/fancy-button.json
```

--------------------------------

### blatui:init command usage

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Example invocation of the blatui:init command. It runs the foundation checks and always exits with SUCCESS.

```bash
php artisan blatui:init
```

--------------------------------

### Install BlatUI and publish foundations

Source: https://github.com/anousss007/blatui/blob/main/README.md

Install BlatUI via Composer, add peer packages (Tailwind Merge, Blade Lucide Icons, Alpine plugins), publish the foundation files, and verify with `blatui:init`. Requires PHP 8.2+, Laravel 11-13, Tailwind v4, Alpine 3, and Node 18+.

```bash
# 1. Install the CLI
composer require anousss007/blatui

# 2. Peer packages used by the components
composer require gehrisandro/tailwind-merge-laravel mallardduck/blade-lucide-icons
npm install -D alpinejs @alpinejs/anchor @floating-ui/dom @alpinejs/collapse @alpinejs/focus

# 3. Publish the foundations (theme tokens + Alpine/chart/calendar engine)
php artisan vendor:publish --tag=blatui-foundations
#   → resources/css/blatui.css      (oklch design tokens, presets, light/dark)
#   → resources/js/blatui.js        (greenfield bootstrap — boots Alpine for you)
#   → resources/js/blatui-core.js   (engine: registerBlatUI, for apps already running Alpine)

# 4. Verify your setup
php artisan blatui:init
```

--------------------------------

### Add and list components with blatui:add and blatui:list

Source: https://github.com/anousss007/blatui/blob/main/README.md

Commands to add components, list available components, get details for a single component, and add everything at once. Dependencies are resolved automatically.

```bash
php artisan blatui:add button card input
```

```bash
php artisan blatui:list
```

```bash
php artisan blatui:list select
```

```bash
php artisan blatui:add --all
```

--------------------------------

### Diff::unified() usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/diff.md

Example call to Diff::unified() showing the resulting unified diff with headers and hunks.

```php
$diff = Diff::unified($local, $stub);
// --- installed
// +++ registry
// @@ -10,3 +10,3 @@
//  <div class="p-4">
//-type="button"
//+type="submit"
//  </div>
```

--------------------------------

### blatui:add command usage examples

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Example invocations of the blatui:add artisan command. The first adds multiple component families, the second adds all bundled components, the third adds remote items via namespace and URL, and the fourth forces overwrite and specifies a custom destination path.

```bash
php artisan blatui:add button card input
php artisan blatui:add --all
php artisan blatui:add @acme/fancy-button https://acme.test/r/thing.json
php artisan blatui:add alert-dialog --force --path=resources/views/components/widgets
```

--------------------------------

### tools/call - get_example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/types.md

Retrieves an example for a block or chart. Requires 'kind' and 'name' arguments.

```APIDOC
## tools/call - get_example

### Description
Retrieves an example for a block or chart.

### Method
POST (HTTP transport) or stdio line

### Endpoint
/ (HTTP transport)

### Parameters
#### Request Body (params)
- **name** (string) - Required - Must be "get_example".
- **arguments** (object) - Required
  - **kind** (string) - Required - Must be one of: "block", "chart".
  - **name** (string) - Required - Name of the block or chart.

### Request Example
```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_example", "arguments": { "kind": "block", "name": "hero" } } }
```

### Response
#### Success Response
- **content** (array) - Array of content items.
  - **type** (string) - "text"
  - **text** (string) - Result text.

#### Response Example
```json
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "..." }] } }
```
```

--------------------------------

### RemoteInstaller::install

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Installs a remote component and its dependencies.

```APIDOC
## `install(string $spec, string $basePath, bool $force = false): array`

### Description
Fetches and writes a remote item and all its dependencies to the project. Returns a summary of written/skipped files, errors, and required Composer/npm packages.

### Method
`RemoteInstaller::install` (instance)

### Parameters
- `$spec` (string) - Required - Spec to install (URL, `@ns/name`, or a bundled family name).
- `$basePath` (string) - Required - Project root the item's `target` paths are relative to.
- `$force` (bool) - Optional - Default `false`. Overwrite files that already exist.

### Returns
- `array{written: list<string>, skipped: list<string>, errors: list<string>, composer: list<string>, npm: list<string>}` - File paths written, files skipped (existing + not `$force`), error strings collected, and unique Composer/npm packages needed.

### Behavior Details
- A bare spec naming a locally bundled family is installed from `stubs/`.
- Remote item's `files[]` entries are written to `$basePath.'/'.ltrim($target, '/')`; entries without target/content are skipped.
- `item.meta.composer` and `item.meta.npm` (fallback `item.dependencies`) are merged into the result.
- `registryDependencies` resolve against the same registry namespace as the original spec.

### Example
```php
$result = $installer->install('@acme/fancy-button', base_path(), (bool) $force);

foreach ($result['written'] as $path) { /* echo "+ path" */ }
foreach ($result['errors'] as $error) { /* report */ }
if ($result['composer'] || $result['npm']) {
    // "composer require …" / "npm install -D …"
}
```
```

--------------------------------

### Install ApexCharts for charts

Source: https://github.com/anousss007/blatui/blob/main/apps/starter/README.md

Installs ApexCharts as a dev dependency to enable the optional chart support. The default bootstrap is charts-free, so this is only needed if you want to use <x-ui.chart>.

```bash
npm install -D apexcharts
```

--------------------------------

### tools/call - install_command

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/types.md

Installs one or more components by name. Requires a 'names' array argument.

```APIDOC
## tools/call - install_command

### Description
Installs one or more components by name.

### Method
POST (HTTP transport) or stdio line

### Endpoint
/ (HTTP transport)

### Parameters
#### Request Body (params)
- **name** (string) - Required - Must be "install_command".
- **arguments** (object) - Required
  - **names** (array of strings) - Required - List of component names to install.

### Request Example
```json
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "install_command", "arguments": { "names": ["button", "card"] } } }
```

### Response
#### Success Response
- **content** (array) - Array of content items.
  - **type** (string) - "text"
  - **text** (string) - Result text.

#### Response Example
```json
{ "jsonrpc": "2.0", "id": 1, "result": { "content": [{ "type": "text", "text": "..." }] } }
```
```

--------------------------------

### GET /llms-full.txt

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides a comprehensive AI-readable reference of all components.

```APIDOC
## GET /llms-full.txt

### Description
Returns a full reference of every component with description, files, dependencies, and composer/npm commands.

### Method
GET

### Endpoint
/llms-full.txt

### Parameters
- none

### Response
#### Success Response (200)
- **text/markdown** (string) - Full reference documentation
```

--------------------------------

### InitCommand signature and handle method

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Signature, description, and handle method signature for the InitCommand. The command checks BlatUI foundations (packages, theme tokens, Alpine setup) and reports what is missing.

```php
protected $signature = 'blatui:init';
```

```php
protected $description = 'Check the BlatUI foundations (packages, theme tokens, Alpine setup) and report what is missing';
```

```php
public function handle(Registry $registry): int
```

--------------------------------

### isRemote() usage examples

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Example calls showing the return values for different spec formats: a plain slug returns false, while a namespaced name and a URL return true.

```php
RemoteInstaller::isRemote('button');              // false
RemoteInstaller::isRemote('@acme/fancy-button');  // true
RemoteInstaller::isRemote('https://x/r/a.json');  // true
```

--------------------------------

### targetFor(string $family): string

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Returns the install target path for a given family.

```APIDOC
## `targetFor(string $family): string`

### Description
Returns the install target (path relative to the project root) for a given family. Block components install to `components/block` and render as `<x-block.*>`; everything else defaults to `resources/views/components/ui`.

### Method
`targetFor`

### Signature
```php
public function targetFor(string $family): string
```

### Parameters
- `$family` (string) - Required - Family name.

### Returns
- `string` - The install target path. Block components (`nav-user`, `team-switcher`, `file-tree`, …) install to `components/block`; everything else defaults to `resources/views/components/ui`. Absent `target` ⇒ `ui`, so older manifests still work.
```

--------------------------------

### targetFor method signature

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Signature of the targetFor method. It returns the install target path relative to the project root for a family. Block components install to components/block and render as <x-block.*>; everything else defaults to resources/views/components/ui. Absent target defaults to ui.

```php
public function targetFor(string $family): string
```

--------------------------------

### Handling a component item: files, composer, npm

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-registry-client.md

Demonstrates handling a component item: check for null (unknown family or remote unreachable), then iterate over files to write content to the target path, and iterate over composer and npm packages for installation. The comments show the intended actions for each loop.

```php
$item = $client->component('server-tree-table');
if ($item === null) {
    // unknown family + remote unreachable
}
foreach ($item['files'] as $file) {
    // write $file['content'] to base_path().'/'.ltrim($file['target'], '/')
}
foreach ($item['composer'] as $pkg) { /* composer require $pkg */ }
foreach ($item['npm'] as $pkg) { /* npm install -D $pkg */ }
```

--------------------------------

### RegistryClient usage: catalogue and single-item retrieval

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-registry-client.md

Shows how to instantiate RegistryClient with a custom base URL or the BLATUI_REGISTRY_URL environment variable, then use catalogue methods (index, itemsOfType, search) and single-item methods (component, example). Note that component works offline with bundled stubs, while example is remote-only.

```php
use BlatUI\Mcp\RegistryClient;
use BlatUI\Registry;

$client = new RegistryClient(new Registry); // base: https://blatui.remix-it.com
$client = new RegistryClient(new Registry, 'https://my-registry.test'); // or setenv BLATUI_REGISTRY_URL

// Catalogue
$all = $client->index();                 // remote /registry.json items, offline fallback
$ui  = $client->itemsOfType('registry:ui');
$hits = $client->search('date picker', 'component');

// Single item
$button = $client->component('button');  // works offline (bundled stubs)
$dash = $client->example('block', 'dashboard-01');   // remote only
$area = $client->example('chart', 'chart-area-default'); // remote only
```

--------------------------------

### Run blatui:mcp with custom registry

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Shows how to run the blatui:mcp command with a custom registry URL. The commented JSON shows an example MCP server configuration for AI editors.

```bash
# Editor MCP config:
# { "mcpServers": { "blatui": { "command": "php", "args": ["artisan", "blatui:mcp"] } } }
php artisan blatui:mcp --registry=https://my-mirror.test
```

--------------------------------

### Bootstrap blatui.js for greenfield applications

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/js-foundations.md

Use this file to import Alpine and register BlatUI automatically. It includes a guard to start Alpine if it is not already present on the window object.

```js
import Alpine from 'alpinejs';
import { registerBlatUI } from './blatui-core.js';

document.addEventListener('alpine:init', () => registerBlatUI(window.Alpine));

if (!window.Alpine) {
    window.Alpine = Alpine;
    Alpine.start();
}
```

--------------------------------

### blatui:list command usage

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Example invocations of the blatui:list command. Without an argument it lists all component families; with a component slug it shows details for that family.

```bash
php artisan blatui:list          # all families
php artisan blatui:list select   # details for one family
```

--------------------------------

### Register BlatUI into an existing Alpine instance

Source: https://github.com/anousss007/blatui/blob/main/README.md

For existing projects already running Alpine, register BlatUI into your own instance instead of importing `blatui.js` (which would boot a second Alpine). Call `registerBlatUI(Alpine)` before starting Alpine.

```javascript
import Alpine from 'alpinejs'
import { registerBlatUI } from './blatui-core.js'

registerBlatUI(Alpine)   // plugins + theme store + chart/calendar engines
window.Alpine = Alpine
Alpine.start()
```

--------------------------------

### Fix permissions with server-setup.sh

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/deploy/README.md

Run the server setup script once to fix permissions. It adds the deploy user to the www-data group, sets shared-group + setgid + group-writable layout on storage and bootstrap/cache, makes php-fpm create group-writable files (umask 002), and sets opcache.revalidate_freq=0. Log out/in once afterwards so the group change applies.

```bash
sudo bash deploy/server-setup.sh
```

--------------------------------

### RegistryClient::example() method signature

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-registry-client.md

Method signature for fetching a remote block or chart example. The $kind parameter accepts 'chart' or anything else (treated as block). Returns a normalized remote item from {base}/r/{charts|blocks}/{name}.json, or null if unreachable or unknown. Blocks and charts are not bundled in the package, so this is remote-only.

```php
/** A block or chart example (remote only — not bundled in the package). */
public function example(string $kind, string $name): ?array
```

--------------------------------

### blatui:update command usage examples

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/console-commands.md

Example invocations of the `blatui:update` Artisan command. Use `--dry-run` with `--diff` or `--ignore-whitespace` to preview changes, pass component families like `button card` with `--force` to overwrite without confirmation, and combine `--force` with `--no-backup` to skip `.bak` copies.

```bash
php artisan blatui:update --dry-run --diff
php artisan blatui:update --dry-run --ignore-whitespace
php artisan blatui:update button card --force
php artisan blatui:update --force --no-backup
```

--------------------------------

### Configure nginx and set up TLS with Certbot

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/deploy/README.md

Configure nginx with the provided config, replace SERVER_NAME with your subdomain, enable the site, and reload nginx. Then install Certbot and obtain a TLS certificate for the subdomain.

```bash
sudo cp deploy/nginx.conf /etc/nginx/sites-available/blatui-demo
sudo sed -i 's/SERVER_NAME/demo.blatui.dev/' /etc/nginx/sites-available/blatui-demo
sudo ln -sf /etc/nginx/sites-available/blatui-demo /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

# Point your subdomain's A/AAAA record at the VPS, then:
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d demo.blatui.dev
```

--------------------------------

### Returned shape for component method

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-registry-client.md

Shows the normalized array shape returned by the component method. Includes keys for name, type, title, description, files, registryDependencies, composer, npm, and install. The install value is a string like 'php artisan blatui:add <name>'.

```php
[
    'name' => string, 'type' => 'registry:ui',
    'title' => string,
    'description' => ?string,
    'files' => list<array{target: string, content: string}>,
    'registryDependencies' => list<string>,
    'composer' => list<string>, 'npm' => list<string>,
    'install' => string,
]
```

--------------------------------

### Usage with darkMode: false

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/js-foundations.md

Example showing how to register BlatUI with the `darkMode` option set to `false` to prevent BlatUI from toggling the `dark` class, useful when Flux/Livewire already manages dark mode.

```js
// Flux already drives dark mode — stop BlatUI from toggling .dark:
import { registerBlatUI } from './blatui-core.js';
registerBlatUI(window.Alpine, { darkMode: false });
```

--------------------------------

### Register BlatUI with Livewire's Alpine via alpine:init

Source: https://github.com/anousss007/blatui/blob/main/README.md

For Livewire or Flux projects, register BlatUI onto Livewire's Alpine via the `alpine:init` hook. Do not install `alpinejs` or import `blatui.js` to avoid a duplicate Alpine. Pass `{ darkMode: false }` if Flux already drives dark mode.

```javascript
import { registerBlatUI } from './blatui-core.js'

document.addEventListener('alpine:init', () => {
    registerBlatUI(window.Alpine)
})
```

--------------------------------

### Clone the demo repository and set up .env

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/deploy/README.md

Clone the demo repository into /var/www and prepare the environment file. Copy .env.production.example to .env and edit APP_URL to your subdomain.

```bash
sudo mkdir -p /var/www && sudo chown $USER /var/www
git clone https://github.com/anousss007/blatui-demo.git /var/www/blatui-demo
cd /var/www/blatui-demo
cp .env.production.example .env       # then edit APP_URL to your subdomain
```

--------------------------------

### RemoteInstaller::__construct

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/remote-installer.md

Constructor for the RemoteInstaller class, which installs registry items from a remote, shadcn-compatible registry.

```APIDOC
## RemoteInstaller — `BlatUI\RemoteInstaller`

### Description
Installs registry items from a remote, shadcn-compatible registry — turning `blatui:add` into a platform: anyone can publish components by serving a registry-item JSON, and consumers add them by namespace or URL.

### Constructor

```php
public function __construct(
    protected Registry $local,
    array $registries = [],
    ?callable $fetcher = null,
)
```

### Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `$local` | `Registry` | yes | — | The bundled registry, used to resolve local families/dependencies. |
| `$registries` | `array<string, string>` | no | `[]` | Namespace → URL template map (must contain `{name}`). Merged **under** the built-in `@blatui` entry, which defaults to `'https://blatui.remix-it.com/r/{name}.json'`. |
| `$fetcher` | `callable(string): ?array` | no | `fn (string $url) => $this->httpGet($url)` | Override the HTTP layer (used by tests). Given a URL, returns a decoded JSON array or `null`. |

### Usage Example

```php
$installer = new RemoteInstaller(
    $registry,
    (array) config('blatui.registries', []),
);
```
```

--------------------------------

### Editor quick-add: local stdio config

Source: https://github.com/anousss007/blatui/blob/main/apps/demo/MCP-LISTING.md

JSON configuration for adding the local BlatUI MCP server to Claude Code, Cursor, or VS Code. Uses the stdio transport with the artisan command after installing the package.

```json
{ "mcpServers": { "blatui": { "command": "php", "args": ["artisan", "blatui:mcp"] } } }
```

--------------------------------

### Use BlatUI components in Blade

Source: https://github.com/anousss007/blatui/blob/main/resources/boost/skills/blatui-development/SKILL.md

Compose UI with `x-ui.` namespace components. The example shows button, input, and card with header, title, description, and content.

```blade
<x-ui.button variant="default">Save</x-ui.button>
<x-ui.input type="email" placeholder="you@example.com" />
<x-ui.card>
    <x-ui.card-header>
        <x-ui.card-title>Title</x-ui.card-title>
        <x-ui.card-description>Subtitle</x-ui.card-description>
    </x-ui.card-header>
    <x-ui.card-content>...</x-ui.card-content>
</x-ui.card>
```

--------------------------------

### Using window.Chart helpers

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/js-charts.md

Example usage of the window.Chart helper API to create an area chart. Loads ApexCharts, builds options with automatic color resolution, renders the chart, and observes theme changes to update options.

```javascript
const Apex = await window.Chart.load();
const el = document.querySelector('#my-chart');

const options = window.Chart.buildChartOptions({
    type: 'area',
    height: 300,
    series: [{ name: 'Sales', data: [30, 40, 35] }],
    colors: ['oklch(0.6 0.12 262)'],   // resolved automatically
});
const chart = new Apex(el, options);
await chart.render();

const stop = window.Chart.observeTheme(() => chart.updateOptions(window.Chart.buildChartOptions(raw)));
```

--------------------------------

### Run browser tests against the testbed

Source: https://github.com/anousss007/blatui/blob/main/apps/livewire/README.md

Run the browser test suite against the default local server or a custom host and port. The suite reuses the demo's Playwright harness, so Playwright must be installed from the demo's package.json if not already available.

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

--------------------------------

### boot() method implementation

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/blatui-service-provider.md

Inside a runningInConsole() guard, it registers six artisan commands, declares a 'blatui-foundations' publish group, and an opt-in 'blatui-charts' publish group.

```php
$this->commands([
    InitCommand::class,
    ListCommand::class,
    AddCommand::class,
    UpdateCommand::class,
    DoctorCommand::class,
    McpCommand::class,
]);
```

```php
$this->publishes([
    dirname(__DIR__).'/stubs/foundations/app.css'        => resource_path('css/blatui.css'),
    dirname(__DIR__).'/stubs/foundations/app.js'         => resource_path('js/blatui.js'),
    dirname(__DIR__).'/stubs/foundations/blatui-core.js' => resource_path('js/blatui-core.js'),
], 'blatui-foundations');
```

```php
$this->publishes([
    dirname(__DIR__).'/stubs/foundations/blatui-charts.js' => resource_path('js/blatui-charts.js'),
], 'blatui-charts');
```

--------------------------------

### GET /mcp

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Returns a 405 error for GET requests to the MCP endpoint.

```APIDOC
## GET /mcp

### Description
Returns a 405 error indicating that POST should be used for JSON-RPC.

### Method
GET

### Endpoint
/mcp

### Response
#### Error Response (405)
- **error** (string) - "Use POST for JSON-RPC. Server card: /.well-known/mcp/server-card.json"
- **Allow** (header) - POST
```

--------------------------------

### Diff::stat() usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/diff.md

Example return value of Diff::stat() showing added and removed counts.

```php
['added' => 1, 'removed' => 2]; // shown by blatui:update as +1 -2
```

--------------------------------

### Constructor with RegistryClient and version

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/mcp-server.md

Initializes the server with a RegistryClient data source and an optional version string, defaulting to 'dev'.

```php
public function __construct(
    protected RegistryClient $client,
    protected string $version = 'dev',
) {}
```

--------------------------------

### familyOf usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Example usage of familyOf showing the return value for an existing slug and null for an unknown slug.

```php
$registry->familyOf('accordion-trigger'); // => "accordion"
$registry->familyOf('nope');              // => null
```

--------------------------------

### Diff::ops() usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/diff.md

Example usage of Diff::ops() showing the returned edit script for a single-line change. The output is a list of op/line pairs in output order.

```php
$ops = Diff::ops(['a', 'b', 'c'], ['a', 'B', 'c']);
// [[' ', 'a'], ['-', 'b'], ['+', 'B'], [' ', 'c']]
```

--------------------------------

### sameIgnoringWhitespace usage example

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/diff.md

Example call showing that a newline inside the attribute value is ignored, so the two strings are considered equal. The method drops whitespace entirely rather than collapsing it to a single space.

```php
Diff::sameIgnoringWhitespace("<div class=\"p-4\">\n<x-ui.button/>", '<div class="p-4"><x-ui.button/>'); // true
```

--------------------------------

### Add real auth with Laravel Breeze

Source: https://github.com/anousss007/blatui/blob/main/apps/starter/README.md

Adds working authentication on top of the UI-only auth screens. Installs Laravel Breeze as a dev dependency and installs the Blade stack, keeping the BlatUI forms.

```bash
composer require laravel/breeze --dev
php artisan breeze:install blade
```

--------------------------------

### boot() method signature

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/blatui-service-provider.md

The boot() method is console-only and returns void. It registers artisan commands and publish groups.

```php
public function boot(): void
```

--------------------------------

### initialize

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/types.md

Initializes the MCP server, returning protocol version, capabilities, server info, and instructions.

```APIDOC
## initialize

### Description
Initializes the MCP server, returning protocol version, capabilities, server info, and instructions.

### Method
POST (HTTP transport) or stdio line

### Endpoint
/ (HTTP transport)

### Parameters
#### Request Body
- **method** (string) - Required - Must be "initialize".
- **params** (object) - Optional - May contain client capabilities and protocol version.

### Request Example
```json
{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {} }
```

### Response
#### Success Response
- **protocolVersion** (string) - "2025-06-18"
- **capabilities** (object) - Contains tools, resources, prompts.
  - **tools** (object) - Empty object.
  - **resources** (object) - Empty object.
  - **prompts** (object) - Empty object.
- **serverInfo** (object) - Server information.
  - **name** (string) - "blatui"
  - **version** (string) - Server version.
- **instructions** (string) - Instructions string.

#### Response Example
```json
{ "jsonrpc": "2.0", "id": 1, "result": { "protocolVersion": "2025-06-18", "capabilities": { "tools": {}, "resources": {}, "prompts": {} }, "serverInfo": { "name": "blatui", "version": "1.0.0" }, "instructions": "..." } }
```
```

--------------------------------

### GET /openapi.json

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the OpenAPI specification for the registry API.

```APIDOC
## GET /openapi.json

### Description
Returns the OpenAPI description of the registry API.

### Method
GET

### Endpoint
/openapi.json

### Response
#### Success Response (200)
- **application/json** (object) - OpenAPI description
```

--------------------------------

### GET /.well-known/api-catalog

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the API catalogue in linkset format.

```APIDOC
## GET /.well-known/api-catalog

### Description
Returns the RFC 9727 API catalogue.

### Method
GET

### Endpoint
/.well-known/api-catalog

### Response
#### Success Response (200)
- **application/linkset+json** (object) - API catalogue
```

--------------------------------

### register() method implementation

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/blatui-service-provider.md

Merges config/blatui.php into the 'blatui' config key and binds BlatUI\Registry as a singleton. The singleton ensures all commands receive the same Registry instance per request.

```php
$this->mergeConfigFrom(dirname(__DIR__).'/config/blatui.php', 'blatui');
$this->app->singleton(Registry::class, fn () => new Registry);
```

--------------------------------

### GET /.well-known/agent-skills/blatui/SKILL.md

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the skill markdown for the blatui-development skill.

```APIDOC
## GET /.well-known/agent-skills/blatui/SKILL.md

### Description
Returns the body of the 'blatui-development' skill.

### Method
GET

### Endpoint
/.well-known/agent-skills/blatui/SKILL.md

### Response
#### Success Response (200)
- **text/markdown** (string) - Skill body
```

--------------------------------

### GET /.well-known/agent-skills/index.json

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the agent skills index for discovery.

```APIDOC
## GET /.well-known/agent-skills/index.json

### Description
Returns the agent skills index.

### Method
GET

### Endpoint
/.well-known/agent-skills/index.json

### Response
#### Success Response (200)
- **application/json** (object) - Agent skills index
```

--------------------------------

### GET /.well-known/agent-card.json

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the A2A agent card for discovery.

```APIDOC
## GET /.well-known/agent-card.json

### Description
Returns the A2A agent card.

### Method
GET

### Endpoint
/.well-known/agent-card.json

### Response
#### Success Response (200)
- **application/json** (object) - A2A agent card
```

--------------------------------

### Constructor

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/registry.md

Creates a new Registry instance. Optionally accepts a custom manifest path and stubs directory. Throws RuntimeException if the manifest file does not exist or is not valid JSON.

```APIDOC
## Constructor

### Description
Creates a new Registry instance. Optionally accepts a custom manifest path and stubs directory. Throws RuntimeException if the manifest file does not exist or is not valid JSON.

### Method
Constructor

### Signature
```php
public function __construct(?string $manifestPath = null, ?string $stubsDir = null)
```

### Parameters
- **$manifestPath** (?string) - Optional - Path to the JSON manifest. Default: `dirname(__DIR__).'/stubs/registry.json'`
- **$stubsDir** (?string) - Optional - Directory holding the component `.blade.php` stubs the manifest describes. Default: `dirname(__DIR__).'/stubs/ui'`

### Throws
- **RuntimeException** - When the manifest file does not exist.
- **RuntimeException** - When the manifest is not valid JSON.

### Example
```php
$registry = new Registry;
$registry = new Registry('/custom/registry.json', '/custom/stubs/ui');
```
```

--------------------------------

### GET /.well-known/mcp/server-card.json

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/endpoints.md

Provides the MCP server card for discovery.

```APIDOC
## GET /.well-known/mcp/server-card.json

### Description
Returns the MCP server card with protocol versions and capabilities.

### Method
GET

### Endpoint
/.well-known/mcp/server-card.json

### Response
#### Success Response (200)
- **application/json** (object) - MCP server card
```

--------------------------------

### register() method signature

Source: https://github.com/anousss007/blatui/blob/main/_autodocs/api-reference/blatui-service-provider.md

The register() method merges config and binds a singleton. It returns void and throws no exceptions.

```php
public function register(): void
```
Tokens:
Raw