tarball use case?

Trying to explain / make sense of / the “download tarball” menu.

The documentation explains how to npm install notebook.tgz but the rest is left as a (slightly cryptic) exercise for the reader. (The demos listed are all using the js module with online URLs.)

yarn add "https://api.observablehq.com/@jashkenas/breakout.tgz?v=3" includes a terse README.md file that explains how to view (I used http-server node_modules/\@jashkenas/breakout/) or load the notebook’s functions in a node application (and it might or might not work depending on the version of node).

However, looking around for real-life usage examples (by searching on github), I couldn’t find any. Maybe it’s too early…


Hi @Fil .

After @bgchen revealed the magic of the tarball to me on this forum, I have found at least one practical use case for tarballs: Controlling View Permissions and Excerpting Sections of Long, Unwieldy Notebooks

I have one central notebook that describes a ‘case’ received by my office by way of over 500 data fields, defined as Observable inputs. For me, it’s handy to have all of these fields in a single place, but–except when using a computer with relatively large amounts of RAM and a decent processing card–I find that opening and dealing with this notebook via Observable to be pretty slow (though using @jashkenas inputs is extremely convenient). There are also some sensitivities among people I work with about providing a ‘public’ (albeit obscured) URL.

By hosting the tarball on AWS S3, I can control which IP addresses have access to the file–mitigating the second of my concerns named above. As to overcoming speed issues, I find that the JS as a tarball loads more quickly than does an Observable notebook, and it allows me the same flexibility to expose only those inputs I want in a given page. Linking the Observable inputs into a custom HTML document also affords me greater control over placement of inputs and their rendered outputs (such as creating a separate ‘input’ tab and ‘view’ tab). I do this sort of work especially when I am trying to model layouts and behaviors I want to web application developers with whom I work.

Is this the sort of use case you were looking for?


My use case: I wrote a tool for a work project and linked to it in a JIRA issue. Additionally I created a tarball export and attached it to the issue to ensure that the tool could always be accessed.

To run the notebook locally I would simply start a web server (as described in the included readme), without installing any packages.

In summary: Archiving a notebook independently of Observable.


Interesting! So in both cases it’s more “plain js” than complex node.js projects where a part of the code would have been developed on observable (as a library for example).

1 Like

Certainly for me, at least. Probably b/c I am not (yet) so advanced as to be building libraries. Maybe consider reaching out to some users who have been publishing libraries?

What to me is most interestig about the tarballs is their ready abstaction from the observablehq context. Otherwise, why not just reference back to the source notebook?

The Idyll project has an experimental plugin for inserting cells from a notebook into a text document so that presumably you’d develop a visualization in Observable and then insert it into an article directly without having to actually extract it and work the js into your document. Conversely, you could drop users from your article directly into the notebook that powers it. I believe it uses the JS API so that you can write

    lineWidth: lineWidth,
    height: height
  }` /]

and it will download and cache the notebook. It’s been suggested though that the tarball would be a better way to accomplish this since it includes all of the dependencies in a way that’s a bit more useful for the particular approach.


Importing notebooks as tarball dependencies with npm is discussed here:

1 Like

This question has evolved into the following blog post, which details our methodology to transform a mildly complex @observablehq notebook into a fully self-contained standalone application:

The method is explained in details and there is an example repository that we plan to use as a template to publish our next projects.

In that repo (and the blog post), we’re covering how to host all code and data locally, at least in some simple cases. The case of web workers (importScripts) in particular is not yet covered (but will be soon).


One common problem when hosting the downloaded tgz package uncompressed to a folder and using simplehttp or ias or other out of the box solutions is: file attachments have no extension and will not be served with correct mime type or often not served at all depending on the default configuration of ias or other enterprise default static hosting configurations. It would be great to have the download as zip + have extensions to the file attachments to make it easy to host them locally as a standalone web application along with the current tgz option for using it as a dependency in node based projects etc.,

1 Like

You may want to add your voice to What's your method to compress FileAttachements?