kibana/docs/developer/best-practices/index.asciidoc

[[development-best-practices]]
== Best practices

Consider these best practices, whether developing code directly to the {kib} repo or building your own plugins.
They are intended to support our https://github.com/elastic/engineering/blob/master/kibana_dev_principles.md[{kib} development principals].

[discrete]
=== Performance

Are you planning with scalability in mind?

* Consider data with many fields
* Consider data with high cardinality fields
* Consider large data sets, that span a long time range
* Are you loading a minimal amount of JS code in the browser?
** See <<plugin-performance>> for more guidance.
* Do you make lots of requests to the server?
** If so, have you considered using the streaming {kib-repo}tree/{branch}/src/plugins/bfetch[bfetch service]?

[discrete]
=== Accessibility

Did you know {kib} makes a public statement about our commitment to
creating an accessible product for people with disabilities?
<<accessibility,We do>>!
It’s very important all of our apps are accessible.

* Learn how https://elastic.github.io/eui/#/guidelines/accessibility[EUI
tackles accessibility]
* If you don’t use EUI, follow the same EUI accessibility standards

[[kibana-localization-best-practices]]
[discrete]
=== Localization

{kib} is translated into other languages. Use our i18n utilities to
ensure your public facing strings will be translated to ensure all
{kib} apps are localized.

* Read and adhere to our
{kib-repo}blob/{branch}/src/platform/packages/shared/kbn-i18n/GUIDELINE.md[i18n
guidelines]

[discrete]
=== Conventions

* Become familiar with our
{kib-repo}blob/{branch}/STYLEGUIDE.mdx[styleguide]
(use Typescript!)
* Write all new code on
{kib-repo}blob/{branch}/src/core/README.md[the
platform], and following
{kib-repo}blob/{branch}/src/core/CONVENTIONS.md[conventions].
* _Always_ use the `SavedObjectClient` for reading and writing Saved
Objects.
* Add `README`s to all your plugins and services.
* Make your public APIs as small as possible. You will have to maintain
them, and consider backward compatibility when making any changes to
them.
* Use https://elastic.github.io/eui[EUI] for all your basic UI
components to create a consistent UI experience.

[discrete]
=== Re-inventing the wheel

Over-refactoring can be a problem in it’s own right, but it’s still
important to be aware of the existing services that are out there and
use them when it makes sense. We have service oriented teams dedicated
to providing our solution developers the tools needed to iterate faster.
They take care of the nitty gritty so you can focus on creative
solutions to your particular problem sphere. Some examples of common
services you should consider:

* {kib-repo}tree/{branch}/src/plugins/data/README.mdx[Data
services]
** {kib-repo}tree/{branch}/src/plugins/data/README.mdx#search[Search
strategies]
*** Use the `esSearchStrategy` to make raw queries to ES that will
support async searching and partial results, as well as injecting the
right advanced settings like whether to include frozen indices or not.
* {kib-repo}blob/{branch}/src/platform/plugins/shared/embeddable/README.md[Embeddables]
** Rendering maps, visualizations, dashboards in your application
** Register new widgets that will can be added to a dashboard or Canvas
workpad, or rendered in another plugin.
* {kib-repo}tree/{branch}/src/platform/plugins/shared/ui_actions/README.asciidoc[UiActions]
** Let other plugins inject functionality into your application
** Inject custom functionality into other plugins
* Stateless helper utilities
* {kib-repo}tree/{branch}/src/platform/plugins/shared/kibana_utils/docs/state_sync/README.md[state
syncing] and
* {kib-repo}tree/{branch}/src/platform/plugins/shared/kibana_utils/docs/state_containers/README.md[state
container] utilities provided by
* {kib-repo}tree/{branch}/src/platform/plugins/shared/kibana_utils/README.md[kibana_utils]
if you want to sync your application state to the URL?
** {kib-repo}tree/{branch}/src/platform/plugins/shared/kibana_react/README.md[kibana_react]
for react specific helpers

Re-using these services will help create a consistent experience across
{kib} from every solution.

[discrete]
=== Backward compatibility

Eventually we want to guarantee to our plugin developers that their plugins will not break from minor to minor.

Any time you create or change a public API, keep this in mind, and consider potential
backward compatibility issues. While we have a formal
saved
object migration system and are working on adding a formal state migration system, introducing state changes and migrations in a
minor always comes with a risk. Consider this before making huge and
risky changes in minors, _especially_ to saved objects.

* Are you persisting state from registries? Consider what will happen if
the author of the implementation changed their interfaces.
* Are you adding implementations to registries? Consider that someone
may be persisting your data, and that making changes to your public
interfaces can break their code.

Be very careful when changing the shape of saved objects or persistable
data.

Saved object exported from past {kib} versions should continue to work.
In addition, if users are relying on state stored in your app’s URL as
part of your public contract, keep in mind that you may also need to
provide backwards compatibility for bookmarked URLs.

[discrete]
=== Routing, Navigation and URL

The {kib} platform provides a set of tools to help developers build consistent experience around routing and browser navigation.
Some of that tooling is inside `core`, some is available as part of various plugins.

<<kibana-navigation, Follow this guide>> to get an idea of available tools and common approaches for handling routing and browser navigation.

[discrete]
=== Testing & stability

Review:

* <<development-unit-tests>>
* <<stability>>
* <<security-best-practices>>
* <<typescript>>

include::performance.asciidoc[leveloffset=+1]

include::navigation.asciidoc[leveloffset=+1]

include::stability.asciidoc[leveloffset=+1]

include::security.asciidoc[leveloffset=+1]

include::typescript.asciidoc[leveloffset=+1]