- Kibana Guide: other versions:
- What is Kibana?
- What’s new in 8.13
- Kibana concepts
- Quick start
- Set up
- Install Kibana
- Configure Kibana
- Alerting and action settings
- APM settings
- Banners settings
- Cases settings
- Enterprise Search settings
- Fleet settings
- i18n settings
- Logging settings
- Logs settings
- Metrics settings
- Monitoring settings
- Reporting settings
- Search sessions settings
- Secure settings
- Security settings
- Spaces settings
- Task Manager settings
- Telemetry settings
- URL drilldown settings
- Start and stop Kibana
- Access Kibana
- Securing access to Kibana
- Add data
- Upgrade Kibana
- Configure security
- Configure reporting
- Configure logging
- Configure monitoring
- Command line tools
- Production considerations
- Discover
- Dashboard and visualizations
- Canvas
- Maps
- Build a map to compare metrics by country or region
- Track, visualize, and alert on assets in real time
- Map custom regions with reverse geocoding
- Heat map layer
- Tile layer
- Vector layer
- Plot big data
- Search geographic data
- Configure map settings
- Connect to Elastic Maps Service
- Import geospatial data
- Troubleshoot
- Reporting and sharing
- Machine learning
- Graph
- Alerting
- Observability
- APM
- Set up
- Get started
- How-to guides
- Configure APM agents with central config
- Control access to APM data
- Create an alert
- Create custom links
- Filter data
- Find transaction latency and failure correlations
- Identify deployment details for APM agents
- Integrate with machine learning
- Exploring mobile sessions with Discover
- Viewing sessions with Discover
- Observe Lambda functions
- Query your data
- Storage Explorer
- Track deployments with annotations
- Users and privileges
- Settings
- REST API
- Troubleshooting
- Security
- Dev Tools
- Fleet
- Osquery
- Stack Monitoring
- Stack Management
- REST API
- Get features API
- Kibana spaces APIs
- Kibana role management APIs
- User session management APIs
- Saved objects APIs
- Data views API
- Get all data views
- Get data view
- Create data view
- Update data view
- Delete data view
- Swap references preview
- Swap references
- Get default data view
- Set default data view
- Update data view fields metadata
- Get runtime field
- Create runtime field
- Upsert runtime field
- Update runtime field
- Delete runtime field
- Index patterns APIs
- Alerting APIs
- Action and connector APIs
- Cases APIs
- Add comment
- Create case
- Delete cases
- Delete comments
- Find case activity
- Find cases
- Find connectors
- Get alerts
- Get case activity
- Get case
- Get case status
- Get cases by alert
- Get comments
- Get configuration
- Get reporters
- Get tags
- Push case
- Set configuration
- Update cases
- Update comment
- Update configuration
- Import and export dashboard APIs
- Logstash configuration management APIs
- Machine learning APIs
- Osquery manager API
- Short URLs APIs
- Get Task Manager health
- Upgrade assistant APIs
- Synthetics APIs
- Uptime APIs
- Kibana plugins
- Troubleshooting
- Accessibility
- Release notes
- Kibana 8.13.4
- Kibana 8.13.3
- Kibana 8.13.2
- Kibana 8.13.1
- Kibana 8.13.0
- Kibana 8.12.2
- Kibana 8.12.1
- Kibana 8.12.0
- Kibana 8.11.4
- Kibana 8.11.3
- Kibana 8.11.2
- Kibana 8.11.1
- Kibana 8.11.0
- Kibana 8.10.4
- Kibana 8.10.3
- Kibana 8.10.2
- Kibana 8.10.1
- Kibana 8.10.0
- Kibana 8.9.2
- Kibana 8.9.1
- Kibana 8.9.0
- Kibana 8.8.2
- Kibana 8.8.1
- Kibana 8.8.0
- Kibana 8.7.1
- Kibana 8.7.0
- Kibana 8.6.1
- Kibana 8.6.0
- Kibana 8.5.2
- Kibana 8.5.1
- Kibana 8.5.0
- Kibana 8.4.3
- Kibana 8.4.2
- Kibana 8.4.1
- Kibana 8.4.0
- Kibana 8.3.3
- Kibana 8.3.2
- Kibana 8.3.1
- Kibana 8.3.0
- Kibana 8.2.3
- Kibana 8.2.2
- Kibana 8.2.1
- Kibana 8.2.0
- Kibana 8.1.3
- Kibana 8.1.2
- Kibana 8.1.1
- Kibana 8.1.0
- Kibana 8.0.0
- Kibana 8.0.0-rc2
- Kibana 8.0.0-rc1
- Kibana 8.0.0-beta1
- Kibana 8.0.0-alpha2
- Kibana 8.0.0-alpha1
- Developer guide
Typescript
editTypescript
editAlthough this is not a requirement, we encourage if all new code is developed in Typescript.
Project references
editKibana has crossed the 2m LoC mark. The current situation creates some scaling problems when the default out-of-the-box setup stops working. As a result, developers suffer from slow project compilation and IDE unresponsiveness. As a part of Developer Experience project, we are migrating our tooling to use built-in TypeScript features addressing the scaling problems - project references & incremental builds
In a nutshell - instead of compiling the whole Kibana codebase at once, this setup enforces splitting the code base into independent projects that form a directed acyclic graph (DAG). This allows the TypeScript compiler (tsc
) to apply several advanced optimizations:
-
Every project emits
public
interfaces in the form ofd.ts
type declarations generated by the TypeScript compiler -
These generated
d.ts
type declarations are used whenever a referenced project is imported in a depending project - This makes it possible to determine which project needs rebuilding when the source code has changed to use a more aggressive caching strategy.
More details are available in the official docs
Caveats
editThis architecture imposes several limitations to which we must comply:
- Projects cannot have circular dependencies. Even though the Kibana platform doesn’t support circular dependencies between Kibana plugins, TypeScript (and ES6 modules) does allow circular imports between files. So in theory, you may face a problem when migrating to the TS project references and you will have to resolve this circular dependency. We’ve built a tool that can be used to find such problems. Please read the prerequisites section below to know how to use it.
-
A project must emit its type declaration. It’s not always possible to generate a type declaration if the compiler cannot infer a type. There are two basic cases:
- Your plugin exports a type inferring an internal type declared in Kibana codebase. In this case, you’ll have to either export an internal type or to declare an exported type explicitly.
- Your plugin exports something inferring a type from a 3rd party library that doesn’t export this type. To fix the problem, you have to declare the exported type manually.
Prerequisites
editSince project refs rely on generated d.ts
files, the migration order does matter. You can migrate your plugin only when all the plugin dependencies already have migrated. It creates a situation where commonly used plugins (such as data
or kibana_react
) have to migrate first.
Run node scripts/find_plugins_without_ts_refs.js --id your_plugin_id
to get a list of plugins that should be switched to TS project refs to unblock your plugin migration.
Additionally, in order to migrate into project refs, you also need to make sure your plugin doesn’t have circular dependencies with other plugins both on code and type imports. We run a job in the CI for each PR trying to find if new circular dependencies are being added which runs our tool with node scripts/find_plugins_with_circular_deps
. However there are also a couple of circular dependencies already identified and that are in an allowed list to be solved. You also need to make sure your plugin don’t rely in any other plugin into that allowed list. For a complete overview of the circular dependencies both found and in the allowed list as well as the complete circular dependencies path please run the following script locally with the debug flag node scripts/find_plugins_with_circular_deps --debug
.
Implementation
edit-
Make sure all the plugins listed as dependencies in requiredPlugins, optionalPlugins & requiredBundles properties of
kibana.json
manifest file have migrated to TS project references. -
Add
tsconfig.json
in the root folder of your plugin.
{ "extends": "../../../tsconfig.base.json", "compilerOptions": { "outDir": "./target/types", "emitDeclarationOnly": true, "declaration": true, "declarationMap": true }, "include": [ // add all the folders containing files to be compiled ], "references": [ { "path": "../../core/tsconfig.json" }, // add references to other TypeScript projects your plugin depends on ] }
If your plugin imports a file not listed in include
, the build will fail with the next message File ‘…’ is not listed within the file list of project …’. Projects must list all files or use an 'include' pattern.
-
Build you plugin
./node_modules/.bin/tsc -b src/plugins/my_plugin
. Fix errors iftsc
cannot generate type declarations for your project. -
Add your project reference to
references
property oftsconfig.refs.json
-
Add your plugin to
references
property and plugin folder toexclude
property of thetsconfig.json
it used to belong to (for example, forsrc/plugins/**
it’stsconfig.json
; forx-pack/plugins/**
it’sx-pack/tsconfig.json
). -
List the reference to your newly created project in all the Kibana
tsconfig.json
files that could import your project:tsconfig.json
,test/tsconfig.json
,x-pack/tsconfig.json
,x-pack/test/tsconfig.json
. And in all the plugin-specifictsconfig.refs.json
for dependent plugins. -
You can measure how your changes affect
tsc
compiler performance withnode --max-old-space-size=4096 ./node_modules/.bin/tsc -p tsconfig.json --extendedDiagnostics --noEmit
. Compare withmaster
branch.
You can use https://github.com/elastic/kibana/pull/79446 as an example.
ElasticON events are back!
Learn about the Elastic Search AI Platform from the experts at our live events.
Register now