31:T4da,# Framework Guide #3: Importing Functions, NPM Modules, and Observable Notebooks

Feel free to refer to [_this Github Repository_](https://github.com/kimryan0416/Observable-Framework-Demo), which contains the _Framework_ project that this guide is based off of.

Previously, we [_set up our Framework project_](https://observablehq.com/@rk2546/guide-local_observable_setup) and covered the basics of [_project structure_](https://observablehq.com/@rk2546/guide-project_structure). In this guide, we'll be covering the following topics: 1. [Importing Custom Functions from JavaScript Files](#cell-15) 2. [Importing NPM Modules](#cell-55) 3. [Importing Observable Notebooks](#cell-81) 4. [Importing an Entire Observable Notebook](#cell-130)

[NOTE]: At this point, you are expected to have an (close to) empty _Framework_ project setup from our previous guide. You are also expected to be familiar with basic levels of [Markdown syntax](https://www.markdownguide.org/), [HTML](https://www.w3schools.com/html/html_intro.asp), and JavaScript.

32:T435,### Step 2: Import the NPM module + Export Functions Inside our JavaScript file, let's import [_the popular movie quotes module_](https://www.npmjs.com/package/popular-movie-quotes) and create an export function that can be accessed throughout the entire project. Keep in mind the syntax with the `import` statement below:

// For NPM modules, there is a required `npm:` part prepended to the name of the module
import quotes from "npm:popular-movie-quotes";

// Export a function that lets us query the module and get all quotes.
export function GetAllQuotes() {
    return quotes.getAll();
}

[NOTE]: In a more generic Node.js project, you would import the NPM module via command line (ex. `npm i `. You _can_ do the same with Observable, but the process becomes a bit more complicated. In _Framework_, you do **not** need to import the NPM module via command line; the `npm:` import statement here tells _Framework_ to import it, if you haven't already.

33:[{"id":"0056941e37cb2a015b27cc240557600eda4dfcafcb0733a1010d6f72b7cf783475b76e8bd40329e42cf789724909375a1ca2c2c8b98895df0bc36df81b7cc9ec","href":"https://static.observableusercontent.com/files/0056941e37cb2a015b27cc240557600eda4dfcafcb0733a1010d6f72b7cf783475b76e8bd40329e42cf789724909375a1ca2c2c8b98895df0bc36df81b7cc9ec","name":"framework_chart@1.png","type":"image/png","lastModified":1760711968978.387,"size":26745},{"id":"c10b47a010a774da191a90cdef5d2c3f728424439192855f1cc2c0e223ef91648c3da375b4f22b7847d890a37051befe258506ba6bd7e0b33ea4e89288cfb0bd","href":"https://static.observableusercontent.com/files/c10b47a010a774da191a90cdef5d2c3f728424439192855f1cc2c0e223ef91648c3da375b4f22b7847d890a37051befe258506ba6bd7e0b33ea4e89288cfb0bd","name":"iris_uncolored.png","type":"image/png","lastModified":1760711001947.439,"size":138800},{"id":"9a33fd3a0ce9a1c8116403d5cbad6dbd06adb4013fa4ed9783d891539ed5530fca7f48106da059882170c91db2bede7b5241e429e28855feb580a06014e50c57","href":"https://static.observableusercontent.com/files/9a33fd3a0ce9a1c8116403d5cbad6dbd06adb4013fa4ed9783d891539ed5530fca7f48106da059882170c91db2bede7b5241e429e28855feb580a06014e50c57","name":"iris.csv","type":"text/csv","lastModified":1760711145884.162,"size":5107},{"id":"bbdb35f4aaa5649155e413615cbcf39c446d742cfb52a201c372b297c55928f781197ebde49af2396a28e33232b2dd1d28cac12a616b7128d4c50d1dc3202b61","href":"https://static.observableusercontent.com/files/bbdb35f4aaa5649155e413615cbcf39c446d742cfb52a201c372b297c55928f781197ebde49af2396a28e33232b2dd1d28cac12a616b7128d4c50d1dc3202b61","name":"notebook.png","type":"image/png","lastModified":1760715859915.341,"size":35339}] 2f:{"title":"Framework Guide #3: Importing Functions, NPM Modules, and Observable Notebooks","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":15,"value":"## 1. Importing Custom Functions from JavaScript Files\n\nConsider this example scenario: after looking at [Anderson's Iris Dataset](https://en.wikipedia.org/wiki/Iris_flower_data_set), which we've already covered in our [_Week 4 Exercise_](https://observablehq.com/@rk2546/2025-infovis-cse_exercise-4), we've rendered a D3 chart representing the relationship between \"Sepal Length\" and \"Petal Length\".","pinned":false,"hidden":false,"mode":"md"},{"id":52,"value":"iris_dataset","pinned":false,"hidden":false,"mode":"ojs"},{"id":50,"value":"We've generated the following chart in our _Framework_ project, but we've yet to color the points by \"Species\". This should look familiar to you:\n\n${await FileAttachment(\"iris_uncolored.png\").image({width:800})}\n\nIn past exercises, we would use a custom helper function, `unique()`, to extract all unique values from an array of strings. We would then use it to create a color scale that would map each Species to a color. For our convenience, I posted the helper function below:","pinned":false,"hidden":false,"mode":"md"},{"id":23,"value":"function unique(array) {\n return array.filter((v, i) => array.indexOf(v) === i);\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":30,"value":"We _could_ just copy-paste this function into our JavaScript code on the same page, but what if we wanted to use `unique()` across multiple pages? It would be more optimal to make this helper function available to any other script in our project. Let's do that by creating a separate component script that _exports_ this function.","pinned":false,"hidden":false,"mode":"md"},{"id":32,"value":"### Step 1: Create a `components/` directory + `unique.js` file\n\nLet's create a new `components/` directory inside of our `src/` directory. Inside the new directory, let's create a new JavaScript file, `unique.js`. Your file structure should look something like the following:\n\n

\n${render_filetree({\n    \"src/\": {\n      \"index.md\": null,\n      \"iris.md\": null,\n      \"components/\": { \"unique.js\": null },\n      \"data\": { \"iris.csv\": null },\n  }\n})}\n

","pinned":false,"hidden":false,"mode":"md"},{"id":37,"value":"### Step 2: Add the `unique()` function to `unique.js`\n\nLet's copy-paste the [_`unique()`_](#unique) function below into the new `unique.js` script. You will need to make one modification to it: observe the code below:\n\n

\n// Note the `export` modifier prepended to the function.\nexport function unique(array) {\n  return array.filter((v, i) => array.indexOf(v) === i);\n}\n

","pinned":false,"hidden":false,"mode":"md"},{"id":40,"value":"### Step 3: Importing `unique()` into `index.md`\n\nLet's import our `unique` function and apply it to our scatter plot with the iris dataset. to import the function, add this JavaScript code snippet to the top of `index.md`:\n\n

\n```js\nimport { unique } from \"./components/unique.js\";\n```\n

","pinned":false,"hidden":false,"mode":"md"},{"id":42,"value":"### Step 4: Using our Imports\n\nAt this point, you should be able to use the `unique()` function and create a `color_scale` that colorizes the points based on a divergent color scale (I recommend using tools like [_ColorBrewer_](https://colorbrewer2.org) to help you create an appropriate color scheme). If successful, you should be able to have a more visually interesting chart:\n\n${await FileAttachment(\"framework_chart@1.png\").image({width:400})}","pinned":false,"hidden":false,"mode":"md"},{"id":55,"value":"## 2. Importing NPM Modules\n\nSince you have access to JavaScript, there may be a point where you want to import NPM modules and use them in your JavaScript. This isn't a _common_ thing to do with _Framework_ projects, but let's cover it anyways.\n\nIn the typical Node.js project, you would usually follow these steps:\n\n1. Import your selected NPM module: `npm i `.\n2. Import the NPM module directly into your JavaScript function.\n3. ???\n4. Profit.\n\nUnfortunately, things aren't very simple in _Framework_: **Markdown files cannot import NPM modules**. However, we CAN still import them if we are using a plain JavaScript file. Let's try to do this with [_this NPM module_](https://www.npmjs.com/package/popular-movie-quotes), which provides us a list of popular movie quotes.","pinned":false,"hidden":false,"mode":"md"},{"id":60,"value":"### Step 1: Create a `components/` directory + a new JavaScript file (if needed)\n\nCreate a new `components/` directory inside of our `src/` directory, if you haven't already. Inside the new directory, you can either use an existing JavaScript file (e.g. our `unique.js` script) or create a separate one - it's up to you. In this example, I'm creating a separate file called `quotes.js`:\n\n

\n${render_filetree({\n    \"src/\": {\n      \"index.md\": null,\n      \"iris.md\": null,\n      \"quotes.md\": null,\n      \"components/\": { \"unique.js\": null, \"quotes.js\": null },\n      \"data\": { \"iris.csv\": null },\n  }\n})}\n

\n\nAlso note that we've created a new `quotes.md` file as well inside of `src/`; we'll modify that in Step 3.","pinned":false,"hidden":false,"mode":"md"},{"id":65,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":70,"value":"### Step 3: Import your new functions\n\nAt this stage, you can safely import your new functions into your Markdown files. In our example, I've created a `quotes.md` Markdown file that's a separate page. Inside it, we can import `GetAllQuotes()` and use it accordingly:\n\n

\n# Popular Movie Quotes\n\n```js\nimport { GetAllQuotes } from './components/quotes.js';\n```\n\n```js\nconst quotes = GetAllQuotes();\nconst quotes_lis = quotes.map(q => html`<li>\"${q.quote}\"</li>`);\nconst quotes_html = html`<ul>${quotes_lis}</ul>`;\n\ndisplay(quotes_html);\n```\n

\n\nYou should see a huge list of movie quotes, provided to you by the NPM module.","pinned":false,"hidden":false,"mode":"md"},{"id":81,"value":"## 3. Importing Observable Notebooks\n\nLet's consider a situation where we would import some helper functions from an existing Observable notebook. If you recall in our [_Week 5 Exercise_](https://observablehq.com/@rk2546/2025-infovis-cse_exercise-5), we imported the `Legend` and `Swatches` functions from D3. Here's the code below, which we can safely run in an Observable notebook:","pinned":false,"hidden":false,"mode":"md"},{"id":83,"value":"import {Legend, Swatches} from \"@d3/color-legend\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":86,"value":"The catch, unfortunately, is that **you cannot do the same in Markdown files**. Attempting to do this will lead to errors. This produces a conundrum: _how can we import stuff from Observable notebooks?_","pinned":false,"hidden":false,"mode":"md"},{"id":88,"value":"### The Solution: Importing Notebook _CONTENTS_ into _Framework_\n\nWe can't import raw functions and JavaScript code into our notebook, but we _CAN_ import cells, code blocks, and even entire notebooks into a _Framework_ dashboard. All interactive functions, such as those covered in our [_Week 6 Lab_](https://observablehq.com/@rk2546/2025-infovis-cse_week-6-lab) and [_Week 7 Lab_](https://observablehq.com/@rk2546/2025-infovis-cse_week-7-lab), are also maintained and will work on your _Framework_ page.\n\nThe work flow is thus:\n\n1. Use an Observable Notebook (that's ideally public) to generate your charts and/or interactive elements.\n2. Import the code blocks from that Observable notebook into your _Framework_ pages","pinned":false,"hidden":false,"mode":"md"},{"id":91,"value":"### Use Case: Importing a Chart and its Interactable\n\nObserve the following import below:","pinned":false,"hidden":false,"mode":"md"},{"id":93,"value":"import { ex2, viewof radius } from '@rk2546/2025-infovis-cse_week-7-lab'","pinned":true,"hidden":false,"mode":"ojs"},{"id":96,"value":"If we rendered `ex2` and `radius` into their own code blocks:","pinned":false,"hidden":false,"mode":"md"},{"id":100,"value":"viewof radius;","pinned":true,"hidden":false,"mode":"ojs"},{"id":102,"value":"ex2","pinned":true,"hidden":false,"mode":"ojs"},{"id":104,"value":"The visualization works! This was achievable because _Observable notebooks prefer that every JavaScript code block outputs to a variable_. In the [_original notebook_](https://observablehq.com/@rk2546/2025-infovis-cse_week-7-lab#ex2), this visualization outputted to a variable called `ex2` - this syntax allows us to import the code block and render it here as `ex2`. The same applies with the slider `radius` that came with that visualization. We are careful to also use the `viewof` modifier when importing `radius`, but the two components work together seamlessly in this notebook. Let's try to import these into our own _Framework_ project.","pinned":false,"hidden":false,"mode":"md"},{"id":114,"value":"### Step 1: Prepare your Observable Notebook\n\nThe Observable notebook you are copying from must be public and must have a custom URL (you'll know it's a custom URL once it has `@[USERNAME]/[NOTEBOOK_NAME]` in your noteobok's URL). To do this click the \"Share\" button at the top of your Observable notebook and modify the settings.","pinned":false,"hidden":false,"mode":"md"},{"id":116,"value":"### Step 2: Create an API URL to your Notebook\n\nThis one is a bit complicated. Take note of the URL, which has the format `@[USERNAME]/[NOTEBOOK_NAME]` at the tail end of it. For example, the notebook for [_Week 7's Lab_](https://observablehq.com/@rk2546/2025-infovis-cse_week-7-lab) has this public URL:\n\n

\nhttps://observablehq.com/@rk2546/2025-infovis-cse_week-7-lab\n

\n\nThe tail end of this URL is the following:\n\n

\n@rk2546/2025-infovis-cse_week-7-lab\n

\n\nTake this portion out, and merge it into the following format:\n\n

\nhttps://api.observablehq.com/[TAIL END HERE].js?v=3\n

\n\nThis creates an API access point specifically for your notebook. For example, this notebook's new URL will be:\n\n

\nhttps://api.observablehq.com/@rk2546/2025-infovis-cse_week-7-lab.js?v=3\n

\n\n**Keep a note on this URL - we will use it shortly**.","pinned":false,"hidden":false,"mode":"md"},{"id":107,"value":"### Step 3: Import Runtime and Inspector\n\nEither find an existing Markdown page or create a new Markdown page for this. In this example case, I've created a new page called \"notebook.md\":\n\n

\n${render_filetree({\n    \"src/\": {\n      \"index.md\": null,\n      \"iris.md\": null,\n      \"quotes.md\": null,\n      \"notebook.md\": null,\n      \"components/\": { \"unique.js\": null, \"quotes.js\": null },\n      \"data\": { \"iris.csv\": null },\n  }\n})}\n

\n\nObservable provides helper functions to help render notebook content already. Observe the code below, which imports Observable's `Runtime` class. We also import the `Inspector` class, which allows us to map notebook content to elements in our webpage. These two classes are **crucial**:\n\n

\n```js\nimport {Runtime, Inspector} from \"https://cdn.jsdelivr.net/npm/@observablehq/runtime@5/dist/runtime.js\";\n```\n

","pinned":false,"hidden":false,"mode":"md"},{"id":110,"value":"### Step 4: Import your notebook\n\nWe also want to import our notebook via the URL we created in Step 2. In our example, our API url is:\n\n

\nhttps://api.observablehq.com/@rk2546/2025-infovis-cse_week-7-lab.js?v=3\n

\n\nTo import the notebook contents, add the code below (make sure to replace the URL with your own notebook's URL):\n\n

\n````js\nimport contents from 'https://api.observablehq.com/@rk2546/2025-infovis-cse_week-7-lab.js?v=3';\n````\n

\n\n

[NOTE]: You don't have to use the expression `contents` in the import above. You can use _any_ name - e.g. The [Framework documentation](https://observablehq.com/documentation/embeds/advanced#rendering-cells) uses `import define from...` when importing a notebook. It's up to you want to name the variable as.

","pinned":false,"hidden":false,"mode":"md"},{"id":121,"value":"### Step 5: Create the Appropriate Cells in Your Markdown File\n\nInside of your Markdown page, you need to create HTML elements that the contents from your Observable notebook can slide neatly into. This is done by giving `

` elements (or any other HTML container) an `id` or `class` that uniquely identifies them from other elements on the screen.\n\nIn this example, remember that the cell blocks for the slider and orbiting-circle visualization were named `ex2` and `radius`. Let's make this simple and create two `

` elements with IDs of `ex2` and `radius`:\n\n

\n<div id=\"radius\"></div>\n<div id=\"ex2\"></div>\n

\n\n

[NOTE]: You don't _technically_ need to name them the same ID as their variable names, but we're doing it here just to be clear on what's happening.

","pinned":false,"hidden":false,"mode":"md"},{"id":124,"value":"### Step 6: Run `Runtime` and `Inspector`\n\nNow we need to create a new instance of `Runtime`. This instance will look at our notebook, via `contents`, and copy the notebook contents. During this step, we can tell `Runtime` to render specific cells and use `Inspector` to find our container HTML. Observe the code block below:\n\n

\n````js\nnew Runtime().module(contents, name => {\n  if (name === \"ex2\") return new Inspector(document.querySelector(\"#ex2\"));\n  if (name === \"viewof radius\") return new Inspector(document.querySelector(\"#radius\"));\n});\n````\n\n<div id=\"radius\"></div>\n<div id=\"ex2\"></div>\n

\n\nIn this code block, we created the two `

` elements with the proper IDs. We ran `Runtime()`, and made it so that if it detected any cell blocks named `ex2` or `viewof radius`, then it will insert them into any HTML elements that match the query provided.\n\n${await FileAttachment('notebook.png').image({width: 400})}","pinned":false,"hidden":false,"mode":"md"},{"id":130,"value":"## 4. Importing an Entire Observable Notebook\n\nLet's say that you created a magnum opus Observable notebook, and you'd rather just render the entire notebook to a _Framework_ webpage. Let's try this with _this_ guide notebook.","pinned":false,"hidden":false,"mode":"md"},{"id":138,"value":"### What changes from before?\n\nThe steps are largely the same as the above, except that Step 6 requires different code. For starters, this guide notebook as the following URL:\n\n

\nhttps://observablehq.com/@rk2546/guide-imports\n

\n\nIn the API URL format, it'll look like:\n\n

\nhttps://api.observablehq.com/@rk2546/guide-imports.js?v=3\n

\n\nThen, in your Markdown file, we can import the entire notebook via the following:\n\n

\n````js\nimport guide from 'https://api.observablehq.com/@rk2546/guide-imports.js?v=3';\nnew Runtime().module(guide, Inspector.into());\n````\n

\n\nThe above code is a different syntax, where we are are _inserting_ the contents of our guide notebook into an existing container that may have other content. In this case, we're telling _Framework_ to 1) use `Runtime` to grab the contents of this guide notebook, and 2) insert it into ``.","pinned":false,"hidden":false,"mode":"md"},{"id":140,"value":"### Example in our project\n\nIn our example project, I created a completely separate file called \"guide.md\" in my `src/` directory. Inside it, I included a `

` to insert the notebooks contents into. \n\n

\n${render_filetree({\n    \"src/\": {\n      \"index.md\": null,\n      \"iris.md\": null,\n      \"quotes.md\": null,\n      \"notebook.md\": null,\n      \"guide.md\": null,\n      \"components/\": { \"unique.js\": null, \"quotes.js\": null },\n      \"data\": { \"iris.csv\": null },\n  }\n})}\n

\n\nInside `guide.md`, I've included the following:\n\n

\n# Guide Example\n\n---\n\n<div id=\"guide\"></div>\n\n```js\nimport {Runtime, Inspector} from \"https://cdn.jsdelivr.net/npm/@observablehq/runtime@5/dist/runtime.js\";\n```\n\n```js\nimport guide from 'https://api.observablehq.com/@rk2546/guide-imports.js?v=3';\nnew Runtime().module(guide, Inspector.into('#guide'));\n```\n

","pinned":false,"hidden":false,"mode":"md"},{"id":143,"value":"## What's Next?\n\nNext up is determining the styling and theming of your _Framework_ project. Check out our next guide, [Styling & Theming](https://observablehq.com/@rk2546/guide-imports).\n\nAlternatively, you can check our other guides on _Framework_:\n\n${framework_guides}","pinned":false,"hidden":false,"mode":"md"},{"id":6,"value":"---\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":46,"value":"iris_dataset = FileAttachment(\"iris.csv\").csv({typed:true})","pinned":false,"hidden":false,"mode":"ojs"},{"id":8,"value":"import { css, render_filetree, framework_guides } from '@rk2546/2025-infovis-cse_notebook-gallery';","pinned":false,"hidden":false,"mode":"ojs"},{"id":10,"value":"css","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W33","stdlib":"1","titling":"auto"}