wpluut/oc-vite-plugin

Vite integration for October CMS

Vite ⚡integration for October CMS

This plugin provides simple integration of Vite for October CMS (Versions 3+).

Setup

Install the plugin using composer

composer require offline/oc-vite-plugin

For the Vite integration to work, you first need to set the VITE_MANIFEST env variable to the path of the manifest file generated by Vite.

# /themes/your-theme/assets/build/manifest.json
VITE_MANIFEST=assets/build/manifest.json

Then make sure to place the {% styles %} and {% scripts %} tags in your layout, so assets are included correctly.

Configuring Vite

Install Vite via npm in your theme.

npm install --dev vite@latest
# or
yarn add -D vite@latest

You can adapt the following Vite configuration to bundle your theme assets:

// themes/your-theme/vite.config.ts
import { defineConfig } from 'vite'
import { resolve, basename } from 'path'

// Your JS/TS/CSS entrypoints.
const input = {
    main: resolve(__dirname, 'resources/ts/main.ts'),
    css: resolve(__dirname, 'resources/scss/main.scss'),
}

// Auto detect the theme name, works only if one theme is available.
// const themeName = __dirname.match(/themes\/([^\/]+)/)[1];
const themeName = 'your-theme'

export default defineConfig({
    // Included assets will use this path as the base URL.
    base: `/themes/${themeName}/assets/build/`,
    build: {
        rollupOptions: { input },
        manifest: true,
        emptyOutDir: true,
        // Output assets to /themes/your-theme/assets/build
        outDir: resolve(__dirname, 'assets/build'),
    },
    server: {
        hmr: {
            // Do not use encrypted connections for the HMR websocket.
            protocol: 'ws',
        },
    }
})

Workflow

• To use Vite in development, start the Vite server using the vite command
• To build assets for production, use the vite build command

Including Vite Assets

Use the vite() function anywhere in Twig to include assets from the Vite Dev Server or the Vite manifest.json (depending on the environment).

You must provide an array of files to include as the first argument. All paths are relative to the theme directory.

{# includes /themes/your-theme/resources/ts/main.ts #}
{{ vite([ 'resources/ts/main.ts' ]) }}

{# or using the object syntax: #}
{{ vite([ { path: 'resources/ts/main.ts' }, { path: 'resources/scss/main.scss' } ]) }}

{# force a script/link tag if the asset has no extension:  #}
{{ vite([ { path: '@some-special-vendor-asset', ext: 'js' }, { path: '@has-no-extension', ext: 'css' } ]) }}

By default, the vite() function will output the required assets to your markup directly.

Using October's asset pipeline

If you want to push assets to October's asset pipeline instead, you can set the render parameter to false. No output will be generated where the vite() function was called in this case.

{{ vite([ { path: 'resources/ts/main.ts', render: false } ]) }}

Remember to place the {% styles %} and {% scripts %} tags in your layout, for this to work.

Passing in additional attributes

Any additional attributes will be passed to the generated HTML tag.

{{ vite([ { path: 'resources/ts/main.ts', defer: true ]) }}

Including assets from PHP code

You can use a special vite: token to include files in PHP:

$this->controller->addJs('vite:resources/ts/main.ts');

The asset will now be included using October's asset pipeline and output wherever you have placed the {% scripts %} and {% styles %} tag.

Environments

Dev

By default, local and dev are regarded as dev environments. If your app environment is a dev environment, the Vite Dev Server will automatically be included for you.

You can use the following .env variables to configure how the Vite Dev Server is included:

# These are the defaults:
VITE_MANIFEST_FILENAME=manifest.json
VITE_DEV_ENVS=dev,local
VITE_HOST=http://localhost:5173

Production

If your app is configured to be run in a production environment, the plugin will automatically use the Vite manifest to include assets.