Dev Blog:Modern front-end development in OpenCms with Vite

Date:
October 29, 2025
Developing front-end layouts with the Mercury Template is now faster and more dynamic than ever. With the integration of Vite, front-end changes can be previewed instantly, streamlining workflows and making rapid iteration effortless.
Vite development with OpenCms

Vite brings a modern, efficient development experience to OpenCms. Updates appear in real time for (S)CSS and JavaScript, reducing complexity and keeping the creative flow uninterrupted. With its lightweight setup and powerful live-reload capabilities, Vite redefines how front-end work is done in OpenCms. The result: less waiting, more creativity, and a more efficient way to customize the Mercury Template.

In the following article, we’ll walk through how to set up OpenCms and the Mercury Template for development with Vite. You’ll learn how to configure your project, connect it to the OpenCms workspace, and begin developing with instant feedback and modern front-end tooling. Once configured, you can enjoy a smooth, modern workflow that combines the power of OpenCms with the speed of today’s front-end ecosystem.

What is Vite?

Vite is a modern front-end build tool and development server designed to make web development faster and more efficient. Vite takes advantage of native ES modules in the browser to serve source files directly during development.

This means that changes are reflected in real time through Hot Module Replacement (HMR) without a full page reload. For more information about Vite, please visit the project website.

https://vite.dev/

Prepare your environment for using Vite

Checkout the Mercury Vite demo project

The Mercury Vite repository can be downloaded or checked out from GitHub. In order to use Vite for local development, you have to checkout the repositoryt to your local file system. To do so, open a terminal window and change to your development folder where the Mercury Vite demo project should be checked out to. Clone the repository by using the following command:

git clone https://github.com/alkacon/mercury-vite-work.git

This checks out the master branch of the Mercury Vite demo project. After that, switch to the project folder by typing:

cd mercury-vite-work

If you want to start developing in your own branch like "myproject" starting from a specific tag version, e.g. Mercury version 20, enter the following command:

git checkout -b myproject tags/build_20_0_0

This creates a new working branch named "myproject". You have now checked out the Mercury Vite demo project and can start setting up your environment.

Install project dependencies

In order to be able to start the Vite proxy for the Mercury Vite demo, you have to install all necessary project dependencies. NPM (Node Package Manager) already has to be installed on your development system.

Use again a terminal window and navigate to your Mercury Vite demo project folder ("mercury-vite-work"). Enter the following command:

npm install

This installs the project dependencies specified in the package.json file and may take a while. Before continuing, please ensure that there are no errors thrown during the installation.

Import the Vite demo page in OpenCms

For this dev blog, a demo page to work with has to be imported to your development OpenCms system. Please follow this instruction to import the page properly:

  • Login to OpenCms as user with "Root administrator" role, e.g. "Admin".
  • Switch to the "Mercury Default Demo" site.
  • Change to the Launchpad and click on "Database". In the overlay, select "Import (HTTP)".
  • Click the "Choose file" button and find the file "mercury-vite-demopage.zip" in the "resources" folder of your Mercury Vite demo project.
  • Click "OK" to start the import.

After the import, switch to the Page editor in the Mercury default demo. There should be a new main navigation entry named "Vite". Click on it and preview the page.

Conventional workflow with custom CSS and JavaScript

To enable customization for pages with the Mercury template, a sitemap attribute has to be added to the site or subsite configuration file located in ".content/.config". The attribute key is "template.allow.mods" with the value "true". After that modification custom files placed in the subsite folder will be additionally loaded by the Mercury template.

The Vite demo page uses a custom CSS and JavaScript. Both files are placed directly in the "mercury-vite/" folder in OpenCms, named "custom.css" and "custom.js". They can be used to enhance the pages of the subsite.

To work on the files, you have to follow these steps:

  • Switch to the Explorer view in OpenCms and locate the folder "mercury-vite/".
  • Edit the files by using the built in source code editor of OpenCms.
  • After saving the changes, switch back to the page editor and check your changes in the preview.

With Vite configured as shown below, the workflow will be much simpler and faster. 

Configure the Vite environment (TODO)

Vite needs some information about the environment and the OpenCms site to work with. This configuration is provided by the configuration file "vite.env.js" in the Mercury Vite demo project.

 

Conventional deployment (TODO)

Note: in this blog, we will work with the standard Mercury theme CSS ("template-src/scss/themes/theme-standard.scss") that is used by the Mercury default demo site pages.

After installing the necessary dependencies, your system is ready to launch the conventional building process by using

npm run css

to trigger the build after each change to the SCSS files. This generates the minified theme CSS "theme-standard.min.css" including its corresponding source map and stores it in the folder build/npm/3_minified/ below your "mercury-template" project folder.

In the next step, these changed files have to be uploaded to the virtual file system of your OpenCms development server. Login as a user with "Root administrator" role (e.g. "Admin"), change to the root site  and navigate to the folder /system/modules/alkacon.mercury.theme/css/ in the Explorer view. Upload the files "theme-standard.min.css" and "theme-standard.min.css.map", overwrite the existing ones.

After that, you can switch to the Mercury default demo site and preview eventual changes to the CSS.

With Vite configured as shown below, long waiting times for the build, upload and manual reload of the preview page in the browser will not be needed any more. 

Create a local Vite environment config file (TODO)

In the Mercury template project folder ("mercury-template"), create a new file with the exact file name "vite.env.js". This file is needed to configure the local environment for Vite. Paste the following contents in the new file:


let server = 'https://ocms-workplace-server-url';
let site = '/sites/default/';
let workspace = '/path/to/workspace/folder';
let secret = 'mysecret';

module.exports = {
    OPENCMS_SERVER: server,
    OPENCMS_SITE: site,
    OPENCMS_WORKSPACE: workspace,
    OPENCMS_VITE_PREFIX: ['/template-src/', '/node_modules/'],
    OPENCMS_VITE_SECRET: secret,
    OPENCMS_VITE_REPLACE_CUSTOM: true,
    OPENCMS_MERCURY_SCSS: '/scss/themes/'
};

You have to adjust the values of the variables in the first 4 lines of the configuration to match to your development environment:

  • server: Enter here the URL to your OpenCms workplace server, e.g. "http://localhost:8080".
  • site: The root path of the OpenCms site to work with has to be entered here, e.g. "/sites/default/" for the Mercury default demo site.
  • workspace: Specify the absolute path to the workplace folder containing the "mercury-template" project folder, without trailing "/".
  • secret: The string entered here is used to prevent misuse and ensures that only an OpenCms user that has exactly the same secret string configured is able to use Vite for development. This configuration is done in the next step.

Set the Vite secret for an OpenCms user

Vite-Secret additional info

To be able to use the Vite environment with a specific OpenCms user, this user has to provide the same secret String that is configured in the environment config file. To do so, you have to login to OpenCms as a user with "Root administrator" role, e.g. "Admin".

  • Switch to the Launchpad and click on "Accounts".
  • Click "Users" and locate the user you want to be able to work with Vite.
  • Right click on the user name to open the context menu and select "Additional infos".
  • In the dialog, either click the "Add" button or the "+" icon on the right side of an existing editable addional user info while hovering the "target" icon.
  • In the new line, enter "Vite-Secret" as the key for the new entry and your secret string from the configuration file as value.
  • Click "OK" to save the changes.

Working with Vite

Launch the Vite proxy

Vite proxy output

In your terminal window, launch the Vite proxy in your "mercury-template" project folder using the following command:

npm run vite-proxy

You should see an output containing your environment information and the server URL of the Vite proxy, usually "http://localhost:8099".

Login to OpenCms and work with Vite

Vite development mode overlay for CSS

Point your browser to the URL of the Vite proxy, followed by the OpenCms login path, usually "http://localhost:8099/system/login". Login to OpenCms with the user that has the Vite secret configured and switch to the site you configured in the Vite environment configuration.

Open a page in the page editor. The "User info" icon in the top right corner should now have a yellow overlay that provides additional information when hovering it. This indicates that the Vite development mode is currently active for this page.

Check if the Vite development works

Style preview with Vite

If you followed the instructions and configured the Mercury default demo as Vite site, you can now edit the file "template-src/scss/themes/theme-standard.scss" to check if Vite works correctly.

  • Find the line "$main-theme: #b31b34 !default; // dark red".
  • Change the color value "#b31b34" to another value, e.g. "#900090" (purple). 
  • Save your changes.

The page preview should be rendered using the changed main theme color, e.g. in the main navigation, the link text colors or button backgrounds. Now you are ready to develop your custom styles for Mercury.

Please note: after finishing development, you still have to recompile the minified CSS files with the command

npm run css

and upload the updated files to OpenCms as described above in order to deploy your changes permanently to Mercury on your OpeCms development server.

Conclusion

Congratulations, you can now use Vite to develop CSS for Mercury.

The next step is to create your own theme CSS for Mercury that you can use for your website layout. The necessary steps will be described in a dev blog coming next month.