Merge branch 'master' of github.com:elastic/kibana into unify-search-3

STYLEGUIDE.md → STYLEGUIDE.mdx

@@ -1,15 +1,15 @@
-# Kibana Style Guide
+---
+id: kibStyleGuide
+slug: /kibana-dev-docs/styleguide
+title: StyleGuide
+summary: JavaScript/TypeScript styleguide.
+date: 2021-05-06
+tags: ['kibana', 'onboarding', 'dev', 'styleguide', 'typescript', 'javascript']
+---
 
 This guide applies to all development within the Kibana project and is
 recommended for the development of all Kibana plugins.
 
-- [General](#general)
-- [HTML](#html)
-- [API endpoints](#api-endpoints)
-- [TypeScript/JavaScript](#typeScript/javaScript)
-- [SASS files](#sass-files)
-- [React](#react)
-
 Besides the content in this style guide, the following style guides may also apply
 to all development within the Kibana project. Please make sure to also read them:
 
@@ -52,9 +52,7 @@ This part contains style guide rules around general (framework agnostic) HTML us
 Use camel case for the values of attributes such as `id` and `data-test-subj` selectors.
 
 ```html
-<button id="veryImportantButton" data-test-subj="clickMeButton">
-  Click me
-</button>
+<button id="veryImportantButton" data-test-subj="clickMeButton">Click me</button>
 ```
 
 The only exception is in cases where you're dynamically creating the value, and you need to use
@@ -378,6 +376,20 @@ import inFoo from 'foo/child';
 import inSibling from '../foo/child';
 ```
 
+#### Avoid export \* in top level index.ts files
+
+The exports in `common/index.ts`, `public/index.ts` and `server/index.ts` dictate a plugin's public API. The public API should be carefully controlled, and using `export *` makes it very easy for a developer working on internal changes to export a new public API unintentionally.
+
+```js
+// good
+export { foo } from 'foo';
+export { child } from './child';
+
+// bad
+export * from 'foo/child';
+export * from '../foo/child';
+```
+
 ### Global definitions
 
 Don't do this. Everything should be wrapped in a module that can be depended on
@@ -592,20 +604,20 @@ Do not use setters, they cause more problems than they can solve.
 ### Avoid circular dependencies
 
 As part of a future effort to use correct and idempotent build tools we need our code to be
-able to be represented as a directed acyclic graph. We must avoid having circular dependencies 
-both on code and type imports to achieve that. One of the most critical parts is the plugins 
-code. We've developed a tool to identify plugins with circular dependencies which 
-has allowed us to build a list of plugins who have circular dependencies 
-between each other. 
-
-When building plugins we should avoid importing from plugins 
-who are known to have circular dependencies at the moment as well as introducing 
-new circular dependencies. You can run the same tool we use on our CI locally by 
-typing `node scripts/find_plugins_with_circular_deps --debug`. It will error out in 
-case new circular dependencies has been added with your changes 
+able to be represented as a directed acyclic graph. We must avoid having circular dependencies
+both on code and type imports to achieve that. One of the most critical parts is the plugins
+code. We've developed a tool to identify plugins with circular dependencies which
+has allowed us to build a list of plugins who have circular dependencies
+between each other.
+
+When building plugins we should avoid importing from plugins
+who are known to have circular dependencies at the moment as well as introducing
+new circular dependencies. You can run the same tool we use on our CI locally by
+typing `node scripts/find_plugins_with_circular_deps --debug`. It will error out in
+case new circular dependencies has been added with your changes
 (which will also happen in the CI) as well as print out the current list of
-the known circular dependencies which, as mentioned before, should not be imported 
-by your code until the circular dependencies on these have been solved. 
+the known circular dependencies which, as mentioned before, should not be imported
+by your code until the circular dependencies on these have been solved.
 
 ## SASS files
 
@@ -626,10 +638,8 @@ import './component.scss';
 // All other imports below the SASS import
 
 export const Component = () => {
-  return (
-    <div className="plgComponent" />
-  );
-}
+  return <div className="plgComponent" />;
+};
 ```
 
 ```scss