From 3682d8541ca1f4c6216d1e8c6a842b5c8ef4b9e0 Mon Sep 17 00:00:00 2001 From: Konstantinos Paparas Date: Wed, 11 Mar 2026 12:42:34 +0100 Subject: [PATCH] docs: expand frontend developer guide with env vars, proxy, workspace, and linting - Document all frontend environment variables (dev tools, API URLs, feature flags, i18n, test-only) - Add development proxy section with auto-start behavior, configuration, and endpoint mocking - Add workspace structure overview and Vite configuration files explanation - Add linting and type checking commands - Add environment files reference with example .env.development.local - Update build-from-source with Node.js/pnpm version requirements and Rust/Cargo prerequisite - Simplify pnpm installation instructions to use corepack - Document what `pnpm run dev` starts and link to the frontend guide --- contribution-guides/working-with-frontend.md | 195 +++++++++++++++++- .../build-from-source.md | 33 ++- 2 files changed, 208 insertions(+), 20 deletions(-) diff --git a/contribution-guides/working-with-frontend.md b/contribution-guides/working-with-frontend.md index 0696c67..4a470ff 100644 --- a/contribution-guides/working-with-frontend.md +++ b/contribution-guides/working-with-frontend.md @@ -1,5 +1,198 @@ # Working with the Frontend +## Editor Integration + While working with the frontend code, type errors will be displayed inside the page. To make clicking the errors open in your editor or IDE, you need to set the [`LAUNCH_EDITOR`](https://github.com/yyx990803/launch-editor#supported-editors) environment variable in your system. -To enable the Vue Dev Tools during development in the Electron app, set `ENABLE_DEV_TOOLS=true` in `.env.development.local`. +## Environment Variables + +The frontend uses Vite environment variables for configuration. These variables are prefixed with `VITE_` and are accessed via `import.meta.env` at runtime. Non-`VITE_` variables are only available at build time (e.g., in `vite.config.ts` or Node scripts). + +You can override any variable by creating a `.env.development.local` file in `frontend/app/`. This file is gitignored and won't be committed. + +### Development Tools + +| Variable | Default | Description | +| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | +| `ENABLE_DEV_TOOLS` | – | Set to `true` to enable Vue DevTools in the Electron app during development. Build-time only (used in `vite.config.ts`). | +| `DEBUGGER_PORT` | – | Set a port number to enable the Node.js debugger for the Electron main process (used by the dev script). | +| `VITE_DEV_LOGS` | – | When set, stores Electron main process logs in the project directory instead of the system app data directory. | +| `VITE_VERBOSE_CACHE` | – | When set, enables verbose logging for the item cache composable. Useful for debugging cache behavior. | +| `VITE_PERSIST_STORE` | – | When set to `true`, enables persistence of the Pinia debug store across page reloads. | + +### API & Service URLs + +| Variable | Default | Description | +| ------------------------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VITE_BACKEND_URL` | `http://127.0.0.1:4242` | URL for the rotki backend API. When set in `.env.development.local`, the dev script automatically starts the [development proxy](#development-proxy) alongside the frontend. | +| `VITE_COLIBRI_URL` | `http://127.0.0.1:4343` | URL for the Colibri service. | +| `VITE_ROTKI_WEBSITE_URL` | `https://rotki.com` | URL for the rotki website. Can be pointed to a local instance during development. | +| `VITE_PUBLIC_PATH` | – | When set, adjusts the base path for the router and API URL resolution. Used in Docker builds. | + +## Development Proxy + +The frontend includes a development proxy (`frontend/dev-proxy`) that sits between the frontend and the real backend. It forwards all requests to the backend by default, but allows you to mock specific endpoints — useful for developing frontend features in parallel with the backend or testing premium features without the premium backend. + +### Starting the Proxy + +When `VITE_BACKEND_URL` is set in `.env.development.local`, the proxy starts **automatically** when you run `pnpm run dev`. The typical setup is: + +```bash +# frontend/app/.env.development.local +VITE_BACKEND_URL=http://localhost:4243 +``` + +This points the frontend to the proxy (port 4243), which in turn forwards requests to the real backend (port 4242). + +You can also start the proxy manually: + +```bash +pnpm run --filter @rotki/dev-proxy serve +``` + +### Proxy Configuration + +Configure the proxy via environment variables or a `.env` file in the `frontend/dev-proxy/` directory: + +| Variable | Default | Description | +| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- | +| `PORT` | `4243` | The port the proxy listens on. | +| `BACKEND` | `http://localhost:4242` | The URL of the real backend to forward requests to. | +| `PREMIUM_COMPONENT_DIR` | – | Path to the premium components source directory. Only needed for testing premium components locally. | + +### Mocking Endpoints + +The proxy can mock backend responses using an `async-mock.json` file in the `frontend/dev-proxy/` directory. See `async-mock.example.json` for the format. + +```json +{ + "/api/1/assets/updates": { + "GET": { + "result": { "local_version": 1, "remote_version": 6 }, + "message": "" + } + } +} +``` + +- Use an **object** for a static mock that returns the same response every time. +- Use an **array** to return different responses on successive requests (cycling through items, repeating the last one when exhausted). + +Any endpoint without a mock entry is forwarded to the real backend. + +## Workspace Structure + +The frontend is a pnpm workspace with several packages: + +| Package | Directory | Description | +| ------------------ | -------------------- | --------------------------------------------------------------------------------------------- | +| `@rotki/app` | `frontend/app` | The main rotki application (Electron + web). | +| `@rotki/common` | `frontend/common` | Shared utilities and types used across packages. | +| `@rotki/dev-proxy` | `frontend/dev-proxy` | Development proxy for mocking backend endpoints. See [Development Proxy](#development-proxy). | + +### Vite Configurations + +The app uses three separate Vite configuration files for different build targets: + +| File | Purpose | +| ------------------------ | ------------------------------------ | +| `vite.config.ts` | Main renderer process (the Vue app). | +| `vite.config.main.ts` | Electron main process. | +| `vite.config.preload.ts` | Electron preload script. | + +When making configuration changes, ensure you edit the correct file for the target you're working on. + +## Linting & Type Checking + +The project uses ESLint with `@rotki/eslint-config` and Stylelint for CSS. All commands are run from the `frontend` directory: + +```sh +# Lint TypeScript/Vue files +pnpm run lint + +# Lint and auto-fix +pnpm run lint:fix + +# Lint CSS styles +pnpm run lint:style + +# Lint styles and auto-fix +pnpm run lint:style:fix + +# Type check with vue-tsc +pnpm run typecheck +``` + +To set up pre-commit hooks that run linting automatically: + +```sh +pnpm run setup:hooks +``` + +## Feature Flags + +| Variable | Default | Description | +| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VITE_NO_AUTO_FETCH` | – | Set to `true` to disable automatic balance fetching on login, periodic balance refresh, and automatic transaction syncing when navigating to the history page. Manual refresh buttons continue to work normally. Useful during frontend development to avoid waiting for backend data loads. | +| `VITE_DEMO_MODE` | – | Set to `minor` or `patch` to enable demo mode. Hides certain UI elements (e.g., privacy mode, redecode button) and adjusts indicators for demo purposes. | + +### Internationalization + +| Variable | Default | Description | +| ------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------- | +| `VITE_I18N_LOCALE` | `en` | Sets the active locale for the application. | +| `VITE_I18N_FALLBACK_LOCALE` | `en` | Sets the fallback locale when a translation is missing. | +| `VITE_SILENT_TRANSLATION_WARN` | – | Set to `true` to suppress missing translation warnings in the console. Enabled by default in test environments. | + +### Third-Party Services + +| Variable | Default | Description | +| ------------------------------------ | --------------- | ---------------------------------------------------------- | +| `VITE_WALLET_CONNECT_PROJECT_ID` | (set in `.env`) | The WalletConnect project ID used for wallet integrations. | +| `VITE_GOOGLE_FORM_URL` | (set in `.env`) | Google Form URL used for the in-app bug report dialog. | +| `VITE_GOOGLE_FORM_TITLE_ENTRY` | (set in `.env`) | Google Form field entry ID for the issue title. | +| `VITE_GOOGLE_FORM_DESCRIPTION_ENTRY` | (set in `.env`) | Google Form field entry ID for the issue description. | + +### Internal / Test-Only + +These variables are used internally by the build system and test environments. You typically don't need to set them manually. + +| Variable | Description | +| ------------- | ------------------------------------------------------------------------------------------ | +| `VITE_DOCKER` | Set to `true` in the Docker build. Adjusts login page behavior (e.g., backend host input). | +| `VITE_TEST` | Set to `true` in test environments. Disables development-only features. | +| `VITE_E2E` | Set to `true` during E2E tests. Exposes `window.interop` for Playwright. | + +## Environment Files + +The frontend uses several `.env` files for different contexts: + +| File | Purpose | +| ------------------------ | ------------------------------------------------------------------------------------------ | +| `.env` | Base defaults shared across all modes. | +| `.env.development.local` | **Your local overrides** (gitignored). Create this file for personal development settings. | +| `.env.docker` | Overrides used when building the Docker image. | +| `.env.e2e` | Overrides used when running E2E tests. | +| `.env.test` | Overrides used when running unit tests. | + +### Example `.env.development.local` + +```bash +# Enable Vue DevTools +ENABLE_DEV_TOOLS=true + +# Use a different backend port +VITE_BACKEND_URL=http://127.0.0.1:4243 + +# Skip automatic data fetching on login +VITE_NO_AUTO_FETCH=true + +# Enable Electron debugger +DEBUGGER_PORT=9229 + +# Store Electron logs in project directory +VITE_DEV_LOGS=true + +# Persist debug store +VITE_PERSIST_STORE=true +``` diff --git a/requirement-and-installation/build-from-source.md b/requirement-and-installation/build-from-source.md index 852581a..6b0cc50 100644 --- a/requirement-and-installation/build-from-source.md +++ b/requirement-and-installation/build-from-source.md @@ -10,8 +10,9 @@ Before starting, ensure you have the following installed: - [Git](https://git-scm.com/downloads) - [Python 3.11.x](https://www.python.org/downloads/) - [uv](https://github.com/astral-sh/uv) (Python package manager) -- [Node.js](https://nodejs.org/en/) -- [pnpm](https://pnpm.io/) +- [Node.js](https://nodejs.org/en/) (version `>=24 <25` — check `frontend/package.json` `engines` for the exact requirement) +- [pnpm](https://pnpm.io/) (version `>=10 <11` — managed via `corepack`, see [Installing pnpm](#installing-pnpm)) +- [Rust/Cargo](https://www.rust-lang.org/tools/install) (needed to build the Colibri service locally) ## Downloading source @@ -116,32 +117,22 @@ rotki REST API server is running at: 127.0.0.1:5042 ## Frontend setup -Make sure you have Node.js installed. You can check https://nodejs.org/en/download/package-manager for more information. +Make sure you have Node.js installed (version `>=24 <25`). You can check https://nodejs.org/en/download/package-manager for more information. -### Installing PNPM +### Installing pnpm -Check the required PNPM version in `frontend/package.json` under the `packageManager` key. For example, if it says: - -```json -{ - "packageManager": "pnpm@10.0.0" -} -``` - -It means you need to have pnpm version `10.0.0` installed. To check the current version of pnpm you have, run: +The project uses [corepack](https://nodejs.org/api/corepack.html) to manage the pnpm version. Enable it and corepack will automatically use the version specified in `frontend/package.json` under the `packageManager` key: ```sh -pnpm --version +corepack enable pnpm ``` -If you are on an older version of pnpm, you can install it by: +To verify: ```sh -corepack enable pnpm +pnpm --version ``` -This will automatically use the version specified in `packageManager`. - ### Install Node.js Dependencies ```sh @@ -157,12 +148,16 @@ Start the application from the `frontend` directory: pnpm run dev ``` -For non-Electron development: +This starts the Electron app with the backend, Colibri service (if Cargo is available), and the frontend dev server. If `VITE_BACKEND_URL` is set in `frontend/app/.env.development.local`, the [development proxy](/contribution-guides/working-with-frontend#development-proxy) is also started automatically. + +For browser-only development (no Electron): ```sh pnpm run dev:web ``` +See [Working with the Frontend](/contribution-guides/working-with-frontend) for environment variables, feature flags, and proxy configuration. + ## Packaging To package the application for your platform, you need to install the packaging dependencies and run the packaging script: