React Wrapper for Laravel/Filament


A comprehensive React integration system for Laravel and Filament applications, providing seamless component registration, state management, and real-time synchronization with built-in memory leak prevention and infinite loop protection.

🚀 Features

- 🔧 Universal Component System - Register and render React components anywhere in your Laravel app
- 🎯 Advanced State Management - Built-in state management with persistence and Livewire sync
- ⚡ Performance Optimized - Lazy loading, memoization, efficient re-rendering, and memory leak prevention
- 🛡️ Type Safe - Full TypeScript support with comprehensive type definitions
- 🔄 Real-time Sync - Bidirectional data flow with Livewire components
- 📦 Zero Config - Works out of the box with sensible defaults
- 🎨 Filament Ready - Native integration with Filament admin panels
- 🧩 Extensible - Plugin system with middleware support
- 🔒 Security First - XSS protection, input validation, and secure prop handling
- 🚫 Loop Protection - Built-in infinite loop detection and prevention
- 🧠 Memory Safe - Automatic cleanup and bounded data structures

📦 Installation

$3

``bash


Install packages

npm install @hadyfayed/filament-react-wrapper
composer require hadyfayed/filament-react-wrapper

Enhanced DX (recommended)

npm install --save-dev vite-plugin-filament-react
`

💡 Pro Tip: Use with vite-plugin-filament-react for enhanced developer experience with auto-discovery, dev tools, and performance optimization.

$3

1. Add to your JavaScript entry:

`javascript
// resources/js/app.js
import '@hadyfayed/filament-react-wrapper';
`

2. Update Vite config (with plugin):

`javascript
// vite.config.js
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
import react from '@vitejs/plugin-react';
import filamentReact from 'vite-plugin-filament-react';

export default defineConfig({
plugins: [
laravel({
input: ['resources/css/app.css', 'resources/js/app.js'],
refresh: true,
}),
react(),
filamentReact(), // Auto-discovery and dev tools
],
});
`

3. Optional: Register the Filament plugin:

`php
// app/Providers/Filament/AdminPanelProvider.php
use HadyFayed\ReactWrapper\FilamentReactWrapperPlugin;

public function panel(Panel $panel): Panel
{
return $panel
->plugins([
FilamentReactWrapperPlugin::make(),
]);
}
`

3. Add to your app.js:

`javascript
import '@hadyfayed/filament-react-wrapper';
`

4. Build your assets:

`bash
npm run build
`

🎯 Quick Start

$3

`typescript
import { componentRegistry } from '@hadyfayed/filament-react-wrapper';
import MyComponent from './components/MyComponent';

// Simple registration
componentRegistry.register({
name: 'MyComponent',
component: MyComponent,
defaultProps: {
message: 'Hello World!'
}
});
`

$3

`html










`

$3

`php
use HadyFayed\ReactWrapper\Components\ReactComponent;

class EditUser extends EditRecord
{
protected function getHeaderActions(): array
{
return [
ReactComponent::make('UserProfileEditor')
->props([
'userId' => $this->record->id,
'editable' => true
])
->statePath('userProfile')
];
}
}
`

📚 Component Registration

$3

`typescript
import { componentRegistry } from '@hadyfayed/filament-react-wrapper';

componentRegistry.register({
name: 'UserCard',
component: UserCard,
defaultProps: {
showAvatar: true,
size: 'medium'
},
metadata: {
category: 'user',
description: 'Displays user information in a card format',
tags: ['user', 'display', 'card']
}
});
`

$3

`typescript
componentRegistry.register({
name: 'HeavyComponent',
component: () => import('./components/HeavyComponent'),
isAsync: true,
config: {
lazy: true,
cache: true,
preload: false
},
metadata: {
category: 'charts',
description: 'Advanced data visualization component'
}
});
`

$3

`typescript
import { registerComponents } from '@hadyfayed/filament-react-wrapper';

const components = [
{ name: 'Button', component: Button },
{ name: 'Modal', component: Modal },
{ name: 'Form', component: Form }
];

registerComponents(components);
`

$3

You can also register React components from the Laravel/PHP side, which is useful for package authors or when you want to manage component registration through Laravel configuration:

#### Service Provider Registration

`php


namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use HadyFayed\ReactWrapper\Services\ReactComponentRegistry;

class ReactComponentServiceProvider extends ServiceProvider
{
public function boot()
{
$registry = app(ReactComponentRegistry::class);

// Register components with PHP
$registry->register([
'name' => 'UserCard',
'component_path' => 'resources/js/components/UserCard.tsx',
'default_props' => [
'showAvatar' => true,
'size' => 'medium'
],
'metadata' => [
'category' => 'user',
'description' => 'Displays user information in a card format',
'tags' => ['user', 'display', 'card']
]
]);

// Register multiple components
$registry->registerMany([
[
'name' => 'ProductCard',
'component_path' => 'resources/js/components/ProductCard.tsx',
'default_props' => ['showPrice' => true],
'metadata' => ['category' => 'product']
],
[
'name' => 'OrderSummary',
'component_path' => 'resources/js/components/OrderSummary.tsx',
'is_async' => true,
'config' => ['lazy' => true, 'cache' => true]
]
]);
}
}
`

#### Configuration-Based Registration

Add to config/react-wrapper.php:

`php


return [
'components' => [
'auto_register' => true,
'scan_directories' => [
'resources/js/components',
'resources/js/widgets'
],
'registered_components' => [
'UserProfile' => [
'component_path' => 'resources/js/components/UserProfile.tsx',
'default_props' => ['editable' => false],
'config' => ['lazy' => false, 'cache' => true],
'metadata' => [
'category' => 'user',
'description' => 'User profile management component'
]
],
'DataTable' => [
'component_path' => 'resources/js/components/DataTable.tsx',
'is_async' => true,
'default_props' => [
'pageSize' => 10,
'sortable' => true
],
'config' => [
'lazy' => true,
'cache' => true,
'preload' => false
]
]
]
]
];
`

#### Artisan Command for Registration

Generate component registration via Artisan:

`bash


Create a new React component with auto-registration

php artisan make:react-component UserDashboard --register

Register an existing component

php artisan react:register ProductCard --path=resources/js/components/ProductCard.tsx

Register multiple components from a directory

php artisan react:scan resources/js/components --register
`

#### Facade Usage

Use the ReactWrapper facade for quick registration:

`php


use HadyFayed\ReactWrapper\Facades\ReactWrapper;

// In a controller, middleware, or service
class ComponentController extends Controller
{
public function registerComponent()
{
ReactWrapper::register([
'name' => 'DynamicChart',
'component_path' => 'resources/js/charts/DynamicChart.tsx',
'default_props' => [
'type' => 'line',
'animated' => true
],
'config' => [
'lazy' => true,
'cache' => false // Don't cache dynamic components
]
]);

return response()->json(['message' => 'Component registered successfully']);
}

public function getRegisteredComponents()
{
$components = ReactWrapper::getRegistered();
return response()->json($components);
}
}
`

#### Package Integration

For Laravel package authors:

`php


namespace YourPackage\Providers;

use Illuminate\Support\ServiceProvider;
use HadyFayed\ReactWrapper\Services\ReactComponentRegistry;

class YourPackageServiceProvider extends ServiceProvider
{
public function boot()
{
// Register package components automatically
$this->registerPackageComponents();

// Publish package components
$this->publishes([
__DIR__.'/../resources/js/components' => resource_path('js/vendor/your-package'),
], 'your-package-components');
}

protected function registerPackageComponents()
{
$registry = app(ReactComponentRegistry::class);

$packageComponents = [
'PackageWidget' => [
'component_path' => 'js/vendor/your-package/PackageWidget.tsx',
'default_props' => ['theme' => 'package-default'],
'metadata' => [
'category' => 'package-widgets',
'package' => 'your-package',
'version' => '1.0.0'
]
]
];

foreach ($packageComponents as $name => $config) {
$registry->register(array_merge($config, ['name' => $name]));
}
}
}
`

#### Dynamic Registration in Filament

Register components dynamically in Filament resources:

`php


namespace App\Filament\Resources;

use Filament\Resources\Resource;
use HadyFayed\ReactWrapper\Services\ReactComponentRegistry;

class UserResource extends Resource
{
public static function boot()
{
parent::boot();

// Register resource-specific components
app(ReactComponentRegistry::class)->register([
'name' => 'UserResourceChart',
'component_path' => 'resources/js/filament/UserResourceChart.tsx',
'default_props' => [
'resource' => 'users',
'metric' => 'registrations'
]
]);
}

public static function form(Form $form): Form
{
return $form->schema([
ReactField::make('user_analytics')
->component('UserResourceChart')
->props(['userId' => fn($record) => $record?->id])
->visible(fn($record) => $record !== null)
]);
}
}
`

🎯 State Management

$3

`typescript
import { StateManagerProvider, useStateManager } from '@hadyfayed/filament-react-wrapper';

function App() {
return (
initialState={{ user: { name: 'John' } }}
onStateChange={(state) => console.log('State changed:', state)}
syncPath="app.state"
>


);
}

function MyComponent() {
const { state, setState, getState } = useStateManager();

const updateUser = () => {
setState('user.name', 'Jane Doe');
};

return (



);
}
`

$3

`typescript
import { useStatePath } from '@hadyfayed/filament-react-wrapper';

function UserProfile() {
const [user, setUser] = useStatePath('user', { name: '', email: '' });

return (



value={user.name}
onChange={(e) => setUser(prev => ({ ...prev, name: e.target.value }))}
/>
value={user.email}
onChange={(e) => setUser(prev => ({ ...prev, email: e.target.value }))}
/>

);
}


`

$3

`typescript
import { globalStateManager } from '@hadyfayed/filament-react-wrapper';

// Set global state
globalStateManager.setState('app.theme', 'dark');

// Get global state
const theme = globalStateManager.getState('app.theme');

// Subscribe to changes
const unsubscribe = globalStateManager.subscribe('app.theme', (newTheme) => {
console.log('Theme changed to:', newTheme);
});

// Clean up
unsubscribe();
`

💾 State Persistence

$3

`typescript
import { usePersistedState } from '@hadyfayed/filament-react-wrapper';

function ThemeSelector() {
const [theme, setTheme] = usePersistedState('theme', 'light', {
storage: 'localStorage',
syncWithLivewire: true,
livewirePath: 'user.theme'
});

return (
setTheme(e.target.value)}>
Light
Dark

);
}
`

$3

`typescript
import { statePersistenceService } from '@hadyfayed/filament-react-wrapper';

// Register a persistence config
statePersistenceService.register({
key: 'userPreferences',
storage: 'localStorage',
syncWithLivewire: true,
livewirePath: 'user.preferences',
debounceMs: 500,
transformer: {
serialize: (data) => JSON.stringify(data),
deserialize: (data) => JSON.parse(data)
}
});

// Save data
statePersistenceService.save('userPreferences', {
theme: 'dark',
language: 'en'
});

// Load data
const preferences = statePersistenceService.load('userPreferences');
`

🎨 Filament Integration

$3

`php


namespace App\Filament\Components;

use HadyFayed\ReactWrapper\Components\ReactComponent;

class UserDashboard extends ReactComponent
{
protected string $component = 'UserDashboard';

public static function make(string $component = null): static
{
return new static($component ?? static::$component);
}

public function userId(int $userId): static
{
$this->props(['userId' => $userId]);
return $this;
}

public function editable(bool $editable = true): static
{
$this->props(['editable' => $editable]);
return $this;
}
}
`

$3

`php
use App\Filament\Components\UserDashboard;

class Dashboard extends Page
{
protected static string $view = 'filament.pages.dashboard';

protected function getHeaderWidgets(): array
{
return [
UserDashboard::make()
->userId(auth()->id())
->editable(true)
->statePath('dashboard.user')
];
}
}
`

$3

`php
use HadyFayed\ReactWrapper\Forms\Components\ReactField;

class UserForm extends Form
{
public function form(Form $form): Form
{
return $form->schema([
ReactField::make('profile_editor')
->component('UserProfileEditor')
->props([
'allowImageUpload' => true,
'maxImageSize' => '2MB'
])
->statePath('profile')
->reactive()
->afterStateUpdated(function ($state) {
// Handle state updates
$this->user->update($state);
})
]);
}
}
`

🔧 Advanced Features

$3

`typescript
import { componentRegistry } from '@hadyfayed/filament-react-wrapper';

// Global middleware
componentRegistry.addMiddleware((component, props, context) => {
// Add analytics tracking
return (componentProps) => {
React.useEffect(() => {
analytics.track('component_rendered', {
component: context.metadata.name,
props: Object.keys(componentProps)
});
}, []);

return React.createElement(component, componentProps);
};
});

// Component-specific middleware
componentRegistry.register({
name: 'SecureComponent',
component: SecureComponent,
config: {
middleware: [
(component, props, context) => {
// Add authentication check
return (componentProps) => {
if (!componentProps.user?.authenticated) {
return React.createElement('div', null, 'Access Denied');
}
return React.createElement(component, componentProps);
};
}
]
}
});
`

$3

All components are automatically wrapped with error boundaries that provide:

- Graceful error display
- Error reporting to console
- Retry functionality
- Custom error handlers

`typescript
componentRegistry.register({
name: 'RiskyComponent',
component: RiskyComponent,
config: {
onError: (error, componentName) => {
// Custom error handling
console.error(Error in ${componentName}:, error);
// Report to error tracking service
errorTracker.report(error, { component: componentName });
}
}
});
`

🚀 Performance & Memory Safety

$3

The system includes comprehensive protection against memory leaks:

`typescript
// Automatic cleanup on component unmount
React.useEffect(() => {
const unsubscribe = globalStateManager.subscribe('user.data', handleUserChange);

return () => {
unsubscribe(); // Automatic cleanup
};
}, []);

// Bounded data structures prevent unlimited growth
// Maximum 1000 entries in persistence service with automatic cleanup
`

$3

Built-in protection against infinite loops in state updates:

`typescript
// Circular notification detection
if (this._notifyingPaths.has(path)) {
console.warn(Circular notification detected for path: ${path});
return; // Prevents infinite loops
}
`

$3

- Memoization - Automatic memoization of components and state
- Debouncing - Built-in debouncing for state changes and notifications
- Lazy Loading - Code splitting for large components
- Efficient Re-rendering - Smart prop comparison and update batching

🔒 Security Features

$3

`typescript
// Validate props before rendering
componentRegistry.register({
name: 'SecureComponent',
component: SecureComponent,
config: {
middleware: [
(component, props, context) => {
return (componentProps) => {
// Validate props
const validatedProps = validateProps(componentProps, {
userId: 'number',
email: 'email',
role: ['admin', 'user', 'guest']
});

return React.createElement(component, validatedProps);
};
}
]
}
});
`

$3

`typescript
// Sanitize HTML content
import DOMPurify from 'dompurify';

const SafeComponent = ({ htmlContent }) => {
const sanitizedHTML = DOMPurify.sanitize(htmlContent);
return