chianglintu/spiral-vite

Vite integration for Spiral Framework with HMR support for CSS, React, and Vue

v1.1.0 2026-01-27 16:56 UTC

Requires

• php: >=8.1
• spiral/boot: ^3.0
• spiral/config: ^3.0
• spiral/twig-bridge: ^2.0

MIT

• chianglintu

• frontend
• react
• spiral
• vue
• tailwind
• Hmr
• vite
• hot-module-replacement

README

Vite integration for Spiral Framework, inspired by Laravel Vite.

Features

• Hot Module Replacement (HMR) for CSS and JavaScript
• React Fast Refresh support
• Vue HMR support
• Tailwind CSS v4 integration
• Production build with asset versioning
• Twig template functions

Requirements

• PHP >= 8.1
• Spiral Framework 3.x
• Node.js >= 18

Installation

PHP Package

composer require chianglintu/spiral-vite

Register the bootloader in app/src/Application/Kernel.php:

use Spiral\Vite\Bootloader\ViteBootloader;

// ...

public function defineBootloaders(): array
{
    return [
        // ... other bootloaders
        ViteBootloader::class,
    ];
}

Vite Plugin

Add the local package to your package.json:

{
  "dependencies": {
    "spiral-vite-plugin": "file:packages/spiral-vite"
  }
}

Then run:

npm install

Configuration

PHP Configuration

Required: Publish the configuration file before using the package:

php app.php vite:publish

This will create app/config/vite.php:

<?php

return [
    'dev_server_url' => env('VITE_DEV_SERVER_URL', 'http://localhost:5173'),
    'build_directory' => 'build',
    'hot_file' => directory('public') . 'hot',
    'manifest' => directory('public') . 'build/.vite/manifest.json',
];

Important: The configuration file is required. The package will throw an error if it's not published.

Vite Configuration

Configure vite.config.js:

import { defineConfig } from 'vite'
import tailwindcss from '@tailwindcss/vite'
import spiralVitePlugin from 'spiral-vite-plugin'

export default defineConfig({
  plugins: [
    spiralVitePlugin({
      input: ['app/resources/css/tailwind.css'],
    }),
    tailwindcss(),
  ],
})

Plugin Options

Option	Type	Default	Description
input	string | string[]	[]	Entry points for the build
publicDirectory	string	'public'	Public directory path
buildDirectory	string	'build'	Build output directory (relative to public)
hotFile	string	'public/hot'	Hot file path for dev server detection

Usage

In Twig Templates

{# Load CSS and JS entry points #}
{{ vite(['app/resources/css/app.css', 'app/resources/js/app.js']) }}

{# Load a single entry point #}
{{ vite('app/resources/js/app.js') }}

{# Get a single asset URL #}
<img src="{{ vite_asset('app/resources/images/logo.png') }}">

{# React Fast Refresh (development only) #}
{{ vite_react_refresh() }}

Development Mode

# Start Vite development server
npm run dev

# In another terminal, start RoadRunner
./rr serve

When the Vite dev server is running, it creates a public/hot file. The PHP backend detects this file and loads assets from the dev server with HMR support.

Production Mode

# Build assets for production
npm run build

# Start RoadRunner
./rr serve

In production, assets are loaded from the public/build/ directory with content hashes for cache busting.

Vite Configuration

See vite.config.js for the full configuration. Key features:

• Automatic hot file creation/cleanup
• Tailwind CSS v4 support
• React and Vue support (uncomment in config)
• Path aliases (@ -> app/resources/)

Adding React Support

1. Install dependencies:

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

2. Update vite.config.js:

   import react from '@vitejs/plugin-react';
   
   export default defineConfig({
       plugins: [
           spiralVitePlugin(),
           tailwindcss(),
           react(),
       ],
       // ...
   });

3. Use in templates:

   {{ vite_react_refresh() }}
   {{ vite('app/resources/js/app.jsx') }}

Adding Vue Support

1. Install dependencies:

   npm install @vitejs/plugin-vue vue

2. Update vite.config.js:

   import vue from '@vitejs/plugin-vue';
   
   export default defineConfig({
       plugins: [
           spiralVitePlugin(),
           tailwindcss(),
           vue(),
       ],
       // ...
   });

API Reference

Console Commands

Command	Description
php app.php vite:publish	Publish Vite configuration file

Twig Functions

Function	Description
vite(entries)	Generate HTML tags for entry points
vite_asset(path)	Get URL for a single asset
vite_react_refresh()	React Fast Refresh script (dev only)

PHP Service

use Spiral\Vite\Vite;

class MyController
{
    public function index(Vite $vite): string
    {
        // Check if in development mode
        if ($vite->isDev()) {
            // ...
        }

        // Get asset URL
        $url = $vite->asset('app/resources/js/app.js');

        // Generate HTML tags
        $tags = $vite->tags(['app/resources/css/app.css']);

        return $tags;
    }
}

License

MIT