Perseus-react-scripts NPM

Perseus Academy UI

Perseus Academy is a project with a dual purpose - to expose the Perseus Courses module as well as a Course Editor, which enables Perseus content creators to cerate and publish new courses.

Perseus Academy is a project forked from and built upon perseus-react-scripts.

Installation:

To install the dependencies, run in the root folder:

npm install

Required software

node
npm

Running locally

First, create an .env file with the following fields:

ACADEMY_API_URL=http://localhost:8080/api/v1/course-service

ACADEMY_API_URL can be set to either http://localhost:8080/api/v1/course-service, if you'd like to proxy requests through hive, or to http://localhost:9000/api/v1 if you're running just the course service on its own. More on that below.

There are several ways to run Perseus Academy. If you need just the E-learning module, you can:

Run E-learning module as a standalone application

This is recommended for when there is no need to test integration with Dock/Club. For this, you need to:

Run academy with the following command, which will run only the Academy in localhost:4000.

npm run dev

For this, course-service backend also needs to run. To do this, clone the course-service repository and follow the instructions from the readme. If necessary, run localhost:9000/import in order to import courses to the course-service db.

PS: For all the requests to local course-service, without Dock/Club, userId needs to be defined in the request. Backend will by-pass any validation if userId=-1.

The userId, token and the api used locally can be configured in runtime by a dev-tool, which will be covered in future section.

Run the E-learning module within Dock/Club

This is recommended for when there is a need to check how Perseus Academy looks like and behave regarding its integration with Dock/Club.

in Academy, run

npm run dev

For this, both course-service backend and hive also needs to be running. In Hive backend, the following configuration is required inside application-local.conf in "integrations" object:

integrations: {
  course_service_url = "http://localhost:9000"
}

then run sbt "project hive" run in the root folder of hive backend and sbt run in the root folder of course-service

Running Elearning Editor

This is the application used by content creators to be able to create and publish courses. This application is available on the environments under VPN only:

https://perseus-academy-fe.{env}.perseus.de/

If you're working on just the E-learning Creator, run

npm run dev

and navigate to the editor route.

More explanation of the structure can be found here

Build/Deployment

TBD @Ida/@Emmanuel

Run Tests

ESLint is our linting tool to find problems in the syntax in an early stage and make sure all devs follow the same code-style guidelines. If you are using vscode you will have it in real time. Otherwise you can run the following line to get the list of problems:

npm run lint

You can also run the unit/integration tests with the commands:

npm run test:local - locally and in watch mode (recommeded while developing) npm run test - runs in the pipeline (lint + jest)

You can specify which test case you want to run by passing argument to npm run test:watch:

npm run jest:watch -- Counter.spec.js

The command to collect and display coverage data (which contains more details on what lines of code were not covered with the current tests) is the following:

npm run jest:coverage

Coverage shows in the terminal a table with four criteria: lines, branches, statements and functions. The same information will be also available inside a folder called coverage that is generated from the command.

Testing Libraries

Jest is a JavaScript Testing Framework
React Testing Library is a very light-weight solution for testing React components.
@testing-library/user-event is used to simulate events the same way the user does.
history (createMemoryHistory) is used as a helper library for testing routes/navigation
MSW is helping mocking fetch responses

To develop using the msw setupWorker you will have to update the function in mocks/index.js. The setup worker accepts a URL (the endpoint) to intercept and data (mocks), usually in the form of JSON, to use as a response. Do NOT commit the changes in this file.

Typescript

Academy project uses Typescript for type safety and error checking in development and compile time. Whenever possible, define types in the same file they're used. Always suffix types with ...Type, in order to distinguish them from component names.

interface CourseType {}

CSS

EmotionCss is the approach we use for CSS/styling.

Dev-tools

TBD @Rener

Recommendations

Translation

Instead of hard-code content, please use i18n setup already in place to facilitate future support to multi-language. The files with the translation definions can be found inside the folder src/locales/{en|de} and the preferred user language is get from the cookies (as well as Dock/Club).

Styling

Prefer using object notation over backticks (`) to define styling rules. Since not all editors recognize the template notation out of the box and will not provide error checking and autocomplete for css styles. Example:

const style = css({ display: 'flex' })

instead of

const style = css`
  display: flex;
`

Whenever possible, define styles in the same file they're used. This helps in detecting which styles are not being used and can be removed (exporting them doesn't provide this feature - unused styles aren't detected)
Whenever possible, define the styles inline in the component if the number of rules are less or equal to 2. More than that, the style should be extracted to ouside the component return.

Coding

named export
useAsync
use fetch from utils
folder explanation