Template for modern SPA applications

Possibilities

• Modern JavaScript stack for services: React
• Extensive CI checks (security, style, static analysis, Snyk, DeepScan) to maintain code quality
• Configured testing tools: Playwright, Jest
• This template is based on bulletproof-react
• 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.

• GNU Make 4.0+ is required for the repository Make targets. Linux environments usually already provide a compatible version. On macOS, install a newer Make with Homebrew:

  brew install make

  If Homebrew installs GNU Make as gmake, use gmake anywhere this documentation says make.

• Bun used as the package manager (Node.js remains the runtime). Bun uses the bun.lock file to keep dependency resolutions consistent while delivering fast installs.

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 shared local development stack inside Docker containers named dev and mockoon.
• Use the dependencies already baked into the dev image (mounted via a named node_modules volume) instead of reinstalling on every start.
• Wait for both readiness checks before returning: the frontend dev server and the Mockoon API mock.
• Expose the frontend at port 3000 and the mock API at port 8080.

First-time setup: run make create-network to create the external crm-network before using docker compose directly. make start runs this automatically.

After startup completes:

• Frontend: http://localhost:3000
• Mockoon API mock: http://localhost:8080

Migration Note for Existing Contributors

If you previously used make start expecting only the frontend dev container, update that mental model now: make start is the full local development entrypoint and starts both the frontend and Mockoon together.

If you have local shell aliases, editor tasks, or scripts that used to compose older CI commands manually, replace them with make ci. That target is now the supported contract for pre-push and GitHub Actions validation.

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 create-network: creates the external crm-network (idempotent helper)
  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 bun.lock file using Bun
  make check-node-version: checks if the correct Node.js version is installed

Linting & Formatting

  make lint-eslint: lints the codebase using eslint rules
  make lint-tsc: runs static type checking with TypeScript
  make lint-md: lints all markdown files (excluding CHANGELOG.md) using markdownlint
  make lint-dup: detects copy/paste duplication with jscpd (thresholds in .jscpd.json)

Dependency rules

We use dependency-cruiser to enforce module boundaries and prevent circular dependencies.

• Run locally: make lint-deps
• Config: .dependency-cruiser.js
• Key rules: modules cannot import from other modules directly; shared UI components must not depend on feature modules

Testing

  make ci: runs the full local CI flow (setup, lint, tests, and prod-side checks)
  make test-bats: runs shell-level regression coverage for Makefile targets and CI helper scripts
  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-memory-leak: runs memory leak tests using Memlab
  make test-load: executes load tests using the K6 library

Run Local CI Before Pushing

Use make ci as the canonical pre-push validation command:

  make ci

Running make ci locally exercises the same checks CI runs across its workflows, so passing it before pushing means your changes should pass CI.

Bats Shell Coverage

Use the Bats suite when you need fast regression coverage for Makefile shell flows and the scripts/ci wrappers without running the full prod-side stack:

make test-bats

When you add or change a public Make target, update tests/bats/make-target-coverage.tsv in the same change. Either add or adjust direct Bats coverage for the target, or point the manifest at the pull-request workflow that already executes the target end to end.

Migration guidance for existing contributors:

• replace older local CI command chains or custom wrappers with make ci
• expect make ci to cover both dev-side and prod-side checks instead of only lint or unit phases
• keep any local automation pointed at make ci

At a user-facing level, make ci runs these phases in order:

• environment setup for the shared dev stack
• lint checks
• dev-side automated tests
• production-like setup for Chromium and the prod stack
• production-side automated tests, including end-to-end, visual, load, memory-leak, and Lighthouse checks

Runs tests inside the Playwright container, targeting the production container:

  make test-e2e: full end-to-end tests
  make test-e2e-ui: runs UI-specific end-to-end tests
  make test-visual: runs general visual regression tests
  make test-visual-ui: runs UI-focused visual regression tests

Important Note About Swagger E2E Tests

For Swagger E2E tests, the application uses Mockoon to handle API requests. Mockoon serves as a mock API server for both local development and E2E-style workflows. It uses the OpenAPI specification from the user-service repository and runs on port 8080 within the Docker test network. The mock server provides consistent API responses during automated testing without requiring a real backend connection.

For local development, make start brings up Mockoon alongside the frontend stack. Test-oriented targets such as make test-e2e and make start-prod also bring up the mock server through their own shared startup paths. For container-level configuration details, see docker-compose.yml and 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 targeting the dev container
  make storybook-build: builds Storybook targeting the dev container

Docker

  make down: stops the Docker containers and removes orphaned containers
  make stop: stops dev container
  make start-prod: builds image and starts the prod container (production mode)
  make ps: displays currently running Docker containers with their details
  make sh: starts a terminal inside the dev Docker container for manual commands
  make logs: shows all logs of dev container
  make logs-prod: shows all logs of prd container
  make new-logs: shows live logs of the dev container
  make wait-for-dev: waits for the dev service to be ready on port 3000
  make wait-for-prod: waits for the prod service to be ready on port 3001

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 ./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 ./test/load/config.json.dist as needed.

Documentation

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

• Architecture Decision Records (ADRs)

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 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. Security advisories on GitHub.

Contributing

Please submit bug reports, suggestions, and pull requests to the GitHub issue tracker. 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. on the project page. If your company uses this template, consider taking part in the VilnaCRM's enterprise support program.

Changelog

See changelog.