electronic Babylonian Library frontend

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

Requirements

• yarn
• Node 16
• Chrome (for Lighthouse)

The following services are needed to run application:

• eBL API
• Auth0
• Sentry

Installation

• yarn install 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).

Gitpod

The project comes with a Gitpod configuration including select extensions. Click the button below, configure the environment variables and you are good to go. It might be necessary to use .env.local instead of the facilities provided in Gitpod as they override .env.test.

Gitpod uses too many domains to feasibly whitelist it Auth0. Use local companian app to access the running application via localhost.

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