Frontend Documentation
Overview
Tecken has a JavaScript React frontend. The frontend code tries to be as
separate from the web server code as possible. The frontend is a static app
(written in React with react-router) that communicates with the web server
by making AJAX calls for JSON/REST and rendering in run-time.
The goal is for the web server (i.e. Django) to only return pure responses in JSON (or plain text or specific to some files) and never generate HTML templates.
The Code
All source code is in the ./frontend directory. More specifically
the ./frontend/src which are the files you’re most likely going to
edit to change the front-end.
All CSS is loaded with yarn by either drawing from .css files
installed in the node_modules directory or from imported .css files
inside the ./frontend/src directory.
The project is based on create-react-app so the main rendering engine
is React. There is no server-side rendering. The idea is that all (unless
explicitly routed in Nginx) requests that don’t immediately find a static file
should fall back on ./frontend/build/index.html. For example, loading
https://symbols.mozilla.org//uploads/browse will actually load ./frontend/build/index.html
which renders the .js bundle which loads react-router which, in turn,
figures out which component to render and display based on the path
(“/uploads/browse” for example).
Production Build
(At the moment…)
Ultimately, the command cd frontend && yarn run build will output
all the files you need in the build directory. These files are purely
static and do not depend on NodeJS to run in production.
The contents of the directory changes names every time and .css and
.js files are not only minified and bundled, they also have a hash
in the filename so the files can be very aggressively cached.
The command to generate the build artifact is done by CircleCI.
See the .circleci/config.yml file which kicks off a build.
You never need the production build when doing local development, on your laptop, with Docker.
Dev Server
For local development, when you run docker compose up web worker frontend
it starts the NodeJS dev server in the foreground, mixing its output with
Django. Normally in create-react-app apps, the yarn start command is
highly interactive, clears the screen, runs in full screen in the terminal,
color coded and able to spit out any warnings or compilation errors. When run
in docker, with non-TTY terminal, all output from the dev server is sent to
stdout one line at a time.
When you start Docker for development (again make run or
docker compose up web worker frontend) it starts the dev server on port
:3000 and it also exposes a WebSocket on port :35729.
The WebSocket is there to notice if you change any of the source files, it then
triggers a “hot reload” which tells the browser to reload
http://localhost:3000.
Proxying
The dev server is able to proxy any requests that would otherwise be a
404 Not Found over to the the same URL but with a different host.
See the frontend/package.json (the “proxy” section). Instead, it
rewrites the request to http://web:8000/$uri which is the Django server.
So, if in http://localhost:3000 you try to load something like
http://localhost:3000/api/users/search it knows to actually forward
that to http://localhost:8000/api/users/search.
When you run in production, this is entirely disabled. To route requests
between the Django server and the static files (with its react-router
implementation) that has to be configured in Nginx.
Authentication and Auth0
The frontend app does not handle authentication. Instead it relies on the browser to be able to maintain a cookie from the web server in consequent AJAX requests. This is done by doing fetches with “same-origin” credentials; meaning the frontend trusts that the client will pass its current cookies when it makes the AJAX request if and only if the origin is the same.
There is a REST endpoint the frontend talks to under /api/_auth which
will tell the frontend if the client has a valid cookie, and/or the URL
needed to go to to make the client authenticate herself with Auth0 and the
Django web server.
No credentials are ever passed between the frontend and the Django web server. Only the user’s email. This presence helps the frontend decide whether to render the “Sign In” or the “Sign Out” button.
Django API Endpoints
All AJAX requests from the frontend to the Django server should go via the
/api/ prefix which is the tecken.api Django app. This Django
app will be for all frontend apps such as user management, API tokens or
browsing the uploads history.
Watch out for node_modules!
If you ever run and build the frontend outside of Docker you end up with
a directory frontend/node_modules which is ignored by git but is still
part of the current working directory that Docker serves up and will
cause things like make build be excessively slow since the directory
can end up north of 100MB.
If you have a frontend/node_modules directory, feel free to delete it.
The dev server runs in a separate Docker container which builds its
node_modules outside the files mounted to the host.
Working on Docerfile.frontend
If you make changes to Dockerfile.frontend you have to rebuild that
container. A trick, to avoid having to rebuild everything is to just run:
docker compose build frontend
Testing
There are no unit, integration or functional tests of the frontend.
A nice-to-have but considering the current expected amount of traffic/users it’s not worth the effort.
State Management in React
The frontend app uses react-router to render different React components
depending on the pushState URL. If a piece of state is needed, and it’s
contained to one component, use regular this.setState(). If a piece of
state is needed across all (or most) components add it to the Mobx store.
See the file frontend/src/Store.js. Changes to that object will
trigger re-render of all active components that are observing the store.