For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Frontend

This guide walks a developer through setting up a local development environment for the OCS Inventory Server Frontend Rework repository - the Vue 3 / Vite-based rewrite of the OCS Inventory administration console.

This guide is for development environments only. For a production deployment, see the OCS Inventory Server Setup guide instead.

Overview

This repository contains only the frontend (a Vue 3 single-page application built with Vite). It talks to the backend REST API but doesn't include it. To get a working environment, you'll need the backend running as well - see its own developer installation guide.

Prerequisites

  • Node.js 18 or later (an active LTS release, e.g. Node 20 or 22) - required by Vite 6, which this project uses.

  • npm (bundled with Node.js) to install dependencies and run project scripts.

  • Git - to clone the repository.

  • A running instance of the backend API - since the frontend is a client for it and has nothing to display without it.

This project doesn't ship a Dockerfile or docker-compose.yml for development. Setup is done directly on your machine (or inside a VM/container you manage yourself).

Step 1 - Clone the Repository

If you plan to contribute back to the project (bug fixes, features, pull requests), fork the repository on GitHub first and clone your fork instead of the main repository. This lets you push branches and open pull requests without needing write access to the original repo.

git clone https://github.com/OCSInventory-NG/OCSInventory-Server-Frontend-Rework.git
cd OCSInventory-Server-Frontend-Rework

The default branch for active development is dev.

Step 2 - Install Dependencies

This installs Vue 3, Vite, Bootstrap/Tabler UI components, and the other packages listed in package.json.

Step 3 - Point the Frontend at Your Backend

The frontend reads the backend API URL from public/config/config.json. Open this file and set it to the address where your backend is running (e.g. http://localhost:8000).

This file is read at runtime, not at build time - you can change it without rebuilding the app, but you do need to reload the page in the browser for the change to take effect.

Step 4 - Run the Development Server

This starts Vite's dev server with hot-reload: your changes to .vue, .js, and style files appear in the browser immediately without a full page reload. Vite will print the local URL to open (typically http://localhost:5173/).

Make sure the backend API is running and reachable before logging in - the login screen and most pages depend on it.

Other Useful Commands

Command
What it does

npm run build

Compiles and minifies the app for production, output to dist/.

npm run preview

Serves the production build locally, useful for a final sanity check.

npm run lint

Runs ESLint and automatically fixes what it can.

npm run format

Runs Prettier on the src/ folder to normalize code formatting.

Troubleshooting

Symptom
Likely cause

npm install fails or hangs

Confirm your Node.js version is 18+ (node -v). Older versions aren't supported by Vite 6.

Blank page or endless spinner after npm run dev

The backend API likely isn't running, or the URL in public/config/config.json doesn't match where it's listening.

Login works but most pages show errors or empty data

Check the browser console/network tab - this usually points to a mismatch between the frontend's expected API URL and where the backend is actually listening.

Style/layout looks broken

Run npm run lint and npm run format - a stale build cache or a formatting issue is a common cause; also try clearing Vite's cache (node_modules/.vite).

How to Contribute

1

Fork the repository on GitHub, then clone your fork locally (see the note in Step 1 above).

2

Create a branch for your change, based on dev:

3

Make your changes, following the existing code style. The repository includes several linting and quality configs (.eslintrc.json / eslint.config.mjs, .stylelintrc.json, .scss-lint.yml, .markdownlint.json, .mega-linter.yml) — running npm run lint and npm run format before committing will catch most issues early and matches what CI checks on your pull request.

4

Commit and push your branch to your fork:

5

Open a pull request from your branch to the dev branch of the main repository, with a clear description of what the change does and why.

Keep pull requests focused on a single change. Smaller, well-scoped PRs are easier to review and more likely to be merged quickly.

Adding a Language

Translations live in src/locales/, one JSON file per language. To add a new language:

  1. Copy src/locales/en.json to src/locales/<code>.json, where <code> is a language tag such as de, es or pt-BR.

  2. Translate the values (keep the keys unchanged).

That's it: the file is loaded automatically and the language appears in the language selectors, labelled with its own name (e.g. "Deutsch"). Missing keys fall back to English.

One Last Thing

You've got Vue running, hot-reload doing its thing, and a backend to talk to - the hard part's already behind you.

This console is what every sysadmin sees first thing in the morning, so a cleaner form, a faster table, or a fixed edge case in a chart genuinely makes someone's day better somewhere. Component by component, this is how a tired old PHP interface turns into something people actually enjoy clicking around in.

So don't overthink that first PR. Fix the small thing, ship it, and let dev branch take it from there. 🚀

Last updated