Integrating Java Velocity Templates into Vue Projects with Local Rendering and Mock Data Support

Recent development needs required the use of Java Velocity templates in a Vue project, but the existing Vue setup could not compile or run Velocity locally, forcing developers to deploy before seeing results and incurring high configuration costs.

Here, "Velocity" refers to Java Velocity; the article assumes readers are already familiar with its basics and provides no introductory explanation.

The industry has moved toward front‑end/back‑end separation using frameworks like Vue and React, yet legacy systems built with Velocity pose maintenance challenges: front‑end developers must learn Java, Maven, and outdated MVC frameworks, while backend teams face costly refactoring and long iteration cycles.

To improve developer efficiency, the goal is to render Velocity templates locally, merge the generated HTML with Vue's index.html , and allow Vue to mount the DOM, thereby supporting hot updates and mock data without altering the normal Vue build process.

Two implementation paths are explored. Method 1 launches a Node.js service before the Vue entry point, compiles Velocity templates to HTML, and serves the result to Vue. Method 2 embeds a custom Velocity loader into the Webpack chain, compiling templates during the build.

Method 1 implementation:

// setup.js – start Node service and compile Velocity
import './setup';
import './entry';

// node.js – simple HTTP server that runs Velocity
const http = require('http');
const fs = require('fs');
const { exec } = require('child_process');
const hostname = '127.0.0.1';
const port = 3000;
const server = http.createServer((req, res) => {
  if (req.url === '/initdom') {
    exec('velocity ./index.vm', { encoding: 'utf-8' }, (error, stdout, stderr) => {
      if (error) console.error(error);
      if (stderr) console.error(stderr);
      fs.writeFileSync('dist/index.html', stdout);
      res.end('template compiled');
    });
  } else {
    console.log('url not correct');
  }
});
server.listen(port, hostname, () => console.log(`Server running at http://${hostname}:${port}/`));

While this approach works, the Vue build reads the generated HTML before the Node service finishes, causing delayed hot‑updates that require a double browser refresh.

Method 2 implementation:

// webpack chain configuration for .vm files
config.module.rule('velocity')
  .test(/\.vm$/)
  .exclude.add(/node_modules/).end()
  .use('html-loader')
    .loader('html-loader')
    .end()
  .use('velocity-loader')
    .loader(path.resolve(__dirname, './v-loader.js'))
    .options({ basePath: path.join(__dirname, 'src') });

// v-loader.js – core loader logic
module.exports = function(content) {
  const callback = this.async();
  const filePath = this.resourcePath;
  const fileDirPath = path.dirname(filePath);
  const mockPath = path.join(fileDirPath, 'mock.js');
  let mock = {};
  if (fs.existsSync(mockPath)) {
    this.addDependency(mockPath);
    delete require.cache[mockPath];
    mock = require(mockPath);
  }
  content = new Compile(parse(content), { escape: false })
    .render(mock, macros(filePath, {}, mock));
  callback(null, content);
};

Method 2 leverages Webpack's loader mechanism to compile Velocity files on the fly, watch mock data files for changes, and inject the rendered HTML directly into the Vue build, solving the hot‑update issue without a separate Node process.

Both methods ultimately enable local compilation of Velocity templates, support mock data injection, and provide hot‑reloading, significantly improving development efficiency and reducing maintenance overhead.

The article concludes with references to the official Velocity, velocityjs, Webpack, and Vue documentation, and notes that many mature solutions already exist for this problem.