From d810af1d42c9161e9da7021ffdd05c727c4f30d0 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Mon, 11 Oct 2021 16:46:09 -0400 Subject: [PATCH 01/10] Update kibana_platform_plugin_intro.mdx --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 133b96f44da88..cd2d24f482142 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -35,11 +35,13 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana If it's stateful, it has to go in a plugin, but packages are often a good choices for stateless utilities. Stateless code exported publicly from a plugin will increase the page load bundle size of _every single page_, even if none of those plugin's services are actually needed. With packages, however, only code that is needed for the current page is downloaded. -The downside however is that the packages folder is far away from the plugins folder so having a part of your code in a plugin and the rest in a package may make it hard to find, leading to duplication. +There a couple downsides however to packages. One is that the folder is far away from the plugins folder so actively works against our . Having a part of your code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to resolve this conundrum by supporting co-located packages and plugins and automatically putting all stateless code inside a package. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). -The Operations team hopes to resolve this conundrum by supporting co-located packages and plugins and automatically putting all stateless code inside a package. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). +The other con is that developing in packages tends to be slower. You have to run `yarn kbn watch` to have changes rebuilt automatically, and the rebuild time is typically longer than it would be for the same code in a plugin. -Until then, consider whether it makes sense to logically separate the code, and consider the size of the exports, when determining whether you should put stateless public exports in a package or a plugin. +It's important to understand that moving code to a package will not magically lower the plugin bundle size. The best way to do this is by async loading which you can read more about under . Having the code in a package will however make it easier for consumers to async import your code it when they need it. + +As you can see, the answer to "Should I put my code in a plugin or a package" is 'It Depends'. If you are still having a hard time determining what the best path location is, reach out to the Kibana Operations Team (#kibana-operations) for help. From 3cc0e12f55e3a3bde43ecdeab6723ce9af56c37c Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 15:23:17 -0400 Subject: [PATCH 02/10] updates --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index cd2d24f482142..cfe11f5f9d010 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -35,9 +35,11 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana If it's stateful, it has to go in a plugin, but packages are often a good choices for stateless utilities. Stateless code exported publicly from a plugin will increase the page load bundle size of _every single page_, even if none of those plugin's services are actually needed. With packages, however, only code that is needed for the current page is downloaded. -There a couple downsides however to packages. One is that the folder is far away from the plugins folder so actively works against our . Having a part of your code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to resolve this conundrum by supporting co-located packages and plugins and automatically putting all stateless code inside a package. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). +There a couple downsides however to packages: -The other con is that developing in packages tends to be slower. You have to run `yarn kbn watch` to have changes rebuilt automatically, and the rebuild time is typically longer than it would be for the same code in a plugin. +1. It's not . The packages folder is far away from the plugins folder. Having your stateless code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to resolve this conundrum by supporting co-located packages and plugins and automatically putting all stateless code inside a package. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). + +2. Performance issues and development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically, and the rebuild time is typically longer than it would be for the same code in a plugin. The reason it's slower to build is captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. It's important to understand that moving code to a package will not magically lower the plugin bundle size. The best way to do this is by async loading which you can read more about under . Having the code in a package will however make it easier for consumers to async import your code it when they need it. From b8bd5559e241677fac21a334c6dcf11064b124fa Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 15:25:53 -0400 Subject: [PATCH 03/10] Update kibana_platform_plugin_intro.mdx --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index cfe11f5f9d010..fc0a383065646 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -35,9 +35,9 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana If it's stateful, it has to go in a plugin, but packages are often a good choices for stateless utilities. Stateless code exported publicly from a plugin will increase the page load bundle size of _every single page_, even if none of those plugin's services are actually needed. With packages, however, only code that is needed for the current page is downloaded. -There a couple downsides however to packages: +There a couple downsides to packages: -1. It's not . The packages folder is far away from the plugins folder. Having your stateless code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to resolve this conundrum by supporting co-located packages and plugins and automatically putting all stateless code inside a package. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). +1. It's not . The packages folder is far away from the plugins folder. Having your stateless code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to fix this by supporting packages and plugins existing in the same folder. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). 2. Performance issues and development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically, and the rebuild time is typically longer than it would be for the same code in a plugin. The reason it's slower to build is captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. From 034eb8d41ab34d7e17509b1995ecd3c3a652cc63 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 16:10:59 -0400 Subject: [PATCH 04/10] Update kibana_platform_plugin_intro.mdx --- .../key_concepts/kibana_platform_plugin_intro.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index fc0a383065646..a37489ad2106d 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -33,13 +33,20 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana -If it's stateful, it has to go in a plugin, but packages are often a good choices for stateless utilities. Stateless code exported publicly from a plugin will increase the page load bundle size of _every single page_, even if none of those plugin's services are actually needed. With packages, however, only code that is needed for the current page is downloaded. + +This is a question developers will not have to ask themselves soon, thanks to the work the Operations team is doing on [Bazel](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md). When that work is complete, all code, including plugins, will reside in a package (though not necessarily the `packages` _folder_, it can be a package inside the `src/plugins` folder). + +In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins`. + +If the code is stateful, it has to go in a plugin, but exporting stateless code from plugins can be problematic because it will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is needed for the current page is downloaded. There a couple downsides to packages: 1. It's not . The packages folder is far away from the plugins folder. Having your stateless code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to fix this by supporting packages and plugins existing in the same folder. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). -2. Performance issues and development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically, and the rebuild time is typically longer than it would be for the same code in a plugin. The reason it's slower to build is captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. +2. Development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically. [Phase II](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md#phase-ii---docs-developer-experience) of the Bazel migration work will bring the development experience on par with plugin development. This work can be tracked here. + +3. Performance issues. Rebuild time is typically longer than it would be for the same code in a plugin. The reason it's slower to build is captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. It's important to understand that moving code to a package will not magically lower the plugin bundle size. The best way to do this is by async loading which you can read more about under . Having the code in a package will however make it easier for consumers to async import your code it when they need it. From ffa674747bd8a5e70d25fc76957791fa2bc6face Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 16:32:23 -0400 Subject: [PATCH 05/10] Update kibana_platform_plugin_intro.mdx --- .../kibana_platform_plugin_intro.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index a37489ad2106d..6f2ad3debdd41 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -33,22 +33,26 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana - This is a question developers will not have to ask themselves soon, thanks to the work the Operations team is doing on [Bazel](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md). When that work is complete, all code, including plugins, will reside in a package (though not necessarily the `packages` _folder_, it can be a package inside the `src/plugins` folder). In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins`. -If the code is stateful, it has to go in a plugin, but exporting stateless code from plugins can be problematic because it will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is needed for the current page is downloaded. -There a couple downsides to packages: +**If the code is stateful, it has to be exposed from a plugin's . Do not statically export stateful code.** + +Benefits to packages: + +1. _Potentially_ reduced page load time. All code that is statically exported from plugins will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is needed for the current page is downloaded. +2. Puts the consumer is in charge of how and when to async import. If a consumer async imports code exported from a plugin, it makes no difference, because of the above point. It's already been downloaded. However, simply moving code into a package is _not_ a guaranteed performance improvement. It does give the consumer the power to make smart performance choices, however. If they require code from multiple packages, the consumer can async import from multiple packages at the same time. Read more in our . + +Downsides to packages: 1. It's not . The packages folder is far away from the plugins folder. Having your stateless code in a plugin and the rest in a package may make it hard to find, leading to duplication. The Operations team hopes to fix this by supporting packages and plugins existing in the same folder. You can track this work by following [this issue](https://github.com/elastic/kibana/issues/112886). -2. Development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically. [Phase II](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md#phase-ii---docs-developer-experience) of the Bazel migration work will bring the development experience on par with plugin development. This work can be tracked here. +2. Development overhead. Developers have to run `yarn kbn watch` to have changes rebuilt automatically. [Phase II](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md#phase-ii---docs-developer-experience) of the Bazel migration work will bring the development experience on par with plugin development. This work can be tracked [here](https://github.com/elastic/kibana/issues/104519). -3. Performance issues. Rebuild time is typically longer than it would be for the same code in a plugin. The reason it's slower to build is captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. +3. Development performance. Rebuild time is typically longer than it would be for the same code in a plugin. The reasons are captured in [this issue](https://github.com/elastic/kibana/issues/107648). The ops team is actively working to reduce this performance increase. -It's important to understand that moving code to a package will not magically lower the plugin bundle size. The best way to do this is by async loading which you can read more about under . Having the code in a package will however make it easier for consumers to async import your code it when they need it. As you can see, the answer to "Should I put my code in a plugin or a package" is 'It Depends'. If you are still having a hard time determining what the best path location is, reach out to the Kibana Operations Team (#kibana-operations) for help. From 0741605fd7a97217486905355a8a08b881744472 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 16:45:34 -0400 Subject: [PATCH 06/10] Update dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Co-authored-by: Tyler Smalley --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 6f2ad3debdd41..c882215a4f76e 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -35,7 +35,7 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana This is a question developers will not have to ask themselves soon, thanks to the work the Operations team is doing on [Bazel](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md). When that work is complete, all code, including plugins, will reside in a package (though not necessarily the `packages` _folder_, it can be a package inside the `src/plugins` folder). -In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins`. +In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins` or `x-pack/plugins`. **If the code is stateful, it has to be exposed from a plugin's . Do not statically export stateful code.** From 786e86fdd7c11151587ff63d9d7346c2bb62caaa Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Tue, 12 Oct 2021 16:45:49 -0400 Subject: [PATCH 07/10] Update dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Co-authored-by: Tyler Smalley --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index c882215a4f76e..45dd4acdb54f7 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -33,7 +33,7 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana -This is a question developers will not have to ask themselves soon, thanks to the work the Operations team is doing on [Bazel](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md). When that work is complete, all code, including plugins, will reside in a package (though not necessarily the `packages` _folder_, it can be a package inside the `src/plugins` folder). +When the [Bazel migration](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md) is complete, all code, including plugins, will be a package. With that, packages won't be required to be in the `packages` directory and can be located to somewhere that makes more sense structurally. In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins` or `x-pack/plugins`. From 0d6823cd4e3e47107ff9a5357872d739b980ed64 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Wed, 13 Oct 2021 09:31:09 -0400 Subject: [PATCH 08/10] Update dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Co-authored-by: Tyler Smalley --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 45dd4acdb54f7..0dc87a91af1a0 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -42,7 +42,7 @@ In the meantime, the following can be used to determine whether it makes sense t Benefits to packages: -1. _Potentially_ reduced page load time. All code that is statically exported from plugins will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is needed for the current page is downloaded. +1. _Potentially_ reduced page load time. All code that is statically exported from plugins will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is imported is download, which can be minimized by using async imports. 2. Puts the consumer is in charge of how and when to async import. If a consumer async imports code exported from a plugin, it makes no difference, because of the above point. It's already been downloaded. However, simply moving code into a package is _not_ a guaranteed performance improvement. It does give the consumer the power to make smart performance choices, however. If they require code from multiple packages, the consumer can async import from multiple packages at the same time. Read more in our . Downsides to packages: From cf037b90dc3d4e6520c2c82651c875d17950eb88 Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Wed, 13 Oct 2021 11:46:40 -0400 Subject: [PATCH 09/10] Update dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Co-authored-by: Brandon Kobel --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 0dc87a91af1a0..641bc9be0788d 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -33,7 +33,7 @@ At a super high-level, Kibana is composed of **plugins**, **core**, and **Kibana -When the [Bazel migration](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md) is complete, all code, including plugins, will be a package. With that, packages won't be required to be in the `packages` directory and can be located to somewhere that makes more sense structurally. +When the [Bazel migration](https://github.com/elastic/kibana/blob/master/legacy_rfcs/text/0015_bazel.md) is complete, all code, including plugins, will be a package. With that, packages won't be required to be in the `packages/` directory and can be located somewhere that makes more sense structurally. In the meantime, the following can be used to determine whether it makes sense to add code to a package inside the `packages` folder, or a plugin inside `src/plugins` or `x-pack/plugins`. From 01ff69909fe534a96e838fde3e8c47e0b35e4d3e Mon Sep 17 00:00:00 2001 From: Stacey Gammon Date: Wed, 13 Oct 2021 11:46:53 -0400 Subject: [PATCH 10/10] Update dev_docs/key_concepts/kibana_platform_plugin_intro.mdx Co-authored-by: Brandon Kobel --- dev_docs/key_concepts/kibana_platform_plugin_intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx index 641bc9be0788d..737b9d8708f29 100644 --- a/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx +++ b/dev_docs/key_concepts/kibana_platform_plugin_intro.mdx @@ -42,7 +42,7 @@ In the meantime, the following can be used to determine whether it makes sense t Benefits to packages: -1. _Potentially_ reduced page load time. All code that is statically exported from plugins will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is imported is download, which can be minimized by using async imports. +1. _Potentially_ reduced page load time. All code that is statically exported from plugins will be downloaded on _every single page load_, even if that code isn't needed. With packages, only code that is imported is downloaded, which can be minimized by using async imports. 2. Puts the consumer is in charge of how and when to async import. If a consumer async imports code exported from a plugin, it makes no difference, because of the above point. It's already been downloaded. However, simply moving code into a package is _not_ a guaranteed performance improvement. It does give the consumer the power to make smart performance choices, however. If they require code from multiple packages, the consumer can async import from multiple packages at the same time. Read more in our . Downsides to packages: