packages/README.md
All the @grafana packages in this repo (except @grafana/schema) make use of exports in package.json to define entrypoints that Grafana core and Grafana plugins can access. Exports can also be used to restrict access to internal files in packages.
Package authors are free to create as many exports as they like but should consider the following points:
Resolution of source code within this repo is handled by the customCondition @grafana-app/source. This allows the frontend tooling in this repo to resolve to the source code preventing the need to build all the packages up front. When adding exports it is important to add an entry for the custom condition as the first item. All other entries should point to the built, bundled files. For example:
"exports": {
".": {
"@grafana-app/source": "./src/index.ts",
"types": "./dist/types/index.d.ts",
"import": "./dist/esm/index.mjs",
"require": "./dist/cjs/index.cjs"
}
}
If you add exports to your package you must export the package.json file.
Before exposing anything in these packages please consider the table below to better understand the conventions we have put in place for most of the packages in this repository.
| Export Name | Import Path | Description | Available to Grafana | Available to plugins |
|---|---|---|---|---|
./ | @grafana/ui | The public API entrypoint. If the code is stable and you want to share it everywhere, this is the place to export it. | ✅ | ✅ |
./unstable | @grafana/ui/unstable | The public API entrypoint for all experimental code. If you want to iterate and test code from Grafana and plugins, this is the place to export it. | ✅ | ✅ |
./internal | @grafana/ui/internal | The private API entrypoint for internal code shared with Grafana. If you want to co-locate code in a package with it's public API but only want the Grafana application to access it, this is the place to export it. | ✅ | ❌ |
We use Lerna for packages versioning and releases.
All packages are versioned according to the current Grafana version:
Please note that the @grafana/api-clients package is considered ALPHA even though it is not released as an alpha version.
Even though packages are released under a stable version, they are considered ALPHA until further notice!
Stable releases are published under the latest tag on npm. If there was alpha/beta version released previously, the next tag is updated to stable version.
Alpha and beta releases are published under the next tag on npm.
Every commit to main that has changes within the packages directory is a subject of npm packages release. ALL packages must be released under version from lerna.json file with the drone build number added to it:
<lerna.json version>-<DRONE_BUILD_NUMBER>
All of the steps below must be performed on a release branch, according to Grafana Release Guide.
You must be logged in to NPM as part of Grafana NPM org before attempting to publish to the npm registry.
Run yarn packages:clean script from the root directory. This will delete any previous builds of the packages.
Run yarn packages:prepare script from the root directory. This performs tests on the packages and prompts for the version of the packages. The version should be the same as the one being released.
Run yarn packages:build script that compiles distribution code in packages/grafana-*/dist.
Run yarn packages:pack script to compress each package into npm-artifacts/*.tgz files. This is required for yarn to replace properties in the package.json files declared in the publishConfig property.
Depending on whether or not it's a prerelease:
./scripts/publish-npm-packages.sh --dist-tag 'next' --registry 'https://registry.npmjs.org/' to publish new versions../scripts/publish-npm-packages.sh --dist-tag 'latest' --registry 'https://registry.npmjs.org/' to publish new versions../scripts/publish-npm-packages.sh --dist-tag 'test' --registry 'https://registry.npmjs.org/' to publish test versions.Revert any changes made by the packages:prepare script.
To build individual packages, run:
yarn packages:build --scope=@grafana/<data|e2e|e2e-selectors|runtime|schema|ui>
A known issue with @grafana/* packages is that a lot of times we discover problems on canary channel(see versioning overview) when the version was already pushed to npm.
We can easily avoid that by setting up a local packages registry and test the packages before actually publishing to npm.
In this guide you will set up Verdaccio registry locally to fake npm registry. This will enable testing @grafana/* packages without the need for pushing to main.
From your terminal:
devenv/local-npm directory.docker compose up. This will start your local npm registry, available at http://localhost:4873/.@grafana packages published to your local npm registry uncomment npmScopes and unsafeHttpWhitelist properties in the .yarnrc file.You need to follow manual packages release procedure. The only difference is the last command in order to publish to you local registry.
From your terminal:
yarn packages:clean.yarn packages:prepare.yarn packages:build.yarn packages:pack.NPM_TOKEN=NONE ./scripts/publish-npm-packages.sh.Locally published packages will be published under dev or canary channel, so in your plugin package.json file you can use that channel. For example:
// plugin's package.json
dependencies: {
//... other dependencies
"@grafana/data": "dev" // or canary
}
or you can instruct npm to install directly the specific version you published.
To use your local published package in another package you'll have to create an .npmrc file in that repository and add the following line:
@grafana:registry=http://localhost:4873/
Make sure there is no other line already defined for @grafana.