{"id":19237477,"url":"https://github.com/webrecorder/web-replay-gen","last_synced_at":"2025-04-21T06:31:26.570Z","repository":{"id":58167168,"uuid":"525091383","full_name":"webrecorder/web-replay-gen","owner":"webrecorder","description":"Static Site Generator for Viewing Web Archives (in WACZ) format","archived":false,"fork":false,"pushed_at":"2023-06-30T15:19:32.000Z","size":763,"stargazers_count":24,"open_issues_count":7,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-14T14:30:04.999Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/webrecorder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"webrecorder"}},"created_at":"2022-08-15T18:13:31.000Z","updated_at":"2025-04-10T20:37:30.000Z","dependencies_parsed_at":"2023-01-22T11:01:04.293Z","dependency_job_id":"97e18abd-dcb5-466f-92ab-18eb457ec9e9","html_url":"https://github.com/webrecorder/web-replay-gen","commit_stats":{"total_commits":30,"total_committers":5,"mean_commits":6.0,"dds":"0.43333333333333335","last_synced_commit":"0a3e7b2fe71f50ee200c7e829853ac05caef1439"},"previous_names":[],"tags_count":1,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrecorder%2Fweb-replay-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrecorder%2Fweb-replay-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrecorder%2Fweb-replay-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webrecorder%2Fweb-replay-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webrecorder","download_url":"https://codeload.github.com/webrecorder/web-replay-gen/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249574182,"owners_count":21293237,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T16:26:56.555Z","updated_at":"2025-04-21T06:31:26.194Z","avatar_url":"https://github.com/webrecorder.png","language":"JavaScript","funding_links":["https://github.com/sponsors/webrecorder"],"categories":[],"sub_categories":[],"readme":"# Web Replay Gen\n\nGenerate a website for viewing web archives.\n\n:globe_with_meridians: [Live demo](https://webrecorder.github.io/web-replay-gen/)\n\n## Features\n\n- Compatible with web archives in [WACZ format](https://specs.webrecorder.net/wacz/latest/) (WARC also supported)\n- Automatic deploy to GitHub Pages\n- List \u0026 autocomplete-search web archives\n- Embedded web archive replay\n- Load web archives from any `https://` or `s3://` URLs.\n- IPFS Support Coming soon\n\n---\n\nJump to:\n\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Deployment](#deployment)\n- [Dev Server](#dev-server)\n- [Templates](#templates)\n- [Web Components](#web-components)\n- [Styling](#styling)\n\n---\n\n## Quick Start\n\n### 1. Create new project from template\n\n[![Use this template](https://img.shields.io/badge/Use_this_template-informational)](https://github.com/webrecorder/web-replay-gen/generate)\n\nIn the new repository, go to \"Settings\" \u003e \"Pages\" for the new repository and under \"Source\" select \"GitHub Actions\".\n\nOnce settings have been updated, clone your new repository as usual to your local machine.\n\n### 2. Install dependencies\n\nNavigate to your project directory and run:\n\n```shell\nnpm install\n```\n\n### 3. Update `wrg-config.json`\n\nAdd your website title and web archive URL:\n\n```diff\n{\n  \"site\": {\n    \"title\": \"My Web Archives\"\n  },\n  \"archives\": [\n    \"https://replayweb.page/docs/assets/example.wacz\",\n    \"s3://webrecorder-builds/warcs/netpreserve-twitter.warc\"\n  ]\n}\n```\n\n\u003e See [Configuration](#configuration) for all options.\n\n### 4. Preview website\n\nTo access your site from \u003chttp://localhost:8080\u003e, run:\n\n```shell\nnpm run serve\n```\n\n### 5. Deploy to GitHub Pages\n\nPush to `main` to automatically deploy your site to GitHub Pages. :sparkles:\n\n\u003e You can also opt-out of Pages to use another hosting provider. See [Deployment](#deployment) for more information.\n\n---\n\n## Configuration\n\nConfigure options in `wrg-config.json`.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n#### `site`\n\nObject for configuring site details.\n\n\u003c/summary\u003e\n\n| Key            | Default Value    | Value Type |                                                                     |\n| -------------- | ---------------- | ---------- | ------------------------------------------------------------------- |\n| `site`         | `{}`             | `Object`   |                                                                     |\n| `site.title`   | `\"Web Archives\"` | `string`   | Website title, used in browser title bar and as the primary heading |\n| `site.logoSrc` | `\"\"`             | `string`   | Website logo, any valid `\u003cimg\u003e` `src`                               |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n#### `replay`\n\nObject for configuring the [embedded ReplayWeb.page](https://replayweb.page/docs/embedding) `\u003creplay-web-page\u003e` tag.\n\n\u003c/summary\u003e\n\n| Key                 | Default Value  | Value Type                        |                                                                                               |\n| ------------------- | -------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |\n| `replay`            | `{}`           | `Object`                          |                                                                                               |\n| `replay.embed`      | `\"replayonly\"` | `\"replayonly\"\\|\"full\"\\|\"default\"` | ReplayWeb.page [`embed` option](https://replayweb.page/docs/embedding#embedding-options)      |\n| `replay.replayBase` | `\"./replay/\"`  | `\"./replay/\"\\|string\"`            | ReplayWeb.page [`replayBase` option](https://replayweb.page/docs/embedding#embedding-options) |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n#### `archives`\n\nConfigure location of web archive files.\n\n\u003c/summary\u003e\n\n| Key        | Default Value | Value Type                                        |\n| ---------- | ------------- | ------------------------------------------------- |\n| `archives` | `[]`          | `undefined\\|string[]\\|{name:string;url:string}[]` |\n\nOption values can be a JSON array of plain URL strings or an object with `name` and `url`\n\nExample:\n\n```js\n{\n  \"archives\": [\n    // Plain URL string:\n    \"https://replayweb.page/docs/assets/example.wacz\"\n\n    // Plain URL string to S3 bucket\n    \"s3://my-bucket/a/archive.wacz\",\n\n    // Plain URL string to a file relative to output `_site`\n    \"./public-data/\",\n\n    // Object with name and URL:\n    {\n      \"name\": \"My Web Archive\",\n      \"url\": \"s3://my-bucket/b/archive.wacz\"\n    }\n  ]\n}\n```\n\nSetting `archivesPath` will override this option.\n\n\u003c/details\u003e\n\n### Build-time options\n\nThe 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.\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n#### `replayBaseURL` [_Build-time Only_]\n\nBase URL for ReplayWeb.page scripts.\n\n\u003c/summary\u003e\n\n| Key             | Default Value                                  | Value Type |                                     |\n| --------------- | ---------------------------------------------- | ---------- | ----------------------------------- |\n| `replayBaseURL` | `\"https://cdn.jsdelivr.net/npm/replaywebpage\"` | `string`   | Base URL for ReplayWeb.page scripts |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\n\n#### `archivesPath` [_Build-time Only_]\n\nPath to local web archive files.\n\n\u003c/summary\u003e\n\n| Key            | Default Value | Value Type |\n| -------------- | ------------- | ---------- |\n| `archivesPath` | `undefined`   | `string`   |\n\nPaths should be relative to your project root (i.e. where you execute `npm run build`.) Option values can be:\n\n- Relative path to directory containing `.wacz` files\n- Relative path to `.txt` file with newline-separated list of remote URLs\n- Relative path to JSON file with an `archives` key where the value is a JSON array\n\nExamples:\n\n```js\n{\n  \"archivesPath\": \"./wacz-files/\"\n}\n```\n\n```js\n{\n  \"archivesPath\": \"./source_data/archives.json\"\n}\n```\n\nTake precedence over the `archives` array.\n\n\u003c/details\u003e\n\n## Deployment\n\n### Github Pages\n\nBy default, Web Replay Gen will deploy to Pages on every push to the `main` branch, as configured in [this GitHub Workflow](.github/workflows/publish-gh-pages.yml). To change the deployment workflow (e.g. to change the release branch) update the [`publish-gh-pages.yml`](.github/workflows/publish-gh-pages.yml) workflow file.\n\n#### Local web archive support\n\nDue to GitHub's [file size limit](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-large-files-on-github#file-size-limits) and lack of support for [git LFS in Pages](https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage), you may run into an issue with deploying large web archive files. To resolve the issue, you can create a separate workflow for uploading web archive files elsewhere (e.g. to an S3 bucket) and configure your site with the remote URLs. Alternatively, you can [self-host](#self-hosting).\n\n#### Opt-Out\n\nTo prevent deployment to Pages, either disable the workflow [through the GitHub UI](https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow) or simply delete the workflow file (`publish-gh-pages.yml`.)\n\n### Self-hosting\n\nFirst, [remove the Pages workflow](#opt-out). Run the build script to output your site into a local directory:\n\n```\nnpm run build\n```\n\nThis will output a production-ready build to `/_site`. Transfer the contents of `/_site` to your host.\n\n## Dev Server\n\nRun the dev server with `npm run serve` to serve files from `/_site`.\n\nSaving changes to `src` will automatically reload the page. See [11ty Browsersync docs](https://www.11ty.dev/docs/server-browsersync/) to customize the dev server.\n\n### Local configuration\n\nCreate and configure options in `wrg-config.local.json` to specify different site options during local development.\n\nTo use `wrg-local.local.json`, run the following:\n\n```\necho 'WRG_CONFIG_NAME=wrg-config.local.json' \u003e .env\n```\n\nTo disable, comment out the line in `.env`:\n\n```\n# WRG_CONFIG_NAME=wrg-config.local.json\n```\n\n## Templates\n\nWeb 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.\n\n## Web Components \u0026 client-side JavaScript\n\nJS 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`:\n\n```html\n\u003c!-- my-template.njk --\u003e\n\u003cmy-component\u003e\u003c/my-component\u003e\n\n\u003cscript type=\"module-shim\"\u003e\n  import('./js/my-component.js');\n\u003c/script\u003e\n```\n\n## Styling\n\n### TailwindCSS\n\n[TailwindCSS](https://tailwindcss.com/) is enabled in all [Eleventy template](https://www.11ty.dev/docs/languages/) files. You can install a specific Tailwind version with `npm install -D tailwindcss@{version}`.\n\nNote: Tailwind is not available in web components (`/components/*.js`) due to limitations with the shadow DOM. See [workarounds](https://github.com/tailwindlabs/tailwindcss/discussions/1935) if you'd like to access Tailwind classes in web components.\n\n### Customization\n\nTailwind supports inline-style-like customization through [arbitrary values in class names](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values). For a more global approach to customization (for example, if you have vendor CSS file) include a `\u003clink rel=\"stylesheet\"\u003e` tag in your template file. Any `.css` files in `/src` will be copied to the output site folder and can be referenced in the `\u003clink\u003e` tag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebrecorder%2Fweb-replay-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebrecorder%2Fweb-replay-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebrecorder%2Fweb-replay-gen/lists"}