Skip to content

Latest commit

 

History

History

frontend

README.md

f1tenth-scoreapp-frontend

Client-side web app serving as frontend for the f1tenth-scoreapp.

👉 Available online at f1tenth-scoreapp.netlify.app

The code is written in TypeScript and React.js. See more in the Architecture section.

🚧 Note: This is work in progress.

Content

Description

TODO

The UI of the app is fully translated and localized into Czech and English. By default, the app automatically detects the locale to be used from the browser preferences. In addition, the locale can be changed manually in the app settings.

Architecture

Currently, it is a client-side-only application (SPA). It runs completely in the browser and it communicates with the backend via APIs (REST + WebSocket).

The code is written in TypeScript and React.js.

The project has just three production dependencies (React, react-intl and classnames). Everything else is implemented from scratch.

Technology highlights

Tooling:

  • Webpack – custom configs, custom plugins
  • Babel
  • ESLint, AVA (tests), GitHub Actions (CI/CD)
  • Netlify for Deployment
  • CSS written in Sass (SCSS), vendor prefixes automatically added by autoprefixer with Browserslist

Features:

  • Subresource Integrity (SRI) for all scripts and styles included from index.html
  • PWA, web app manifest including maskable icons
  • custom routing solution for React on top of the History API
  • custom state management for React (with persistence to Local Storage)
  • i18, l10n
    • Intl API (time, numbers, plurals), see for example the LocalizedDate component
    • advanced ICU messages, see for example these messages
    • automatic locale detection/negotiation (navigator.languages) with support for overwriting the locale on the app-level, see LocaleLoader component
  • CSS – fully responsive, Flexbox, Grid, animations, transitions, transforms, media queries, ...
  • HTML5 semantic elements

Project structure

The source code is in the app directory. Some directories contain feature-specific READMEs. The following diagram briefly describes the main directories and files:

. (project root dir)
├── .github - GitHub config (GitHub Actions)
├── app - the app source code
│   ├── components - common React components
│   ├── containers
│   │   ├── LocaleLoader - locale loader
│   │   ├── PageRouter - top-level app specific routing component
│   │   └── Root - root component
│   ├── forms-experimental - a custom solution for forms in React (not used)
│   ├── helpers - core functions for different things
│   ├── i18n - translations files
│   ├── images - mainly the PWA app icon
│   ├── router - a custom routing solution
│   ├── store - a custom app state management solution backed by localStorage
│   ├── styles - app styles written in Sass (SCSS)
│   ├── sw - the service worker that handles precaching app shell (not used)
│   ├── views - pages
│   │   ├── CategoryPage.tsx - category contents browsing
│   │   ├── HomePage.tsx - packages listing
│   │   ├── NotFoundPage.tsx - 404
│   │   ├── PackagePage.tsx - package contents browsing
│   │   ├── PracticePage.tsx - questions practice
│   │   └── SettingsPage.tsx - app settings form (locale, sounds, data)
│   ├── _headers - Netlify HTTP headers customization
│   ├── _redirects - Netlify HTTP redirects/rewrites customization
│   ├── index.js - the app starting point
│   ├── manifest.json - a web app manifest for PWA
│   ├── robots.txt
│   ├── routes.ts - app routes definitions
│   ├── template.ejs - index.html template to be built by Webpack 
│   └── types.js - data, state and API types
├── data - JSON app data that simulates API responses
├── test - a few tests
├── tools - custom Webpack plugins
├── types - TypeScript declarations for non-code imports (SVG, MP3)
├── .browserslistrc - Browserslist config
├── .eslintrc.js - ESLint config
├── .nvmrc - Node.js version specification for Netlify
├── ava.config.js - AVA config
├── babel.config.js - Babel config
├── netlify.toml - Netlify main config
├── package.json
├── tsconfig.json - main TypeScript config
├── webpack.config.*.js - Webpack configs
└── yarn.lock

Development

Requirements

Set up

  1. Install all dependencies with Yarn (run yarn).
  2. You are ready to go.
  3. Use yarn start to start dev server with HMR.
  4. Then open http://localhost:3000/ in the browser.

Available commands

  • yarn start – Starts a development server with hot replacements.

  • yarn build – Builds the production version and outputs to dist folder. Note: Before running an actual build, dist folder is purged.

  • yarn analyze – Same as yarn build but it also outputs stats.json and runs webpack-bundle-analyzer CLI.

  • yarn tsc – Runs TypeScript compiler. Outputs type errors to console.

  • yarn lint – Runs ESLint. Outputs errors to console.

  • yarn test – Runs tests using AVA.

  • yarn test-hot – Runs tests using AVA in watch mode.

Deployment

Currently, We use Netlify which is practically a CDN on steroids with integrated builds. There are 3 configuration files that affect the deployment behavior:

  • netlify.toml – global config
  • app/_headers – HTTP headers customization (mainly for immutable files)
  • app_redirects – HTTP redirects and rewrites (fallback to index.html for client-side routing)