Getting Started

Minimal Steps

Installation:

composer require foxws/wireuse

Publish config if needed (e.g., for customizations):

php artisan vendor:publish --tag="wireuse-config"

First Use Case: Use the HasRouteKey trait to automatically resolve model route keys (e.g., slug instead of id) in Livewire components:

use Foxws\WireUse\Traits\HasRouteKey;

class PostComponent extends Component
{
    use HasRouteKey;

    public $post;

    public function mount(Post $post)
    {
        $this->post = $post;
    }

    // Automatically resolves `post->slug` instead of `post->id`
    public function render()
    {
        return view('livewire.post-component');
    }
}

Key Documentation:
- The package now ships a dedicated documentation site (Docusaurus, website/ directory) — start there rather than the raw docs/ markdown.
- Property Synthesizers for dynamic property handling.
- Component Extensions for reusable UI elements.
- v3.1.0 also adds a Laravel Boost skill, so AI-assisted workflows (Boost-enabled editors/agents) can pick up WireUse-specific guidance automatically once the package is installed.

Implementation Patterns

Core Workflows

Model Route Key Resolution:

Replace manual id usage with HasRouteKey for cleaner URLs and API routes.

Example: A UserProfile component using email as the route key:

use HasRouteKey;

class UserProfile extends Component
{
    use HasRouteKey;

    public $user;

    protected $routeKeyName = 'email'; // Override default
}

Property Synthesizers:

Dynamically generate properties from model relationships or computed values.

Example: Auto-synthesize a fullName property from firstName and lastName:

use Foxws\WireUse\Traits\HasSynthesizedProperties;

class UserComponent extends Component
{
    use HasSynthesizedProperties;

    public $user;

    protected $synthesizedProperties = [
        'fullName' => fn() => "{$this->user->firstName} {$this->user->lastName}",
    ];
}

Component Extensions:

Extend Livewire components with shared logic (e.g., Page for layout management):

use Foxws\WireUse\Components\Page;

class Dashboard extends Page
{
    // Inherits layout, title, and meta tags from `Page`
    public function render()
    {
        return view('livewire.dashboard');
    }
}

Form Handling:

Use HasForm trait for validation and submission logic:

use Foxws\WireUse\Traits\HasForm;

class ContactForm extends Component
{
    use HasForm;

    protected $rules = [
        'name' => 'required|max:255',
        'email' => 'required|email',
    ];

    public function submit()
    {
        $this->validate();
        // Handle submission
    }
}

Integration Tips

Blade Integration: Use wireuse directives in Blade templates for dynamic content:
```
@wireuse('post', $post)
    <h1>{{ $post->title }}</h1>
@endwireuse
```
API Responses: Leverage HasRouteKey to ensure API responses use route keys (e.g., slug instead of id):
```
return response()->json($this->post->toArray());
```

Testing: Mock synthesized properties or route keys in unit tests:

$component = new PostComponent();
$component->setModel(new Post(['slug' => 'test-slug']));
$this->assertEquals('test-slug', $component->getRouteKey());

Upgrading to v3.1.0:
- This is a non-breaking minor release — no code changes required; existing v3.0.x apps can bump the constraint and run composer update as usual.
- If you vendor or mirror the docs, note the website/ directory and its Node/pnpm lockfile are new build artifacts and are irrelevant to your app's dependency tree.

Gotchas and Tips

Pitfalls

Route Key Conflicts:
- If a model has no defined route key (e.g., getRouteKey()), HasRouteKey will fall back to id. Explicitly set $routeKeyName to avoid ambiguity:
```
protected $routeKeyName = 'slug'; // Force usage
```

Synthesized Property Overrides:

Synthesized properties override existing ones. Use protected $synthesizedProperties carefully to avoid unintended side effects:

// ❌ Overrides `user->name` if it exists
protected $synthesizedProperties = ['name' => fn() => 'Default Name'];

// ✅ Safe: Uses `user->name` if it exists
protected $synthesizedProperties = ['fullName' => fn() => "{$this->user->name}"];

Component Lifecycle:

Traits like HasForm assume mount() is called. If using wire:model, ensure the component is properly initialized:

// ❌ May fail if `mount()` isn't called
public function updatedField()
{
    $this->validate(); // Requires `HasForm` rules
}

Blade Directive Scope:
- @wireuse directives must wrap Livewire components or properties. Avoid using them outside Livewire contexts:
```
@wireuse('post') 
    <p>{{ $post->title }}</p>
@endwireuse
```
Docs Site vs. Package Docs:
- Since v3.1.0 there are two sources of truth: the rendered Docusaurus site (website/, pnpm-driven) and the plain docs/*.md files. Anchor links and navigation only behave correctly in the built site — when sharing internal links with your team, prefer the hosted docs URL over local markdown paths, since docs/ filenames can move independently of the site routes.

Debugging

Route Key Issues:
- Check php artisan route:list to verify route key usage. If a route uses id but the model uses slug, update the route definition:
```
Route::get('/posts/{post:slug}', [PostController::class, 'show']);
```
Synthesized Property Errors:
- Use dd($this->synthesizedProperties) to inspect generated properties during development.

Form Validation:

Validate rules in HasForm are correctly scoped to the component’s properties:

protected $rules = [
    'user.name' => 'required', // ❌ May fail if `name` isn’t directly on `$this`
    'name' => 'required',      // ✅ Correct for `$this->name`
];

Docs Build Failures (contributors only):
- The website/ site is built with pnpm/Node; CI bumps in v3.1.0 (setup-node, pnpm/action-setup, upload-pages-artifact, deploy-pages) mean a local build pinned to older Node/pnpm versions may fail. Match the versions in the workflows under .github/workflows/ before opening a docs PR.

Extension Points

Custom Traits:
- Extend existing traits (e.g., HasRouteKey) by publishing the config and overriding defaults:
```
// config/wireuse.php
'route_key' => [
    'default' => 'uuid', // Override global default
],
```

New Synthesizers:

Add custom synthesizers by extending Foxws\WireUse\Traits\HasSynthesizedProperties:

protected $synthesizedProperties = [
    'formattedDate' => fn() => $this->date->format('Y-m-d'),
];

Component Overrides:

Override Page or other base components to modify shared behavior:

class CustomPage extends \Foxws\WireUse\Components\Page
{
    public function getTitle()
    {
        return 'Custom Title: ' . parent::getTitle();
    }
}

Testing Utilities:

Use WireUse::fake() to mock synthesized properties or route keys in tests:

WireUse::fake([
    'route_key' => 'test-slug',
    'synthesized' => ['fullName' => 'Test User'],
]);

AI-Assisted Development (v3.1.0):
- A Laravel Boost skill now ships with the package, giving Boost-aware agents project-accurate context on WireUse traits and components. Combined with the published config, this is the fastest way to scaffold a new component that follows the package's conventions rather than generic Livewire patterns.

Wireuse Laravel Package