serlo.org – Frontend

Next.js app that serves serlo.org. You can find it in apps/web.

Overview

The frontend turns the data it receives from our GraphQL API into pretty views. In our staging and production enviroments the frontend sits behind a cloudflare worker that mostly does redirects and could be used for A/B testing etc.

Getting started

Local installation

You can run the frontend on your local system. Install Node.js v20 and yarn (npm install --global yarn), then run the following commands:

git clone --filter=blob:none https://github.com/serlo/frontend.git
cd frontend
yarn
yarn dev

The development server is now live on localhost:3000. Use same username/password as on staging.

Choose language using http://localhost:3000/{es|de|hi|ta|en|fr}/

Tip for windows users: Set execution policy to remote signed to allow yarn to run.

Libraries

To make working with this codebase easier a basic understanding of React, TypeScript, Tailwind and useSWR is very helpful.

Next.js

The frontend is built with the Next.js React Framework. A good way to get started in this repo is to make yourself familiar with Next.js.

Some of the features we use:

How to work in frontend with local backend

We use our staging API (api.serlo-staging.dev) as our backend when you run yarn dev. However it is also possible to use the frontend with a API instance running on you local machine:

Clone api.serlo.org or update your local repo with git pull.
Run yarn and yarn start in your local api.serlo.org repo.
Set NEXT_PUBLIC_ENV=local in apps/web/.env.
Run yarn dev in the frontend

When you need to simulate an authenticated user, set userId: 1 in graphql-middleware.ts.

Repository Overview

This is a monorepo that contains the editor and the frontend platform. Here are some useful directories:

/apps/web: Serlo.org platform.
/apps/web/src/pages: File-system routing root directory. Add new routes by creating files in this folder.
/apps/web/src/components: Collection of react components for the frontend.
/apps/web/src/fetcher: Requesting data from the GraphQL backend and process it.
/apps/web/src/data: Translations, entries for navigation
/apps/web/public/_: A place for public assets, served as static files under the path /_assets/. Don't use import from here, but use the path as src instead.
/apps/web/external: Third-party code that is not maintained by the frontend.
/packages/editor: Serlo Editor. See here for more information.
/e2e-tests: End to end tests in BDD style with CodeceptJS and playwright. More info on testing below and in the readme of the directory.

Some useful commands:

yarn dev

Starts the development server. This enables hot reloading and development warnings.

yarn format

Runs eslint and prettier, fixes issues automatically if possible.

yarn lint

Runs tsc, eslint and prettier (without automatic fixes). This command needs to pass before merging into staging.

yarn analyze

Creates a build of the frontend, shows summary of build artefacts and creates in-depth analysis of the bundles.

yarn test

Runs jest tests.

yarn codegen

Generates exact types for some GraphQL queries and mutations. Add yours in codegen.yml.

All files are named with kebab-case. You should use @/ to import files from src/ instead of relative paths.

Issues and backlog

Technical issues are opened for bugs and feature that we decided to work on. For improvements and backlogs that will take more resources, we have the Feature-Entwicklungsprozess with its Trello-Board. The backlog is tracked there.

This method should avoid stale issues and make it possible to keep an "zero inbox".

e2e testing

This repo includes e2e test with codeceptjs. To run them for the first time:

cd e2e-tests
yarn
yarn playwright install
cd ..
yarn e2e

You can find the full readme here.

More information

You can find more detailed explanations in our wiki. Currently, we have these pages available:

serlo / frontend

readme