vite-plugin-windmill

1.691.0 verified Mon Apr 27 auth: no javascript

Vite plugin and deploy tooling for Windmill raw apps. Current stable version is 1.691.0, tracking Windmill minor releases. Provides Vite integration for developing and deploying Windmill raw apps with features like automatic path inference from `.raw_app` directories, virtual `wmill` runtime injection, authenticated `/api` proxying, and optional post-build deployment. Released in sync with Windmill minor versions; each major Windmill release gets a corresponding package version line (e.g., 1.691.x). Key differentiators: seamless Vite integration, automatic base path and proxy configuration, and direct deploy capabilities. Requires Node.js 22+ and Vite ^8.0.8.

Common errors

error Error: Cannot find module 'vite-plugin-windmill' ↓

cause Package not installed or not in node_modules.

fix

Run pnpm add -D vite-plugin-windmill (or npm/bun equivalent).

error TypeError: windmill is not a function ↓

cause Using named import instead of default import.

fix

Change import { windmill } from 'vite-plugin-windmill' to import windmill from 'vite-plugin-windmill'.

error Error: Cannot read properties of undefined (reading 'raw_app') ↓

cause Plugin cannot find a `.raw_app` or `__raw_app` directory.

fix

Ensure your project has a directory like app.raw_app/ containing raw_app.yaml.

Warnings

breaking Requires Node.js >=22.0.0. Older Node versions will fail to install or run. ↓

fix Upgrade Node.js to version 22 or later.

breaking Requires Vite ^8.0.8 as a peer dependency. Older Vite versions (6.x, 7.x) are incompatible. ↓

fix Update Vite to version 8.0.8 or newer.

deprecated NPM dist-tags like 'windmill-1.686' may not be published for all historical versions. Pin to exact version instead. ↓

fix Use exact version pinning, e.g., 'vite-plugin-windmill@1.684.0'.

gotcha The `windmill` function is a default export. Attempting named import { windmill } will result in undefined. ↓

fix Use `import windmill from 'vite-plugin-windmill'` (without curly braces).

gotcha The plugin expects the project to contain a `.raw_app` or `__raw_app` directory. Without it, the plugin will throw or behave unexpectedly. ↓

fix Create a directory named `<name>.raw_app` or `<name>__raw_app` with a raw_app.yaml file inside.

gotcha Environment variables `BASE_INTERNAL_URL` and `BASE_URL` are fallbacks for the Windmill base URL. If both are unset and url option is not provided, proxying and deploy may fail. ↓

fix Set `url` option or `BASE_INTERNAL_URL`/`BASE_URL` environment variables.

Install

npm install vite-plugin-windmill

yarn add vite-plugin-windmill

pnpm add vite-plugin-windmill

Imports

windmill

wrong

import { windmill } from 'vite-plugin-windmill'

correct

import windmill from 'vite-plugin-windmill'

Default export only; named import will fail

WindmillOptions

wrong

import { WindmillOptions } from 'vite-plugin-windmill'

correct

import type { WindmillOptions } from 'vite-plugin-windmill'

TypeScript type import for option types

defineConfig

wrong

import { defineConfig } from 'vite-plugin-windmill'

correct

import { defineConfig } from 'vite'

defineConfig comes from vite package, not the plugin

Quickstart

Basic Vite configuration using vite-plugin-windmill with raw app entry point and project structure example.

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

export default defineConfig({
  plugins: [
    windmill({
      entry: 'src/main.tsx',
    }),
  ],
});

// Expected project structure:
// f/example/app.raw_app/
//   raw_app.yaml
//   index.tsx
//   backend/
//     hello.py
//     hello.yaml
//
// Environment variables (optional):
// WM_WORKSPACE, WM_TOKEN, BASE_INTERNAL_URL, BASE_URL, WM_DEPLOY