Vite UXP Plugin

1.2.5 verified Mon Apr 27 auth: no javascript

A Vite plugin for building Adobe UXP plugin panels. Version 1.2.5 is current. Provides seamless integration between Vite's fast development server and Adobe's UXP environment, enabling hot reload, CSS injection, and TypeScript support for UXP panels. Automatically handles UXP-specific module bundling and polyfills. Key differentiator: replaces the slow UXP Developer Tool workflow with Vite's instant HMR, making UXP panel development modern and efficient.

Common errors

error Error: [vite-uxp-plugin] Manifest version must be a number and >= 3 ↓

cause manifestVersion option is missing or invalid.

fix

Add manifestVersion: 4 to plugin options in vite.config.ts.

error ReferenceError: module is not defined ↓

cause Node.js module.exports used in browser context; UXP plugins run in a Chromium-based environment.

fix

Use ES module syntax (import/export) instead of CommonJS (require/module.exports).

error [vite-uxp-plugin] Failed to watch file changes: Error: EPERM: operation not permitted ↓

cause File system permissions issue on Windows when saving files.

fix

Run terminal as Administrator or move project to a directory without restricted permissions (e.g., C:\Users\<name>\Projects).

error TypeError: Cannot read properties of undefined (reading 'main') ↓

cause Manifest object does not have a 'main' property or is undefined.

fix

Ensure manifest.main is defined (e.g., 'index.html').

Warnings

gotcha Manifest version must be 4 for UXP v7+; using manifestVersion: 3 breaks on newer UXP runtimes. ↓

fix Set manifestVersion: 4 in plugin options.

breaking v1.x drop support for UXP v6; plugin only works with UXP v7+. ↓

fix Upgrade UXP Developer Tool to version 7+ or stay on v0.x.

deprecated The `watch` option is deprecated; use `reload` instead. ↓

fix Replace `watch: true` with `reload: true`.

gotcha CSS hot reload works only if styles are imported as JavaScript modules (e.g., import './style.css'). ↓

fix Ensure CSS is imported via import statement, not via <link> tag.

gotcha Plugin may fail to load if vite.config.ts has `build.lib` enabled; library mode is not supported. ↓

fix Remove `build.lib` config or use separate Vite configs for library and plugin.

Install

npm install vite-uxp-plugin

yarn add vite-uxp-plugin

pnpm add vite-uxp-plugin

Imports

viteUxpPlugin

wrong

const viteUxpPlugin = require('vite-uxp-plugin')

correct

import { viteUxpPlugin } from 'vite-uxp-plugin'

ESM-only package; named export.

uxp

wrong

import uxp from 'vite-uxp-plugin'

correct

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

Named export for the UXP plugin instance.

PluginConfig

wrong

import { PluginConfig } from 'vite-uxp-plugin'

correct

import type { PluginConfig } from 'vite-uxp-plugin'

TypeScript type, use `import type` for correct type-only import.

Quickstart

Configures Vite with the UXP plugin, specifying the manifest and enabling hot reload during development.

// vite.config.ts
import { defineConfig } from 'vite';
import { viteUxpPlugin } from 'vite-uxp-plugin';

export default defineConfig({
  plugins: [
    viteUxpPlugin({
      manifest: {
        id: 'com.example.plugin',
        name: 'My Plugin',
        version: '1.0.0',
        main: 'index.html',
        manifestVersion: 4
      },
      reload: true
    })
  ]
});