2018-02-14 17:08:14 +01:00
# Kibana-related packages
2017-04-19 13:31:00 +02:00
2018-02-14 17:08:14 +01:00
This folder contains packages that are intended for use in Kibana and Kibana
plugins.
2017-04-19 13:31:00 +02:00
2018-02-14 17:08:14 +01:00
tl;dr:
- Don't publish to npm registry
- Always use the `@kbn` namespace
- Always set `"private": true` in `package.json`
## Using these packages
We no longer publish these packages to the npm registry. Now, instead of
2018-12-04 01:01:16 +01:00
specifying a version when including these packages, we rely on yarn workspaces,
which sets up a symlink to the package.
2018-02-14 17:08:14 +01:00
2018-12-04 01:01:16 +01:00
For example if you want to use the `@kbn/i18n` package in Kibana itself, you
2018-02-14 17:08:14 +01:00
can specify the dependency like this:
```
2018-12-04 01:01:16 +01:00
"@kbn/i18n": "1.0.0"
2018-02-14 17:08:14 +01:00
```
2018-12-04 01:01:16 +01:00
However, if you want to use this from a Kibana plugin, you need to use a `link:`
dependency and account for the relative location of the Kibana repo, so it would
instead be:
2018-02-14 17:08:14 +01:00
```
2018-12-04 01:01:16 +01:00
"@kbn/i18n": "link:../../kibana/packages/kbn-i18n"
2018-02-14 17:08:14 +01:00
```
How all of this works is described in more detail in the
2018-02-14 18:57:13 +01:00
[`@kbn/pm` docs ](./kbn-pm#how-it-works ).
2018-02-14 17:08:14 +01:00
## Creating a new package
Create a new sub-folder. The name of the folder should mirror the `name` in the
2018-12-04 01:01:16 +01:00
package's `package.json` . E.g. if the name is `@kbn/i18n` the folder name
should be `kbn-i18n` .
2018-02-14 17:08:14 +01:00
All new packages should use the `@kbn` namespace, and should be marked with
`"private": true` .
2017-04-19 13:31:00 +02:00
2018-03-15 08:31:15 +01:00
## Unit tests for a package
2021-01-15 22:17:25 +01:00
Currently there is only one tool being used in order to test packages which is Jest. Below we will explain how it should be done.
2018-03-15 08:31:15 +01:00
2021-01-15 22:17:25 +01:00
### Jest
A package should follow the pattern of having `.test.js` files as siblings of the source code files, and these run by Jest.
2018-03-15 08:31:15 +01:00
A package using the `.test.js` naming convention will have those tests automatically picked up by Jest and run by the unit test runner, currently mapped to the Kibana `test` script in the root `package.json` .
* `yarn test` or `yarn grunt test` runs all unit tests.
2020-12-02 20:42:23 +01:00
* `yarn jest` runs all Jest tests in Kibana.
2018-03-15 08:31:15 +01:00
2021-01-15 22:17:25 +01:00
In order for the plugin or package to use Jest, a jest.config.js file must be present in it's root. However, there are safeguards for this in CI should a test file be added without a corresponding config file.
2018-03-15 08:31:15 +01:00
----
Each package can also specify its own `test` script in the package's `package.json` , for cases where you'd prefer to run the tests from the local package directory.