Unexpected error: Node is not defined

[Martien]

Context: npm run dev is running successfully – preview server works as expected.

• I quit npm run dev and start it again.

• Unexpected error: Node is not defined

I haven’t got a clue how I got here and how to get unstuck and repair it.

node --version: v22.10.0

[Martien]

• Hmmm... disabled some JS code.
• Got it up & running again.
• Pinpointed the location that causes it.
• Finding root cause… – struggling with imports; very confusing –

[Martien]

In a clean installation (npx @observablehq/framework@latest create in a new directory), when I have this observable.config.js:

import { html } from "htl";

export const outliner =
  ({ columns = 2 } = {}) =>
  (tree = {}) =>
    // `hoi`; // this works
    html`hoi`; // this gives “Node is not defined” or “document is not defined”.

export const outline = outliner({})({});

export default {
  title: "Aarde",
  // pages,
  head: '<link rel="icon" href="observable.png" type="image/png" sizes="32x32">',
  root: "src",
  style: "style.css",
  footer: ({ path }) =>
    `Built with <a href="https://observablehq.com/">Observable</a> – <a href="https://github.com/Martien/aarde/blob/main/src/${path}.md?plain=1">view source</a> – <a href="./evolver">view site’s evolution</a>`,
  // markdownIt,
};

then npm run dev says:

> dev
> observable preview


Unexpected error: document is not defined

Tip: To see the full stack trace, run with the --debug flag.

If you think this is a bug, please file an issue at
↳ https://github.com/observablehq/framework/issues

It seems to have to do with import { html } from "htl"; and the use of html`hoi`, and/or the outliner = ({ columns = 2 } = {}) => (tree = {}) =>….

I also sometimes get Node is not defined.

If I use `hoi`rather thanhtml`hoi`, it runs fine.

I cannot get my head around this. Please help.

[Fil]

This config file runs in Node.js ("server-side"), and htl uses the DOM to build nodes within a document (typically from a browser, but you might use JSDOM instead).

[Martien]

So, this means that the config file should best avoid htl and importing any files that directly use it.

If so, does that also imply that stuff you import in the config file should be separated from stuff that is used/imported in Markdown files?

I don’t need htl in the config file per sé, therefore JSDOM seems not the right path. The htl gets included by importing.

So, I’ll refactor accordingly.

BTW, this is the second time I got ‘bitten’ by the different contexts: Node.js in the config file and Page Loader, and Framework JS in Markdown files. Where can I find a comprehensive overview of these different execution contexts? Or is it something that I should know, is trivial?

Please advise.

[Fil]

It's definitely not trivial.

There is code that runs “server-side”, and is used to produce files (HTML5 in the general sense of HTML, CSS, JavaScript, and supporting data files).

Those files, in turn, include code that runs in the browser.

The code that runs server-side does not have a document, and anything it outputs will be “serialized to disk” during the build process — in other words represented as files. This is typically using nodejs, but nodejs can spawn other programmes (data loaders, page loaders) so you can write this stuff in pretty much any language you want. You can also write some code in typescript, and it will be transpiled to JavaScript so that it can run in the browser.

The code that runs client-side (in the browser) is HTML5 (*), and will typically use the page's document, which allows it to create interactive widgets, animate SVG and canvas images, etc.

Maybe we need to create some sort of diagram to visualize these spaces and the ways they communicate.

(*) HTML5 includes HTML, CSS, JavaScript: you can do everything that runs in a browser, and now that includes code written in SQL and passed to DuckDB-wasm, code written in WebGL and sent to the GPU, code written in R and running in WebR, etc.

[Martien]

Maybe we need to create some sort of diagram to visualize these spaces and the ways they communicate.

🙏 For me, that would be extremely helpful.

Thanks for your reply. My fog is clearing up. Have created a very rough sketch ✍️ of how I understand what you just said. I’ll let it sink in and maybe refine it after.