Jack Westbrook
5bedcc7bd7
* build(frontend): enable custom condition for resolving source files during dev and build * feat(packages): apply conditional name to export properties * chore(packages): add standard exports to flamegraph and prometheus * chore(packages): resolve main, module, types to built files * build(packages): clean up prepare-npm-package for custom condition changes * refactor(packages): reduce repetition in conditional exports * build(storybook): add @grafana-app/source to conditionNames * test(frontend): add grafana-app/source customCondition for jest tests * refactor(frontend): remove nested package import paths * chore(jest): use customExportConditions for source files and browser * chore(i18n): use src for ./eslint-plugin export * chore(packages): set packages tsconfigs to moduleResolution bundler * chore(packages): fix rollup builds * build(packages): build cjs as multiple files * chore(sql): reference MonitoringLogger for moduleresolution bundler to pass typecheck * chore(ui): add type refs for moduleresolution bundler to pass typecheck * feat(schema): add exports for cleaner import paths * refactor(frontend): clean up schema paths to point to exports instead of nested file paths * build(storybook): hack the builder-manager for custom conditions to resolve * build(decoupled-plugins): fix broken builds due to missing conditionNames * chore(e2e): pass condition to playwright to resolve local packages * build(frontend): fix failing build * chore(select): fix typings * style(frontend): clean up eslint suppressions * chore(packages): fix type errors due to incorrect tsconfig settings * build(generate-apis): use swc with ts-node and moduleResolution bundler * chore(cypress): add conditionNames to resolve monorepo packages * build(npm): update prepare to work with latest exports changes * build(packages): fix prepare-npm-package script * fix(e2e-selectors): update debugoverlay for data-testid change * build(packages): stop editing package.json at pack n publish time * rerun ci * chore(api-clients): use moduleResolution: bundler for customConditions support * chore(api-clients): fix generation * build(packages): remove aliasing exports, remove exports with only customConditions * Revert "refactor(frontend): clean up schema paths to point to exports instead of nested file paths" This reverts commit 7949b6ea0e60e51989d2a8149b7a24647cd68916. * revert(schema): remove exports from package so builds work * build(api-clients): fix up api-clients exports and rollup config * build(api-clients): Update generated package exports for api clients * build(schema): add overrides to cjsOutput and esmOutput so built directory structure is correct * fix(packages): use rootDirs to prevent types/src directories in built d.ts file paths * build(packages): prevent empty exports added to package.json during pack * docs(packages): update readme with custom conditions information --------- Co-authored-by: Tom Ratcliffe <tom.ratcliffe@grafana.com>
140 lines
7.9 KiB
Markdown
140 lines
7.9 KiB
Markdown
# 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](https://www.typescriptlang.org/tsconfig/#customConditions) `@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:
|
|
|
|
```json
|
|
"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](https://github.com/lerna/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-<COMMIT-SHA> (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](#Versioning)) 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](https://verdaccio.org/) 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](#manual-release). 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`.
|