grafana/packages/README.md

Grafana frontend packages

Exporting code conventions

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:

1. 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"
     }
   }
   

2. If you add exports to your package you must export the package.json file.

3. 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.	✅	❌

Versioning

We use Lerna for packages versioning and releases.

All packages are versioned according to the current Grafana version:

• Grafana v6.3.0-alpha1 -> @grafana/* packages @ 6.3.0-alpha.1
• Grafana v6.2.5 -> @grafana/* packages @ 6.2.5
• Grafana - main branch version (based on package.json, i.e. 6.4.0-pre) -> @grafana/* packages @ 6.4.0-pre- (see details below about packages publishing channels)

Please note that the @grafana/api-clients package is considered ALPHA even though it is not released as an alpha version.

Stable releases

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

Alpha and beta releases are published under the next tag on npm.

Automatic prereleases

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>

Manual release

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.

1. Run yarn packages:clean script from the root directory. This will delete any previous builds of the packages.

2. 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.

   • Make sure you use semver convention. So, place a dot between prerelease id and prerelease number, i.e. 6.3.0-alpha.1
   • Make sure you confirm the version bump when prompted!

3. Run yarn packages:build script that compiles distribution code in packages/grafana-*/dist.

4. 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.

5. Depending on whether or not it's a prerelease:

   • When releasing a prerelease run ./scripts/publish-npm-packages.sh --dist-tag 'next' --registry 'https://registry.npmjs.org/' to publish new versions.
   • When releasing a stable version run ./scripts/publish-npm-packages.sh --dist-tag 'latest' --registry 'https://registry.npmjs.org/' to publish new versions.
   • When releasing a test version run ./scripts/publish-npm-packages.sh --dist-tag 'test' --registry 'https://registry.npmjs.org/' to publish test versions.

6. Revert any changes made by the packages:prepare script.

Building individual packages

To build individual packages, run:

yarn packages:build --scope=@grafana/<data|e2e|e2e-selectors|runtime|schema|ui>

Setting up @grafana/* packages for local development

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.

Setting up local npm registry

From your terminal:

1. Navigate to devenv/local-npm directory.
2. Run docker compose up. This will start your local npm registry, available at http://localhost:4873/.
3. To test @grafana packages published to your local npm registry uncomment npmScopes and unsafeHttpWhitelist properties in the .yarnrc file.

Publishing packages to local npm registry

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:

1. Run yarn packages:clean.
2. Run yarn packages:prepare.
3. Run yarn packages:build.
4. Run yarn packages:pack.
5. Run NPM_TOKEN=NONE ./scripts/publish-npm-packages.sh.
6. Navigate to http://localhost:4873 and verify the version was published

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.

Using your local package in another package (e.g. a plugin)

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.