browsertrix/docs/develop/frontend-dev.md

Running the Frontend for Development

This guide explains how to deploy an instance of the Browsertrix Cloud frontend for development.

This setup may be ideal for rapid development on the frontend, as it will allow running the frontend via yarn instead of the frontend image deployed in Kubernetes.

Requirements

This setup does require a Browsertrix Cloud API backend already in a Kubernetes cluster.

Refer to setup for local deployment for additional details on this setup.

Quickstart

Ensure the current working directory is set to the /frontend folder.

Install dependencies:

yarn

Copy environment variables from the sample file:

cp sample.env.local .env.local

Update API_BASE_URL in .env.local to point to your dev backend API. For example:

API_BASE_URL=http://dev.example.com/api

If connecting to a local deployment cluster, set API_BASE_URL to:

API_BASE_URL=http://localhost:30870/api

??? info "Minikube (on Mac)"

When using Minikube on a Mac, the port will not be 30870. Instead, Minikube opens a tunnel to a random port,
obtained by running `minikube service browsertrix-cloud-frontend --url` in a separate terminal.

Set API_BASE_URL to provided URL instead, eg. `API_BASE_URL=http://127.0.0.1:<TUNNEL_PORT>`

Start the dev server:

yarn start

This will open localhost:9870 in a new tab in your default browser.

To develop against a local instance of the backend API, follow instructions for deploying to a local Docker instance. Update API_BASE_URL and then restart the dev server.

Scripts

yarn <name>
start	runs app in development server, reloading on file changes
test	runs tests in chromium with playwright
build-dev	bundles app and outputs it in dist directory
build	bundles app, optimized for production, and outputs it to dist
lint	find and fix auto-fixable javascript errors
format	formats js, html and css files
localize:extract	generate XLIFF file to be translated
localize:build	output a localized version of strings/templates

Testing

Tests assertions are written in Chai.

To watch for file changes while running tests:

yarn test --watch

To run tests in multiple browsers:

yarn test --browsers chromium firefox webkit

Localization

Wrap text or templates in the msg helper to make them localizable:

// import from @lit/localize:
import { msg } from "@lit/localize";

// later, in the render function:
render() {
  return html`
    <button>
      ${msg("Click me")}
    </button>
  `
}

Entire templates can be wrapped as well:

render() {
  return msg(html`
    <p>Click the button</p>
    <button>Click me</button>
  `)
}

See: https://lit.dev/docs/localization/overview/#message-types

To add new languages:

1. Add BCP 47 language tag to targetLocales in lit-localize.json
2. Run yarn localize:extract to generate new .xlf file in /xliff
3. Provide .xlf file to translation team
4. Replace .xlf file once translated
5. Run yarn localize:build bring translation into src

See: https://lit.dev/docs/localization/overview/#extracting-messages