A monorepo starter for products that need an admin panel, an API, and a public website. It ships an AdonisJS backend, a React admin panel with a module generator, and a Next.js website that renders the pages editors publish through the built-in CMS.

App	Source	Dev port	What it is
Backend API	`apps/backend/`	3333	AdonisJS — data, auth, permissions, public content API
Admin panel	`apps/admin/`	5173	React + Vite — the internal UI
Public website	`apps/web/`	3000	Next.js — the site visitors see
Shared packages	`packages/`	—	UI, hooks, services, types, utils

Full documentation lives in docs/.

Tech Stack

Backend

AdonisJS
TypeScript
Lucid ORM
PostgreSQL / MySQL (configurable)
Redis, S3 / MinIO storage

Admin panel

React
TypeScript
Vite
React Query / MobX / Axios
Radix UI + Tailwind component system
React Hook Form + Zod

Public website

Next.js (App Router, React Server Components)
TypeScript
next-intl
Tailwind CSS

Getting Started

Prerequisites

Node.js 24.18.0 (see .nvmrc; the package manifest requires >=24.0.0)
npm >=11.6.2 (the repo pins npm@11.15.0)
PostgreSQL

Installation

git clone gitlab@git.rexsoftproduction.com:crux/admin.git

cd crux && npm install --force

--force is required. typescript-eslint does not yet declare support for the TypeScript version this repo uses, so a plain npm install fails with ERESOLVE. Never substitute --legacy-peer-deps — it strips nested peer dependencies and breaks the backend at runtime. Use npm ci --force for a reproducible install, and npm install <package> --force when adding one. See troubleshooting.md.

Configuration

Each workspace defines its own environment variables. Copy the workspace's .env.example to .env and fill in the values:

Env file	Covers
`apps/backend/.env`	Server (`PORT`, `APP_KEY`), database (`DB_`), storage (`AWS_`, `S3_*`), and the public site link (`WEB_APP_URL`, `WEB_REVALIDATE_SECRET`) used to purge its cache
`apps/admin/.env`	`VITE_API_URL` (backend), `VITE_WEB_URL` (public site, used for page previews), `VITE_TINYMCE_API_KEY`
`apps/web/.env`	`BACKEND_API_URL` (backend base URL for server rendering), `REVALIDATE_SECRET` (must match the backend's `WEB_REVALIDATE_SECRET`), `SITE_URL` (canonical origin)

docker-compose.yml loads each service's env from the same per-app files. Inside Docker, service URLs must use compose service names (http://backend:3333), not localhost.

Running

Locally

Command	Description
`npm run dev:backend`	Start the AdonisJS backend in development mode
`npm run dev:admin-app`	Start the React admin application
`npm run dev:web`	Start the Next.js web application
`npm run dev:all`	Start backend, admin, and web apps concurrently

With Docker

docker compose up -d

Brings up everything: backend (3333), admin (5173), web (3000), PostgreSQL (5432), Redis (6379), MinIO (9000 / console 9001) and pgAdmin (5050).

Two quirks worth knowing when a change appears not to take effect:

The web container keeps .next on an anonymous volume that survives rebuilds. Clear it with docker compose up -d --force-recreate --renew-anon-volumes web.
Backend HMR does not always pick up edits on macOS (bind-mount file events); restart crux_backend_adonis to load them.

Scripts

Build

Command	Description
`npm run build:backend`	Build the backend application
`npm run build:admin`	Type-check and build the admin application
`npm run build:web`	Type-check and build the Next.js web app

Test

Command	Description
`npm run test:backend`	Backend functional tests (requires a database)
`npm run test:admin`	Admin unit tests (Vitest)
`npm run test:web`	Web app unit tests (Vitest)

Lint and format

Command	Description
`npm run lint`	ESLint across the monorepo
`npm run lint:fix`	ESLint with autofix
`npm run format`	Prettier write
`npm run format:check`	Prettier check, no writes

Versions

Command	Description
`npm run version:patch`	Update patch version of all packages
`npm run version:minor`	Update minor version of all packages
`npm run version:major`	Update major version of all packages

Versions are updated without creating git tags.

Features

Module Generator

Create full CRUD modules by selecting:

Database table
Fields and types
Validation rules
List view configuration

Generated output — Backend: controllers, validators, routes. Frontend: pages, forms, tables, API.

Authentication & Authorization

JWT / session-based authentication
Role & permission system
Policy-based access control

Content Management

Web Manager is the built-in CMS: editors build localized pages from prebuilt blocks in the admin panel, preview them privately, and publish to the Next.js site, which purges only the cache entries the change affects. See Web Manager.

Documentation

Topic	Where
Documentation home	docs/Readme.md
Public website	apps/web/Readme.md
Architecture	docs/architecture/
Core modules	docs/core/
Shared packages	docs/packages/Readme.md
Install and setup issues	troubleshooting.md