Update docs

lib/kino/js.ex

@@ -150,39 +150,54 @@ defmodule Kino.JS do
       choice. When the user selects a secret, `callback` is called
       with the secret name
 
-  ## CDN
-
-  It is possible to use a regular JavaScript bundler for generating
-  the assets, however in many cases a simpler and preferred approach
-  is to import the necessary dependencies directly from a CDN.
+  ## Dependencies
+
+  On the JavaScript side you are free to use any external packages and
+  bundling tooling, as long as you provide the `main.js` file with the
+  `init(ctx, data)` entrypoing. Kino itself defines a couple components
+  using `Kino.JS` and we use [esbuild](https://esbuild.github.io) to
+  bundle their assets, but it's entirely up to you.
+
+  For simple components that don't require additional dependencies,
+  it may be totally fine to write a single JS/CSS file without any
+  bundling. Theoretically, you could even import dependencies from a
+  CDN, however, we do recommend bundling dependencies with your assets
+  because: (a) occasionally content from CDNs may get blocked; (b) most
+  users run Livebook locally, so fetching assets from the local server
+  is actually faster than fetching from a CDN; (c) nowadays many packages
+  actually assume their end users use a bundler.
+
+  To give a concrete example, let's say we want to render a graph using
+  `mermaid`. We would define an NPM project at `assets/mermaid`, with
+  regular `package.json` and the following `main.js` file:
+
+  ```javascript
+  import mermaid from "mermaid";
+
+  mermaid.initialize({ startOnLoad: false });
+
+  export function init(ctx, graph) {
+    mermaid.render("graph1", graph, (svgSource, bindListeners) => {
+      ctx.root.innerHTML = svgSource;
+      bindListeners && bindListeners(ctx.root);
+    });
+  }
+  ```
 
-  To give a concrete example, here's how we could use the `mermaid`
-  JavaScript package for rendering diagrams:
+  Next, we would bundle the file into `lib/assets/mermaid/build/main.js`,
+  and reference in our Elixir module:
 
       defmodule KinoDocs.Mermaid do
         use Kino.JS
 
+        use Kino.JS, assets_path: "lib/assets/mermaid/build"
+
         def new(graph) do
           Kino.JS.new(__MODULE__, graph)
         end
-
-        asset "main.js" do
-          """
-          import "https://cdn.jsdelivr.net/npm/[email protected]/dist/mermaid.min.js";
-
-          mermaid.initialize({ startOnLoad: false });
-
-          export function init(ctx, graph) {
-            mermaid.render("graph1", graph, (svgSource, bindListeners) => {
-              ctx.root.innerHTML = svgSource;
-              bindListeners && bindListeners(ctx.root);
-            });
-          }
-          """
-        end
       end
 
-  And we would use it like so:
+  With all that, we would use the component like so:
 
       KinoDocs.Mermaid.new("""
       graph TD;
@@ -192,6 +207,16 @@ defmodule Kino.JS do
         C-->D;
       """)
 
+  > #### Directory structure {: .info}
+  >
+  > Note that we intentionally suggest keeping the NPM project in the
+  > `assets/` directory, but placing the bundle output in `lib/assets/`.
+  > This convention ensures that you do not include the assets source
+  > (including `node_modules/`) in the Hex package, but you do include
+  > the bundled assets. While it is possible to specify which directories
+  > are published to Hex, following the convention makes everything work
+  > as expected by default.
+
   ## Live kinos
 
   So far we covered the API for defining static kinos, where the

mix.lock

@@ -1,12 +1,12 @@
 %{
   "complex": {:hex, :complex, "0.4.2", "923e5db0be13dbb3ea00cf8459d9f75f3afdd9ff5a82742ded21064330d28273", [:mix], [], "hexpm", "069a085ef820ce675a2619fd125b963ff4514af2102c7f7d7965128e5ec0a429"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.33", "3c3fd9673bb5dcc9edc28dd90f50c87ce506d1f71b70e3de69aa8154bc695d44", [:mix], [], "hexpm", "2d526833729b59b9fdb85785078697c72ac5e5066350663e5be6a1182da61b8f"},
-  "ex_doc": {:hex, :ex_doc, "0.29.4", "6257ecbb20c7396b1fe5accd55b7b0d23f44b6aa18017b415cb4c2b91d997729", [:mix], [{:earmark_parser, "~> 1.4.31", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "2c6699a737ae46cb61e4ed012af931b57b699643b24dabe2400a8168414bc4f5"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
+  "ex_doc": {:hex, :ex_doc, "0.31.1", "8a2355ac42b1cc7b2379da9e40243f2670143721dd50748bf6c3b1184dae2089", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "3178c3a407c557d8343479e1ff117a96fd31bafe52a039079593fb0524ef61b0"},
   "fss": {:hex, :fss, "0.1.0", "4118001edca820baba4b68c3295e92a7e9b80bbcd34abbfd9cf46f180e407595", [:mix], [], "hexpm", "c9659bf4a5438f0b2150629a3345b9370a8daca297554b8267a8708520e37ac7"},
-  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
+  "makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.2", "ad87296a092a46e03b7e9b0be7631ddcf64c790fa68a9ef5323b6cbb36affc72", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f3f5a1ca93ce6e092d92b6d9c049bcda58a3b617a8d888f8e7231c85630e8108"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.3.1", "2c54013ecf170e249e9291ed0a62e5832f70a476c61da16f6aac6dca0189f2af", [:mix], [], "hexpm", "2682e3c0b2eb58d90c6375fc0cc30bc7be06f365bf72608804fb9cffa5e1b167"},
+  "makeup_erlang": {:hex, :makeup_erlang, "0.1.3", "d684f4bac8690e70b06eb52dad65d26de2eefa44cd19d64a8095e1417df7c8fd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "b78dc853d2e670ff6390b605d807263bf606da3c82be37f9d7f68635bd886fc9"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
   "nx": {:hex, :nx, "0.4.0", "2ec2cebec6a9ac8a3d5ae8ef79345cf92f37f9018d50817684e51e97b86f3d36", [:mix], [{:complex, "~> 0.4.2", [hex: :complex, repo: "hexpm", optional: false]}], "hexpm", "bab955768dadfe2208723fbffc9255341b023291f2aabcbd25bf98167dd3399e"},
   "table": {:hex, :table, "0.1.2", "87ad1125f5b70c5dea0307aa633194083eb5182ec537efc94e96af08937e14a8", [:mix], [], "hexpm", "7e99bc7efef806315c7e65640724bf165c3061cdc5d854060f74468367065029"},
 }