Getting Started

Vernok.Vite provides modern Vite integration for October CMS themes and plugins.

It works together with the @vernok/vite-plugin-october npm package. The npm package handles Vite configuration, entrypoint discovery and build output, while Vernok.Vite handles asset resolution and rendering inside October CMS.

Development servers are detected automatically. In production, assets are resolved from the generated Vite manifest.

Requirements

• October CMS 4.x
• PHP 8.3+
• Node.js 24.11.1+
• Vite 8.x

Installation

Install Vernok.Vite through the October CMS Marketplace or CLI:

php artisan plugin:install Vernok.Vite

Then install the Vite package inside each theme or plugin that owns frontend assets:

npm install --save-dev @vernok/vite-plugin-october vite

Add the standard Vite scripts to package.json:

{
    "scripts": {
        "dev": "vite",
        "build": "vite build"
    }
}

Theme Setup

Create vite.config.ts in the root of your theme:

import { defineThemeConfig } from '@vernok/vite-plugin-october';

export default defineThemeConfig();

Create the main theme entrypoint:

resources/entrypoint.ts

Additional page-specific or feature-specific bundles can be created as modules:

resources/modules/<name>/entrypoint.ts

Entrypoints are discovered automatically.

Plugin Setup

Create vite.config.ts in the root of your plugin:

import { definePluginConfig } from '@vernok/vite-plugin-october';

export default definePluginConfig();

Plugin entrypoints are automatically discovered from:

resources/modules/<name>/entrypoint.ts
resources/formwidgets/<name>/entrypoint.ts

No Rollup input configuration is required.

Loading Assets from PHP

Vernok.Vite integrates with October's existing asset API using the vite: protocol:

$this->addJs('vite:resources/modules/checkout/entrypoint.ts');

For example, a FormWidget can load its own Vite entrypoint:

public function loadAssets()
{
    $this->addJs(
        'vite:resources/formwidgets/my-widget/entrypoint.ts'
    );
}

Vernok.Vite automatically determines the owning plugin from the calling context.

The same source path is used in both development and production. There is no need to reference development server URLs or hashed production filenames manually.

Loading Assets from Twig

Theme entrypoints can be rendered directly from Twig:

{{ vite_styles(['resources/entrypoint.ts']) }}
{{ vite_scripts(['resources/entrypoint.ts']) }}

Explicit plugin or theme scopes are also available for advanced scenarios.

Development

Start Vite from your theme or plugin directory:

npm run dev

That's it.

The active Vite development server is discovered automatically and its development state is made available to Vernok.Vite.

October CMS will then serve the entrypoint from the correct Vite development server.

Each theme and plugin maintains its own development state. This allows multiple Vite-powered plugins and a theme to run independent development servers simultaneously within the same October CMS installation.

For example:

themes/acme/                 → Vite :5173
plugins/acme/shop/           → Vite :5174
plugins/acme/dashboard/      → Vite :5175

Each source is resolved independently.

For Docker, virtual machines or custom networking environments where the automatically detected origin is not suitable, an explicit development origin can be configured. See the npm package documentation for advanced development configuration.

Production

Build the assets from your theme or plugin directory:

npm run build

The Vite package generates hashed production assets under:

assets/

and creates the Vite manifest at:

assets/.vite/manifest.json

Vernok.Vite automatically reads the manifest and resolves the correct JavaScript, CSS and shared imports.

Application code continues to reference the original source entrypoint:

$this->addJs('vite:resources/modules/checkout/entrypoint.ts');

Vernok.Vite handles the environment automatically:

Development
source entrypoint
      ↓
Vite development server

Production
source entrypoint
      ↓
Vite manifest
      ↓
hashed production assets

Multiple Themes and Plugins

Vernok.Vite is designed around independent asset sources.

A theme, plugin or reusable package can own its frontend build without depending on an application-wide Vite configuration.

Each source can have its own:

• Vite configuration
• Entrypoints
• Development server
• Development state
• Production assets
• Vite manifest

This makes Vernok.Vite particularly suitable for modular October CMS projects and reusable plugins.

Plugin Dependencies

October CMS plugins that use Vernok.Vite should declare it as a dependency in plugin.yaml:

require:
    - Vernok.Vite

Themes can declare the same dependency in theme.yaml.

Full Documentation

For the complete PHP integration documentation, including asset resolution, PHP and Twig APIs, explicit scopes, environment configuration and troubleshooting:

https://github.com/hello-vernok/oc-vite-plugin

For Vite configuration, entrypoint discovery, build output, asset handling and advanced development configuration:

https://github.com/hello-vernok/vite-plugin-october