Skip to content

Latest commit

 

History

History
120 lines (81 loc) · 5.2 KB

README.md

File metadata and controls

120 lines (81 loc) · 5.2 KB
Raw

Perses UI

This serves as the monorepo root for the packages that make up the Perses UI.

UI quick start

If you are new to Perses, please review the rest of this README first before starting development.

Perses app

  • Start the backend server in development mode by running this script from the project root: ./scripts/api_backend_dev.sh
  • Change to the ui directory.
  • Install dependencies: npm install
  • Start the Perses app: npm run start
  • Open the app: http://localhost:3000/

Storybook

  • Change to the ui directory.
  • Install dependencies: npm install
  • Start the storybook: npm run storybook
  • Open the storybook: http://localhost:6006/

Perses app and storybook

Follow the steps for "Perses app", but start using this script: npm run start-with-storybook.

Run Jest tests

  • Change to the ui directory.
  • Install dependencies: npm install
  • Run tests: npm run test

Run end-to-end tests

  • Follow the instructions to start the Perses app.
  • Change to the ui directory.
  • Run the end-to-end tests from the command line: npm run e2e

Package organization

The UI-based code for Perses is organized as a monorepo using turborepo.

The root package.json in ui has NPM workspaces enabled, so running npm install will install dependencies for all packages and add symlinks to the local versions for packages that depend on other packages in the workspace. The root package.json also contains devDependencies that are commonly used across multiple packages in the workspace.

Perses is broken up in to a number of separate packages to allow for flexibility when embedding functionality. You can generate a graph of the dependencies by using the turbo cli's --graph option. For example, npm run start -- --graph=graph.svg will output a graph of the dependencies of the start command in SVG format.

Applications

  • app: The main Perses UI React application.

Libraries

The following packages include components, plugins, utilities, and other code that is used to compose the Perses UI React application and can be used by consumers to compose their own applications.

These packages are published to npm with the @perses-dev namespace.

  • components: common components available to the app, plugins, or users who want to embed common Perses UI elements into their own applications.
  • core: Core functionality that's exposed to plugins and also consumed by the app.
  • dashboards: Dashboard components and related utilities.
  • panels-plugin: a plugin module with Panel plugins for the core visualizations supported by Perses.
  • plugin-system: All the type definitions and components that power our plugins, also includes the definitions for the runtime available to plugins (e.g. the current time range state, the current template variable state).
  • prometheus-plugin: a plugin module with multiple plugin types (e.g. Variable, ChartQuery, etc.) for supporting Prometheus in Perses.

Internal tooling

The following packages are internal tooling that assists with development of the Perses UI. These are not published and are not intended for use outside of the project.

  • e2e: End-to-end tests.
  • storybook: Storybook management and configuration.

Development Environment

First, check out the UI Guidelines for some information on how the codebase is organized and our approach to development in the UI. You'll need to have the following installed locally before you can start developing:

  • Node.js v18 or higher: we suggest using NVM for installing and managing versions.
  • NPM v7 or higher: a version of npm that supports workspaces (use npm --version to check your version locally)

Running Scripts

You can use the -w ${WORKSPACE_NAME} flag of npm run to run scripts inside workspace packages from this root folder. For example, to start the main app, you would run:

npm run start -w app

Keep in mind that since npm install symlinks to other local packages in the workspace, you may need to build some packages first locally before they will be available to the local packages that depend on them (e.g. you need to build core before building/running app locally).

You can also run a script across all packages in the workspace using NPM's --workspaces flag.

Note: If you are trying to run the app (npm run start -w app), you may need to first setup a local backend server.

Troubleshooting

I am getting build errors. What do I do?

Occasionally, after switching branches or installing new dependencies, your environment may start throwing build errors. To fix, try clearing all dist folders by running npm run clean in the ui folder (before rerunning npm start).

If this does not work, npm run reinstall can be used to remove all node_modules folders and clear the dist folders.