You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The `ui` directory contains static files and templates used in the web UI. For
4
-
easier distribution they are compressed (c.f. Makefile) and statically compiled
5
-
into the Prometheus binary using the embed package.
3
+
The `ui` directory contains the following subdirectories:
6
4
7
-
During development it is more convenient to always use the files on disk to
8
-
directly see changes without recompiling.
9
-
To make this work, remove the `builtinassets` build tag in the `flags` entry
10
-
in `.promu.yml`, and then `make build` (or build Prometheus using
11
-
`go build ./cmd/prometheus`).
5
+
*`mantine-ui`: The new (3.x) React-based web UI for Prometheus.
6
+
*`react-app`: The old (2.x) React-based web UI for Prometheus.
7
+
*`modules`: Shared npm modules for PromQL code editing via [CodeMirror](https://codemirror.net/), which are used by both React apps and external consumers (like [Thanos](https://thanos.io/)).
8
+
*`static`: The build output directory for both React apps. The files in this directory are compiled into the Prometheus binary unless built-in assets are disabled (see the section on this below).
12
9
13
-
This will serve all files from your local filesystem. This is for development purposes only.
10
+
The directory also contains helper files for building and compiling the UI assets for both React application versions into the Prometheus binary.
14
11
15
-
### Using Prebuilt UI Assets
12
+
Prometheus serves the new UI by default, but you can still use the Prometheus server feature flag `--enable-feature=old-ui` to switch back to the old UI for the time being.
16
13
17
-
If you are only working on the go backend, for faster builds, you can use
18
-
prebuilt web UI assets available with each Prometheus release
19
-
(`prometheus-web-ui-<version>.tar.gz`). This allows you to skip building the UI
20
-
from source.
14
+
While both the `mantine-ui` and `modules` directories are part of the same shared npm workspace, the old UI in the `react-app` directory has been separated out of the workspace setup, since its dependencies were too incompatible to integrate.
21
15
22
-
1. Download and extract the prebuilt UI tarball:
23
-
```bash
24
-
tar -xvf prometheus-web-ui-<version>.tar.gz -C web/ui
25
-
```
26
-
27
-
2. Build Prometheus using the prebuilt assets by passing the following parameter
28
-
to `make`:
29
-
```bash
30
-
make PREBUILT_ASSETS_STATIC_DIR=web/ui/static build
31
-
```
32
-
33
-
This will include the prebuilt UI files directly in the Prometheus binary,
34
-
avoiding the need to install npm or rebuild the frontend from source.
35
-
36
-
## React-app
37
-
38
-
### Introduction
39
-
40
-
This directory contains two generations of Prometheus' React-based web UI:
16
+
### Pre-requisites
41
17
42
-
*`react-app`: The old 2.x web UI
43
-
*`mantine-ui`: The new 3.x web UI
18
+
To be able to build either of the React applications, you will need:
44
19
45
-
Both UIs are built and compiled into Prometheus. The new UI is served by default, but a feature flag
46
-
(`--enable-feature=old-ui`) can be used to switch back to serving the old UI.
47
-
48
-
Then you have different npm packages located in the folder `modules`. These packages are supposed to be used by the
49
-
two React apps and also by others consumers (like Thanos).
50
-
51
-
While most of these applications / modules are part of the same npm workspace, the old UI in the `react-app` directory
52
-
has been separated out of the workspace setup, since its dependencies were too incompatible.
53
-
54
-
### Pre-requisite
55
-
56
-
To be able to build either of the React applications, you need:
57
-
58
-
* npm >= v7
59
-
* node >= v20
20
+
* npm >= v10
21
+
* node >= v22
60
22
61
23
### Installing npm dependencies
62
24
63
-
The React UI depends on a large number of [npm](https://www.npmjs.com/) packages. These are not checked in, so you will
64
-
need to move to the directory `web/ui` and then download and install them locally via the npm package manager:
65
-
66
-
npm install
67
-
68
-
npm consults the `package.json` and `package-lock.json` files for dependencies to install. It creates a `node_modules`
69
-
directory with all installed dependencies.
25
+
To install all required [npm](https://www.npmjs.com/) package dependencies and also build the local workspace npm modules, run this command from the root of the repository:
70
26
71
-
**NOTE**: Do not run `npm install` in the `react-app` / `mantine-ui` folder or in any sub folder of the `module` directory.
27
+
```bash
28
+
make ui-build
29
+
```
72
30
73
-
### Upgrading npm dependencies
31
+
This will run `npm install` both in the main `web/ui` workspace directory, as well as in the `web/ui/react-app` directory, and it will further run `npm run build` in both directories to make sure that both apps and their dependencies are built correctly.
74
32
75
-
As it is a monorepo, when upgrading a dependency, you have to upgrade it in every packages that composed this monorepo
76
-
(aka, in all sub folders of `module` and `react-app` / `mantine-ui`)
33
+
npm consults the `package.json` and `package-lock.json` files for dependencies to install. It creates a `node_modules` directory with all installed dependencies.
77
34
78
-
Then you have to run the command `npm install` in `web/ui`and not in a sub folder / sub package. It won't simply work.
35
+
**NOTE**: Do not run `npm install`directly in the `mantine-ui`folder or in any sub folder of the `module` directory - dependencies for these should be installed only via the npm workspace setup from `web/ui`.
79
36
80
37
### Running a local development server
81
38
@@ -85,61 +42,106 @@ You can start a development server for the new React UI outside of a running Pro
85
42
86
43
(For the old UI, you will have to run the same command from the `react-app` subdirectory.)
87
44
88
-
This will open a browser window with the React app running on http://localhost:5173/. The page will reload if you make
89
-
edits to the source code. You will also see any lint errors in the console.
45
+
This will start the development server on http://localhost:5173/. The page will hot-reload if you make edits to the source code. You will also see any lint errors in the console.
46
+
47
+
**NOTE**: Hot reloads will only work for code in the `mantine-ui` and `react-app` folders. For changes in the `module` directory (the CodeMirror PromQL editor code) to become visible, you will need to run `npm run build:module` from `web/ui`.
90
48
91
-
**NOTE**: It will reload only if you change the code in `mantine-ui` folder. Any code changes in the folder `module` is
92
-
not considered by the command `npm start`. In order to see the changes in the react-app you will have to
93
-
run `npm run build:module`
49
+
### Proxying API requests to a Prometheus backend server
94
50
95
-
Due to a `"proxy": "http://localhost:9090"` setting in the `mantine-ui/vite.config.ts` file, any API requests from the React UI are
96
-
proxied to `localhost` on port `9090` by the development server. This allows you to run a normal Prometheus server to
97
-
handle API requests, while iterating separately on the UI.
51
+
To do anything useful, the web UI requires a Prometheus backend to fetch and display data from. Due to a proxy configuration in the `mantine-ui/vite.config.ts` file, the development web server proxies any API requests from the UI to `http://localhost:9090`. This allows you to run a normal Prometheus server to handle API requests, while iterating separately on the UI:
98
52
99
53
[browser] ----> [localhost:5173 (dev server)] --(proxy API requests)--> [localhost:9090 (Prometheus)]
100
54
55
+
If you prefer, you can also change the `mantine-ui/vite.config.ts` file to point to a any other Prometheus server. Note that connecting to an HTTPS-based server will require an additional `changeOrigin: true` setting. For example, to connect to the demo server at `https://prometheus.demo.prometheus.io/`, you could change the `vite.config.ts` file to:
56
+
57
+
```typescript
58
+
import { defineConfig } from"vite";
59
+
importreactfrom"@vitejs/plugin-react";
60
+
61
+
// https://vitejs.dev/config/
62
+
exportdefaultdefineConfig({
63
+
base: '',
64
+
plugins: [react()],
65
+
server: {
66
+
proxy: {
67
+
"/api": {
68
+
target: "https://prometheus.demo.prometheus.io/",
69
+
changeOrigin: true,
70
+
},
71
+
"/-/": {
72
+
target: "https://prometheus.demo.prometheus.io/",
73
+
changeOrigin: true,
74
+
},
75
+
},
76
+
},
77
+
});
78
+
```
79
+
101
80
### Running tests
102
81
103
-
To run the test for the new React app and for all modules, you can simply run:
82
+
To run the tests for the new React app and for all modules:
104
83
105
84
```bash
106
85
npm test
107
86
```
108
87
109
-
(For the old UI, you will have to run the same command from the `react-app` subdirectory.)
110
-
111
-
If you want to run the test only for a specific module, you need to go to the folder of the module and run
112
-
again `npm test`.
88
+
(For the old UI, you would have to run the same command from the `react-app` subdirectory.)
113
89
114
-
For example, in case you only want to run the test of the new React app, go to `web/ui/mantine-ui`and run `npm test`
90
+
To run the tests only for a specific module, change to the module's directory and run `npm test` from there.
115
91
116
-
To generate an HTML-based test coverage report, run:
92
+
By default, `npm test` will run the tests in an interactive watch mode. This means that it will keep running the tests when you change any source files.
93
+
To run the tests only once and then exit, use the `CI=true` environment variable:
117
94
118
-
CI=true npm test:coverage
95
+
```bash
96
+
CI=true npm test
97
+
```
119
98
120
-
This creates a `coverage` subdirectory with the generated report. Open `coverage/lcov-report/index.html` in the browser
121
-
to view it.
99
+
### Building the app for production
122
100
123
-
The `CI=true` environment variable prevents the tests from being run in interactive / watching mode.
101
+
To build a production-optimized version of both React app versions to the `static/{react-app,mantine-ui}` output directories, run:
124
102
125
-
See the [Create React App documentation](https://create-react-app.dev/docs/running-tests/) for more information about
126
-
running tests.
103
+
npm run build
127
104
128
-
### Building the app for production
105
+
**NOTE:** You will likely not need to do this directly. Instead, this is taken care of by the `build` target in the main Prometheus `Makefile` when building the full binary.
129
106
130
-
To build a production-optimized version of both React app versions to a `static/{react-app,mantine-ui}` subdirectory, run:
107
+
### Upgrading npm dependencies
131
108
132
-
npm run build
109
+
As this is a monorepo containing multiple npm packages, you will have to upgrade dependencies in every package individually (in all sub folders of `module`, `react-app`, and `mantine-ui`).
133
110
134
-
**NOTE:** You will likely not need to do this directly. Instead, this is taken care of by the `build` target in the main
135
-
Prometheus `Makefile` when building the full binary.
111
+
Then, run `npm install` in `web/ui` and `web/ui/react-app` directories, but not in the other sub folders / sub packages (this won't produce the desired results due to the npm workspace setup).
136
112
137
113
### Integration into Prometheus
138
114
139
115
To build a Prometheus binary that includes a compiled-in version of the production build of both React app versions, change to the
140
116
root of the repository and run:
141
117
142
-
make build
118
+
```bash
119
+
make build
120
+
```
121
+
122
+
This installs dependencies via npm, builds a production build of both React apps, and then finally compiles in all web assets into the Prometheus binary.
123
+
124
+
### Serving UI assets from the filesystem
125
+
126
+
By default, the built web assets are compressed (via the main Makefile) and statically compiled into the Prometheus binary using Go's `embed` package.
127
+
128
+
During development it can be convenient to tell the Prometheus server to always serve its web assets from the local filesystem (in the `web/ui/static` build output directory) without having to recompile the Go binary. To make this work, remove the `builtinassets` build tag in the `flags` entry in `.promu.yml`, and then run `make build` (or build Prometheus using `go build ./cmd/prometheus`).
129
+
130
+
Note that in most cases, it is even more convenient to just use the development web server via `npm start` as mentioned above, since serving web assets like this from the filesystem still requires rebuilding those assets via `make ui-build` (or `npm run build`) before they can be served.
131
+
132
+
### Using prebuilt UI assets
133
+
134
+
If you are only working on the Prometheus Go backend and don't want to bother with the dependencies or the time required for producing UI builds, you can use the prebuilt web UI assets available with each Prometheus release (`prometheus-web-ui-<version>.tar.gz`). This allows you to skip building the UI from source.
135
+
136
+
1. Download and extract the prebuilt UI tarball:
137
+
```bash
138
+
tar -xvf prometheus-web-ui-<version>.tar.gz -C web/ui
139
+
```
140
+
141
+
2. Build Prometheus using the prebuilt assets by passing the following parameter
142
+
to `make`:
143
+
```bash
144
+
make PREBUILT_ASSETS_STATIC_DIR=web/ui/static build
145
+
```
143
146
144
-
This installs dependencies via npm, builds a production build of both React apps, and then finally compiles in all web
145
-
assets into the Prometheus binary.
147
+
This will include the prebuilt UI files directly in the Prometheus binary, avoiding the need to install npm or rebuild the frontend from source.
0 commit comments