serlo / frontend

Next.js app that serves serlo.org

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:

• Routing
• Internationalised Routing
• Static Site Generation
• Incremental Static Regeneration
• …

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:

1. Clone api.serlo.org or update your local repo with git pull.
2. Run yarn and yarn start in your local api.serlo.org repo.
3. Set NEXT_PUBLIC_ENV=local in apps/web/.env.
4. 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:

• Internationalization
• Entities and Schema
• Tailwind Getting Started Guide
• VS Code Setup
• Unsorted old stuff
• Forked packages
• Editor package

frontend's Issues

🦟Safari

Safari 13.0.4 on OSX 10.15.2
(not the newest but unfortunately not terribly old)

Landing Page, font not loading in SVG

Searchinput (GCS) hides text

Scarry images again

breadcrumbs styling current item

The last item should not be a link
compare this:

to our version:

And the back button should point to the second last item:

(should be "Zahlen und Größen" instead)

Taxonomy Topic

https://de.serlo.org/mathe/geometrie/satzgruppe-pythagoras

Props:

title: string
description: ReactComponent
courses: Link[]
article: Link[]
...

Link has title und url

content & design

Notifications

Goal: Components for a page containing all notifications, like https://github.com/notifications/beta Current version:

Feedback Footer

Mobile

• Slogan, Logo, Infobox und Content auf eine Linie:
  

• Sucheinstellungsicon:
  • Hellblau statt grau
  • klein bisschen mehr abstand nach links
  • bzw: Wie wichtig sind die Einstellungen, wäre es auch denkbar, dass die erst angezeigt werden, wenn die Suche aktiv ist?

• active/focus lieber über die farbe des icons (oder auch mit einem Kreis drum rum):
  
• schaut ein bisschen gestaucht aus (weniger breit als es sein sollte) kann das sein?
  

• Menü:
  • Linktexte sind nicht vertikal mittig.
  • Community, Fächer und Spendenicons könnten bisschen kleiner
  • Nach dem einklappen sollte der Bereich nicht mehr fokusiert (dunkler hintergrund) sein.
    
• Submenü:
  • Weißer Hintergrund, damit abgesetzt vom restlichen Menü
  • nach dem letzten Submenü-Punkt eine leerzeile mit halber höhe.
    

Desktop

• Wenn genug Platz: Slogan einrücken, dass “Serlo” und “Die …” auf der gleichen Linie beginnen.
  
• Ausklappmenüs bei Hover schon öffnen.

• Submenü (damit man nicht ins leere klicken kann):
  • li ohne margin-bottom
  • a auf display block und mit mehr padding oben und unten
• Menülinks:
  • selbe idee, möglichst große clicktargets, am besten so, dass man nicht über die links klicken kann.
  • (also weniger padding-top: aufm header und mehr padding-top auf den link)

breadcrumbs styling when path is very long

Ideas how to prevent this?

Analytics

• Add Google Analytics tracking code
• Check if a tag is a good way to filter old & redesign
• Add custom tag

cloudflare-worker: splitting traffic

Mobile shortcut icon

Define an icon for mobile homescreen shortcut. Maybe also add a popup on mobile devices with instructions on creating such a shortcut.

Maybe this helps: https://developer.chrome.com/multidevice/android/installtohomescreen

rendering tables

some articles (1565, 1553) contain tables that should be rendered

Support Opensearch

Sweet feature, unfortunately needs more work with the current search implementation.

header:
<link href="/opensearch.de.xml" rel="search" type="application/opensearchdescription+xml" title="Serlo (de)">

opensearch.de.xml:

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/" xmlns:moz="http://www.mozilla.org/2006/browser/search/">
<ShortName>Serlo (de)</ShortName>
<Description>Serlo.org – Die freie Lernplattform</Description>
<InputEncoding>UTF-8</InputEncoding>
<Image width="16" height="16" type="image/x-icon">https://de.serlo.org/favicon.ico</Image>
<Url type="text/html" method="get" template="https://de.serlo.org/search?q={searchTerms}"/>
<moz:SearchForm>https://de.serlo.org/search</moz:SearchForm>
</OpenSearchDescription>

Review Privacy Policy

Things that might change (please add):

• Google Web Fonts (self hosting is probably preferred and necessary for karmilla atm, Keep it for now!)
• Matamo
• Vercel
• Cloudflare
• GCS Integration

Who has experience with that? Who worked on it so far?

Table weirdness?

This is a content problem right?

Source: https://frontend.dal123.now.sh/1565

Discussion: What else should we implement from serlo.org?

In this issue I list the features which are currently missing in the frontend project but which are implemented at serlo.org

• Support for Hotjar (we might want to discuss this issue)
• Popup for the email newsletter https://github.com/serlo/serlo.org/blob/6983e369dff10dadd6b3832bf9be489f4619435d/packages/public/server/src/module/Ui/templates/layout/partials/popup.phtml
• The following MathJax extensions have been enabled. Do we need them?
  • mediawiki-texvc
  • mhchem

RFC: remove initialProps

I propose to remove the getInitialProps from our pages in frontend for a couple of reasons:

• It mixes fixtures for testing purposes with production code
• It hides some potential issues (namely when you don't pass required props and it the default value is used instead)

Instead, I'd rather move fixtures (intended for testing purposes) into the storybook. This way, we have one location for our "fixtures" and devs can develop their components with the storybook (and the same fixtures) without having to go through the nextjs stack. Additionally, we might add e2e tests that also test that the nextjs toolchain works correctly (e.g. rehydration etc.), maybe as part of serlo/serlo.org-legacy#222.

Google Custom Search

With Google Custom Search.

Overview over different implementation options:
https://support.google.com/customsearch/answer/9069107?hl=en&ctx=topic

Full control solution is a paid version of GCS with JSON-API access:
https://developers.google.com/custom-search/v1/site_restricted_api
(5 Dollar per 1000 Searches)
This way we could style everything ourselves, use components, add autocomplete etc.
Nice Tutorial if we choose this way.

Free alternative that is not as nice but is also less work uses google embeded search and a result field. I will try to implement that first.

Example of a pretty nice dynamic implementation:
https://www.khanacademy.org/search

Misc:

• Exercises are most important search filter and should come first if possible

content to wide at /abc

see:
https://frontend.dal123.now.sh/abc

show secondary menu on static/taxonomy pages

include subject sub menu in

• taxonomy views
• static pages within subjects

don't include it in any content page

Secondary menu: Arrows to small

In the last Lama-meeting I got the feedback that the arrows in the secondary menu are to small in order to comfortably click on them on a mobile phone:

Secondary navigation

remove "Zugehörige Themen"?

Implementation of GraphQL backend

Using graphql to load content and breadcrumbs

https://api.serlo.org/___graphql

footer (from redesign)

missing pieces?

What pieces are missing from existing templates?

Consistent exports and types

Some components have inconsistent types / exports.

Integrate compilation of patch into toolchain

Currently, we commit both patch/next/dist/index.tsx and patch/next/dist/index.js. Instead, we should commit only patch/next/dist/index.tsx and compile that webpack, too.

Add schema.org

schema.org ( https://schema.org/ ) is a way to add metadata to html (which can be used by search engines to understand an article). For example we have the following markup for an article:

<div itemscope itemtype="http://schema.org/Article">
<div class="page-header">
<h1 itemprop="name">Faktorisieren</h1>
</div>
<article itemprop="articleBody">
...

The attributes itemprop, itemtype and itemscope give a more detailed semantic structure for the HTML element.

translations (i18n)

There are strings/content in footer, header and probably other components that need to come from athene instead of being hardcoded (for translations etc).

Use keys in <Topic__Wrapper>.

Warning: Each child in a list should have a unique "key" prop.

Check the top-level render call using <Topic__Wrapper>. See https://fb.me/react-warning-keys for more information.

Content wrapper markup

Suggestion:
Use a <div> in place of the current <main> element to create the column and use the <main> to only wrap the actual content (no warning, no horizon).
Breadcrumbs can actually be inside, because they are individual to the site, but I'll wrap them inside a <nav>.
-> better markup, accessibility and seo.

Tools for logged in users

In the current dropdown menu the following items are missing:

• Subscribe
• History
• Log
• Manage related items

These are only relevant for logged in users. Where shall we add them?

Visible scrollbar on formula

Source: https://frontend.dal123.now.sh/mathe/terme-gleichungen/gleichungen/gleichungen-allgemein/%C3%84quivalenzumformungen

Not sure if content or css problem.

breadcrumbs (from redesign)

Definition of breadcrumbs in the redesign prototype: https://github.com/serlo/serlo.org/blob/17a3847a6666a4f9d82790d2c1babc7585c6a9b5/packages/public/frontend/src/breadcrumb.component.tsx

Prototype in action: https://athene2-blue-gum.netlify.com/?path=/story/example-page--test

Resolve injections server side

Problems with the current approach:

• Longer loading times and more data
• Google Analytics get's confused and measures this as (really early) switch to another site
• iframe resizing does work, but it's not as clean as the actual content (e.g. collapse animations of spoilers)

So instead of resolving the injections using an iframe and the content-API (as implemented in @edtr-io/plugin-serlo-injection) we should resolve these serverside.

Implement Taxonomy

The new API now supports querying taxonomy. Implement fetcher and use existing component.

replace mathjax with katex

In the new editor we'll be using KaTeX for rendering math formulas, so it makes sense to get rid of mathjax altogether. Also we should check if the server side rendering to HTML by KaTeX is an option.

Startpage

implementing start page.

Subjects: https://athene2-blue-gum.netlify.com/?path=/story/misc-components--landing-subjects and https://github.com/serlo/athene2-blue-gum/tree/master/src/landing

The remaining parts can be copied from https://de.serlo.org/

rendering injections

this one needs some more time to implement

Don't show breadcrumbs on meta pages

Browser Testing

We should do some browser testing,
I think we have Chrome and Firefox covered, which leaves all time favourites like
IE, Safari and div. mobile browser.

Quick checks desktop:

• 🟢current Chrome/Firefox on mac
• 🟢relatively current Safari on mac (after #83 is done)
• 🟢current Edge on Mac: Thankfully it's basically Chrome.
• 🟠 IE11 on Win: Inconsistencies but usable
• 🟢Firefox/Chrome/Brave on Linux/Windows: Do we have those covered? (@Entkenntnis, @kulla)
• 🟢Opera on Mac: Looks good!

Quick checks mobile:

• 🟢Mobile Preview in Chrome and Firefox
• 🟠Firefox and stock Chrome on Android: Weird colors (will investigate), bit sluggish, sec-menu ux really bad but looks fine.
• 🟢Safari, iPhone? (looks good)
• ⚪iPad: (postponed)

Current Stats:

so imo for opera + ie11 it would be nice to have it at least working.

page header

Sharing menu

cookie consent banner

add a cookie consent banner similiar to existing one on serlo.org:

maybe a bit more compact and optimized for mobile.

horizon

Lighthouse audit notes

just a super quick summary. not complete.

---

SEO
should be enough:

• increase footer tap target size: aim for 48x48px
• robots.txt
• meta and graph tags ( see #64)

---

Performance

• i think biggest problem by far are images. Solutions: different sizes(!), maybe webp, and of course lots of svgs :)
• less dom elements! I think Katex is the biggest problem here.
• Katex: Do we lazy load formulas (@Entkenntnis)? Maybe even defer font loading with rel="prefetch" so browsers get it if they have time
• Main thread work: well… hard to improve right?
• TTFB sometimes quite long

---

Accessibility

• Too low contrast on all buttons is indeed a problem
• Nice guide to check accessibility

---

Best Practices*
💯 👍

---

PWA looks good, would be doable.

license in solutions below comment section

https://de.serlo.org/mathe/deutschland/bayern/realschule/jahrgangsstufentest-6-klasse/2017/88000

The license looks as if it is part of the solution. And the license is not important. Could you pls put it below the comment section?

<title> should not be used in _document.js's <Head>

new warning in yarn dev:
<title> should not be used in _document.js's <Head>
see https://github.com/zeit/next.js/blob/master/errors/no-document-title.md

Content: ids for headers

All headers (h1 to at least h4) should get an id automatically so they can be linked to directly.

This is not a very common feature, but at least some internal links make use of that, so we should make sure to create the same ids as currently.

Example here: https://de.serlo.org/nachhaltigkeit/anbau/anzucht-aussaat/pflanzzeiten

legacy content