2c:null 2d:["$","title",null,{"children":"Introduction to the new observable-prerender CLI | Alex Garcia | Observable"}] 32:T6d7,html`

const { load } = require("@alex.garcia/observable-prerender");
(async function() {
const notebook = await load("@d3/bar-chart", ["chart"]);
const data = [
  { name: "alex", value: 20 },
  { name: "brian", value: 30 },
  { name: "craig", value: 10 },
];
const color = "lightgreen";
await notebook.redefine({ data, color});
await notebook.screenshot("chart", "bar-chart.png");
await notebook.browser.close();
})()

`33:T629,html`

const { load } = require("@alex.garcia/observable-prerender");
(async () => {
  const notebook = await load("@mbostock/covid-19-daily-new-cases", [
    "chart",
    "update",
  ]);
  const dates = await notebook.value("dates");
  for await (let i = 0; i < times.length; i++) {
    await notebook.redefine("date", dates[i]);
    await notebook.waitFor("update");
    await notebook.screenshot("chart", \`tmp/\${i}_chart.png\`);
  }
  await notebook.browser.close();
})();

`34:[{"id":"a469ff61300032ded759c0a8f2ac040eaaa5ca7f1e2107784ec3eadecf52154c57851fbd8bf4f67ae65497d4274788a2276a3ae0d4cb3343e42550f339787a6e","href":"https://static.observableusercontent.com/files/a469ff61300032ded759c0a8f2ac040eaaa5ca7f1e2107784ec3eadecf52154c57851fbd8bf4f67ae65497d4274788a2276a3ae0d4cb3343e42550f339787a6e","name":"bar-chart.png","type":"image/png","lastModified":1599292904333.847,"size":16412},{"id":"6c4a59090437da4f899884432e1adb30c45c12fddcd608220561dcc48400726bff3dbc334069011166f33af7befd19ae308094d196db7770f82aa05deb59a78f","href":"https://static.observableusercontent.com/files/6c4a59090437da4f899884432e1adb30c45c12fddcd608220561dcc48400726bff3dbc334069011166f33af7befd19ae308094d196db7770f82aa05deb59a78f","name":"us-covid19-daily.mp4","type":"video/mp4","lastModified":1599550873701.474,"size":4876991},{"id":"6d01d34969b8af8e8296d2e6b3c45324f297898456d5761141d77ee28605e00b0a0541812ee309b53aac8ec39826fbb1287c494a8d0265d526c75d0b0caadded","href":"https://static.observableusercontent.com/files/6d01d34969b8af8e8296d2e6b3c45324f297898456d5761141d77ee28605e00b0a0541812ee309b53aac8ec39826fbb1287c494a8d0265d526c75d0b0caadded","name":"lightgreen-barchart.png","type":"image/png","lastModified":1599289951525.762,"size":9958},{"id":"f446ccf6bb7277e0d21f1cefb69a22771d831fcf1d7c75bcbb197e6a0e15ce02fc5984d5679951c129862a98e3d83ef59fd1211dc015dba4e7f6c98aced63105","href":"https://static.observableusercontent.com/files/f446ccf6bb7277e0d21f1cefb69a22771d831fcf1d7c75bcbb197e6a0e15ce02fc5984d5679951c129862a98e3d83ef59fd1211dc015dba4e7f6c98aced63105","name":"calendar-2000s.png","type":"image/png","lastModified":1599547464234.604,"size":310837},{"id":"2c1b2bced03ed902d437b5b0632527de831bfa5094aae6802f1cae8ae1e989d33590db6367bf8d1196ef5cc50ff81d1a37eb008f7f00c5a487ddb43e92ba9065","href":"https://static.observableusercontent.com/files/2c1b2bced03ed902d437b5b0632527de831bfa5094aae6802f1cae8ae1e989d33590db6367bf8d1196ef5cc50ff81d1a37eb008f7f00c5a487ddb43e92ba9065","name":"calendar-2020.png","type":"image/png","lastModified":1599547723665.33,"size":11600}] 30:{"id":"2a25256fc7c02bca","slug":"introduction-to-the-new-observable-prerender-cli","title":"Introduction to the new observable-prerender CLI","thumbnail":"8da4d87f470dd6f4069a8876a363ce05e024cb42296969a3b3c9b52442ffde5a","access_level":"public","create_time":"$D2020-09-04T18:56:10.730Z","update_time":"$D2020-09-08T08:08:28.181Z","view_time":null,"first_public_time":"$D2020-09-08T16:12:41.415Z","fork":false,"stars":38,"starred":false,"owner":{"type":"team","id":"512cbe7209990c30","login":"asg017","name":"Alex Garcia","avatar_url":"https://avatars-next.observableusercontent.com/fa4015f63c3a56af76b90247b0b0f8a98019b671f135157d746d3924eda27c07","tier":"starter_2024"},"version":585,"publish_version":585,"role":null,"authored":false,"authors":[{"type":"individual","id":"113fc3dc69e1f893","login":"asg017","name":"Alex Garcia","avatar_url":"https://avatars-next.observableusercontent.com/fa4015f63c3a56af76b90247b0b0f8a98019b671f135157d746d3924eda27c07","tier":null}],"members":[{"type":"individual","id":"113fc3dc69e1f893","login":"asg017","name":"Alex Garcia","avatar_url":"https://avatars-next.observableusercontent.com/fa4015f63c3a56af76b90247b0b0f8a98019b671f135157d746d3924eda27c07","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":4,"collection":{"id":"97034164b3018a6d","slug":"observable-prerender","title":"observable-prerender","owner":{"id":"512cbe7209990c30","login":"asg017","name":"Alex Garcia"}},"type":"notebook","body":{"title":"Introduction to the new observable-prerender CLI","cells":[{"id":0,"value":"md`# Introduction to the new observable-prerender CLI`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":4,"value":"md`A little while ago I release [\\`observable-prerender\\`](https://github.com/asg017/observable-prerender), an NPM package for pre-rendering Observable notebooks using Puppeteer. If you haven't heard of it, check out the [Intro to \\`observable-prerender\\`](https://observablehq.com/@asg017/introducing-observable-prerender) notebook!\n\nAn NPM package is cool and all, but writing code is tedious, and CLI's are hip and cool! \\`observable-prerender\\` now comes with two CLI programs, \\`observable-prerender\\` and \\`observable-prerender-animate\\`. Both programs cover most of what you'd use \\`observable-prerender\\` for in code, and this notebook will walk you through it all!`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":248,"value":"html`

🚨 Feedback requested!

In this notebook, I use colors to callout similarities between the library code and the new CLI, ${callout(\n 'looking',\n 1\n)} ${callout('like', 2)} ${callout(\n 'this',\n 3\n)}. After you read through this, I'd love to hear what you think of it! Does it help you understand the differences more, is it too distracting, does it help at all? Leave a comment 👈🏼 by clicking on this cell's menu on the left and choose \"Add comment\" and let me know what you think!`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":171,"value":"md`\n## Static Pre-renders\n\nThe first usecase: \"I wanna pre-render a notebook, maybe re-define some data, and save it as a PNG/SVG\".\n\nLet's use the D3 Bar Chart notebook as an example. If you wanted to screenshot the \\`chart\\` cell, you'd have to write a Node script that looked a little something like this:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":173,"value":"html`

const { load } = require(\"@alex.garcia/observable-prerender\");\n(async function() {\n  const notebook = await load(\"@d3/bar-chart\", [\"chart\"]);\n  await notebook.screenshot(\"chart\", \"chart.png\");\n  await notebook.browser.close();\n})()\n

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":232,"value":"md`You require the \\`observable-prerender\\` library, load the ${callout(\n \"@d3/bar-chart\",\n 1\n)} notebook, specify to only render the ${callout(\n \"chart\",\n 2\n)} cell, then you screenshot that ${callout(\n \"chart\",\n 2\n)} cell and save it as a PNG to the ${callout(\"chart.png\", 3)} file.\n\n6 lines of code, not too bad. But how would we do this with the new CLI program?`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":175,"value":"html`\n

$ observable-prerender @d3/bar-chart chart --format png\n

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":304,"value":"md`And that's it! Running this will generate a \\`chart.png\\` file into your current directory, looking like this:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":306,"value":"FileAttachment(\"bar-chart.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":240,"value":"(md` Let's break this down a little more:\n\nFirst, \\`observable-prerender\\` is the name of this CLI program. The first required positional argument in the name of the Observable notebook you want to pre-render, ${callout(\n \"@d3/bar-chart\",\n 1\n)}. Next, the rest of the positional arguments are the names of the cells you want to screenshot/save as SVG. In this case, we only want to screenshot the ${callout(\n \"chart\",\n 2\n)} cell, but we could also pass in other cells as more arguments. Finally, we want to save the cell in ${callout(\n \"png\",\n 3\n)} format, not the default svg, so we'll use the \\`--format\\` flag, or \\`-f\\` for short.`,\nmd``)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":245,"value":"md`That's cool! But one great feature of the \\`observable-prerender\\` package is that we can redefine cells to inject our own data or change configuration of a notebook. Using the NPM package, that would've looked like this in a Node script:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":6,"value":"$32","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":281,"value":"(md`We load the \n${callout(\"@d3/bar-chart\", 1)} notebook and target the \n${callout(\"chart\", 2)} \ncell like before. Here, we are redefining the values of the \n${callout(\"data\", 4)} and \n${callout(\"color\", 4)} \ncells of that original notebook. In the original notebook, the \n${callout(\"data\", 4)} \ncell is an array of JavaScript Objects, where each object has string \\`name\\` fields and integer \\`value\\` fields, which is what we have in our local \n${callout(\"data\", 4)} variable here. The \n${callout(\"color\", 4)} \ncell was just a string of a named color (\\`\"steelblue\"\\`), so we will also redefine it as the named color \\`\"lightgreen\"\\`.\n\nWe pass those new cells into [\\`notebook.redefine()\\`](https://github.com/asg017/observable-prerender#notebookredefinecell-value), we use [\\`notebook.screenshot()\\`](https://github.com/asg017/observable-prerender#notebookscreenshotcell-path-options) like before, and we're good to go!`,\nmd``)","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":420,"value":"md`How would this look like with the \\`observable-prerender\\` CLI?`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":183,"value":"html`

$ observable-prerender @d3/bar-chart chart \\\\\n  --redefine color:lightgreen \\\\\n  --redefine-file data:json:./new-data.json \\\\\n  --format png\n

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":317,"value":"md`Running the above, we get what we expected:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":295,"value":"FileAttachment(\"lightgreen-barchart.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":320,"value":"md`Sweet! The command looks the same as the original command, with just 2 new different flags for redefining cells. \n\nThe \\`--redefine\\` option is for redefining a named cell with a string or number. In this case, we want to redefine the ${callout(\n \"color\",\n 4\n)} cell to be the string value \\`\"lightgreen\"\\`, so the full option would look like \\`--redefine \\` ${callout(\n \"color\",\n 4\n)}\\`:lightgreen\\`.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":331,"value":"md`The \\`--redefine-file\\` option is a little more special. \\`--redefine\\` alone is limiting, it can only handle short strings or numbers. But a lot of the time, you'll want to redefine cells with more rich values like arrays, objects, or much longer strings. That's where \\`--redefine-file\\` comes in, instead of passing the data on the command line, we can re-use the data that already exists in the local filesystem! \n\nSo, for the above example, we create a new \\`new-data.json\\` file with the data we want, and we pass \\`--redefine-file \\` ${callout(\n \"data\",\n 4\n)}\\`:json:./new-data.json\\` into the command and we're good to go!`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":347,"value":"md`Redefining cells isn't the only way we can inject new data into a notebook, however. There is also the \\`--file-attachments\\` flag, which allows you to specifically replace notebook [File Attachments](https://observablehq.com/@observablehq/file-attachments) by name! `","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":398,"value":"md`Let's take a look at the D3 [Calendar View](https://observablehq.com/@d3/calendar-view) notebook as an example. It has a \\`chart\\` cell containing the SVG we want to capture, but the \\`data\\` cell that powers it is an array of JavaScript objects with a \\`date\\` field that are [Date objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), which are not JSON serializable. So, if we used the \\`--redefine-file\\` flag, we wouldn't be able to properly redefine the \\`data\\` value.`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":412,"value":"md`So instead, we can download the [Dow Jones Index Historical data CSV](https://finance.yahoo.com/quote/%5EDJI/history/) from Yahoo Finance, then replace the underlying file for the ${callout(\n \"^DJI@2..csv\",\n 7\n)} FileAttachment with the \\`--file-attachments\\` option!\n\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":414,"value":"html`

$ observable-prerender @d3/calendar-view chart \\\\\n    -o calendar.png \\\\\n    --file-attachments ^DJI@2.csv:dji.csv\n

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":461,"value":"FileAttachment(\"calendar-2000s.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":464,"value":"md`Sweet! You can see that this calendar view has data up to August 2020, which the current Calendar View notebook doesn't have.\n\nBonus round: If you want to slice the data in a different way and you don't want to create a bunch of little \\`tmp.csv\\` files, you can use [Process Substitution](https://tldp.org/LDP/abs/html/process-sub.html) with \\`--redefine-file\\` or \\`--file-attachments\\` to create new \"files\" on the fly! For example, here we can use [\\`csvgrep\\`](https://csvkit.readthedocs.io/en/1.0.2/scripts/csvgrep.html) on our CSV to only create a calendar view for the year 2020:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":471,"value":"md`~~~bash\n$ observable-prerender @d3/calendar-view chart \\\\\n -o calendar-2020.png \\\\\n --file-attachments ^DJI@2.csv:<(csvgrep -c Date -r \"2020*\" dji.csv) \n~~~`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":474,"value":"FileAttachment(\"calendar-2020.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":191,"value":"md`\n## Animations\nThe second cool usecase for \\`observable-prerender\\` is to generate frames of a video of an animated Observable notebook!\n\nLet's use Mike Bostock's [COVID-19 Daily New Cases\n](https://observablehq.com/@mbostock/covid-19-daily-new-cases) notebook as an example. There we have a \\`chart\\` cell that updates whenever the \\`date\\` cell updates, which creates a timeline of where COVID-19 has hit the United States. Before, if we wanted to generate PNG frames of each of these dates, this is what it would've looked like:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":494,"value":"$33","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":509,"value":"md`It's pretty involved, mostly because we are taking 100's of screenshots instead of just one. We load in the notebook like before, but we also loop over all the values in the \n${callout(\"dates\", 5)}\narray and redefine the\n${callout(\"date\", 4)}\ncell with those values. Whenever we do that, we wait for those changes to propagate by waiting on the \n${callout(\"update\", 3)}\ncell, then screenshot the \n${callout(\n \"chart\",\n 2\n)} cell like before and save it to a PNG file. In the end, our \n${callout(\"tmp\", 6)} \ndirectory will have ~300 PNG frames for each day defined in the \n${callout(\"dates\", 5)}\ncell.\n\nBut now, we have the \\`observable-prerender-animate\\` CLI program. How would this workflow look like with that program?`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":500,"value":"html`

$ observable-prerender-animate \\\\\n    @mbostock/covid-19-daily-new-cases chart \\\\\n    --iter-waitfor update \\\\\n    --iter date:dates \\\\\n    --out-dir tmp/ \\\\\n    --format png\n

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":534,"value":"md`When this finishes, your tmp directory will look like this:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":535,"value":"md`~~~\n$ ls tmp/\n000_chart.png\t046_chart.png\t092_chart.png\t138_chart.png\t184_chart.png\n001_chart.png\t047_chart.png\t093_chart.png\t139_chart.png\t185_chart.png\n002_chart.png\t048_chart.png\t094_chart.png\t140_chart.png\t186_chart.png\n003_chart.png\t049_chart.png\t095_chart.png\t141_chart.png\t187_chart.png\n004_chart.png\t050_chart.png\t096_chart.png\t142_chart.png\t188_chart.png\n...\n~~~`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":554,"value":"md`The two new options \\`--iter\\` and \\`--iter-waitfor\\` do most of the heavy lifting here. \\`observable-prerender-animate\\` is meant to loop through one cell and redefine another cell along the way, which is what \\`--iter\\` specifies. Here, we are saying to loop through the \n${callout(\"dates\", 5)}\ncell and to redefine \n${callout(\"date\", 4)} along the way. \n\\`--iter-waitfor\\` is an optional flag where you can specificy another cell to wait for before taking a screenshot in the loop. In this case, we want to wait for the \n${callout(\"update\", 3)} \ncell to finish updating the chart before we actually screenshot it. `","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":562,"value":"md`\\`observable-prerender-animate\\` saves each individual frame with zero-padded numbers into the specified directory, which integrates well with other CLI tools like [ffmpeg](https://ffmpeg.org/)! In fact, we can use ffmpeg to read in these individual PNG frames and write out a new MP4 video of this animation, like so:`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":544,"value":"md`~~~\n$ ffmpeg -framerate 15 \\\\\n -i tmp/%03d_chart.png \\\\\n -c:v libx264 -pix_fmt yuv420p \\\\\n\t-vf \"pad=ceil(iw/2)*2:ceil(ih/2)*2\" \\\\\n us-covid19-daily.mp4\n~~~`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":548,"value":"html`

`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":496,"value":"md`## Try it out!\n\nTry out the new CLI today! It's included with the \\`observable-prerender\\` package as of v0.1.0, so if you can install it like so:\n\n~~~bash\nnpm install --global @alex.garcia/observable-prerender\n~~~\n\nThere are several more options and flags for these programs that may make your workflow much simpler, check out the fill reference on [Github](https://github.com/asg017/observable-prerender)!\n`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":478,"value":"md`---\n## Appendix`","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":26,"value":"html`