From 61475ab5fe2dccfa1a0796487234b3c26b0ee531 Mon Sep 17 00:00:00 2001
From: spalger <email@spalger.com>
Date: Tue, 15 May 2018 17:23:40 -0700
Subject: [PATCH] [docs] expand typescript mentions in plugin docs

---
 .../development-plugin-resources.asciidoc     | 22 ++++++++++++++++++-
 packages/kbn-plugin-helpers/README.md         | 17 +++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/docs/development/plugin/development-plugin-resources.asciidoc b/docs/development/plugin/development-plugin-resources.asciidoc
index c4a46cde0464f90..ef05fad1b6027b5 100644
--- a/docs/development/plugin/development-plugin-resources.asciidoc
+++ b/docs/development/plugin/development-plugin-resources.asciidoc
@@ -51,4 +51,24 @@ The Kibana directory must be named `kibana`, and your plugin directory must be l
 If you're developing a plugin that has a user interface, take a look at our https://elastic.github.io/eui[Elastic UI Framework].
 It documents the CSS and React components we use to build Kibana's user interface.
 
-You're welcome to use these components, but be aware that they are rapidly evolving and we might introduce breaking changes that will disrupt your plugin's UI.
\ No newline at end of file
+You're welcome to use these components, but be aware that they are rapidly evolving and we might introduce breaking changes that will disrupt your plugin's UI.
+
+[float]
+==== TypeScript Support
+Plugin code can be written in http://www.typescriptlang.org/[TypeScript] if desired. To enable TypeScript support create a `tsconfig.json` file at the root of your plugin that looks something like this:
+
+["source","js"]
+-----------
+{
+  // extend Kibana's tsconfig, or use your own settings
+  "extends": "../../kibana/tsconfig.json",
+
+  // tell the TypeScript compiler where to find your source files
+  "include": [
+    "server/**/*",
+    "public/**/*"
+  ]
+}
+-----------
+
+TypeScript code is automatically converted into JavaScript during development, but not in the distributable version of Kibana. If you use the {repo}blob/{branch}/packages/kbn-plugin-helpers[@kbn/plugin-helpers] to build your plugin then your `.ts` and `.tsx` files will be permanently transpiled before your plugin is archived. If you have your own build process, make sure to run the TypeScript compiler on your source files and ship the compilation output so that your plugin will work with the distributable version of Kibana.
diff --git a/packages/kbn-plugin-helpers/README.md b/packages/kbn-plugin-helpers/README.md
index 328faedd4d5408f..d2b2e6966545b72 100644
--- a/packages/kbn-plugin-helpers/README.md
+++ b/packages/kbn-plugin-helpers/README.md
@@ -76,4 +76,19 @@ Setting | Description
 
 ## TypeScript support
 
-Plugin code that runs in the browser can be written in [TypeScript](http://www.typescriptlang.org/) if desired. During development the Kibana Optimizer will transform your TypeScript into JavaScript automatically, but that does not happen in production mode. Instead, when building plugins with the plugin-helpers, the `tsconfig.json` file at the root of the plugin is temporarily copied into the build and the local `tsc` executable is used to transpile `.ts` and `.tsx` files into `.js` files that will ultimately be included in the built version of the plugin. All `.ts`, `.tsx`, and `.d.ts` files will be removed along with the `tsconfig.json` file before archiving the built version of your plugin.
+Plugin code can be written in [TypeScript](http://www.typescriptlang.org/) if desired. To enable TypeScript support create a `tsconfig.json` file at the root of your plugin that looks something like this:
+
+```js
+{
+  // extend Kibana's tsconfig, or use your own settings
+  "extends": "../../kibana/tsconfig.json",
+
+  // tell the TypeScript compiler where to find your source files
+  "include": [
+    "server/**/*",
+    "public/**/*"
+  ]
+}
+```
+
+> NOTE: If you define a custom `buildSourcePatterns`, make sure to include your `tsconfig.json` file so that the build task will transpile your `.ts` files into `.js` files before archiving your plugin.