965aa7ff90
* docs refactor: - add local deployment guide local-dev-setup.md - deploy/local.md focuses only on deployment with latest release, links to local-dev-setup.md for local image deployment - add nav to mkdocs.yml to ensure correct order of pages - update microk8s specific info - update minikube specific info --------- Co-authored-by: Ilya Kreymer <ikreymer@gmail.com>
131 lines
3.6 KiB
Markdown
131 lines
3.6 KiB
Markdown
# 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](./local-dev-setup.md) for additional details on this setup.
|
|
|
|
## Quickstart
|
|
|
|
Ensure the current working directory is set to the `/frontend` folder.
|
|
|
|
Install dependencies:
|
|
|
|
```sh
|
|
yarn
|
|
```
|
|
|
|
Copy environment variables from the sample file:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](https://www.chaijs.com/api/bdd/).
|
|
|
|
To watch for file changes while running tests:
|
|
|
|
```sh
|
|
yarn test --watch
|
|
```
|
|
|
|
To run tests in multiple browsers:
|
|
|
|
```sh
|
|
yarn test --browsers chromium firefox webkit
|
|
```
|
|
|
|
## Localization
|
|
|
|
Wrap text or templates in the `msg` helper to make them localizable:
|
|
|
|
```js
|
|
// 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:
|
|
|
|
```js
|
|
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](https://www.w3.org/International/articles/language-tags/index.en) 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>
|