2020-07-13 16:47:01 +02:00
|
|
|
|
[[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].
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== 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
|
2020-11-24 09:46:19 +01:00
|
|
|
|
* Are you loading a minimal amount of JS code in the browser?
|
|
|
|
|
** See <<plugin-performance>> for more guidance.
|
2020-07-13 16:47:01 +02:00
|
|
|
|
* 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]?
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== Accessibility
|
|
|
|
|
|
|
|
|
|
Did you know {kib} makes a public statement about our commitment to
|
|
|
|
|
creating an accessible product for people with disabilities?
|
|
|
|
|
https://www.elastic.co/guide/en/kibana/master/accessibility.html[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]]
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== 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}/packages/kbn-i18n/GUIDELINE.md[i18n
|
|
|
|
|
guidelines]
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== Conventions
|
|
|
|
|
|
|
|
|
|
* Become familiar with our
|
|
|
|
|
{kib-repo}blob/{branch}/STYLEGUIDE.md[styleguide]
|
|
|
|
|
(use Typescript!)
|
|
|
|
|
* Write all new code on
|
|
|
|
|
{kib-repo}blob/{branch}/src/core/README.md[the
|
|
|
|
|
platform], and following
|
2020-08-26 15:30:47 +02:00
|
|
|
|
{kib-repo}blob/{branch}/src/core/CONVENTIONS.md[conventions].
|
2020-07-13 16:47:01 +02:00
|
|
|
|
* _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.
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== 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.md[Data
|
|
|
|
|
services]
|
|
|
|
|
** {kib-repo}tree/{branch}/src/plugins/data/public/search/README.md[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}tree/{branch}/src/plugins/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/plugins/ui_actions/README.md[UiActions]
|
|
|
|
|
** Let other plugins inject functionality into your application
|
|
|
|
|
** Inject custom functionality into other plugins
|
|
|
|
|
* Stateless helper utilities
|
|
|
|
|
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/docs/state_sync/README.md[state
|
|
|
|
|
syncing] and
|
|
|
|
|
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/docs/state_containers/README.md[state
|
|
|
|
|
container] utilities provided by
|
|
|
|
|
* {kib-repo}tree/{branch}/src/plugins/kibana_utils/README.md[kibana_utils]
|
|
|
|
|
if you want to sync your application state to the URL?
|
|
|
|
|
** {kib-repo}tree/{branch}/src/plugins/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.
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== Backward compatibility
|
|
|
|
|
|
2020-08-24 17:31:27 +02:00
|
|
|
|
Eventually we want to guarantee to our plugin developers that their plugins will not break from minor to minor.
|
2020-07-13 16:47:01 +02:00
|
|
|
|
|
|
|
|
|
Any time you create or change a public API, keep this in mind, and consider potential
|
|
|
|
|
backward compatibility issues. While we have a formal
|
|
|
|
|
{kib-repo}tree/{branch}/src/core/server/saved_objects/migrations/README.md[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.
|
|
|
|
|
|
2020-09-15 14:08:30 +02:00
|
|
|
|
[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.
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
[discrete]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
=== Testing & stability
|
|
|
|
|
|
|
|
|
|
Review:
|
|
|
|
|
|
|
|
|
|
* <<development-unit-tests>>
|
|
|
|
|
* <<stability>>
|
|
|
|
|
* <<security-best-practices>>
|
2020-10-06 08:46:56 +02:00
|
|
|
|
* <<typescript>>
|
2020-07-13 16:47:01 +02:00
|
|
|
|
|
2020-11-24 09:46:19 +01:00
|
|
|
|
include::performance.asciidoc[leveloffset=+1]
|
|
|
|
|
|
2020-09-15 14:08:30 +02:00
|
|
|
|
include::navigation.asciidoc[leveloffset=+1]
|
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
include::stability.asciidoc[leveloffset=+1]
|
2020-07-13 16:47:01 +02:00
|
|
|
|
|
2020-07-16 16:13:51 +02:00
|
|
|
|
include::security.asciidoc[leveloffset=+1]
|
2020-10-06 08:46:56 +02:00
|
|
|
|
|
|
|
|
|
include::typescript.asciidoc[leveloffset=+1]
|