31:T41f,# Framework Guide #1: Local Observable/Framework Project Setup Observable provides an interesting framework to build web interfaces, called [_"Framework"_](https://observablehq.com/framework/what-is-framework). _Framework_ allows someone to create interactive, data-driven websites and dashboards. This makes _Framework_ particularly useful for our course project. _Framework_ inherently depends on [_Node.js_](https://nodejs.org/en) to run. For those who haven't worked with _Node.js_ before, _Node.js_ is a JavaScript-based runtime environment that lets you develop websites, servers, and scripts. In fact, the [_official Observable installation guide_](https://www.youtube.com/watch?v=N2qiGG2RqwY&list=PLOHIJAFwtkEcuVZO6WK-Uuswd09Y2Rk2b) assumes you have _Node.js_ installed. This guide will provide instructions on how to install _Framework_ from scratch and get it working locally on your web browser. this includes how to install _Node.js_ and other various programs from scratch. We will also cover how to set it up to be compatible with Github.32:Te0b,--- ## Step 1. Installing _Node.js_ & _npm_ _Node.js_ comes with its own package library, [_npm_](https://www.npmjs.com/), and both come pre-packaged with each other. _npm_ is similar to other package managers such as [_Yarn_](https://yarnpkg.com/) and [_Homebrew_](https://brew.sh/) and allows you to install packages for Python, JavaScript, etc. We generally recommend that you install the [latest LTS version of _Node.js_](https://nodejs.org/en/download/archive/v22.20.0) (currently v22). We have instructions for both Mac OS and Windows.

[NOTE]: _Node.js_ has some installers provided on their [_downloads page_](https://nodejs.org/en/download). However, installing in this manner may lead to complications; one of the most common issues is that, if installed via an installer, _Node.js_ will only be installed locally and may not be installed _globally_ (i.e. accessible via command line across your entire computer). I generally recommend only installing via an installer if the steps below don't work.

### If you already have _Node.js_ installed or need to update: Make sure to check that your version of _Node.js_ is at least v18 (recommended: v22 LTS). You can check your version by running the following command in a terminal shell (Mac OSX: the in-built `Terminal.app` / Windows: [`Powershell` as an Administrator](https://learn.microsoft.com/en-us/powershell/scripting/windows-powershell/starting-windows-powershell?view=powershell-7.4#with-administrative-privileges-run-as-administrator) / Both: [Visual Studio Code (VS Code)](https://code.visualstudio.com/)): ```sh node -v ``` If you do not have the correct version, please follow the steps below. ### If you do not have _Node.js_ installed:

For Mac OSX:

Install nvm, a tool that lets you easily manage and switch between Node.js versions. Follow the instructions to install on their Github page.
If you haven't yet, open a terminal shell (in [VS Code]((https://code.visualstudio.com/)) or open Terminal.app).
Run this command, which installs the latest LTS version of Node.js:
```
nvm install --lts
```
Run this command, which switches the default Node.js version that your system uses to the LTS version:
```
nvm use --lts
```

For Windows:

Install nvm-windows, a tool that lets you easily manage and switch between Node.js versions. Follow the instructions to install on their Github page.
If you haven't already, Open PowerShell as an administrator (you MAY be able to use VS Code, but I haven't tried).
Run this command, which installs the latest LTS version of Node.js:
```
nvm install lts
```
Run this command, which switches the default Node.js version that your system uses to the LTS version:
```
nvm use lts
```

33:T625,## Step 2. Creating a Framework Project With _Node.js_ and _npm_ installed, we can proceed with actually creating a _Framework_ project. From this point on, the following steps will work on either Mac OS and Windows. 1. Open a terminal window (either the `Terminal.app` on MacOS, `Command Prompt` on Windows, or _VS Code_ on either MacOS or Windows). 2. Navigate to any folder or location where you will be comfortable creating a new folder (e.g. the "Documents/" directory on MacOS or the "Desktop/" on Windows). You can navigate to that location using the following command:

     # Generic format:
     cd [PATH]/[TO]/[LOCATION]

4. Paste and run the command:

     npx @observablehq/framework@latest create

3. New instructions will be prompted from you in the terminal window. Answer all the directions that appear. - The defaults are fine, if you want to just check how things work. - If you want to have sample pages and content, you are free to say "Yes" to "Include sample files to help you get started?"; otherwise, say "No" to that prompt. - When prompted with "Install dependencies?", you are safe to say "Yes, via npm (recommended)" - When prompted with "Initialize git repository?", you are safe to say "Yes". 5. At this point, _Framework_ will create a brand new folder for you with all the code necessary to run a _Framework_ project locally. If you ran with defaults, then the new folder will be titled "`hello-framework`". Navigate into your new folder by using the `cd` command.34:T693,## Step 4. Version Control via Github The ideal step here is to effectively have a form of version control for your _Framework_ project. The most accessible way is to use [_Github_](https://github.com/). Some individuals prefer to use `.git` commands directly through the command prompt, while others like to use tools such as [_GitKraken_](https://www.gitkraken.com/). We leave that choice up to you, as each will require different steps to set up. Regardless, this guide expects that 1) you already have a Github account that you feel comfortable uploading projects to, and 2) during [Step 2](#cell-82), you followed the default option to prepare the project folder for Github. Generally, the steps to connect your Github to your new project is as follows: 1. Online, create an **empty** Github repository and feel free to name it anything you want (though generally you should try to match project names when possible). 2. Locally (via command line or via Github tool), add and commit all files in your project window. 3. Set the branch to "main", add a new _remote_ origin, and push your changes. The 3 commands to do so are provided below, as an example:

  git branch -M main
  git remote add origin git@github.com:[USERNAME]/[PROJECT_NAME].git
  git push -u origin main

After these steps, you should be able to push changes to your Github repository and pull them when needed.

[NOTE]: Whenever you clone your repo to another folder or device, you **must** install dependencies again. To do that via npm, you can run the following command:

npm install

35:[] 2f:{"title":"Framework Guide #1: Local Observable/Framework Project Setup","cells":[{"id":0,"value":"$31","pinned":false,"hidden":false,"mode":"md"},{"id":7,"value":"$32","pinned":false,"hidden":false,"mode":"md"},{"id":82,"value":"$33","pinned":false,"hidden":false,"mode":"md"},{"id":95,"value":"## Step 3. Running a Development Server\n\nOnce you've installed your dependencies, we are ready to run a local server that we can use for development. _Framework_ gives you the ability to preview any changes you make to any of your files. To do this, run the following command inside your project folder:\n\n

\nnpm run dev\n

\n\nYour _Framework_ webpage should then be loaded into a localhost server that you can view via the browser. The _Framework_ architecture tracks any changes to any files and updates in real-time every time you save changes in a file.","pinned":false,"hidden":false,"mode":"md"},{"id":100,"value":"$34","pinned":false,"hidden":false,"mode":"md"},{"id":103,"value":"---\n\n## Command Line Summary\n\nHere's a summary of all shell commands needed:\n\n

\n# Step 1: Install Node.js LTS, for Mac OSX (after installing npx)\nnvm install --lts\nnvm use --lts\n\n# Step 1: Install Node.js LTS, for Windows (after installing npx-windows)\nnvm install lts\nnvm use lts\n\n# Step 2: Create a _Framework_ Project\nnpx @observablehq/framework@latest create\n\n# Step 3: Run a Development Preview Server\nnpm run dev\n  \n# Step 4: Connecting an Empty Github Repo\ngit add -A\ngit commit -m \"first commit\"\ngit branch -M main\ngit remote add origin git@github.com:[USERNAME]/[PROJECT_NAME].git\ngit push -u origin main\n

","pinned":false,"hidden":false,"mode":"md"},{"id":121,"value":"---\n\n## What's Next?\n\nNext, let's review the way in which _Framework_ projects are (generally) sorted. Follow along to the next guide: [_Project Structure_](https://observablehq.com/@rk2546/guide-project_structure).\n\nAlternatively, check out the other guides in this series:\n\n${framework_guides}","pinned":false,"hidden":false,"mode":"md"},{"id":160,"value":"### Additional Materials\n\n- [Inspiration for this document](https://observablehq.com/@columbia-data-club/installing-observable-framework-from-zero)\n- [Framework Documentation: Getting Started](https://observablehq.com/framework/getting-started)\n- [Video: Installation Guide](https://www.youtube.com/watch?v=N2qiGG2RqwY&list=PLOHIJAFwtkEcuVZO6WK-Uuswd09Y2Rk2b)\n- [_Node.js_](https://nodejs.org/en)\n- [Stack Overflow: How to install LTS via nvm](https://stackoverflow.com/questions/64002438/installing-node-lts-with-nvm-on-windows)","pinned":false,"hidden":false,"mode":"md"},{"id":10,"value":"---\n\n## Changelog\n\n- Originally centered the tutorial on _pnpm_, an alternative to _Node.js_'s _npm_ package manager. However, due to unforeseen issues with _pnpm_ and deploying to web services such as [Github Pages](https://docs.github.com/en/pages), we will be reverting the tutorial to use _npm_.\n\n## Appendix","pinned":false,"hidden":false,"mode":"md"},{"id":143,"value":"import {previews, css, framework_guides } from \"@rk2546/2025-infovis-cse_notebook-gallery\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":12,"value":"css","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W35","stdlib":"1","titling":"auto"}