Perses Shared Libraries

A monorepo containing shared UI libraries for the Perses project. All libraries are versioned together and published as independent npm packages under the @perses-dev org.

Overview

This monorepo manages the core UI libraries that power the Perses platform. Each workspace is published as a separate npm package, but they all share the same version number to ensure compatibility.

Packages

Package	NPM	Description
@perses-dev/components		Common UI components used across Perses features
@perses-dev/dashboards		The dashboards feature in Perses
@perses-dev/explore		The explore feature in Perses
@perses-dev/plugin-system		The plugin system for Perses

Getting Started

Prerequisites

• Node.js 22+
• npm 10+

Installation

Clone the repository and install dependencies:

git clone https://github.com/perses/shared.git
cd shared
npm install

Development

This monorepo uses Turborepo for efficient task running and caching.

Build all packages

npm run build

Run tests

npm run test

Type checking

npm run type-check

Linting

# Check for linting issues
npm run lint

# Fix linting issues automatically
npm run lint:fix

Development mode

Watch for changes and rebuild automatically:

npm run start

Clean build artifacts

# Clean all build outputs
npm run clean

# Clean and reinstall all dependencies
npm run reinstall

# Clear Turborepo cache
npm run clear-turbo-cache

Linking with the Perses UI

To link these shared libraries with your local Perses UI development environment, use the provided script:

./scripts/link-with-perses/link-with-perses.sh

The script will back up your current dependencies, build and link the shared libraries for local development. It will search for the Perses UI app as a sibling directory by default. See the script helper for more details:

./scripts/link-with-perses/link-with-perses.sh --help

Warning

As the shared dependencies are file references, you cannot build the Perses UI for production while linked to local shared libraries. Make sure to unlink the shared libraries before building for production.

Regular workflow

1. Clone the perses repo https://github.com/perses/perses
2. From the perses ui folder install the ui dependencies with npm install.
3. From the perses root folder, start the Perses API in dev mode with ./scripts/api_backend_dev.sh.
4. Clone this shared repo and install dependencies with npm install. ⚠️ Do not rename the cloned repo, otherwise it breaks the paths resolution on the perses repo side.
5. From the shared root folder, run ./scripts/link-with-perses/link-with-perses.sh. If your perses repo is in a different location than a sibling directory, use the --path option to specify its location.
6. From the perses ui folder, run npm run start:shared to start the Perses UI in dev mode using the linked shared libraries with hot module reloading.
7. Make changes to the shared libraries and see them reflected in your local Perses UI.
8. When done, run ./scripts/link-with-perses/link-with-perses.sh unlink to restore the original dependencies in the Perses UI.

Contributing

Please read CONTRIBUTING.md for details on our development process and how to submit pull requests.

Release Process

See RELEASE.md for information about the release process.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• Perses Project
• Perses Documentation
• Report Issues
• Report Plugins