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

> Learn how to configure the RomM frontend with Vite. Follow this setup guide to integrate Vue 3, Vuetify, set environment variables, and build your application.

- Repository: [The RomM Project/romm](https://github.com/rommapp/romm)
- Tags: how-to-guide
- Published: 2026-07-07

---

**Configure the RomM frontend by editing [`frontend/vite.config.js`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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:

```javascript
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:

```javascript
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:

```bash
cd frontend
npm ci

```

This command reads [`package-lock.json`](https://github.com/rommapp/romm/blob/main/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:

```bash
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`:

```typescript
// 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`](https://github.com/rommapp/romm/blob/main/vite.config.js):

```javascript
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:

```bash
npm run dev

```

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

```bash
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`](https://github.com/rommapp/romm/blob/main/vite.config.js) controls output behavior and optimizations:

```javascript
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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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`](https://github.com/rommapp/romm/blob/main/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.