electronic Babylonian Library frontend

This project was bootstrapped with Create React App. You can find the most recent version of the guide in the Create React App template README.

Requirements

• yarn
• Node 20
• Chrome (for Lighthouse)

The following services are needed to run application:

• eBL API
• Auth0
• Sentry

Development Environment Setup

This project supports two development setup options: GitHub Codespaces with dev containers (recommended) or local installation.

Option 1: GitHub Codespaces with Dev Containers (Recommended)

This project is configured to work with GitHub Codespaces using dev containers. The dev container provides a pre-configured development environment with all necessary dependencies (Node 20, yarn, Chrome, etc.) without requiring local installation.

To use GitHub Codespaces:

1. Navigate to the repository on GitHub
2. Click the Code button and select the Codespaces tab
3. Create a new codespace or open an existing one
4. Important: For dev containers to work properly, open the codespace in the desktop version of VS Code rather than the browser. When the codespace starts, VS Code will prompt you to open it in the desktop application.
5. Once opened in VS Code desktop, the dev container will automatically set up the development environment
6. Configure the required environment variables in .env.local (see Running the application section)
7. Dependencies are installed automatically via the postCreateCommand in the dev container configuration (you can manually run yarn install if needed)
8. You're ready to develop!

Option 2: Local Installation

If you prefer to develop locally without using Codespaces, follow these steps:

Prerequisites:

• Install Node 20
• Install yarn
• Install Git LFS (required for the Git hooks)
• Install Chrome (required for Lighthouse)

Setup:

1. Clone the repository:

   git clone https://github.com/ElectronicBabylonianLiterature/ebl-frontend.git
   cd ebl-frontend

2. Install dependencies:

   yarn install

   This will automatically patch history in node_modules which is an indirect dependency for react-router version 5 because of remix-run/history#505 (updating react-router to version 6 would fix this issue too).

3. Configure environment variables in .env.local (see Running the application section)

4. Start the development server:

yarn start

Running tests

yarn lint
yarn tsc
yarn test

Running test coverage check

yarn test --coverage --watchAll

Configuring services

Auth0

A single page application has to be setup in Auth0. The frontends root URL (e.g. http://localhost:3000 for development) must be in Callback URLs, Logout URLs, and Web Origins. Domain and Client ID are needed for the environment variables (see below). In a production environment the domain must be added to frame-src in the CSP.

Sentry

An organization and project need to be setup in Sentry. The applications domain must be in Allowed Domains of the project. DSN under Client Keys is needed for the for the environment variables (see below). In a production environment the domain must be added to frame-src in CSP.

eBL API

In a production environment the api domain must be added to img-src in CSP.

Running the application

The application reads the configuration from following environment variables:

REACT_APP_AUTH0_DOMAIN=<Auth0 domain>
REACT_APP_AUTH0_CLIENT_ID=<Auth0 client ID>
REACT_APP_AUTH0_AUDIENCE=<Auth0 audience>
REACT_APP_DICTIONARY_API_URL=<eBL API URL>
REACT_APP_SENTRY_DSN=<Sentry DSN>
REACT_APP_CORRECTIONS_EMAIL=<Email for submitting corrections>
REACT_APP_INFO_EMAIL=<Email for general questions and contact>
REACT_APP_GA_TRACKING_ID=<Google Analytics 4 tracking (measurement) Id>

In production environments INLINE_RUNTIME_CHUNK must be set to false due to Content Security Policy.

yarn start starts the development server. The environment variables are read from .env.local.

Updating dependencies

Updating react-image-annotation could break Annotation.js in the annotation-tool.

Lighthouse

Google Lighthouse is installed as a development dependency and can be run via yarn:

yarn lighthouse <url>

Promises

bluebird promises are used whenever a cancellable promise is needed. E.g. when loading data to components (see isMounted is an Antipattern). bluebird is compatible with native JavaScript promises, but care should taken that a bluebird promise is always used when Promise.cancel() is needed.

Authentication and Authorization

Authentication is handled with Auth0 and @auth0/auth0-spa-js.

Display of content can be controlled using SessionContext:

// Access with Context.Consumer
;<SessionContext.Consumer>
  {(session: Session): JSX.Element => (
    <span>{session.isAllowedToReadFragments() ? 'access' : 'no access'}</span>
  )}
</SessionContext.Consumer>

// Access with useContext hook
const session = useContext(SessionContext)
const hasAccess = session.isAllowedToReadTexts()

Sitemap

The sitemap provides a roadmap of the website's content to help search engines index all pages and improve the site's visibility in search results.

✅ Automated Update (Recommended)

The sitemap is now updated automatically using a GitHub Actions workflow. This routine runs once a week and also allows manual execution when needed.

To manually trigger the automated sitemap update:

1. Go to the repository's "Actions" tab on GitHub.
2. Select the workflow named "Update Sitemap".
3. Click "Run workflow" (top right) and confirm.

This action will:

• Download and regenerate the sitemap files.
• Create a pull request with the updated files.
• Automatically merge the pull request once all required checks pass.

⚠️ Note that an application redeploy (Swarmpit) is still needed for the sitemap to refresh.

🔑 Personal Access Token (PAT) Setup (Yearly Maintenance)

To keep the automation working, you must refresh the SITEMAP_AUTOUPDATE secret approximately once per year, as PATs expire.

1. Go to your GitHub Developer Settings → Fine-Grained Tokens.
2. Create a Fine-Grained Token:
   • Restrict it to just the ElectronicBabylonianLiterature/ebl-frontend repo.
   • Minimal scopes. Contents: Read and write, Pull requests: Read and write.
3. Name the token sitemap-autoupdate and set an expiration period (max. 12 months).
4. Save the value of the new token.
5. In the repository, go to Settings → Secrets and variables → Actions → Repository secrets.
6. Find SITEMAP_AUTOUPDATE and update the value with the token you just generated.
7. Save the secret. The next time the workflow runs, it will use the updated token.
8. If the PAT user changes, update git config user.name and git config user.email information in .github/workflows/update-sitemaps.yml.

🛠 Manual Update (Legacy Method)

Manual update is possible if automation fails.

1. Visit the sitemap page: https://www.ebl.lmu.de/sitemap
2. Wait until all files (sitemap.xml.gz, sitemap1.xml.gz, etc.) are downloaded.
3. Replace the content of the public/sitemap directory with the downloaded files.
4. Commit the changes to the master branch.

Coding Conventions

• Write clean code. Use linters and analysers to find code smells.
• Write tests for your code. Test Driven Development is recommended but not mandatory. There is no hard requirement for code coverage but it should improve over time.
• Use GitHub Flow for branches..
• Implement a proper domain model. Avoid passing data around in dictionaries.
• Prefer immutable value objects. Use Immer to update objects.
• Use Prettier code style.
• Always use TypeScript files .ts, .tsx.
• Stick to the good parts.
• Avoid Common mistakes with React Testing Library.

HTML/CSS

• Try to use semantic HTML.
• Use BEM naming convention for CSS classes.
• Use lowercase names for CSS classes.

Filenames

• TypeScript files with default import should have the same name as the default import. E.g. MyComponent.tsx, myFunction.tsx.
• CSS/Sass files for components should have the same name as the TSX File they are used in. E.g. MyComponent.css
• Other files and folders should have kebab case names. E.g. test-helpers.ts

Acknowledgements

Junicode webfont by psb1558 is licensed under the SIL Open Font License, Version 1.1. You can get the full distribution from Junicode download page.

Assurbanipal, Esagil, Santakku, SantakkuM, UllikummiA webfonts by Sylvie Vanséveren are freely available for the scientific community. You can get the full distributions from Download page.

Annotation.js in the annotation-tool is from Arian Allenson Valdez