Configure site at runtime (#33)

webrecorder · Oct 20, 2022 · 90a8ada · 90a8ada
1 parent 9606f42
commit 90a8ada
Show file tree

Hide file tree

Showing 32 changed files with 383 additions and 583 deletions.
diff --git a/.eleventy.js b/.eleventy.js
@@ -1,34 +1,20 @@
+const config = require('./getConfig')();
+
 module.exports = function (eleventyConfig) {
-  // Copy assets, retain dir structure
-  eleventyConfig.addPassthroughCopy('src/[!_data]**/*.{css,js,json}');
+  // Copy and watch assets, retain dir structure
+  eleventyConfig.addPassthroughCopy('src/[!_]**/*.{css,js}');
+  eleventyConfig.addWatchTarget('src/[!_]**/*.{css,js}');
 
   // Keep web archive files in gitignore but remove from eleventyignore
   eleventyConfig.ignores.delete('*.wacz');
   eleventyConfig.ignores.delete('*.warc');
-  // Copy web archive files, retain dir structure
-  eleventyConfig.addPassthroughCopy('{,!(_site)/**/}*.wa{cz,rc}');
-
-  // Copy node modules needed in client
-  // TODO rollup?
-  const litLibs = [
-    'node_modules/@lit/reactive-element/reactive-element.js',
-    'node_modules/@lit/reactive-element/css-tag.js',
-    'node_modules/lit/index.js',
-    'node_modules/lit-element/lit-element.js',
-    'node_modules/lit-html/lit-html.js',
-    'node_modules/lit-html/is-server.js',
-    'node_modules/lit-html/directive.js',
-    'node_modules/lit-html/directive-helpers.js',
-  ].reduce(
-    (acc, path) => ({
-      ...acc,
-      [path]: path,
-    }),
-    {}
-  );
-  eleventyConfig.addPassthroughCopy(litLibs);
 
-  eleventyConfig.addWatchTarget('src/components/');
+  if (config.archivesPath) {
+    // Copy web archive files, retain dir structure
+    eleventyConfig.addPassthroughCopy(
+      `{${config.archivesPath},archives}/**/*.wa{cz,rc}`
+    );
+  }
 
   return {
     // When a passthrough file is modified, rebuild the pages:

diff --git a/README.md b/README.md
@@ -79,7 +79,7 @@ Push to `main` to automatically deploy your site to GitHub Pages. :sparkles:
 
 ## Configuration
 
-Configure options in `wrg-config.json`:
+Configure options in `wrg-config.json`.
 
 <details>
 <summary>
@@ -108,12 +108,11 @@ Object for configuring the [embedded ReplayWeb.page](https://replayweb.page/docs
 
 </summary>
 
-| Key              | Default Value                                  | Value Type                        |                                                                                                                     |
-| ---------------- | ---------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `replay`         | `{}`                                           | `Object`                          |                                                                                                                     |
-| `replay.embed`   | `"replayonly"`                                 | `"replayonly"\|"full"\|"default"` | ReplayWeb.page [`embed` option](https://replayweb.page/docs/embedding#embedding-options)                            |
-| `replay.baseUrl` | `"https://cdn.jsdelivr.net/npm/replaywebpage"` | `string`                          | Base URL for ReplayWeb.page scripts. `replay.version` will be ignored if a base URL is specified.                   |
-| `replay.version` | `""`                                           | `string`                          | ReplayWeb.page version. Omit for the latest. [See releases](https://github.com/webrecorder/replayweb.page/releases) |
+| Key                 | Default Value  | Value Type                        |                                                                                               |
+| ------------------- | -------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
+| `replay`            | `{}`           | `Object`                          |                                                                                               |
+| `replay.embed`      | `"replayonly"` | `"replayonly"\|"full"\|"default"` | ReplayWeb.page [`embed` option](https://replayweb.page/docs/embedding#embedding-options)      |
+| `replay.replayBase` | `"./replay/"`  | `"./replay/"\|string"`            | ReplayWeb.page [`replayBase` option](https://replayweb.page/docs/embedding#embedding-options) |
 
 </details>
 
@@ -122,36 +121,17 @@ Object for configuring the [embedded ReplayWeb.page](https://replayweb.page/docs
 
 #### `archives`
 
-Configure location of web archive files at website build-time.
+Configure location of web archive files.
 
 </summary>
 
-| Key        | Default Value | Value Type                                                |
-| ---------- | ------------- | --------------------------------------------------------- |
-| `archives` | `undefined`   | `undefined\|string\|string[]\|{name:string;url:string}[]` |
+| Key        | Default Value | Value Type                                        |
+| ---------- | ------------- | ------------------------------------------------- |
+| `archives` | `[]`          | `undefined\|string[]\|{name:string;url:string}[]` |
 
-Pre-process and render static HTML based on archive data. Option values can be:
+Option values can be a JSON array of plain URL strings or an object with `name` and `url`
 
-- JSON array of plain URL strings or an object with `name` and `url`
-- Relative path to directory containing `.wacz` files
-- Relative path to `.txt` file with newline-separated list of remote URLs
-- Relative path to JSON file with an `archives` key where the value is a JSON array
-
-Paths should be relative to your project root (i.e. where you execute your `npm run build` command.) Examples:
-
-```js
-{
-  "archives": "./wacz-files/"
-}
-```
-
-```js
-{
-  "archives": "data/archives.json"
-}
-```
-
-Example JSON array:
+Example:
 
 ```js
 {
@@ -162,6 +142,9 @@ Example JSON array:
     // Plain URL string to S3 bucket
     "s3://my-bucket/a/archive.wacz",
 
+    // Plain URL string to a file relative to output `_site`
+    "./public-data/",
+
     // Object with name and URL:
     {
       "name": "My Web Archive",
@@ -171,29 +154,63 @@ Example JSON array:
 }
 ```
 
+Setting `archivesPath` will override this option.
+
 </details>
 
+### Build-time options
+
+The following options can only be set at build-time (i.e. when you run `npm run build`.) Updates to options in your output `_site/wrg-config.json` file will have no effect.
+
 <details>
 <summary>
 
-#### `runtimeOnlyArchives`
+#### `replayBaseURL` [_Build-time Only_]
 
-Configure location of web archives when the website loads in the browser.
+Base URL for ReplayWeb.page scripts.
 
 </summary>
 
-| Key                   | Default Value | Value Type          |                                                        |
-| --------------------- | ------------- | ------------------- | ------------------------------------------------------ |
-| `runtimeOnlyArchives` | `undefined`   | `undefined\|string` | Path to JSON file with `archives`, relative to `_site` |
+| Key             | Default Value                                  | Value Type |                                     |
+| --------------- | ---------------------------------------------- | ---------- | ----------------------------------- |
+| `replayBaseURL` | `"https://cdn.jsdelivr.net/npm/replaywebpage"` | `string`   | Base URL for ReplayWeb.page scripts |
 
-By default, the generator configures the location of your archives at build-time (i.e. when you run `npm run build`) in order to pre-process data and render static HTML based on that data. However, you may have a use case where you need to check archive locations every time the website loads in the browser. Setting `runtimeOnlyArchives` enables you to do things like configure and update archive data without redeploying your entire website.
+</details>
 
-Caveats:
+<details>
+<summary>
 
-- The generated sitemap will no longer list a page per archive.
-- JSON data must conform to an array of objects with `url` and optionally `name`.
+#### `archivesPath` [_Build-time Only_]
 
-See [runtime-only-archives](./examples/runtime-only-archives/) for a more in-depth example.
+Path to local web archive files.
+
+</summary>
+
+| Key            | Default Value | Value Type |
+| -------------- | ------------- | ---------- |
+| `archivesPath` | `undefined`   | `string`   |
+
+Paths should be relative to your project root (i.e. where you execute `npm run build`.) Option values can be:
+
+- Relative path to directory containing `.wacz` files
+- Relative path to `.txt` file with newline-separated list of remote URLs
+- Relative path to JSON file with an `archives` key where the value is a JSON array
+
+Examples:
+
+```js
+{
+  "archivesPath": "./wacz-files/"
+}
+```
+
+```js
+{
+  "archivesPath": "./source_data/archives.json"
+}
+```
+
+Take precedence over the `archives` array.
 
 </details>
 
@@ -247,9 +264,18 @@ To disable, comment out the line in `.env`:
 
 Web Replay Gen templates are written in [Nunjucks](https://mozilla.github.io/nunjucks/templating.html). You are free to use any templating language [Eleventy supports](https://www.11ty.dev/docs/languages/), like plain HTML, markdown, or ejs.
 
-## Web Components
+## Web Components & client-side JavaScript
+
+JS files in `/js` will be copied as-is to `_site`. To include JS files in templates, import as ES modules and use [`module-shim`](https://github.com/guybedford/es-module-shims). For example, to render a Web Component called `my-component`:
 
-Web components in the `/components` directory will be pre-rendered at build-time and hydrated at run-time. See `archive.njk` for an example and refer to the [@lit-labs/eleventy-plugin-lit](https://github.com/lit/lit/tree/main/packages/labs/eleventy-plugin-lit) docs to customize SSR behavior.
+```html
+<!-- my-template.njk -->
+<my-component></my-component>
+
+<script type="module-shim">
+  import('./js/my-component.js');
+</script>
+```
 
 ## Styling
 

diff --git a/archives/README.md b/archives/README.md
@@ -1 +1,9 @@
 Web Archive files (`.wacz`, `.warc`) in this directory will be copied to the generated site. Web Archive files are ignored in git (see [.gitignore](../.gitignore).)
+
+To list all files in this directory in your website, set the following option in `wrg-config.json`:
+
+```json
+{
+  "archivesPath": "archives"
+}
+```
diff --git a/examples/.gitignore b/examples/.gitignore
diff --git a/examples/runtime-only-archives/README.md b/examples/runtime-only-archives/README.md
diff --git a/examples/runtime-only-archives/_site/custom_data_source/archives.json b/examples/runtime-only-archives/_site/custom_data_source/archives.json
diff --git a/examples/runtime-only-archives/_site/index.html b/examples/runtime-only-archives/_site/index.html
diff --git a/examples/runtime-only-archives/wrg-config.json b/examples/runtime-only-archives/wrg-config.json
diff --git a/src/_data/archiveConfig.js b/src/_data/archiveConfig.js