atwx/silverstripe-vitehelper

A helper to use vitejs with silverstripe cms

v1.3 2025-09-25 13:09 UTC

Requires

• silverstripe/framework: ^6
• silverstripe/htmleditor-tinymce: ^1

BSD-3-Clause

• cms
• silverstripe

README

This module helps you to use vite in your Silverstripe project. When you have a normal vite build, you have hashed filenames. This module helps you to get the correct file names from the manifest.json.

Installation

composer require atwx/silverstripe-vitehelper

Usage

In your template, you can use the following code

    $ViteClient.RAW
    <link rel="stylesheet" href="$Vite("app/client/src/scss/main.scss")">
    <script type="module" src="$Vite("app/client/src/js/main.js")"></script>

The $ViteClient.RAW will load the vite client. This is needed for the dev server. The $Vite will get the correct file name for the given input file from the manifest.json.

Configuration

You can configure the location of the build files in your mysite.yml:

Atwx\ViteHelper\Helper\ViteHelper:
    manifest_path: "/app/client/dist/.vite/manifest.json"  # default
    output_url: "/app/client/dist/"  # default

The manifest_path is the path to the manifest file generated by vite. The output_url is the url to the output folder. It will be prepended with the resources folder name, normally _resources.

Dev Mode

To use vite in dev mode, you need to add the dev server url to your .env:

VITE_DEV_SERVER_URL=http://localhost:3000

Editor CSS

As the build files have hashes, the module needs to get the correct file name for the editor css.

You can use the following in your mysite.yml to get the correct file name:

Atwx\ViteHelper\Helper\ViteHelper:
    editor_css: 'app/client/src/scss/editor.scss'

Vite Config

Our default config for vite defines:

• the input files:
  • main.js: The entry point for main js
  • main.scss: The entry point for main css
  • editor.scss: The entry point for editor css, which will be loaded in the cms
• the development server

Important is the base option. If you don't set this, the default is / which will likely not work.

import {defineConfig} from 'vite'

// https://vitejs.dev/config/
export default defineConfig(({command}) => {
    return {
        server: {
            host: '0.0.0.0',
            port: 3000,
        },
        alias: {
            alias: [{find: '@', replacement: './app/client/src'}],
        },
        base: './',
        build: {
            outDir: './app/client/dist',
            manifest: true,
            sourcemap: true,
            rollupOptions: {
                input: {
                    'main.js': './app/client/src/js/main.js',
                    'main.scss': './app/client/src/scss/main.scss',
                    'editor.scss': './app/client/src/scss/editor.scss',
                },
            },
        },
        plugins: []
    }
})

Working With Themes

See Config Templates for an example that works with themes and has also TailwindCSS configured.

You need to tell vite where your theme is located, e.g. in your app/_config/themes.yml:

Atwx\ViteHelper\Helper\ViteHelper:
  manifest_path: "/themes/<mytheme>/dist/.vite/manifest.json"
  output_url: "/themes/<mytheme>/dist/"
  editor_css: 'src/css/editor.css'

In your theme you can include Vite like:

    $ViteClient.RAW
    <link rel="stylesheet" href="$Vite("src/css/app.css")">
    <script type="module" src="$Vite("src/javascript/index.js")"></script>

Note: The paths need to match the rollupOptions in your vite.config.js.

Developing With DDEV

If you have ddev running, please export the relevant ports in your .ddev/config.yml:

web_extra_exposed_ports:
    - name: vite
      container_port: 5173
      http_port: 5172
      https_port: 5173

Thanks to

This module is inspired by https://github.com/brandcom/silverstripe-vite