Piral CLI Vite

1.4.0 verified Mon Apr 27 auth: no javascript

Plugin for Piral CLI that enables using Vite as the bundler for Piral instances and pilets. Current stable version is 1.4.0, released with provenance support. Releases are frequent with bug fixes and feature additions. Key differentiator: batteries-included approach with built-in vite-plugin-codegen and vite-plugin-environment, no need to install Vite separately. Handles assets, stylesheets (CSS, SASS), and TypeScript out of the box. Supports custom Vite config via vite.config.js/ts.

Common errors

error Error: Cannot find module 'piral-cli-vite' ↓

cause Plugin not installed or not in node_modules.

fix

Run: npm install piral-cli-vite --save-dev

error TypeError: piral_cli_vite_1.default is not a function ↓

cause Using CommonJS require with an ESM-only plugin (v1.2.0+).

fix

Use ES module import syntax, or downgrade to v1.1.1.

error Error: The 'vite' package is not installed or configuration is invalid. ↓

cause Missing Vite dependency; plugin expects vite to be available but it bundles its own internally.

fix

Ensure you have installed piral-cli-vite correctly; it includes Vite internally. If you have a global Vite, remove it or align versions.

Warnings

breaking Since v1.2.0, the plugin is ESM-only. Using require() will fail with an error. ↓

fix Use import syntax or switch to CommonJS-compatible version ≤1.1.1.

deprecated v1.0.x versions are deprecated; upgrade to at least v1.1.0 for pilet schema v3 support and standard vite.config.js support. ↓

fix Update to latest version: npm install piral-cli-vite@latest

gotcha The plugin automatically sets the source folder (e.g., /src) as root. If you have a public folder, use src/public, not /public. Customize via vite.config.js publicDir. ↓

fix Either place your public assets in src/public or set a custom publicDir in vite.config.js.

gotcha Scripts with type=module in index.html are treated as entry points by Vite. The plugin patches index.html to avoid breaking, but explicit non-bundled scripts need attributes like async/defer/blocking. ↓

fix Add async, defer, or blocking attribute to scripts that should not be bundled.

gotcha If a vite.config.js exists in the execution root, it will be used. Double usage was fixed in v1.0.2, but ensure you don't have conflicting configs. ↓

fix Remove or rename extra vite.config.js files; the plugin will pick up the one in the root.

Install

npm install piral-cli-vite

yarn add piral-cli-vite

pnpm add piral-cli-vite

Imports

default
wrong
```
const piralCliVite = require('piral-cli-vite')
```
correct
```
import piralCliVite from 'piral-cli-vite'
```
Plugin is ESM-only since v1.2.0; CommonJS require not supported for the main import.
PiralCliVitePlugin
wrong
```
import { PiralCliVitePlugin } from 'piral-cli-vite/lib/index'
```
correct
```
import { PiralCliVitePlugin } from 'piral-cli-vite'
```
Named export for the plugin class or function. Path imports like '/lib/index' are incorrect.

createViteConfig

wrong

import createViteConfig from 'piral-cli-vite'

correct

import { createViteConfig } from 'piral-cli-vite'

createViteConfig is a named export, not default.

Quickstart

Shows installation and usage of piral-cli-vite as a Piral CLI plugin: install, then use standard piral/pilet commands. Optionally add custom Vite config.

// Install: npm i piral-cli-vite --save-dev

// No code needed in your project; standard Piral commands will leverage Vite automatically.
// Example: build a Piral instance
// piral build

// Example: debug a pilet
// pilet debug

// For custom Vite config, create vite.config.js:
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    // your custom plugins here
  ],
});