Remix Application Template

⚠️ Be warned: This template is currently work in progress and has not been tested in production yet.

Bootstrap a Remix and TypeScript application with Continuous Delivery

Prerequisites

Node.js

We aim to use the current active LTS version of nodejs, which is V22 from October 2024. There is a .node-version file to simplify setup using nodenv.

Dependencies

Install the dependencies using npm.

npm install

Testing

For E2E and a11y testing with Playwright you will need to install the supported browsers:

npx playwright install

Git Hooks

For the provided Git hooks you will need to install lefthook (git hook manager) and talisman (secrets scanner):

brew install lefthook talisman

The following hooks are specified in the lefthook.yml:

• commitlint - write conventional commit messages
• lint - avoid committing code violating linting rules
• format - avoid committing wrongly formatted code

Before pushing, the following checks are additionally ran:

• licenses-audit - uses license-checker to verify depency licenses
• secrets-audit - avoid accidental pushes of secrets and sensitive information

Finish project setup

To then finish the setup of the git hooks and to change the project name from the template name you can run:

./run.sh init

security.txt

This template contains a security.txt, where you probably want to update the expiration date. The following entry may also be added:

Canonical: https://<<PROJECT_URL>>/.well-known/security.txt

Development

You need to create an .env file based on the example and fill it in with the Personio secrets from 1Password and the NocoDB API token.

From your terminal:

npm run dev

This starts your app in development mode, rebuilding assets on file changes.

Testing

The application has

• unit tests (using Jest)
• end-to-end tests (using Playwright)
• accessibility tests (using Playwright and Axe)

Test commands

• Run unit tests: npm test
• Run unit tests with watcher: npm test -- --watch
• Run E2E tests: npm run test:e2e
• Run A11y tests: npm run test:a11y

Code quality checks (linting & formatting)

The project uses ESLint for linting and Prettier. for formatting.

Commands

• Check formatting: npm run format:check
• Autofix formatting issues: npm run format:fix
• Check lint: npm run lint:check
• Autofix lint issues: npm run lint:fix
• Check style (formatting & linting): npm run style:check
• Autofix style issues (formatting & linting): npm run style:fix

Deployment

Build and run the app in production mode:

npm run build
npm start

Docker

The project includes a Dockerfile to create a Docker Image for the project.

You can build the Docker Image using

docker build -t achill .

and then start it using

docker run -d -p 3000:3000 --name achill achill

The website is then available under http://localhost:3000

If you want to include any additional files during the build that are not in the app or public directories you need to add them to the .dockerignore file.

The pipeline GitHub Action includes a job to build the Docker Image and push it to GitHub Packages. This job is currently deactivated. To enable it you need to remove the && false from the end of the if predicate of the build-and-push-image job.

DIY

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

Make sure to deploy the output of npm run build

• build/
• public/build/

Architecture Decision Records

The docs/adr directory contains architecture decisions. For adding new records the adr-tools command-line tool is useful but not strictly necessary:

brew install adr-tools

Contributing

🇬🇧 Everyone is welcome to contribute the development of the achill. You can contribute by opening pull request, providing documentation or answering questions or giving feedback. Please always follow the guidelines and our Code of Conduct.

🇩🇪 Jede:r ist herzlich eingeladen, die Entwicklung der achill mitzugestalten. Du kannst einen Beitrag leisten, indem du Pull-Requests eröffnest, die Dokumentation erweiterst, Fragen beantwortest oder Feedback gibst. Bitte befolge immer die Richtlinien und unseren Verhaltenskodex.

Contributing code

🇬🇧 Open a pull request with your changes and it will be reviewed by someone from the team. When you submit a pull request, you declare that you have the right to license your contribution to the DigitalService and the community. By submitting the patch, you agree that your contributions are licensed under the MIT license.

Please make sure that your changes have been tested befor submitting a pull request.

🇩🇪 Nach dem Erstellen eines Pull Requests wird dieser von einer Person aus dem Team überprüft. Wenn du einen Pull-Request einreichst, erklärst du dich damit einverstanden, deinen Beitrag an den DigitalService und die Community zu lizenzieren. Durch das Einreichen des Patches erklärst du dich damit einverstanden, dass deine Beiträge unter der MIT-Lizenz lizenziert sind.

Bitte stelle sicher, dass deine Änderungen getestet wurden, bevor du einen Pull-Request sendest.