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.
Step 1 - Clone the Repository
git clone https://github.com/OCSInventory-NG/OCSInventory-Server-Frontend-Rework.git
cd OCSInventory-Server-Frontend-ReworkThe 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
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
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
Fork the repository on GitHub, then clone your fork locally (see the note in Step 1 above).
Create a branch for your change, based on dev:
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.
Commit and push your branch to your fork:
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.
Adding a Language
Translations live in src/locales/, one JSON file per language. To add a new language:
Copy
src/locales/en.jsontosrc/locales/<code>.json, where<code>is a language tag such asde,esorpt-BR.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

