Template for modern SSR applications

Possibilities

• A modern JavaScript-based stack for services: React, Next.js.
• Extensive CI checks (including security checks, code style fixing, static linters, DeepScan, and Snyk) ensure the highest code quality.
• Configured testing tools: Playwright, Jest.
• This template is based on bulletproof-react, but has been adapted to meet the specific needs of this project and may differ from the original implementation.
• Much more!

Why you might need it

Many front-end developers need to create new projects from scratch and spend a lot of time.

We decided to simplify this exhausting process and create a public template for modern front-end applications. This template is used for all our microservices in VilnaCRM.

License

This software is distributed under the Creative Commons Zero v1.0 Universal license. Please read LICENSE for information on the software availability and distribution.

🚀 Minimal Installation Guide

1. Clone the Repository

Clone locally or use GitHub’s Use this template feature.

2. Install Prerequisites

Before running the application, make sure the following tools are installed on your machine:

• Node.js (version 20 or higher). You can download and install Node.js from the official website, or use a version manager like nvm Node Version Manager to easily manage versions.

• Docker required for containerization and managing isolated environments. Install Docker according to the instructions for your operating system. Follow the guide to ensure Docker is properly configured and running on your machine.

• Docker Compose is needed to manage multi-container Docker applications. Docker Compose is essential for starting up the development environment and running the services defined in docker-compose.yml.

3. Run the Application

After installing all prerequisites, you can start the application inside a Docker container:

   make start

What Happens When You Run make start:

The command will:

• Build and start the project inside a Docker container named dev.
• Install all the necessary dependencies (including Node.js dependencies) inside the container.
• The application will be up and running.

Access the application at http://localhost:3000.

Project Commands

To view all available commands, run make help:

  make help

The following commands are available when the project is installed locally.

General

  make start: starts the application
  make build: builds the application
  make format: formats the codebase to ensure consistent style across all files
  make update: updates node modules according to the current package.json file
  make install: installs node modules according to the current pnpm-lock.yaml file
  make check-node-version: checks if the correct Node.js version is installed

Linting & Formatting

  make lint-next: lints the codebase using Next.js rules
  make lint-tsc: runs static type checking with TypeScript
  make lint-md: lints all markdown files (excluding CHANGELOG.md) using markdownlint

Testing

  make test-unit-all: runs unit tests for both client and server environments
  make test-unit-client: runs unit tests for the client using Jest
  make test-unit-server: runs unit tests for the server using Jest
  make test-bats: runs the Bats shell regression suite for Makefile targets and CI helper scripts
  make test-memory-leak: runs memory leak tests using Memlab
  make load-tests: executes load tests using the K6 library
  make test-e2e: runs end-to-end tests inside the prod container
  make test-e2e-ui: runs end-to-end tests with UI inside the prod container
  make test-visual: runs visual tests inside the prod container
  make test-visual-ui: runs visual tests with UI inside the prod container

Important Note About Swagger E2E Tests

For Swagger E2E tests, the application uses Mockoon to handle API requests. The API endpoints from the Swagger schema are automatically rewritten during both production and development container builds. This means that all API requests are currently directed to Mockoon instead of a real backend. Please keep this in mind if you plan to integrate with a real backend service in the future—you'll need to update the API configuration accordingly.

To run tests locally, the Mockoon mock server is automatically started via make test-e2e. For manual setup, see the Mockoon configuration in docker-compose.test.yml.

Lighthouse

  make lighthouse-desktop: runs Lighthouse audits in desktop mode
  make lighthouse-mobile: runs Lighthouse audits in mobile mode

Git

  make husky: sets up Husky (Git hooks manager) — run once after cloning the repo

Storybook

  make storybook-start: starts Storybook UI
  make storybook-build: builds Storybook UI

Docker

  make down: stops the Docker containers and removes orphaned containers
  make stop: stops Docker
  make start-prod: builds image and starts the container in production mode
  make ps: logs into the Docker container
  make sh: logs into the Docker container
  make logs: shows all logs
  make new-logs: shows live logs of the dev container
  make wait-for-prod: waits for the prod service to be ready on port 3001

Note: The following commands do not require the CI=1 prefix:

  make test-e2e: starts production and runs end-to-end tests inside the prod container
  make test-visual: runs visual tests inside the prod container
  make test-e2e-ui: runs end-to-end tests with UI inside the prod container
  make test-visual-ui: runs visual tests with UI inside the prod container
  make test-memory-leak: runs memory leak tests using Memlab inside the prod container

  make load-tests: executes load tests using the K6 library
  (uses "prod" as hostname, which maps to the Docker service)

  make git-hooks-install: installs husky Git hooks locally
  make update: runs locally on the host machine, not in a container

💡 Tip: To run commands locally without Docker, please prefix command with CI=1. Example:

  CI=1 make start

Bats Shell Coverage

Use the Bats suite to validate Makefile shell flows and scripts/ci helpers that are not already exercised by the pull request workflows:

  make test-bats

The coverage inventory lives in tests/bats/make-target-coverage.tsv. When you add a new Makefile target, either add Bats coverage for it or document the workflow that already exercises it in that file. Additional suite-maintenance notes live in tests/bats/README.md.

Load Testing with K6

This project includes a dedicated load testing service using K6, configured via a Docker Compose profile.

What are Docker Compose Profiles?

Docker Compose profiles let you selectively start groups of services. The load testing service is tagged with the load profile in docker-compose.test.yml, so it only runs when you explicitly include that profile.

Running Load Tests

Using the make command (recommended):

  make load-tests

The load testing service waits for the production service to become healthy before starting. Test results will be streamed to the K6 web dashboard and saved under ./src/test/load/results/.

Available Load Test Scenarios:

• smoke: a quick health check with a small number of virtual users.
• average: simulates a typical daily traffic load.
• stress: pushes the system to its limits to identify breaking points.
• spike: sudden ramp-up of virtual users to test burst handling.

Adjust scenarios and thresholds in ./src/test/load/config.json.dist as needed.

Routing

This project includes a routing script for managing URLs. The routing script maps requests to the correct HTML files, ensuring proper navigation. For detailed information, check the routing script.

How It Works

• Mapping: Specific URL paths are mapped to corresponding HTML files.
• Fallback Logic: For undefined routes, the script appends /index.html to handle directory-like paths.
• Error Handling: If an error occurs, the script logs it and returns the original request.

This routing logic is useful for SSR (Server-Side Rendered) applications, particularly when hosted on platforms like AWS CloudFront.

Documentation

Start reading at the GitHub wiki. If you're having trouble, head for the troubleshooting guide as it's frequently updated.

You can generate complete API-level documentation by running doc in the top-level folder, and documentation will appear in the docs folder, though you'll need to have API-Extractor installed.

If the documentation doesn't cover what you need, search the many questions on Stack Overflow, and before you ask a question, read the troubleshooting guide.

Tests

Tests

If this isn't passing, is there something you can do to help?

Security

Please disclose any vulnerabilities found responsibly – report security issues to the maintainers privately.

See SECURITY and Security advisories on GitHub.

Contributing

Please submit bug reports, suggestions, and pull requests to the GitHub issue tracker.

We're particularly interested in fixing edge cases, expanding test coverage, and updating translations.

If you found a mistake in the docs, or want to add something, go ahead and amend the wiki – anyone can edit it.

Sponsorship

Development time and resources for this repository are provided by VilnaCRM, the free and opensource CRM system.

Donations are very welcome, whether in beer 🍺, T-shirts 👕, or cold, hard cash 💰. Sponsorship through GitHub is a simple and convenient way to say "thank you" to maintainers and contributors – just click the "Sponsor" button on the project page. If your company uses this template, consider taking part in the VilnaCRM's enterprise support program.

Changelog

See changelog.