Download the PHP package vernok/vite-plugin without Composer

Vernok.Vite

PHP asset resolver for October CMS themes and plugins. Built for agencies and developers who ship production October CMS projects and need predictable Vite integration on the server — dev-server URLs during local development, manifest-driven hashed assets in production.

This plugin reads .vite-dev.json and assets/.vite/manifest.json, then exposes Twig functions, global helpers, traits, and the vite: asset protocol for addJs / addCss.

Companion package (Node/Vite): @vernok/vite-plugin-october — install this in each theme or plugin repository for Vite config, entry autodiscovery, build output, and .vite-dev.json during local development. Vernok.Vite (this plugin) handles the PHP side only.

Table of contents

• Overview
• Requirements
• Installation
• Configuration
• Quick start
• Registering assets with addJs and addCss
• Twig and PHP helpers
• Scope resolution
• Development vs production
• Docker and multi-owner setups
• Testing
• Troubleshooting
• Known limitations
• Related packages

Overview

October CMS frontend assets are split across two packages:

Agencies benefit from shared conventions — the same folder layout, manifest location, and cache-busting behaviour in every client repository. Developers reference source entry paths (for example resources/modules/blog/entrypoint.ts) from Twig or PHP; the resolver maps those paths to dev-server URLs or hashed production files. You never hard-code manifest hashes in templates or PHP.

• Development: run npm run dev in the plugin or theme directory. The npm package writes .vite-dev.json. Vernok.Vite reads origin and emits module scripts (including @vite/client once per origin per request).
• Production: run npm run build. Output lands under assets/ with assets/.vite/manifest.json. Vernok.Vite resolves hashed filenames, shared chunks (imports), and CSS linked to each entry.

Node / Vite setup: this README covers PHP only. For vite.config.ts, entry discovery, folder layout, Docker hostUrl, and build output paths, see the @vernok/vite-plugin-october documentation on npm.

Agency checklist

Before shipping a theme or plugin with Vite assets:

1. October CMS app — composer require vernok/vite-plugin:^0.0.5 (Packagist) or php artisan plugin:install Vernok.Vite
2. Your plugin/theme — require: [Vernok.Vite] in plugin.yaml or theme.yaml
3. Asset repo — npm i -D @vernok/vite-plugin-october vite and a vite.config.ts using definePluginConfig() or defineThemeConfig()
4. Local dev — npm run dev from the theme/plugin directory (not the October root)
5. Deploy — npm run build so assets/.vite/manifest.json exists; add .vite-dev.json to .gitignore

Requirements

Each theme or plugin with frontend assets needs its own package.json, vite.config.ts (or .js), and npm run dev / npm run build scripts. Run those commands from the theme or plugin directory — not from the October project root.

Installation

October CMS application

Via Composer (Packagist):

Via October CLI or marketplace:

Declaring Vernok.Vite as a dependency

Plugin — plugin.yaml:

Plugin — composer.json (Composer-distributed plugins only):

Theme — theme.yaml:

If the plugin or theme lives only under plugins/ or themes/ in a project repo, plugin.yaml or theme.yaml is sufficient. Add the Composer entry when you publish through Packagist or a private registry.

Plugin or theme repository (Node)

Use definePluginConfig() or defineThemeConfig() in vite.config.ts. Full setup, entry discovery rules, and output paths: @vernok/vite-plugin-october on npm.

Entry paths (what to pass to Twig / vite:)

Pass the source path as discovered by the npm package — the same string appears as a key in assets/.vite/manifest.json:

If a path 404s or the manifest reports "entry not found", open assets/.vite/manifest.json and copy the key exactly. Details on which folders are autodiscovered: npm package docs.

Configuration

Config file: plugins/vernok/vite/config/vite.php
October key prefix: vernok.vite::vite

The dev-server origin is not configured in this plugin — it comes from .vite-dev.json (written by the npm package). For Docker, set hostUrl in the Vite project; see Docker and multi-owner setups.

Quick start

1. Build assets in the theme or plugin repo:

2. Theme layout (Twig):

3. PHP (recommended) — components, controllers, FormWidgets:

For TypeScript entrypoints that import SCSS, addJs() alone is sufficient — linked CSS from the manifest or dev-server module graph is emitted automatically. Use addCss('vite:…scss') only for dedicated stylesheet entrypoints not imported via JS.

Entry paths match the source paths under resources/ in your repository (as registered in the manifest), not hashed output filenames.

Components in theme partials

CMS components declared in a partial's front matter ([myComponent] in the INI section) run onRun() when the partial renders. Vite scope is registered automatically from the component namespace via component.run — no explicit vite:plugin:… token required.

Place {% partial %} before {% scripts %} in your layout or page. CSS from partial-only components cannot appear in <head> {% styles %} because October renders the head before body partials; Vernok.Vite appends pending vite-CSS when {% scripts %} runs.

The {% component %} tag is only required when you want the component's default markup — asset registration via onRun() works from the INI alias alone.

Registering assets with addJs and addCss

The vite: prefix is the recommended way to load Vite bundles from PHP. Use it anywhere October's addJs() and addCss() are available — no trait, no vite_assets() loop, and no knowledge of manifest hashes or dev-server URLs.

TypeScript module entrypoints:

Dedicated SCSS entrypoint (not imported via JS):

Do not register the same .ts entrypoint with both addJs and addCss — addJs is enough for bundled CSS.

Works on the frontend ({% scripts %} / {% styles %}) and in the backend layout <head>.

Where agencies use this

Scope is inferred from the calling class namespace (plugin code from Vendor\Plugin\...). FormWidgets and backend widgets resolve to their owning plugin automatically.

Explicit scope in the token

Use when autodetection is ambiguous — shared partials, loading a theme bundle from a plugin, or cross-plugin references:

CSS behaviour

• Development: CSS imported by a JS entry loads through the Vite module graph. addJs('vite:…entrypoint.ts') is sufficient for typical module bundles.
• Production: CSS arrays on the manifest entry (and shared chunks via imports) are emitted as <link> tags automatically.
• Partial components: vite-CSS queued from addCss() in a partial is appended at {% scripts %} when it could not be drained at {% styles %}.

Alternatives

Under the hood, vite: tokens are intercepted via system.assets.beforeAddAsset, then resolved on cms.assets.render (frontend) or backend.layout.extendHead (backend).

Twig and PHP helpers

Twig functions

Theme — site bundle:

Plugin — module entrypoint:

Global PHP helpers

HasViteAssets trait (optional)

Event listeners

Prefer vite: on the controller when possible:

Or wrap the host with Vernok\Vite\Classes\Assets\ViteAssetHostAdapter and call enqueue() for scope inference from the host class.

Scope resolution

ViteScopeResolver determines theme vs plugin and the Vendor.Plugin code:

1. Explicit $scope and/or plugin code from the caller (Twig, helper, or vite:plugin:… token)
2. Namespace of the calling class (components, controllers, widgets)
3. Theme heuristics (resources/entrypoint.ts, resources/images/*, resources/fonts/*)
4. Call stack path (Twig partials under themes/ or plugins/)
5. Default: theme

When in doubt — especially in shared Twig partials — pass scope and plugin code explicitly.

Development vs production

Example .vite-dev.json (written while npm run dev runs):

Invalid or incomplete JSON (missing origin) falls back to build mode.

Manifest locations

Manifest keys are source paths (e.g. resources/entrypoint.ts). Values include file, optional css, and imports for shared chunks.

Add .vite-dev.json to .gitignore in each theme/plugin repo. Whether you commit built assets/ depends on your deployment workflow.

Docker and multi-owner setups

Multiple Vite dev servers: each theme or plugin with its own vite.config.ts writes its own .vite-dev.json and origin. A theme on port 5173 and a plugin on 5174 work simultaneously — pass the correct scope when registering entries.

PHP in Docker, Vite on the host — configure in the Vite project (not in Vernok.Vite):

The npm package writes that origin to .vite-dev.json; Vernok.Vite reads it automatically.

Testing

From the October CMS project root:

From this plugin directory:

Troubleshooting

Enable debug logging:

Inspect storage/logs for [Vernok.Vite] entries.

Known limitations

• Manifest path is fixed to assets/.vite/manifest.json per theme or plugin.
• A stale .vite-dev.json after a crashed dev server keeps dev mode active until removed.
• vite_asset() resolves only paths known to the manifest (or dev URLs for tracked source paths).
• The vite: protocol hooks October's AssetMaker pipeline only — assets registered outside addJs / addCss are not intercepted.

License

MIT — see LICENSE.

Related packages

Typical workflow: @vernok/vite-plugin-october in each asset repository + Vernok.Vite in the October project. Read both READMEs — Node setup on npm, PHP integration here.