Observable data loaders reject npm: imports: they are plain Node.js

TL;DR

When an Observable Framework data loader fails on npm: imports, do not try to make the npm: specifier work: data loaders run as plain Node.js, so replace npm: imports with regular package imports (npm install the package, import by name) and replace FileAttachment with node:fs reads.

Steps

1. When an Observable Framework data loader fails on npm: imports, do not try to make the npm: specifier work: data loaders run as plain Node.js, so replace npm: imports with regular package imports (npm install the package, import by name) and replace FileAttachment with node:fs reads. Keep npm: specifiers in .md pages only. If an agent generates both page code and data loaders, it must not copy imports between the two contexts.

Expected: The maintainer confirmed JavaScript data loaders are simply normal Node.js programs: npm: imports are a Framework page construct and are not supported natively by Node.js.

When to use

You are seeing this: If an agent generates both page code and data loaders, it must not copy imports between the two contexts. Use this skill when you run into "Observable data loaders reject npm: imports: they are plain Node.js".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: GitHub issue observablehq/framework#1623 (closed, 4 comments): a data loader using import from npm: failed with ERRUNSUPPORTEDESMURLSCHEME at build time. The maintainer confirmed JavaScript data loaders are simply normal Node.js programs: npm: imports are a Framework page construct and are not supported natively by Node.js. The fix is to use normal Node.js APIs (node:fs/promises) for file reads, and to install any npm package with npm and import it by package name instead of the npm: specifier. A second reporter hit the same wall with import from npm:parquet-wasm and got the same confirmed answer.

Verified resolution: When an Observable Framework data loader fails on npm: imports, do not try to make the npm: specifier work: data loaders run as plain Node.js, so replace npm: imports with regular package imports (npm install the package, import by name) and replace FileAttachment with node:fs reads. Keep npm: specifiers in .md pages only. If an agent generates both page code and data loaders, it must not copy imports between the two contexts.

Source URL: https://github.com/observablehq/framework/issues/1623