React Router template for the City of Amsterdam

Features

• React Router (framework) with Vite builder - React framework and build tool
• TypeScript - strongly typed programming language built on JavaScript
• Testing Library and Vitest - testing utilities and framework
• ESLint - TypeScript, JavaScript, TSX, JSON and Markdown linter
• ESLint Stylistic and Perfectionist - ESLint plugins for code style and formatting
• Stylelint - CSS style linter
• Husky + lint-staged - git hooks to ensure code quality and standards

Development standards

This project is part of the City of Amsterdam and aims to comply with the Development Standards.

The user interface is build with the Amsterdam Design System.

Git commits should follow the Conventional Commits specification.

Requisites

• Node.js - the latest long-term support (LTS) version (see engines in package.json for current version)
• PNPM - performant Node.js package manager (see engines and packageManager in package.json for current version)
• Corepack - manage bridge between Node.js and PNPM
• Make - build automation tool
• Docker - container platform for development and deployment (optional for development)

Tip: PNPM can be used as Node.js version manager with pnpm env. See PNPM Node.js version management. We recommend to remove any Node.js installations on your system and then install PNPM with a standalone script. Then install the current Node.js LTS version and Corepack with pnpm env use -g lts && pnpm add -g corepack. Use Corepack to keep PNPM up-to-date in the project: corepack use pnpm@latest.

About development and build tooling

Many instructions in this README use Make to simplify commands. Check the Makefile for the actual commands.

This app can be developed, build and run for production locally or in Docker containers. Check the Makefile, the Dockerfile and the docker-compose.yaml to learn more.

Development

Local development environment

You can develop locally (A) or in a Docker container (B).

A) Local development

Install the dependencies and run the app in a dev server with live reloading:

make dev-local

Your application will be available at http://localhost:5173.

B) Develop with Docker

Start the development server with live reloading in a Docker container:

make dev

The application will be available at http://localhost:5173.

Testing

The project uses Testing Library and Vitest for unit, integration and snapshot testing.

To do: add test plan.

Run all tests once:

make test

Continuously run the test suite and watch for file changes:

make test-watch

Check test coverage:

make test-coverage

Then open test/coverage/index.html to view the coverage report in a browser.

Linting and formatting

This project uses ESLint to lint and type-check code with the TypeScript ESLint, React, JSON and Markdown plugins. For code style and formatting the Stylistic and Perfectionist plugins are used.

For CSS linting we use Stylelint.

Run the linters and formatters once:

make lint

Fix all auto-fixable issues:

make lint-fix

Building for production

Locally install the dependencies and build for production:

make build-local

Deployment

You can deploy yourself (A) or push a Docker container (B).

A) DIY deployment

If you're familiar with deploying Node applications, the built-in app server is production-ready.

Make sure to deploy the output of make build-local

├── package.json
├── pnpm-lock.yaml
├── build/
│   ├── client/    # Static assets
│   └── server/    # Server-side code

To locally start the production server:

make app-local # This also builds the application.

B) Docker deployment

Build and start the production server in a Docker container:

make app

The application will be available at http://localhost:3000.

Cleanup

To clean everything up run:

make clean
# or to only bring down Docker containers do:
make clean-docker
# or to only clean local files do:
make clean-local

Note: node_modules and .react-router may have been created due to volume mapping with a Docker container. It might not be possible to remove them without root privileges. If this happens do sudo rm -Rf .react-router node_modules manually.

---

Built with ❤️ by developers of the City of Amsterdam using React Router.