Setting up Vite on a DDEV-based Drupal project

This guide outlines the basic steps required to integrate Vite into a DDEV-based project for Drupal. Vite is a fast frontend tool for web development, and combining it with DDEV can streamline the development process, especially with features like Hot Module Replacement (HMR).

Prerequisites

Before starting, ensure that you have the following set up:

• A DDEV project.

• NPM or any other package manager of your preference installed within your DDEV environment.

• A basic understanding of Vite and Drupal theme development.

Step 1: Expose Node Server Port in DDEV

This detailed explanation outlines the necessary steps to integrate Vite into a DDEV project. First, we need to expose the node server port in DDEV. To do so, modify your .ddev.config.yaml file as shown below, and restart DDEV:

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

Step 2: Configure Vite

Once the base DDEV configuration is set up, you then need to configure Vite to listen on all local addresses, as explained in the Vite documentation, and create a manifest file for your build. In the vite.config.js file, you'll also define the entry points for Vite's build process.

Here’s an example configuration:

# vite.config.js
import { defineConfig } from "vite";
import path from "path";

const port = 5173;
const origin = `${process.env.DDEV_PRIMARY_URL}:${port}`;

export default defineConfig({
  plugins: [],
  build: {
    manifest: true,
    rollupOptions: {
      input: [
        path.resolve(__dirname, "./src/scss/main.scss"),
        path.resolve(__dirname, "./src/js/main.js")
      ]
    },
  },
  server: {
    host: "0.0.0.0",
    port: port,
    strictPort: true,
    origin: origin,
    cors: {
      origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
    },
  },
});

Step 3: Setting Up a Basic Theme Structure

In a basic DDEV but non-Drupal setup, you would only need to include the @vite/client scripts and your source files in your HTML or PHP files, and these steps would suffice to have a properly running demo. A common misconception based on prior experience to Vite projects is that the needed URL to launch the project is http://localhost:5173; however, this not true. Once the development server is up and running, you need to use the auto-generated project URL, for your DDEV project (e.g. https://[ddev-project].ddev.site). So, the next steps are related to Drupal and involve a few extra configurations you need to add.

In your Drupal theme, a basic file structure might look like the following:

- theme_name
[...]
-- dist
-- src
--- js
---- main.js
--- scss
---- main.scss
-- theme_name.info.yml
-- theme_name.libraries.yml
-- vite.config.js

Step 4: Configure Drupal Libraries

Next, define the necessary Drupal libraries in your theme_name.libraries.yml file, as described in the module documentation. This will allow Vite to manage the CSS and JavaScript assets.

# theme.libraries.yml
main:
  vite: true
  js:
    src/js/main.js: {}
  css:
    theme:
      src/scss/main.scss: {}
  dependencies:
    - core/drupal
    - core/drupalSettings

Step 5: Setting the devServerUrl for HMR

To enable Hot Module Replacement (HMR) during development, you need to set the devServerUrl in your settings.local.php file:

# settings.local.php
$settings['vite'] = [
  'devServerUrl' => $_ENV['DDEV_PRIMARY_URL'] .':5173'
];

This configuration ensures that the HMR scripts will be loaded from the correct DDEV project URL instead of localhost:5173.

Step 6: Build and Run the Project

After configuring Vite and your Drupal theme, run the following commands inside your DDEV environment:

ddev npm i #if not already done to install node modules
ddev npm run build #will create manifest.json from the entry files assigned in vite.config.js
ddev drush cr
ddev npm run dev #starts vite dev server

Once the development server is running, access your project via https://[project-name].ddev.site. Vite will handle HMR, and changes to any of the specified source files (e.g., main.js, main.scss) will trigger instant updates. When adding new entry points in your Vite configuration, rebuild the the manifest file and then clear the caches to make sure the newest updates are included.