@internetarchive/fetch-handler 1.0.1

package/src/utils/fetch-retrier.ts

@@ -0,0 +1,141 @@
+import type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';
+import { AnalyticsHandler } from '@internetarchive/analytics-manager';
+import { promisedSleep } from './promised-sleep';
+
+/**
+ * A class that retries a fetch request.
+ */
+export interface FetchRetrierInterface {
+  /**
+   * Execute a fetch with retry.
+   *
+   * @param requestInfo RequestInfo
+   * @param init Optional RequestInit
+   * @param retries Optional number of retries to attempt
+   * @returns Promise<Response>
+   */
+  fetchRetry(
+    requestInfo: RequestInfo,
+    init?: RequestInit,
+    retries?: number,
+  ): Promise<Response>;
+}
+
+/** @inheritdoc */
+export class FetchRetrier implements FetchRetrierInterface {
+  private analyticsHandler = new AnalyticsHandler({ enableAnalytics: true });
+  private sleep = promisedSleep; // default sleep function
+
+  private retryCount = 2;
+
+  private retryDelay = 1000;
+
+  constructor(options?: {
+    analyticsHandler?: AnalyticsHandlerInterface;
+    retryCount?: number;
+    retryDelay?: number;
+    sleepFn?: (ms: number) => Promise<void>; // <-- add this!
+  }) {
+    if (options?.analyticsHandler)
+      this.analyticsHandler = options.analyticsHandler;
+    if (options?.retryCount) this.retryCount = options.retryCount;
+    if (options?.retryDelay) this.retryDelay = options.retryDelay;
+    if (options?.sleepFn) this.sleep = options.sleepFn; // override if provided
+  }
+
+  /** @inheritdoc */
+  public async fetchRetry(
+    requestInfo: RequestInfo,
+    init?: RequestInit,
+    retries: number = this.retryCount,
+  ): Promise<Response> {
+    const urlString =
+      typeof requestInfo === 'string' ? requestInfo : requestInfo.url;
+    const retryNumber = this.retryCount - retries + 1;
+
+    try {
+      const response = await fetch(requestInfo, init);
+      if (response.ok) return response;
+      // don't retry on a 404 since this will never succeed
+      if (response.status === 404) {
+        this.log404Event(urlString);
+        return response;
+      }
+      if (retries > 0) {
+        await this.sleep(this.retryDelay);
+        this.logRetryEvent(
+          urlString,
+          retryNumber,
+          response.statusText,
+          response.status,
+        );
+        return this.fetchRetry(requestInfo, init, retries - 1);
+      }
+      this.logFailureEvent(urlString, response.status);
+      return response;
+    } catch (error) {
+      // if a content blocker is detected, log it and don't retry
+      if (this.isContentBlockerError(error)) {
+        this.logContentBlockingEvent(urlString, error);
+        throw error;
+      }
+
+      if (retries > 0) {
+        await this.sleep(this.retryDelay);
+        // intentionally duplicating the error message here since we want something
+        // in the status code even though we won't have an actual code
+        this.logRetryEvent(urlString, retryNumber, error, error);
+        return this.fetchRetry(requestInfo, init, retries - 1);
+      }
+
+      this.logFailureEvent(urlString, error);
+      throw error;
+    }
+  }
+
+  private isContentBlockerError(error: unknown): boolean {
+    // all of the content blocker errors are `TypeError`
+    if (!(error instanceof TypeError)) return false;
+    const message = error.message.toLowerCase();
+    return message.includes('content blocker');
+  }
+
+  private readonly eventCategory = 'offshootFetchRetry';
+
+  private logRetryEvent(
+    urlString: string,
+    retryNumber: number,
+    status: unknown,
+    code: unknown,
+  ) {
+    this.analyticsHandler.sendEvent({
+      category: this.eventCategory,
+      action: 'retryingFetch',
+      label: `retryNumber: ${retryNumber} / ${this.retryCount}, code: ${code}, status: ${status}, url: ${urlString}`,
+    });
+  }
+
+  private logFailureEvent(urlString: string, error: unknown) {
+    this.analyticsHandler.sendEvent({
+      category: this.eventCategory,
+      action: 'fetchFailed',
+      label: `error: ${error}, url: ${urlString}`,
+    });
+  }
+
+  private log404Event(urlString: string) {
+    this.analyticsHandler.sendEvent({
+      category: this.eventCategory,
+      action: 'status404NotRetrying',
+      label: `url: ${urlString}`,
+    });
+  }
+
+  private logContentBlockingEvent(urlString: string, error: unknown) {
+    this.analyticsHandler.sendEvent({
+      category: this.eventCategory,
+      action: 'contentBlockerDetectedNotRetrying',
+      label: `error: ${error}, url: ${urlString}`,
+    });
+  }
+}

package/src/utils/promised-sleep.ts

@@ -0,0 +1,15 @@
+/**
+ * Asynchronously pause execution for a given number of milliseconds.
+ *
+ * Used for waiting for some asynchronous updates.
+ *
+ * Usage:
+ * await promisedSleep(100)
+ *
+ * @export
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function promisedSleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/ssl/server.crt

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDszCCApugAwIBAgIUYr5csS2ntaMTww0b5QoFI0xlOpUwDQYJKoZIhvcNAQEL
+BQAwaTELMAkGA1UEBhMCVVMxCzAJBgNVBAgMAkNBMRYwFAYDVQQHDA1TYW4gRnJh
+bmNpc2NvMRkwFwYDVQQKDBBJbnRlcm5ldCBBcmNoaXZlMRowGAYDVQQDDBFsb2Nh
+bC5hcmNoaXZlLm9yZzAeFw0yNTAzMDcxOTM1MzRaFw0yNTA0MDYxOTM1MzRaMGkx
+CzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNj
+bzEZMBcGA1UECgwQSW50ZXJuZXQgQXJjaGl2ZTEaMBgGA1UEAwwRbG9jYWwuYXJj
+aGl2ZS5vcmcwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDZqbS9hNS3
+8AtcA7Uszq7EA7RavuHc8AcpbURa6Y7NORs0SmfDD0oLptQ7DX5pSuHyOeDHzQ3U
+XRCUDAhAD1XlaYQ6PPdiJPRAe4ACELzgDzepxVz3pdKPcfXd5/mHV3ghUZya2XW5
+DSF1CRYUX2j10a+JORJIG4bhvTg4HxTJZZDuaNfBMC6ZSn7d9YLQoAf1MLLJm43Y
+cj1WlOnyG4DHxNEqEk260BlbBywJH+SJA6GA0GR2bnzYZaDnZ0wqea0Zamx8ijpd
+JxBUxYOqLfzs2KREVkkGOmsFEu82W6G3D4bKsY1UNaWXb/jcl3UkXIJJij6CdbbM
+QkUJc8dow3sVAgMBAAGjUzBRMB0GA1UdDgQWBBSla0L0Yhpx9/DEV4uJ6OoHH92Q
+bTAfBgNVHSMEGDAWgBSla0L0Yhpx9/DEV4uJ6OoHH92QbTAPBgNVHRMBAf8EBTAD
+AQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBEzt9sgWtwjLI7AVrejDSE6F/01ng4bTni
+0PJXa7IpwjhAApVWcjxDKp8SkDUAcZNULqBGvpPicqjnKf+wxk3xTMc7pvLqzOor
+pm+plDUBfCEbrv1ouLDMgOtxQxbwbBUPySsLoNmDUGAGnL2zENX7qidOOmmSQEN4
+jZuPtiEkgTqmtkfHaRX/7jhmGVfxMxj0Krlar1/cSbvwaVs4kRSjiL9/avT+AX59
+0QoNYTLGcBP0RKia8NF2A3cgUivIMFZQDvdsiAvqY+DbC7Mnyv4Sj/ZHHwVa9+8k
+iRU56DrOt7sgaa/oQfzWnvRtL0F5eXC3veqM4qZrXs9hHeGlgPFo
+-----END CERTIFICATE-----

package/ssl/server.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQDZqbS9hNS38Atc
+A7Uszq7EA7RavuHc8AcpbURa6Y7NORs0SmfDD0oLptQ7DX5pSuHyOeDHzQ3UXRCU
+DAhAD1XlaYQ6PPdiJPRAe4ACELzgDzepxVz3pdKPcfXd5/mHV3ghUZya2XW5DSF1
+CRYUX2j10a+JORJIG4bhvTg4HxTJZZDuaNfBMC6ZSn7d9YLQoAf1MLLJm43Ycj1W
+lOnyG4DHxNEqEk260BlbBywJH+SJA6GA0GR2bnzYZaDnZ0wqea0Zamx8ijpdJxBU
+xYOqLfzs2KREVkkGOmsFEu82W6G3D4bKsY1UNaWXb/jcl3UkXIJJij6CdbbMQkUJ
+c8dow3sVAgMBAAECggEANgLpITAhcuVDhFk9L3m4H1bF/dCpDmCXfl2pXR/guicm
+C4M9HUeheaOzvVWbXThiOe/HyfylpmFTmFEmCPNlPrDAyYzQXE/MNmYO/TQ3Eihk
+iSG68I764XKHbsG+Byoa2rW8NSaqEjniZ/7Rtkt4qasXMmdxlGgUP9bq6O45g8HV
+kHxneFlA2KbrvmWnBi7NTea9+tp61NWiq5n97UgHacQR6KkYIpbxd7uNSnCSdmXt
+pcwzO4ZPabJ2/DKRjePhU5OggPh+9AhJ3jsBo99GwYPgSZDh8E3vh2OWOtLBMUH3
+rmAYwlRT2aZ5hy5yi+4QD98WoUQtsr+9n757F8V6MQKBgQDzZycdgaKwWd5d34NN
+0TkFtPQPwxxJTCCs3I3q02uWcS3svQzBK0cWb4nISO04TnJ3MnXo83dgGhCMF+uZ
+FCXxAA53z8F92iZo+ELlXFDFwNeNYih/afDA42tWZ6TlVsDnZ4zQgRjHS7jEF/JV
+0ZgwGpw5725JQt64dic8wTOcDQKBgQDk7YYACQcWTnmjDhZQ3PZSX4fcTtzPZKZj
+fa1GrXEaUH1hSyc9VmY6qJpUmXexpvtr194nXE+O5wbThOHcBjVlo2Qv+vswmUX3
+WEcVzTVN4/fODCLCqFcMNIr+BzwZfwpT+p0u8g9FxDy1gGmvkxwIu8DCpnUT12Xj
+hm2wO+UxKQKBgFxCSDBF9+2SUtgQJYv0dwGzwiLLWMhro6MCAoT02D3w7nBihBgg
+GFTnuDkDc285ROfrZ4gB6MizeHwxgOrIGU2NMO62/+d9LbvyBiE76Z3bZ5i+kQ0i
+kc/7I69fn8ASLxJHTLenh0XbbNBfJ0riJCZvn7HSEGKShysyFdNQhAhtAoGAFYVi
+0IQIv4cXFkYPwQBUw7+pVQOw7GpI3heFf5x0goXIk6nuAW0q5R7Oi192CiRphGTh
+xI+ABy4ezSmz1exbfreShpQwowv1sOACpsEI3s6skBlB90y+Ci6yVlk1xCvWO7jW
+qAAngWaGUoXE6bWJsCR+ZY4ieYAJWw9bJnMrA6kCgYAzV4Xeoh5ofENZM21wKW3W
+iCzRibPObv6Vb/j9A9yT57yzI3BdfvsX5zmuSvOJm1DimgGY9nCJUzUEYG0a1Dhh
+/rqObPoVIFGesmvwflVYFktmVHk7ycEDVreSTz23cvmraPz1fnpdKeuEs4sRQJV7
+iJhLoxX5SJlJc0RXMhgHGQ==
+-----END PRIVATE KEY-----

package/test/fetch-retrier.test.ts

@@ -0,0 +1,173 @@
+import { expect } from '@open-wc/testing';
+import sinon from 'sinon';
+import { FetchRetrier } from '../src/utils/fetch-retrier';
+import { MockAnalyticsHandler } from './mocks/mock-analytics-handler';
+
+describe('FetchRetrier', () => {
+  let fetchStub: sinon.SinonStub;
+  let sleepStub: sinon.SinonStub;
+  let analytics: MockAnalyticsHandler;
+
+  beforeEach(() => {
+    analytics = new MockAnalyticsHandler();
+    fetchStub = sinon.stub(globalThis, 'fetch');
+    sleepStub = sinon.stub().resolves(); // stubbed promisedSleep
+  });
+
+  afterEach(() => {
+    fetchStub.restore();
+  });
+
+  it('returns response on first success', async () => {
+    fetchStub.resolves(new Response('ok', { status: 200 }));
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/data');
+
+    expect(res.status).to.equal(200);
+    expect(fetchStub.callCount).to.equal(1);
+    expect(sleepStub.callCount).to.equal(0);
+    expect(analytics.events.length).to.equal(0);
+  });
+
+  it('does not retry on 404 and logs event', async () => {
+    fetchStub.resolves(new Response('not found', { status: 404 }));
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/404');
+
+    expect(res.status).to.equal(404);
+    expect(fetchStub.callCount).to.equal(1);
+    expect(sleepStub.callCount).to.equal(0);
+    expect(analytics.events[0].action).to.equal('status404NotRetrying');
+  });
+
+  it('retries on 500 and logs retry/failure events', async () => {
+    fetchStub.onCall(0).resolves(new Response('fail', { status: 500 }));
+    fetchStub.onCall(1).resolves(new Response('fail again', { status: 500 }));
+    fetchStub.onCall(2).resolves(new Response('still fail', { status: 500 }));
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 2,
+      retryDelay: 1,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/fail');
+
+    expect(res.status).to.equal(500);
+    expect(fetchStub.callCount).to.equal(3);
+    expect(sleepStub.callCount).to.equal(2);
+    expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;
+    expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;
+  });
+
+  it('retries on fetch error and eventually succeeds', async () => {
+    fetchStub.onCall(0).rejects(new Error('Network error'));
+    fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 1,
+      retryDelay: 1,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/retry');
+
+    expect(res.status).to.equal(200);
+    expect(fetchStub.callCount).to.equal(2);
+    expect(sleepStub.calledOnce).to.be.true;
+    expect(analytics.events.some(e => e.action === 'retryingFetch')).to.be.true;
+  });
+
+  it('throws and logs when retries are exhausted due to network error', async () => {
+    fetchStub.rejects(new Error('Boom'));
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 1,
+      retryDelay: 1,
+      sleepFn: sleepStub,
+    });
+
+    try {
+      await retrier.fetchRetry('https://foo.org/networkfail');
+      throw new Error('Should have thrown');
+    } catch (err: any) {
+      expect(err.message).to.equal('Boom');
+    }
+
+    expect(fetchStub.callCount).to.equal(2);
+    expect(sleepStub.callCount).to.equal(1);
+    expect(analytics.events.some(e => e.action === 'fetchFailed')).to.be.true;
+  });
+
+  it('detects content blocker error and does not retry', async () => {
+    const blockerError = new TypeError('Content Blocker denied request');
+    fetchStub.rejects(blockerError);
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 2,
+      sleepFn: sleepStub,
+    });
+
+    try {
+      await retrier.fetchRetry('https://foo.org/blocked');
+      throw new Error('Should have thrown');
+    } catch (err: any) {
+      expect(err).to.equal(blockerError);
+    }
+
+    expect(fetchStub.callCount).to.equal(1);
+    expect(sleepStub.callCount).to.equal(0);
+    expect(
+      analytics.events.some(
+        e => e.action === 'contentBlockerDetectedNotRetrying',
+      ),
+    ).to.be.true;
+  });
+
+  it('calls sleepFn on retry with correct delay', async () => {
+    fetchStub.onCall(0).resolves(new Response(null, { status: 500 }));
+    fetchStub.onCall(1).resolves(new Response('ok', { status: 200 }));
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 2,
+      retryDelay: 1234,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/retry-with-sleep');
+
+    expect(res.status).to.equal(200);
+    expect(sleepStub.calledOnce).to.be.true;
+    expect(sleepStub.calledWith(1234)).to.be.true;
+  });
+
+  it('sleeps for each retry attempt', async () => {
+    fetchStub.resolves(new Response(null, { status: 500 }));
+
+    const retrier = new FetchRetrier({
+      analyticsHandler: analytics,
+      retryCount: 2,
+      retryDelay: 300,
+      sleepFn: sleepStub,
+    });
+
+    const res = await retrier.fetchRetry('https://foo.org/retry-fail');
+
+    expect(res.status).to.equal(500);
+    expect(sleepStub.callCount).to.equal(2);
+    expect(sleepStub.alwaysCalledWith(300)).to.be.true;
+  });
+});

package/test/ia-fetch-handler.test.ts

@@ -0,0 +1,66 @@
+import { expect } from '@open-wc/testing';
+import { IaFetchHandler } from '../src/ia-fetch-handler';
+import { FetchRetrierInterface } from '../src/utils/fetch-retrier';
+
+class MockFetchRetrier implements FetchRetrierInterface {
+  requestInfo?: RequestInfo;
+  init?: RequestInit;
+  retries?: number;
+
+  async fetchRetry(
+    requestInfo: RequestInfo,
+    init?: RequestInit,
+    retries?: number,
+  ): Promise<Response> {
+    this.init = init;
+    this.requestInfo = requestInfo;
+    this.retries = retries;
+    return new Response(JSON.stringify({ boop: 'snoot' }), { status: 200 });
+  }
+}
+
+describe('Fetch Handler', () => {
+  describe('fetch', () => {
+    it('adds reCache=1 if it is in the current url', async () => {
+      const fetchRetrier = new MockFetchRetrier();
+      const fetchHandler = new IaFetchHandler({
+        fetchRetrier: fetchRetrier,
+        searchParams: '?reCache=1',
+      });
+      await fetchHandler.fetch('https://foo.org/api/v1/snoot');
+      expect(fetchRetrier.requestInfo).to.equal(
+        'https://foo.org/api/v1/snoot?reCache=1',
+      );
+    });
+  });
+
+  describe('fetchIAApiResponse', () => {
+    it('prepends the IA basehost to the url when making a request', async () => {
+      const endpoint = '/foo/service/endpoint.php';
+      const fetchRetrier = new MockFetchRetrier();
+      const fetchHandler = new IaFetchHandler({
+        iaApiBaseUrl: 'www.example.com',
+        fetchRetrier: fetchRetrier,
+      });
+      await fetchHandler.fetchIAApiResponse(endpoint);
+      expect(fetchRetrier.requestInfo).to.equal(
+        'www.example.com/foo/service/endpoint.php',
+      );
+    });
+  });
+
+  describe('fetchApiResponse', () => {
+    it('adds credentials: include if requested', async () => {
+      const endpoint = '/foo/service/endpoint.php';
+      const fetchRetrier = new MockFetchRetrier();
+      const fetchHandler = new IaFetchHandler({
+        iaApiBaseUrl: 'www.example.com',
+        fetchRetrier: fetchRetrier,
+      });
+      await fetchHandler.fetchApiResponse(endpoint, {
+        includeCredentials: true,
+      });
+      expect(fetchRetrier.init).to.deep.equal({ credentials: 'include' });
+    });
+  });
+});

package/test/mocks/mock-analytics-handler.ts

@@ -0,0 +1,43 @@
+import type { AnalyticsEvent } from '@internetarchive/analytics-manager';
+import type { AnalyticsHandlerInterface } from '@internetarchive/analytics-manager';
+
+export type MockAnalyticsEvent = AnalyticsEvent & {
+  bucketType: '1%' | '100%';
+  additionalEventParams?: object;
+};
+export class MockAnalyticsHandler implements AnalyticsHandlerInterface {
+  events: MockAnalyticsEvent[] = [];
+
+  sendPing(values: Record<string, any>): void {}
+  sendEvent(event: MockAnalyticsEvent): void {
+    const thisEvent = Object.assign({}, event, { bucketType: '1%' });
+    this.events.push(thisEvent);
+  }
+  send_event(
+    category: string,
+    action: string,
+    label?: string,
+    additionalEventParams?: object,
+  ): void {
+    this.events.push({
+      category,
+      action,
+      label,
+      bucketType: '1%',
+      additionalEventParams: { ...additionalEventParams },
+    });
+  }
+  sendEventNoSampling(event: AnalyticsEvent): void {
+    this.events.push({
+      ...event,
+      bucketType: '100%',
+    } as unknown as MockAnalyticsEvent);
+  }
+  trackIaxParameter(location: string): void {}
+  trackPageView(options?: {
+    mediaType?: string;
+    mediaLanguage?: string;
+    primaryCollection?: string;
+    page?: string;
+  }): void {}
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "es2018",
+    "module": "esnext",
+    "moduleResolution": "node",
+    "noEmitOnError": true,
+    "lib": ["es2017", "dom"],
+    "strict": true,
+    "esModuleInterop": false,
+    "allowSyntheticDefaultImports": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "outDir": "dist",
+    "sourceMap": true,
+    "inlineSources": true,
+    "rootDir": "./",
+    "declaration": true,
+    "plugins": [
+      {
+        "name": "ts-lit-plugin"
+      }
+    ],
+    "paths": {
+      // workaround for: https://github.com/vitest-dev/vitest/issues/4567
+      "rollup/parseAst": [
+        "./node_modules/rollup/dist/parseAst"
+    ]
+}
+  },
+  "include": ["**/*.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vite';
+import { resolve } from 'path';
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  base: './',
+  root: resolve(__dirname, './demo'),
+  build: {
+    /**
+     * This is the directory where the built files will be placed
+     * that we upload to GitHub Pages.
+     */
+    outDir: '../ghpages/demo',
+    emptyOutDir: true,
+    manifest: true,
+    rollupOptions: {
+      input: {
+        main: resolve(__dirname, 'demo/index.html'),
+      },
+      output: {
+        entryFileNames: 'app-root.js',
+      },
+    },
+  },
+});

package/web-dev-server.config.mjs

@@ -0,0 +1,32 @@
+// import { hmrPlugin, presets } from '@open-wc/dev-server-hmr';
+
+/** Use Hot Module replacement by adding --hmr to the start command */
+const hmr = process.argv.includes('--hmr');
+
+export default /** @type {import('@web/dev-server').DevServerConfig} */ ({
+  nodeResolve: true,
+  open: '/demo',
+  watch: !hmr,
+  sslCert: './ssl/server.crt',
+  sslKey: './ssl/server.key',
+  hostname: 'local.archive.org',
+  http2: true,
+
+  /** Compile JS for older browsers. Requires @web/dev-server-esbuild plugin */
+  // esbuildTarget: 'auto'
+
+  /** Set appIndex to enable SPA routing */
+  // appIndex: 'demo/index.html',
+
+  /** Configure bare import resolve plugin */
+  // nodeResolve: {
+  //   exportConditions: ['browser', 'development']
+  // },
+
+  plugins: [
+    /** Use Hot Module Replacement by uncommenting. Requires @open-wc/dev-server-hmr plugin */
+    // hmr && hmrPlugin({ exclude: ['**/*/node_modules/**/*'], presets: [presets.litElement] }),
+  ],
+
+  // See documentation for all available options
+});

package/web-test-runner.config.mjs

@@ -0,0 +1,41 @@
+// import { playwrightLauncher } from '@web/test-runner-playwright';
+
+const filteredLogs = ['Running in dev mode', 'lit-html is in dev mode'];
+
+export default /** @type {import("@web/test-runner").TestRunnerConfig} */ ({
+  /** Test files to run */
+  files: 'dist/test/**/*.test.js',
+
+  /** Resolve bare module imports */
+  nodeResolve: {
+    exportConditions: ['browser', 'development'],
+  },
+
+  /** Filter out lit dev mode logs */
+  filterBrowserLogs(log) {
+    for (const arg of log.args) {
+      if (typeof arg === 'string' && filteredLogs.some(l => arg.includes(l))) {
+        return false;
+      }
+    }
+    return true;
+  },
+
+  /** Compile JS for older browsers. Requires @web/dev-server-esbuild plugin */
+  // esbuildTarget: 'auto',
+
+  /** Amount of browsers to run concurrently */
+  // concurrentBrowsers: 2,
+
+  /** Amount of test files per browser to test concurrently */
+  // concurrency: 1,
+
+  /** Browsers to run tests on */
+  // browsers: [
+  //   playwrightLauncher({ product: 'chromium' }),
+  //   playwrightLauncher({ product: 'firefox' }),
+  //   playwrightLauncher({ product: 'webkit' }),
+  // ],
+
+  // See documentation for all available options
+});