embedded api

docs/chart.js

@@ -0,0 +1,11 @@
+import {FileAttachment} from "npm:@observablehq/stdlib";
+import * as Plot from "npm:@observablehq/plot";
+
+export async function Chart() {
+  const gistemp = await FileAttachment("./lib/gistemp.csv").csv({typed: true});
+  return Plot.plot({
+    y: {grid: true},
+    color: {scheme: "burd"},
+    marks: [Plot.dot(gistemp, {x: "Date", y: "Anomaly", stroke: "Anomaly"}), Plot.ruleY([0])]
+  });
+}

docs/config.md

@@ -157,7 +157,7 @@ Whether to show the previous & next links in the footer; defaults to true. The p
 
 ## dynamicPaths <a href="https://github.com/observablehq/framework/releases/tag/v1.11.0" class="observablehq-version-badge" data-version="^1.11.0" title="Added in 1.11.0"></a>
 
-The list of [parameterized pages](./params) and [dynamic pages](./page-loaders) to generate, either as a (synchronous) iterable of strings, or a function that returns an async iterable of strings if you wish to load the list of dynamic pages asynchronously.
+The list of [parameterized pages](./params), [dynamic pages](./page-loaders), and [embedded modules](./embeds) to generate, either as a (synchronous) iterable of strings, or a function that returns an async iterable of strings if you wish to load the list of dynamic pages asynchronously.
 
 ## head
 

docs/data-loaders.md

@@ -1,5 +1,5 @@
 ---
-keywords: server-side rendering, ssr
+keywords: server-side rendering, ssr, polyglot
 ---
 
 # Data loaders
@@ -11,7 +11,7 @@ Why static snapshots? Performance is critical for dashboards: users don’t like
 <div class="tip">Data loaders are optional. You can use <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch">fetch</a></code> or <code><a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">WebSocket</a></code> if you prefer to load data at runtime, or you can store data in static files.</div>
 <div class="tip">You can use <a href="./deploying">continuous deployment</a> to rebuild data as often as you like, ensuring that data is always up-to-date.</div>
 
-Data loaders can be written in any programming language. They can even invoke binary executables such as ffmpeg or DuckDB. For convenience, Framework has built-in support for common languages: JavaScript, TypeScript, Python, and R. Naturally you can use any third-party library or SDK for these languages, too.
+Data loaders are polyglot: they can be written in any programming language. They can even invoke binary executables such as ffmpeg or DuckDB. For convenience, Framework has built-in support for common languages: JavaScript, TypeScript, Python, and R. Naturally you can use any third-party library or SDK for these languages, too.
 
 A data loader can be as simple as a shell script that invokes [curl](https://curl.se/) to fetch recent earthquakes from the [USGS](https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php):
 

docs/embeds.md

@@ -0,0 +1,130 @@
+# Embedded analytics <a href="https://github.com/observablehq/framework/pull/1637" class="observablehq-version-badge" data-version="prerelease" title="Added in #1637"></a>
+
+In addition to generating full-page apps, Framework can generate modules to embed analytics — such as individual charts or tables, or coordinated interactive views — in external applications. Embedded modules take full advantage of Framework’s polyglot, baked data architecture for instant page loads.
+
+Embedded modules are vanilla JavaScript, and behave identically when embedded in an external application as on a Framework page. As always, you can load data from a [data loader](./data-loaders) using [`FileAttachment`](./files), and you can [import](./imports) [self-hosted](./imports#self-hosting-of-npm-imports) local modules and libraries from npm; file and import resolutions are baked into the generated code at build time so that imported modules “just work”.
+
+Embedded modules are often written as component functions that return DOM elements. These functions can take options (or “props”), and typically load their own data. For example, below is a simple `chart.js` module that exports a `Chart` function that renders a scatterplot of global surface temperature data.
+
+```js run=false
+import {FileAttachment} from "npm:@observablehq/stdlib";
+import * as Plot from "npm:@observablehq/plot";
+
+export async function Chart() {
+  const gistemp = await FileAttachment("./lib/gistemp.csv").csv({typed: true});
+  return Plot.plot({
+    y: {grid: true},
+    color: {scheme: "burd"},
+    marks: [
+      Plot.dot(gistemp, {x: "Date", y: "Anomaly", stroke: "Anomaly"}),
+      Plot.ruleY([0])
+    ]
+  });
+}
+```
+
+<div class="note">
+
+When Framework builds your app, any transitive static imports are preloaded automatically when the embedded module is imported. This ensures optimal performance by avoiding long request chains.
+
+</div>
+
+## Embedding modules
+
+To allow a module to be embedded in an external application, declare the module’s path in your [config file](./config) using the [**dynamicPaths** option](./config#dynamic-paths). For example, to embed a single component named `chart.js`:
+
+```js run=false
+export default {
+  dynamicPaths: [
+    "/chart.js"
+  ]
+};
+```
+
+Or for [parameterized routes](./params), name the component `product-[id]/chart.js`, then load a list of product identifiers from a database with a SQL query:
+
+```js run=false
+import postgres from "postgres";
+
+const sql = postgres(); // Note: uses psql environment variables
+
+export default {
+  async *dynamicPaths() {
+    for await (const {id} of sql`SELECT id FROM products`.cursor()) {
+      yield `/product-${id}/chart.js`;
+    }
+  }
+};
+```
+
+An embedded component can be imported into a vanilla web application like so:
+
+```html run=false
+<script type="module">
+
+import {Chart} from "https://my-workspace.observablehq.cloud/my-app/chart.js";
+
+document.body.append(await Chart());
+
+</script>
+```
+
+<div class="note">
+
+The code above assumes the Framework app is called “my-app” and that it’s deployed to Observable Cloud in the workspace named “my-workspace”.
+
+</div>
+
+<div class="note">
+
+If the external (host) application is on a different origin than the Framework app — for example, if the host application is on example.com and the Framework app is on app.example.com — then you will need to [enable CORS](https://enable-cors.org/) on app.example.com or use a proxy to forward requests from example.com to app.example.com for same-origin serving.
+
+</div>
+
+In React, you can do something similar using [dynamic import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import) and [`useEffect`](https://react.dev/reference/react/useEffect) and [`useRef`](https://react.dev/reference/react/useRef) hooks:
+
+```jsx run=false
+import {useEffect, useRef} from "react";
+
+export function EmbedChart() {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    let parent = ref.current, child;
+    import("https://my-workspace.observablehq.cloud/my-app/chart.js")
+      .then(({Chart}) => Chart())
+      .then((chart) => parent?.append((child = chart)));
+    return () => ((parent = null), child?.remove());
+  }, []);
+
+  return <div ref={ref} />;
+}
+```
+
+<div class="tip">
+
+Since both dynamic import and the imported component are async, the code above is careful to clean up the effect and avoid race conditions.
+
+</div>
+
+<div class="tip">
+
+You can alternatively embed Framework pages using [iframe embeds](https://observablehq.observablehq.cloud/framework-example-responsive-iframe/).
+
+</div>
+
+## Developing modules
+
+To develop your component, you can import it into a Framework page like normal, giving you instant reactivity as you make changes to the component or its data.
+
+```js echo
+import {Chart} from "./chart.js";
+```
+
+To instantiate the imported component, simply call the function:
+
+```js echo
+Chart()
+```
+
+A Framework page can serve as live documentation for your component: you can describe and demonstrate all the states and options for your component, and review the behavior visually.

observablehq.config.ts

@@ -32,6 +32,7 @@ export default {
     {name: "Themes", path: "/themes"},
     {name: "Page loaders", path: "/page-loaders"},
     {name: "Parameterized routes", path: "/params"},
+    {name: "Embedded analytics", path: "/embeds"},
     {name: "Configuration", path: "/config"},
     {name: "Examples", path: "https://github.com/observablehq/framework/tree/main/examples"},
     {
@@ -89,6 +90,7 @@ export default {
     {name: "Contributing", path: "/contributing", pager: false}
   ],
   dynamicPaths: [
+    "/chart.js",
     "/theme/dark",
     "/theme/dark-alt",
     "/theme/dashboard",

package.json

@@ -19,7 +19,7 @@
     "observable": "dist/bin/observable.js"
   },
   "scripts": {
-    "dev": "tsx watch --ignore docs --no-warnings=ExperimentalWarning ./src/bin/observable.ts preview --no-open",
+    "dev": "tsx watch --ignore docs --no-warnings=ExperimentalWarning ./src/bin/observable.ts preview --no-open --cors",
     "docs:build": "tsx --no-warnings=ExperimentalWarning ./src/bin/observable.ts build",
     "docs:deploy": "tsx --no-warnings=ExperimentalWarning ./src/bin/observable.ts deploy",
     "build": "rimraf dist && node build.js --outdir=dist --outbase=src \"src/**/*.{ts,js,css}\" --ignore \"**/*.d.ts\"",

src/bin/observable.ts

@@ -155,28 +155,41 @@ try {
           ...CONFIG_OPTION,
           host: {
             type: "string",
-            default: "127.0.0.1"
+            default: "127.0.0.1",
+            description: "the server host; use 0.0.0.0 to accept external connections"
           },
           port: {
-            type: "string"
+            type: "string",
+            description: "the server port; defaults to 3000 (or higher if unavailable)"
+          },
+          cors: {
+            type: "boolean",
+            description: "allow cross-origin requests on all origins (*)"
+          },
+          "allow-origin": {
+            type: "string",
+            multiple: true,
+            description: "allow cross-origin requests on a specific origin"
           },
           open: {
             type: "boolean",
-            default: true
+            default: true,
+            description: "open browser"
           },
           "no-open": {
             type: "boolean"
           }
         }
       });
-      const {config, root, host, port, open} = values;
+      const {config, root, host, port, open, cors, ["allow-origin"]: origins} = values;
       await readConfig(config, root); // Ensure the config is valid.
       await import("../preview.js").then(async (preview) =>
         preview.preview({
           config,
           root,
           hostname: host!,
           port: port === undefined ? undefined : +port,
+          origins: cors ? ["*"] : origins,
           open
         })
       );