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.

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.

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

• Node.js 24+
• npm 11+

Clone the repository and install dependencies:

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

This monorepo uses Turborepo for efficient task running and caching.

npm run build

npm run test

npm run type-check

# Check for linting issues
npm run lint

# Fix linting issues automatically
npm run lint:fix

The Oxlint configuration includes React Doctor's lint-native rules. Run npm run doctor for the full React Doctor project scan; pull requests and pushes to main also run that scan in GitHub Actions.

Watch for changes and rebuild automatically:

npm run start

# Clean all build outputs
npm run clean

# Clean and reinstall all dependencies
npm run reinstall

# Clear Turborepo cache
npm run clear-turbo-cache

To link these shared libraries with your local Perses UI or plugins 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. By default, it will search for the Perses UI app as a sibling directory. You can also link with plugins by using the --plugins flag.

For detailed usage information:

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

Common commands:

# Link with Perses UI (default, sibling directory at ../perses)
./scripts/link-with-perses/link-with-perses.sh link

# Link with Perses UI at custom location
./scripts/link-with-perses/link-with-perses.sh link --perses ~/projects/perses

# Link with plugins (sibling directory at ../plugins)
./scripts/link-with-perses/link-with-perses.sh link --plugins

# Link with plugins at custom location
./scripts/link-with-perses/link-with-perses.sh link --plugins ~/projects/plugins

# Check link status
./scripts/link-with-perses/link-with-perses.sh status --plugins

# Unlink
./scripts/link-with-perses/link-with-perses.sh unlink

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 link. If your perses repo is in a different location than a sibling directory, use the --perses option to specify its location.
6. From the perses ui/app 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.

1. Clone the plugins repo https://github.com/perses/plugins
2. From the plugins root folder install dependencies with npm install.
3. Clone this shared repo and install dependencies with npm install.
4. From the shared root folder, run ./scripts/link-with-perses/link-with-perses.sh link --plugins. If your plugins repo is in a different location than a sibling directory, use the --plugins option with the custom path.
5. From the plugins root folder, run the appropriate development command for your plugin.
6. Make changes to the shared libraries and see them reflected in your plugins.
7. When done, run ./scripts/link-with-perses/link-with-perses.sh unlink --plugins to restore the original dependencies in the plugins repo.

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

See RELEASE.md for information about the release process.

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

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