Vite Stubby Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require phppirate/vite-stubby
   

   Run the publisher to publish the stubs:

   php artisan vendor:publish --provider="PhpPirate\ViteStubby\ViteStubbyServiceProvider" --tag="vite-stubby"
   

2. Configuration Locate the published config file at config/vite-stubby.php and adjust settings like:

   • entryPoints (default: ['resources/js/app.js'])
   • buildDirectory (default: public/build)
   • devServerPort (default: 5173)

3. First Use Case Replace your resources/js/app.js with a basic Vite entry point (e.g., using the published stub):

   import './bootstrap';
   import '../css/app.css';
   

   Run Vite dev server:

   npm run dev
   

   Or build for production:

   npm run build
   

Implementation Patterns

Workflows

1. Scaffolding New Projects Use the published stubs (resources/js/app.js, resources/css/app.css) as a starting point for new Laravel projects, ensuring consistency across teams.

2. Integration with Laravel Mix Replace webpack.mix.js with Vite’s vite.config.js (published stub) and update package.json scripts:

   {
     "scripts": {
       "dev": "vite",
       "build": "vite build"
     }
   }
   

3. Asset Organization Leverage Vite’s native support for:

   • Modular Imports: Split JS/CSS into smaller files (e.g., resources/js/components/Button.js).
   • Asset Optimization: Use @vitejs/plugin-react or @vitejs/plugin-vue for framework-specific optimizations.

4. Environment-Specific Configs Use vite.config.js to conditionally load assets:

   import { defineConfig } from 'vite';
   import laravel from 'laravel-vite-plugin';
   
   export default defineConfig({
     plugins: [
       laravel({
         input: ['resources/js/app.js'],
         refresh: true,
       }),
     ],
     build: {
       outDir: process.env.NODE_ENV === 'production'
         ? 'public/build'
         : 'public/hot',
     },
   });
   

Integration Tips

• Laravel Blade: Use @vite(['resources/js/app.js']) in Blade templates for dynamic asset loading.
• Hot Module Replacement (HMR): Enable in vite.config.js for seamless dev experience:

  server: {
    hmr: {
      host: 'localhost',
    },
  }
  

• TypeScript Support: Add @vitejs/plugin-basic-ssl and configure tsconfig.json for type safety.

Gotchas and Tips

Pitfalls

1. Stub Overwrites

   • The publisher may overwrite existing resources/js/app.js or vite.config.js. Backup files before running vendor:publish.
   • Fix: Use --tag="vite-stubby" explicitly to avoid unintended overwrites.

2. Port Conflicts

   • Vite’s default port (5173) may clash with other dev servers (e.g., Laravel Valet).
   • Fix: Update devServerPort in config/vite-stubby.php or use:

     VITE_PORT=3000 npm run dev
     

3. Missing Dependencies

   • Forgetting to install laravel-vite-plugin or Vite core packages (vite, @vitejs/plugin-*) will break builds.
   • Fix: Add to package.json:

     "devDependencies": {
       "vite": "^4.0.0",
       "laravel-vite-plugin": "^0.7.0"
     }
     

4. Production Build Paths

   • Hardcoding asset paths (e.g., /css/app.css) in Blade templates will fail in production if buildDirectory changes.
   • Fix: Use Laravel’s mix() helper or Vite’s @vite() directive with dynamic paths:

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

Debugging

• Build Errors: Check npm run build -- --debug for detailed Vite logs.
• HMR Issues: Clear browser cache or restart the dev server if HMR fails.
• Laravel Caching: Run php artisan config:clear and php artisan view:clear after config changes.

Extension Points

1. Custom Stubs Override published stubs by copying them to your project (e.g., resources/js/app.js) before installation.

2. Vite Plugins Extend vite.config.js with plugins like:

   import { VitePWA } from 'vite-plugin-pwa';
   plugins: [laravel(), VitePWA({ registerType: 'autoUpdate' })]
   

3. CI/CD Optimization Use Vite’s --mode production flag in CI for faster builds:

   npm run build -- --mode production
   

4. Monorepo Support Configure Vite to work with monorepos (e.g., Turborepo) by adjusting resolve.alias in vite.config.js.