Skip to content

Latest commit

 

History

History
153 lines (120 loc) · 6 KB

index.asciidoc

File metadata and controls

153 lines (120 loc) · 6 KB
Raw

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 {kib} development principals.

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?

  • 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]?

Accessibility

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

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]

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 {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 EUI for all your basic UI components to create a consistent UI experience.

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.

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 {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.

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.

Follow this guide to get an idea of available tools and common approaches for handling routing and browser navigation.

Testing & stability

Review: