Vite Integration¶

Vite is a popular front-end build tool that provides fast development server with Hot Module Replacement (HMR) and optimized production builds. DDEV supports Vite development workflows for various frameworks including Laravel, Vue.js, React, Svelte, and more.

Quick Setup¶

To use Vite with DDEV, you need to:

1. Configure DDEV to expose Vite’s port in .ddev/config.yaml:

   web_extra_exposed_ports:
     - name: vite
       container_port: 5173
       http_port: 5172
       https_port: 5173
   

2. Configure Vite in your vite.config.js:

   import { defineConfig } from 'vite'
   
   export default defineConfig({
     // Your settings
     // ...
   
     // Adjust Vites dev server to work with DDEV
     // https://vitejs.dev/config/server-options.html
     server: {
       // Respond to all network requests
       host: "0.0.0.0",
       port: 5173,
       strictPort: true,
       // Defines the origin of the generated asset URLs during development,
       // this must be set to the Vite dev server URL and selected port.
       origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
       // Configure CORS securely for the Vite dev server to allow requests
       // from *.ddev.site domains, supports additional hostnames (via regex).
       // If you use another `project_tld`, adjust this value accordingly.
       cors: {
         origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
       },
     },
   })
   

3. Restart DDEV to apply configuration changes:

   ddev restart
   

4. Start Vite development server:

   ddev npm run dev
   # or
   ddev yarn dev
   

Your Vite development server will be available at https://yourproject.ddev.site:5173.

export default defineConfig({
  server: {
    cors: {
      origin: new RegExp(
        `https?:\/\/(${process.env.DDEV_HOSTNAME.split(",")
          .map((h) => h.replace("*", "[^.]+"))
          .join("|")})(?::\\d+)?$`
      )
    },
  },
});

Example Projects¶

Example implementations demonstrating Vite integration with DDEV:

• Working with Vite in DDEV - Basic PHP project with step-by-step setup guide
• vite-php-setup - General PHP + Vite integration (adapt VITE_HOST for DDEV)

For additional integration patterns and framework-specific examples:

• Vite Backend Integration Guide - Official Vite documentation for backend frameworks
• Vite Awesome List - Community-maintained list of integrations

Craft CMS¶

The Vite plugin by nystudio107 provides official DDEV support with detailed configuration instructions for vite.config.js and config/vite.php.

Example implementations:

• Craft CMS with Vite integration
• Craft CMS Starter
• How we use DDEV, Vite and Tailwind with Craft CMS

Drupal¶

Several tools and modules are available for integrating Vite with Drupal:

• Vite module - Uses Vite’s manifest.json to map Drupal library files to compiled versions in /dist or to the Vite development server
• UnoCSS Starter theme - Drupal theme with Vite integration and DDEV setup instructions
• Foxy - Alternative asset bundling solution for Drupal

Community resources:

• UnoCSS Starter Theme Documentation
• Proof of concept for Vite bundling in Drupal

The Drupal community is actively developing Vite integration solutions for bundling assets across multiple modules and themes.

Laravel¶

Laravel adopted Vite as the default asset bundler in v9.19, replacing Laravel Mix.

Configure DDEV to expose Vite’s port in .ddev/config.yaml:

web_extra_exposed_ports:
  - name: vite
    container_port: 5173
    http_port: 5172
    https_port: 5173

Configure Vite in your vite.config.js:

import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
  plugins: [
    laravel({
      input: [
        'resources/css/app.css',
        'resources/js/app.js',
      ],
      refresh: true,
    }),
  ],
  server: {
    host: "0.0.0.0",
    port: 5173,
    strictPort: true,
    origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
    cors: {
      origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
    },
  },
});

Start the Vite development server:

ddev npm run dev

Example implementation:

• ddev-laravel-vite - Laravel with Vite integration

Node.js¶

DDEV supports Node.js-only projects by proxying requests to the correct ports within the web container. This configuration enables running Node.js applications like Keystone CMS or SvelteKit entirely within DDEV.

This approach supports various architectures:

• Monorepo setup: Run a PHP backend with a Node.js frontend on separate subdomains within a single DDEV project
• Headless CMS: Ideal for decoupled architectures combining traditional backends with modern JavaScript frameworks
• Multi-project setup: Use separate DDEV projects for frontend and backend with inter-project communication

Additional resources:

• Node.js Development with DDEV - Comprehensive guide to Node.js project configuration
• How to Run Headless Drupal and Next.js on DDEV - Headless CMS implementation guide
• ddev-laravel-breeze-sveltekit - Monorepo example with Laravel and SvelteKit

TYPO3¶

Several tools are available for integrating Vite with TYPO3:

• typo3-vite-demo - Vite demo project
• vite-asset-collector - TYPO3 extension for Vite integration
• vite-plugin-typo3 - Vite plugin for TYPO3
• ddev-vite-sidecar - DDEV add-on for zero-config Vite integration

The vite-asset-collector extension provides detailed DDEV installation instructions. For questions or support, join the Vite channel on TYPO3 Slack.

WordPress¶

Several libraries are available for integrating Vite with WordPress:

• php-wordpress-vite-assets - PHP library for loading Vite assets in WordPress
• vite-for-wp - WordPress integration for Vite
• wp-vite-manifest - Vite manifest loader for WordPress

Example implementations:

• ddev-wp-vite-demo - Demo theme using php-wordpress-vite-assets
• wp-vite-manifest usage guide - Integration guide for themes and plugins
• Integrating Vite and DDEV into WordPress

GitHub Codespaces¶

DDEV supports Vite in GitHub Codespaces with alternative port configuration. Example implementations:

• Laravel with Vite in Codespaces
• Craft CMS with Vite in Codespaces

services:
  web:
    ports:
      - 5173:5173

For additional Codespaces configuration details, see the DDEV Codespaces documentation.

Auto-starting Vite¶

You can configure DDEV to automatically start Vite when the project starts using hooks:

Add to .ddev/config.yaml:

hooks:
  post-start:
    - exec: "npm run dev"

Or use a more robust daemon configuration (logs available via ddev logs -s web):

web_extra_daemons:
  - name: "vite"
    command: bash -c 'npm install && npm run dev -- --host'
    directory: /var/www/html

For a real-world daemon implementation example, see the ddev.com repository configuration.

Production Builds¶

For production builds, ensure your vite.config.js includes proper manifest generation:

export default defineConfig({
  build: {
    manifest: true,
    rollupOptions: {
      input: {
        main: 'path/to/your/main.js',
      }
    }
  },
  // ... other configuration
})

Build for production:

ddev npm run build

DDEV Add-ons¶

Several community add-ons simplify Vite integration:

• ddev-vite-sidecar - Zero-config Vite integration exposing the development server as a https://vite.* subdomain, eliminating the need to expose ports to the host system
• ddev-vitest - Helper commands for projects using Vitest, a Vite-native testing framework
• ddev-viteserve - First DDEV Vite add-on (no longer maintained, but pioneered the integration)

Additional Vite-related add-ons are available in the DDEV Add-on Registry.

Troubleshooting¶

Bad Gateway Errors¶

Problem: Getting “502 Bad Gateway” when accessing Vite URL.

Solutions:

1. Check port configuration: Ensure web_extra_exposed_ports is correctly configured in .ddev/config.yaml.

2. Verify Vite is running: Check if Vite development server is actually running:

   ddev logs -s web
   

3. Restart DDEV: After changing configuration:

   ddev restart
   

CORS Issues¶

Problem: Browser console shows CORS errors.

Solutions:

1. Update CORS configuration in vite.config.js:

   export default defineConfig({
     server: {
       cors: {
         origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
       },
     },
   });
   

2. Check origin setting:

   export default defineConfig({
     server: {
       origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
     },
   });
   

Port Already in Use¶

Problem: “Port 5173 is already in use” error.

Solutions:

1. Use different port: Change the port in both DDEV and Vite configurations:

   # .ddev/config.yaml
   web_extra_exposed_ports:
     - name: vite
       container_port: 5174
       http_port: 5172
       https_port: 5174
   

   // vite.config.js
   export default defineConfig({
     server: {
       port: 5174,
     },
   });
   

2. Kill existing process:

   ddev exec "pkill -f vite"
   

Assets Not Loading¶

Problem: CSS/JS assets not loading properly.

Solutions:

1. Verify base path in production builds matches your web server configuration.

2. Check manifest.json is being generated and loaded correctly.

3. Ensure proper asset URLs in your templates/framework integration.

Best Practices¶

1. Use specific Node.js versions: Specify nodejs_version in your DDEV configuration for consistency across team members.

2. Include Vite in your project dependencies: Don’t rely on global Vite installations.

3. Configure proper .gitignore: Exclude build artifacts:

   /dist/
   /build/
   node_modules/
   

4. Document your setup: Include Vite configuration instructions in your project’s readme.

5. Use environment variables: Leverage process.env.DDEV_PRIMARY_URL_WITHOUT_PORT for dynamic configuration.