Merge pull request #1 from observablehq/mythmon/241118/readme

Author: mythmon

README.md

@@ -1,36 +1,67 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Framework Embedded Analtycs in Next.js
 
-## Getting Started
+This repository is an example of importing a JS module from a [Observable Cloud](https://observablehq.com/documentation/data-apps/) data app using signed URLs and embedding it in a [Next.js](https://nextjs.org) site using Next.js's App router. The Observable Cloud data app provides charts of the number of medals won by countries in the 2024 Olympic Games, optionally broken down by continent.
 
-First, run the development server:
+## Tour
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+The repository uses Observable Cloud's *signed URLs* feature, which enables secure embedding for private data apps. In this example the data app is public, for demonstration purposes.
+
+The entry point for embedding is in [`src/app/page.tsx`](https://github.com/observablehq/nextjs-observable-embed/blob/main/src/app/page.tsx), which renders on the host application server and uses a React component to render the embed.
+
+```tsx
+<ObservableEmbed
+  module="https://observablehq.observablehq.cloud/olympian-embeds/medals-chart.js"
+  importName="MedalsChart"
+/>
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+The `ObservableEmbed` component is imported from `src/components/observableEmbed/server.tsx`, and is a server-only component. Because of that it has access to the private key used to make signed URLs. [`jose`](https://github.com/panva/jose) is used to generate the JWT for the signed URL:
+
+```tsx
+const parsedUrl = new URL(url);
+const now = Date.now();
+const notBefore = now - (now % SIGNATURE_ALIGN_MS);
+const notAfter = notBefore + SIGNATURE_VALIDITY_MS;
+const token = await new SignJWT({"urn:observablehq:path": parsedUrl.pathname})
+  .setProtectedHeader({alg: "EdDSA"})
+  .setSubject("nextjs-example")
+  .setNotBefore(notBefore / 1000)
+  .setExpirationTime(notAfter / 1000)
+  .sign(privateKey);
+```
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+This token is passed to the component `ObservableEmbedClient`, imported from `src/components/observableEmbed/client.tsx`. This is a client-only component, responsible for rendering the embed in the browser. It uses the signed URL generated by the Next.js server to import the module from Observable Cloud, and renders the imported component into the DOM:
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```tsx
+const ref = useRef<HTMLDivElement | null>(null);
 
-## Learn More
+useEffect(() => {
+  (async () => {
+    const target = ref.current;
+    if (!target) return;
+    while (target.firstChild) target.removeChild(target.firstChild);
+    const mod = await import(/* webpackIgnore: true */ module);
+    const component = mod[importName];
+    const element = component instanceof Function ? await component() : component;
+    target.append(element);
+  })();
+}, [importName, module]);
 
-To learn more about Next.js, take a look at the following resources:
+return <div ref={ref} />;
+```
+
+## Development
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Install dependencies:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+```sh
+yarn install
+```
 
-## Deploy on Vercel
+Run the development server:
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+```sh
+yarn dev
+```
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.

src/components/observableEmbed/client.tsx

@@ -16,10 +16,10 @@ export const ObservableEmbedClient: React.FC<ObservableEmbedProps> = ({
     (async () => {
       const target = ref.current;
       if (!target) return;
+      while (target.firstChild) target.removeChild(target.firstChild);
       const mod = await import(/* webpackIgnore: true */ module);
       const component = mod[importName];
       const element = component instanceof Function ? await component() : component;
-      target.innerHTML = "";
       target.append(element);
     })();
   }, [importName, module]);

src/components/observableEmbed/server.tsx

@@ -19,23 +19,21 @@ export const ObservableEmbed: React.FC<ObservableEmbedProps> = async ({ module,
   return <ObservableEmbedClient module={signedUrl.href} importName={importName} />;
 }
 
-async function signUrl(url: string | URL): Promise<URL> {
-  if (typeof url === "string") {
-    url = new URL(url);
-  }
+async function signUrl(url: string): Promise<URL> {
+  const parsedUrl = new URL(url);
   if (!privateKey) {
     console.warn("No private key available for signing");
-    return url;
+    return parsedUrl;
   }
   const now = Date.now();
   const notBefore = now - (now % SIGNATURE_ALIGN_MS);
   const notAfter = notBefore + SIGNATURE_VALIDITY_MS;
-  const token = await new SignJWT({"urn:observablehq:path": url.pathname})
+  const token = await new SignJWT({"urn:observablehq:path": parsedUrl.pathname})
     .setProtectedHeader({alg: "EdDSA"})
     .setSubject("nextjs-example")
     .setNotBefore(notBefore / 1000)
     .setExpirationTime(notAfter / 1000)
     .sign(privateKey);
-  url.searchParams.set("token", token);
-  return url;
+  parsedUrl.searchParams.set("token", token);
+  return parsedUrl;
 }