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 data provides a roadmap of the website's content to ensure all pages are indexed by search engines and to improve a website's visibility in search results. The sitemap should be regularly updated. To do so, follow these steps:

1. Visit the sitemap page at https://www.ebl.lmu.de/sitemap.
2. Wait until the 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 in this repository.

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