How to Configure the RomM Frontend with Vite: Complete Setup Guide

Configure the RomM frontend by editing frontend/vite.config.js to set up Vue 3, Vuetify, and path aliases, then create a .env file with VITE_ prefixed variables and run npm run dev for development or npm run build for production.

The RomM frontend is a Vue 3 + TypeScript application powered by Vite, the fast development server and build tool used in the rommapp/romm repository. The Vite configuration manages everything from development server proxy settings to production bundling with Rollup. Understanding how to modify vite.config.js and environment variables is essential for customizing the UI or contributing to the project.

Understanding the Vite Architecture in RomM

RomM’s frontend architecture relies on Vite as the central build orchestrator. The configuration in frontend/vite.config.js handles Vue Single File Components (SFCs), TypeScript compilation, and Vuetify component auto-importing.

Vite Core serves as the entry point, defining the root folder, plugin array, and build optimizations. Vue 3 and Vuetify are integrated via dedicated plugins that process .vue files and handle Material Design component styles. TypeScript support is configured through tsconfig.json, which shares path alias definitions with Vite for consistent module resolution.

Vite Configuration File Structure

The primary configuration file is located at frontend/vite.config.js. This file exports a configuration object that controls both development and production environments.

Core Plugins and Aliases

The plugins array initializes the Vue compiler and Vuetify auto-import functionality:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
import vuetify from 'vite-plugin-vuetify';
import path from 'node:path';

export default defineConfig({
  plugins: [
    vue(),
    vuetify({ autoImport: true })
  ],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  }
});

The resolve.alias mapping allows you to use @/ as a shortcut to the src/ directory throughout the codebase.

Development Server and Proxy Settings

Vite’s development server configuration supports proxying API requests to the FastAPI backend during local development:

server: {
  port: Number(process.env.VITE_DEV_PORT) || 5173,
  proxy: {
    '/api': {
      target: process.env.VITE_BACKEND_URL,
      changeOrigin: true
    }
  }
}

Step-by-Step Configuration Guide

Follow these steps to configure the RomM frontend for your environment.

1. Install Frontend Dependencies

Navigate to the frontend directory and install the exact dependency versions:

cd frontend
npm ci

This command reads package-lock.json to ensure consistency with the RomM project's tested dependencies.

2. Configure Environment Variables

Copy the example environment file and customize it for your setup:

cp .env.example .env

Edit the .env file to set variables like VITE_API_URL and VITE_SOCKET_URL. Only variables prefixed with VITE_ are exposed to the client code via import.meta.env:

// Accessing env vars in code
const apiBase = import.meta.env.VITE_API_URL;

3. Customize Path Aliases

To add custom import shortcuts, modify the resolve.alias section in vite.config.js:

alias: {
  '@': path.resolve(__dirname, 'src'),
  '@utils': path.resolve(__dirname, 'src/v2/utils'),
  '#components': path.resolve(__dirname, 'src/v2/components')
}

Now you can import utilities using import { helper } from '@utils/helper'.

4. Run Development and Production Builds

Start the development server with hot module replacement:

npm run dev

This launches the server at http://localhost:5173 by default. For production, create an optimized build:

npm run build

The output is written to frontend/dist/, which the FastAPI backend can serve directly or you can deploy to any static file server.

Build Optimization Settings

The build object in vite.config.js controls output behavior and optimizations:

build: {
  outDir: 'dist',
  sourcemap: true,
  rollupOptions: {
    input: {
      main: path.resolve(__dirname, 'index.html')
    }
  }
}

Vite uses esbuild for fast development transforms and Rollup for production bundling, performing tree-shaking and code-splitting automatically. Static assets placed in frontend/public/ are copied verbatim to the output folder, while small assets are inlined as base64 URLs during the build process.

Summary

• Primary configuration happens in frontend/vite.config.js, which defines plugins, aliases, and server settings for the RomM Vue 3 application.
• Environment variables must use the VITE_ prefix to be accessible in client code via import.meta.env.
• Development workflow uses npm run dev (port 5173), while npm run build outputs optimized static files to frontend/dist/.
• Path aliases like @/ map to src/ and can be extended for cleaner imports throughout the frontend/src/v2/ codebase.
• TypeScript integration is managed through tsconfig.json, which shares alias definitions with Vite for consistent module resolution.

Frequently Asked Questions

How do I change the development server port in RomM?

Set the VITE_DEV_PORT variable in your frontend/.env file, or modify the server.port value directly in frontend/vite.config.js to override the default 5173 port.

Why are my environment variables not showing in the frontend?

Vite only exposes environment variables that begin with VITE_ to the client-side code. Ensure your variables in frontend/.env use this prefix and access them via import.meta.env.VITE_VARIABLE_NAME rather than process.env.

Can I add ESLint or other tooling to the Vite config?

Yes, install your preferred Vite plugin (such as vite-plugin-eslint) and add it to the plugins array in frontend/vite.config.js. The configuration supports any standard Vite or Rollup plugin compatible with Vue 3.

Where does the production build output go?

The npm run build command outputs optimized static files to frontend/dist/ as configured by the build.outDir setting. The FastAPI backend serves these files from that location, or you can deploy them to any static hosting service.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}