Skip to content

vite.md

Latest commit

 

History

History
406 lines (287 loc) · 13.6 KB

vite.md

File metadata and controls

406 lines (287 loc) · 13.6 KB
Raw

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.

!!!note "HTTPS Configuration" This guide assumes your project runs on https://. If you are unable to access the HTTPS version of your project, refer to the Configuring Browsers.

!!!tip "Custom TLD" If you use a custom project_tld other than ddev.site, adjust the CORS configuration accordingly in your vite.config.js, or use this snippet:

```javascript
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:

For additional integration patterns and framework-specific examples:

Craft CMS

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

!!!note "Port Configuration" When using web_extra_exposed_ports in .ddev/config.yaml, the .ddev/docker-compose.*.yaml file for port exposure is not required.

Example implementations:

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:

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:

!!!note "Laravel-Specific Integration" Laravel's Vite integration uses a public/hot file to manage development server state through its npm 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:

TYPO3

Several tools are available for integrating Vite with TYPO3:

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:

Example implementations:

GitHub Codespaces

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

!!!note "Alternative Port Configuration Required" The DDEV router is unavailable in Codespaces. Instead of using web_extra_exposed_ports in .ddev/config.yaml, create a .ddev/docker-compose.vite-workaround.yaml file:

```yaml
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.