mudhorn/prometheus
1
0
Fork 0
mirror of https://github.com/prometheus/prometheus.git synced 2024-11-13 17:14:05 -08:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

update documentation around react-app (#9476)

Browse source 
* update documentation around react-app and how to upgrade the npm dependencies

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* wording around caution to take when updating the deps

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* fixing the npm version to be used and explain where you should perform the npm install command

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* simplify what is required to build prometheus from the source

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* aligned period and removed redondant word installed

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* set nodeJS version to be used at 16

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* describe manuel steps to update a dependency for the react-app

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>

* rewording of the manuel step to update the dependencies

Signed-off-by: Augustin Husson <husson.augustin@gmail.com>
This commit is contained in:
Augustin Husson 2021-10-18 12:47:31 +02:00 committed by GitHub
parent 60d0990886
commit 08011925a1
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 116 additions and 112 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -55,10 +55,10 @@ Prometheus will now be reachable at http://localhost:9090/.
### Building from source ### Building from source
To build Prometheus from source code, first ensure that you have a working To build Prometheus from source code, You need:
Go environment with [version 1.14 or greater installed](https://golang.org/doc/install). * Go [version 1.14 or greater](https://golang.org/doc/install).
You also need [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) * NodeJS [version 16 or greater](https://nodejs.org/).
installed in order to build the frontend assets. * npm [version 7 or greater](https://www.npmjs.com/).
You can directly use the `go` tool to download and install the `prometheus` You can directly use the `go` tool to download and install the `prometheus`
and `promtool` binaries into your `GOPATH`: and `promtool` binaries into your `GOPATH`:

21
RELEASE.md
View file

@ -95,24 +95,13 @@ git commit -m "Update dependencies"
#### Updating React dependencies #### Updating React dependencies
Either upgrade the dependencies within their existing version constraints as specified in the `package.json` file (see https://docs.npmjs.com/files/package.json#dependencies): The React application recently moved to a monorepo system with multiple internal npm packages. Dependency upgrades are
quite sensitive for the time being and should be done manually with caution.
``` When you want to update a dependency, you have to go to every internal npm package where the dependency is used and
cd web/ui/react-app manually change the version. Once you have taken care of that, you need to go back to `web/ui` and run `npm install`
npm update
git add package.json package-lock.json
```
Or alternatively, update all dependencies to their latest major versions. This is potentially more disruptive and will require more follow-up fixes, but should be done from time to time (use your best judgement): **NOTE**: We are researching ways to automate and improve this.
```
cd web/ui/react-app
npx npm-check-updates -u
npm install
git add package.json package-lock.json
```
You can find more details on managing npm dependencies and updates [in this blog post](https://www.carlrippon.com/upgrading-npm-dependencies/).
### 1. Prepare your release ### 1. Prepare your release

116
web/ui/README.md
View file

@ -1,12 +1,110 @@
The `ui` directory contains static files and templates used in the web UI. For ## Overview
easier distribution they are statically compiled into the Prometheus binary
using the vfsgen library (c.f. Makefile).
During development it is more convenient to always use the files on disk to The `ui` directory contains static files and templates used in the web UI. For easier distribution they are statically
directly see changes without recompiling. compiled into the Prometheus binary using the vfsgen library (c.f. Makefile).
To make this work, remove the `builtinassets` build tag in the `flags` entry
in `.promu.yml`, and then `make build` (or build Prometheus using During development it is more convenient to always use the files on disk to directly see changes without recompiling. To
make this work, remove the `builtinassets` build tag in the `flags` entry in `.promu.yml`, and then `make build` (or
build Prometheus using
`go build ./cmd/prometheus`). `go build ./cmd/prometheus`).
This will serve all files from your local filesystem. This will serve all files from your local filesystem. This is for development purposes only.
This is for development purposes only.
## React-app
### Introduction
The react application is a monorepo composed by multiple different npm packages. The main one is `react-app` which
contains the code of the react application.
Then you have different npm packages located in the folder `modules`. These packages are supposed to be used by the
react-app and also by others consumers (like Thanos)
### Pre-requisite
To be able to build the react application you need:
* npm >= v7
* node >= v16
### Installing npm dependencies
The React UI depends on a large number of [npm](https://www.npmjs.com/) packages. These are not checked in, so you will
need to move to the directory `web/ui` and then download and install them locally via the npm package manager:
npm install
npm consults the `package.json` and `package-lock.json` files for dependencies to install. It creates a `node_modules`
directory with all installed dependencies.
**NOTE**: Do not run `npm install` in the `react-app` folder or in any sub folder of the `module` directory.
### Upgrading npm dependencies
As it is a monorepo, when upgrading a dependency, you have to upgrade it in every packages that composed this monorepo (
aka, in all sub folder of `module` and in `react-app`)
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.
### Running a local development server
You can start a development server for the React UI outside of a running Prometheus server by running:
npm start
This will open a browser window with the React app running on http://localhost:3000/. The page will reload if you make
edits to the source code. You will also see any lint errors in the console.
**NOTE**: It will reload only if you change the code in `react-app` folder. Any code changes in the folder `module` is
not considered by the command `npm start`. In order to see the changes in the react-app you will have to
run `npm run build:module`
Due to a `"proxy": "http://localhost:9090"` setting in the `package.json` file, any API requests from the React UI are
proxied to `localhost` on port `9090` by the development server. This allows you to run a normal Prometheus server to
handle API requests, while iterating separately on the UI.
[browser] ----> [localhost:3000 (dev server)] --(proxy API requests)--> [localhost:9090 (Prometheus)]
### Running tests
To run the test for the react-app and for all modules, you can simply run:
```bash
npm test
```
if you want to run the test only for a specific module, you need to go to the folder of the module and run
again `npm test`.
For example, in case you only want to run the test of the react-app, go to `web/ui/react-app` and run `npm test`
To generate an HTML-based test coverage report, run:
CI=true npm test:coverage
This creates a `coverage` subdirectory with the generated report. Open `coverage/lcov-report/index.html` in the browser
to view it.
The `CI=true` environment variable prevents the tests from being run in interactive / watching mode.
See the [Create React App documentation](https://create-react-app.dev/docs/running-tests/) for more information about
running tests.
### Building the app for production
To build a production-optimized version of the React app to a `build` subdirectory, run:
npm run build
**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.
### Integration into Prometheus
To build a Prometheus binary that includes a compiled-in version of the production build of the React app, change to the
root of the repository and run:
make build
This installs dependencies via npm, builds a production build of the React app, and then finally compiles in all web
assets into the Prometheus binary.

83
web/ui/react-app/README.md
View file

@ -1,83 +0,0 @@
# Working with the React UI
This file explains how to work with the React-based Prometheus UI.
## Introduction
The [React-based](https://reactjs.org/) Prometheus UI was bootstrapped using [Create React App](https://github.com/facebook/create-react-app), a popular toolkit for generating React application setups. You can find general information about Create React App on [their documentation site](https://create-react-app.dev/).
Instead of plain JavaScript, we use [TypeScript](https://www.typescriptlang.org/) to ensure typed code.
## Development environment
To work with the React UI code, you will need to have the following tools installed:
* The [Node.js](https://nodejs.org/) JavaScript runtime.
* The [npm](https://www.npmjs.com/) package manager. Once you installed Node, npm should already be available.
* *Recommended:* An editor with TypeScript, React, and [ESLint](https://eslint.org/) linting support. See e.g. [Create React App's editor setup instructions](https://create-react-app.dev/docs/setting-up-your-editor/). If you are not sure which editor to use, we recommend using [Visual Studio Code](https://code.visualstudio.com/docs/languages/typescript). Make sure that [the editor uses the project's TypeScript version rather than its own](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript).
**NOTE**: When using Visual Studio Code, be sure to open the `web/ui/react-app` directory in the editor instead of the root of the repository. This way, the right ESLint and TypeScript configuration will be picked up from the React workspace.
## Installing npm dependencies
The React UI depends on a large number of [npm](https://www.npmjs.com/) packages. These are not checked in, so you will need to download and install them locally via the npm package manager:
npm install
npm consults the `package.json` and `package-lock.json` files for dependencies to install. It creates a `node_modules` directory with all installed dependencies.
**NOTE**: Remember to change directory to `web/ui/react-app` before running this command and the following commands.
## Running a local development server
You can start a development server for the React UI outside of a running Prometheus server by running:
npm start
This will open a browser window with the React app running on http://localhost:3000/. The page will reload if you make edits to the source code. You will also see any lint errors in the console.
Due to a `"proxy": "http://localhost:9090"` setting in the `package.json` file, any API requests from the React UI are proxied to `localhost` on port `9090` by the development server. This allows you to run a normal Prometheus server to handle API requests, while iterating separately on the UI.
[browser] ----> [localhost:3000 (dev server)] --(proxy API requests)--> [localhost:9090 (Prometheus)]
## Running tests
Create React App uses the [Jest](https://jestjs.io/) framework for running tests. To run tests in interactive watch mode:
npm test
To generate an HTML-based test coverage report, run:
CI=true npm test --coverage
This creates a `coverage` subdirectory with the generated report. Open `coverage/lcov-report/index.html` in the browser to view it.
The `CI=true` environment variable prevents the tests from being run in interactive / watching mode.
See the [Create React App documentation](https://create-react-app.dev/docs/running-tests/) for more information about running tests.
## Linting
We define linting rules for the [ESLint](https://eslint.org/) linter. We recommend integrating automated linting and fixing into your editor (e.g. upon save), but you can also run the linter separately from the command-line.
To detect and automatically fix lint errors, run:
npm run lint
This is also available via the `react-app-lint-fix` target in the main Prometheus `Makefile`.
## Building the app for production
To build a production-optimized version of the React app to a `build` subdirectory, run:
npm run build
**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.
## Integration into Prometheus
To build a Prometheus binary that includes a compiled-in version of the production build of the React app, change to the root of the repository and run:
make build
This installs dependencies via npm, builds a production build of the React app, and then finally compiles in all web assets into the Prometheus binary.