update documentation around react-app (#9476)
* 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
GitHub
parent
60d0990886
commit
08011925a1
|
|
@ -55,10 +55,10 @@ Prometheus will now be reachable at http://localhost:9090/.
|
|||
|
||||
### Building from source
|
||||
|
||||
To build Prometheus from source code, first ensure that you have a working
|
||||
Go environment with [version 1.14 or greater installed](https://golang.org/doc/install).
|
||||
You also need [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/)
|
||||
installed in order to build the frontend assets.
|
||||
To build Prometheus from source code, You need:
|
||||
* Go [version 1.14 or greater](https://golang.org/doc/install).
|
||||
* NodeJS [version 16 or greater](https://nodejs.org/).
|
||||
* npm [version 7 or greater](https://www.npmjs.com/).
|
||||
|
||||
You can directly use the `go` tool to download and install the `prometheus`
|
||||
and `promtool` binaries into your `GOPATH`:
|
||||
|
|
|
|||
21
RELEASE.md
21
RELEASE.md
|
|
@ -95,24 +95,13 @@ git commit -m "Update 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.
|
||||
|
||||
```
|
||||
cd web/ui/react-app
|
||||
npm update
|
||||
git add package.json package-lock.json
|
||||
```
|
||||
When you want to update a dependency, you have to go to every internal npm package where the dependency is used and
|
||||
manually change the version. Once you have taken care of that, you need to go back to `web/ui` and run `npm install`
|
||||
|
||||
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):
|
||||
|
||||
```
|
||||
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/).
|
||||
**NOTE**: We are researching ways to automate and improve this.
|
||||
|
||||
### 1. Prepare your release
|
||||
|
||||
|
|
|
|||
116
web/ui/README.md
116
web/ui/README.md
|
|
@ -1,12 +1,110 @@
|
|||
The `ui` directory contains static files and templates used in the web UI. For
|
||||
easier distribution they are statically compiled into the Prometheus binary
|
||||
using the vfsgen library (c.f. Makefile).
|
||||
## Overview
|
||||
|
||||
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
|
||||
The `ui` directory contains static files and templates used in the web UI. For 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 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`).
|
||||
|
||||
This will serve all files from your local filesystem.
|
||||
This is for development purposes only.
|
||||
This will serve all files from your local filesystem. 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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue