包简介

Blade islands for Laravel.

README 文档

README

Server-side Blade directives for React, Vue, and Svelte islands in Laravel.

Blade Islands lets you render small React, Vue, or Svelte components inside Laravel Blade views without turning your application into a full single-page app.

This package provides the Blade directives and HTML output. The browser runtime lives in the npm package blade-islands.

Why Blade Islands?

Blade Islands works well when your application is mostly server-rendered but still needs interactive UI in places such as:

search inputs
dashboards
maps
counters
filters
dialogs

Instead of building entire pages in a frontend framework, you can keep Blade as your primary rendering layer and hydrate only the parts of the page that need JavaScript.

Installation

Install the Laravel package:

composer require eznix86/blade-islands

Then install the browser runtime, your frontend framework, and the matching Vite plugin.

React

npm install blade-islands react react-dom @vitejs/plugin-react

Vue

npm install blade-islands vue @vitejs/plugin-vue

Svelte

npm install blade-islands svelte @sveltejs/vite-plugin-svelte

Quick Start

Add the runtime to resources/js/app.js, load that entry from your Blade layout, and render an island from Blade.

React

resources/js/app.js

import islands from 'blade-islands/react'

islands()

Blade layout:

<head>
    @viteReactRefresh
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

@react('ProfileCard', ['user' => $user])

This mounts resources/js/islands/ProfileCard.jsx.

Vue

resources/js/app.js

import islands from 'blade-islands/vue'

islands()

Blade layout:

<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

@vue('ProfileCard', ['user' => $user])

This mounts resources/js/islands/ProfileCard.vue.

Svelte

resources/js/app.js

import islands from 'blade-islands/svelte'

islands()

Blade layout:

<head>
    @vite(['resources/css/app.css', 'resources/js/app.js'])
</head>

@svelte('ProfileCard', ['user' => $user])

This mounts resources/js/islands/ProfileCard.svelte.

Available Directives

Blade Islands provides three directives:

@react('Dashboard', ['user' => $user])
@vue('Support/TicketList', ['tickets' => $tickets])
@svelte('Cart/Drawer', ['count' => $count])

How It Works

Blade Islands has two parts:

this package renders island placeholders from Blade
the npm runtime scans the DOM and mounts the matching frontend component

For example:

@react('Account/UsageChart', ['stats' => $stats])

renders the metadata needed to mount:

resources/js/islands/Account/UsageChart.jsx

Vite Setup

Register the plugin for the framework you use.

React

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
})

If your Laravel layout loads a React entrypoint in development, include:

@viteReactRefresh

Vue

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
})

Svelte

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

export default defineConfig({
  plugins: [svelte()],
})

Component Resolution

By default, the runtime looks for components in resources/js/islands.

Nested folders work automatically. For example:

@vue('Billing/Invoices/Table', [...])

resolves to:

resources/js/islands/Billing/Invoices/Table.vue

Custom Root

This package does not resolve filesystem paths itself, but it works with custom roots configured in the browser runtime.

For example, if your frontend entry uses:

import islands from 'blade-islands/vue'

islands({
  root: '/resources/js/widgets',
  components: import.meta.glob('/resources/js/widgets/**/*.vue'),
})

Then this Blade call:

@vue('Dashboard', [...])

mounts:

resources/js/widgets/Dashboard.vue

Preserve Mounted Islands

Use preserve: true when the same DOM is processed more than once and you want Blade Islands to keep an existing island mounted instead of mounting it again.

This is useful when the page or a DOM fragment is recalculated and your frontend boot logic runs again.

@react('Dashboard/RevenueChart', ['stats' => $stats], preserve: true)
@vue('Dashboard/RevenueChart', ['stats' => $stats], preserve: true)
@svelte('Dashboard/RevenueChart', ['stats' => $stats], preserve: true)

If you reuse a preserved component in a loop, pass a unique key so each island keeps its own identity:

@foreach ($products as $product)
    @react('Product/Card', ['product' => $product], preserve: true, key: "product-{$product->id}")
@endforeach

Options

Each directive accepts up to four arguments:

@react($component, $props = [], $preserve = false, $key = null)

$component - component name relative to the JavaScript component root
$props - props encoded into the rendered HTML
$preserve - keeps an existing island mounted when the same DOM is processed again
$key - unique key for distinguishing repeated preserved islands

Named arguments are supported:

@react(
    component: 'Dashboard',
    props: ['user' => $user],
    preserve: true,
    key: 'dashboard-main',
)

Protocol

Blade Islands renders lightweight placeholders like:

<div
  data-island="react"
  data-component="Dashboard"
  data-props="{&quot;user&quot;:{&quot;name&quot;:&quot;Bruno&quot;}}"
  data-preserve="true"
  data-key="react:dashboard"
></div>

Requirements

PHP 8.3+
Laravel 13+

Companion Package

Use this package with the separate browser runtime:

npm package: blade-islands
repository: blade-islands

Blade Islands vs X

Inertia.js

Inertia is a better fit when your application wants React, Vue, or Svelte to render full pages with a JavaScript-first page architecture.

Blade Islands is a better fit when your application is already Blade-first and you want to keep server-rendered pages while hydrating only selected components.

MingleJS

MingleJS is often used in Laravel applications that embed React or Vue components, especially in Livewire-heavy codebases.

Blade Islands is more naturally suited to Blade-first applications that want progressive enhancement with minimal architectural change. It does not depend on Livewire, and it may also be used alongside Livewire when that fits your application.

Laravel UI

Laravel UI is a legacy scaffolding package for frontend presets and authentication views.

Blade Islands solves a different problem: adding targeted client-side interactivity to server-rendered Blade pages.

Testing

composer install
composer test

Contributing

Contributions are welcome.

Fork the repository
Create a focused branch
Add or update tests
Run composer test
Open a pull request with a clear summary

License

MIT

eznix86/blade-islands 适用场景与选型建议

eznix86/blade-islands 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 334 次下载、GitHub Stars 达 14，最近一次更新时间为 2026 年 03 月 23 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「laravel」「react」「blade」「vue」「svelte」「islands」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 eznix86/blade-islands 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 eznix86/blade-islands 我们能提供哪些服务？

定制开发 / 二次开发

基于 eznix86/blade-islands 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 eznix86/blade-islands 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

voryx/pgasync 112

Async Reactive Postgres Driver for PHP (Non-blocking)

blade-to-react/laravel 0

Laravel integration for blade-to-react

ritechoice23/laravel-reactions 1

A simple, flexible Laravel package for adding polymorphic reactions to any model. React with any text: like, love, care, or anything you want.

mcg-web/promise-factory 2

This library tries to create a simple promise factory standard while waiting for a psr.

foxtes/alfabank-rest 1

Alfabank REST API integration

beeeye/lumen-graphql 1

Facebook GraphQL for lumen

eznix86/blade-islands

包简介

关键字：

README 文档

README

Contents

Why Blade Islands?

Installation

React

Vue

Svelte

Quick Start

React

Vue

Svelte

Available Directives

How It Works

Vite Setup

React

Vue

Svelte

Component Resolution

Custom Root

Preserve Mounted Islands

Options

Protocol

Requirements

Companion Package

Blade Islands vs X

Inertia.js

MingleJS

Laravel UI

Testing

Contributing

License

eznix86/blade-islands 适用场景与选型建议

与 eznix86/blade-islands 相关的其它包

统计信息

GitHub 信息

其他信息