f6bab4f26c
- Renames "Dev" to "Develop" for improved navigation labels - Deployment docs are now located under a larger "Development" section (fewer nav bar choices & realistically I think anyone who wants to do one is going to be referring to the other) - Adds links to tools the first time they're mentioned - Rewords part of the homepage - Hides section navigation on the homepage (now we don't have a blank section nav bar! - Adds some syntax highlighting - Removes some manual word wrapping — this was done very rarely / inconsistently
114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# Running the Frontend
|
|
|
|
This guide explains how to deploy an instance of the Browsertrix Cloud frontend for development.
|
|
The frontend can connect to a Browsertrix Cloud API backend running locally or remotely.
|
|
|
|
## 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
|
|
```
|
|
|
|
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>
|