> For the complete documentation index, see [llms.txt](https://documentation.ocsinventory-ng.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.ocsinventory-ng.org/developer-docs/setup-development-environment/frontend.md). # Frontend This guide walks a developer through setting up a local development environment for the [OCS Inventory Server Frontend Rework](https://github.com/OCSInventory-NG/OCSInventory-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](/administrator-docs/server-setup.md) instead. ### Overview This repository contains only the **frontend** (a Vue 3 single-page application built with Vite). It talks to the [backend REST API](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework) but doesn't include it. To get a working environment, you'll need the backend running as well - see its [own developer installation guide](/developer-docs/setup-development-environment/backend.md). ### 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](https://github.com/OCSInventory-NG/OCSInventory-Server-Backend-Rework) - since the frontend is a client for it and has nothing to display without it. {% hint style="info" %} 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). {% endhint %} ### Step 1 - Clone the Repository {% hint style="info" %} 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. {% endhint %} ```bash 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 ```bash npm install ``` 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 ```bash npm run dev ``` 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 {% stepper %} {% step %} **Fork the repository** on GitHub, then clone your fork locally (see the note in Step 1 above). {% endstep %} {% step %} **Create a branch** for your change, based on `dev`: ```bash git checkout dev git pull git checkout -b my-feature-branch ``` {% endstep %} {% step %} **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. {% endstep %} {% step %} **Commit and push** your branch to your fork: ```bash git add . git commit -m "Describe your change" git push origin my-feature-branch ``` {% endstep %} {% step %} **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. {% endstep %} {% endstepper %} {% hint style="info" %} Keep pull requests focused on a single change. Smaller, well-scoped PRs are easier to review and more likely to be merged quickly. {% endhint %} ### 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. 🚀 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.ocsinventory-ng.org/developer-docs/setup-development-environment/frontend.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.