Installation

System Requirements

Before installing the AdonisJS Starter Kit, ensure your system meets these requirements:

Node.js

Version 20 or higherCheck your version:

node --version

pnpm

Version 10.18.0 or higherCheck your version:

pnpm --version

Docker

Docker Desktop or Docker EngineFor database services

Git

Latest versionFor version control

Installing Prerequisites

Install Node.js

Download and install Node.js from nodejs.org or use a version manager:

# Using nvm (Node Version Manager)
nvm install 20
nvm use 20

Verify installation:

node --version  # Should output v20.x.x or higher
npm --version   # Should be included with Node.js

Install pnpm

Install pnpm globally using npm:

npm install -g [email protected]

Or use alternative installation methods:

npm install -g pnpm

Verify installation:

pnpm --version  # Should output 10.18.0 or higher

The starter kit specifies pnpm as the package manager in package.json for optimal monorepo performance.

Install Docker

Install Docker Desktop for your operating system:

macOS
Windows
Linux

Download from docker.com/products/docker-desktopOr install via Homebrew:

brew install --cask docker

Download from docker.com/products/docker-desktopOr install via Chocolatey:

choco install docker-desktop

Install Docker Engine:

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Install Docker Compose:

sudo apt-get install docker-compose-plugin

Verify installation:

docker --version
docker compose version

Creating a New Project

Scaffold from Template

Use the AdonisJS CLI to create a new project from the starter kit:

pnpm create adonisjs@latest -K="filipebraida/adonisjs-starter-kit"

The -K flag specifies the GitHub repository to use as a template. This clones the starter kit with its complete structure.

The CLI will prompt you for:

Project name: Enter your application name (e.g., my-app)
Package manager: Select pnpm (recommended)
Additional configuration: Follow prompts as needed

Navigate to your project:

cd my-app

Understand Project Structure

The starter kit follows a monorepo architecture:

my-app/
├── apps/
│   └── web/                    # Main AdonisJS application
│       ├── app/                # Feature modules
│       │   ├── auth/          # Authentication module
│       │   ├── users/         # User management module
│       │   ├── common/        # Shared utilities
│       │   ├── core/          # Core functionality
│       │   ├── analytics/     # Analytics module
│       │   └── marketing/     # Marketing pages
│       ├── config/            # Application configuration
│       ├── database/          # (Optional) shared migrations
│       ├── resources/         # Frontend resources
│       │   ├── js/           # React components
│       │   ├── views/        # Edge templates
│       │   └── images/       # Static images
│       ├── start/            # Preload files
│       ├── tests/            # Test suites
│       ├── .env.example      # Environment template
│       ├── adonisrc.ts       # AdonisJS configuration
│       ├── package.json      # App dependencies
│       └── vite.config.ts    # Vite configuration
├── packages/
│   ├── ui/                    # Shared UI components (ShadCN)
│   │   ├── src/
│   │   │   ├── components/   # Reusable components
│   │   │   └── lib/          # Utility functions
│   │   ├── components.json   # ShadCN configuration
│   │   └── package.json
│   ├── eslint-config/         # Shared ESLint configuration
│   └── typescript-config/     # Shared TypeScript configuration
├── .github/                   # CI/CD workflows and configs
│   ├── postgres/             # PostgreSQL init scripts
│   └── pgadmin/              # PgAdmin server configs
├── docker-compose.yaml        # Development services
├── docker-compose.prod.yaml   # Production overrides
├── pnpm-workspace.yaml        # Workspace definition
├── turbo.json                 # TurboRepo configuration
├── package.json               # Root package configuration
└── tsconfig.json              # Root TypeScript config

Each module under apps/web/app/ can have its own controllers, models, services, validators, database migrations, and routes.

Environment Configuration

Create Environment File

Copy the example environment file:

cp apps/web/.env.example apps/web/.env

The .env.example file includes all necessary configuration options with sensible defaults for development.

Generate Application Key

Generate a cryptographically secure key for session encryption and other security features:

node apps/web/ace generate:key

The APP_KEY is critical for security. Never commit your .env file or share this key publicly.

This command generates a secure key and automatically updates the APP_KEY variable in your .env file.

Configure Core Settings

Review and adjust core application settings in apps/web/.env:

# Application Settings
TZ=UTC                      # Timezone for date/time operations
PORT=3333                   # HTTP server port
HOST=localhost              # Server hostname
LOG_LEVEL=info              # Logging level: trace|debug|info|warn|error|fatal
APP_KEY=                    # Generated by ace generate:key
NODE_ENV=development        # Environment: development|production|test

The VITE_API_URL variable is used by the React frontend to make API requests. Update this if you change the PORT.

Configure Database

The starter kit uses PostgreSQL. Configure your database connection:

.env

# Database Configuration
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=root
DB_PASSWORD=root
DB_DATABASE=app

These defaults match the Docker Compose configuration provided in the starter kit.

For production, use strong credentials and consider using connection pooling:

.env (Production)

DB_HOST=your-db-host.com
DB_PORT=5432
DB_USER=your_secure_user
DB_PASSWORD=your_strong_password
DB_DATABASE=your_app_production

Configure Email (Optional)

For local development, the starter kit uses Mailpit for email testing:

.env

# Email Configuration (Mailpit for local development)
SMTP_HOST=localhost
SMTP_PORT=1025
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=XXX
SMTP_SECURE=0
SMTP_REJECTUNAUTHORIZED=false

# Email From Address
EMAIL_FROM=[email protected]

Mailpit captures all outgoing emails during development. Access the interface at http://localhost:8025 after starting Docker services.

For production, configure a real email service like Resend:

RESEND_API_KEY=re_your_api_key
EMAIL_FROM=[email protected]

Configure Social Authentication (Optional)

The starter kit supports social authentication via @adonisjs/ally. Configure providers as needed:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

To set up OAuth providers:

Create OAuth applications in Google Cloud Console or GitHub Developer Settings
Set callback URLs to http://localhost:3333/auth/[provider]/callback
Copy client ID and secret to your .env file

Leave these blank for now if you don’t need social authentication immediately.

Additional Configuration

Optional settings for advanced features:

.env

# Rate Limiting
LIMITER_STORE=database      # Store: memory|redis|database

# CORS (if needed)
CORS_ENABLED=true
CORS_ORIGIN=*

Database Setup

Start Docker Services

The starter kit includes Docker Compose configuration for all required services:

docker compose up -d

This starts three containers:

PostgreSQL
PgAdmin
Mailpit

Container: {PROJECT_NAME}_pgsql

Port: 5432
Database: Configured via DB_DATABASE in .env
Initialization: Auto-creates adonis_app database via init script

Database Details:
- Host: 127.0.0.1
- Port: 5432
- User: root
- Password: root
- Database: app

Container: {PROJECT_NAME}_pgadmin

Port: 5050
URL: http://localhost:5050
Email: [email protected]
Password: secret

Pre-configured with server connection to PostgreSQL container.

Container: {PROJECT_NAME}_mailpit

Web UI: http://localhost:8025
SMTP: localhost:1025
Max Messages: 5000
Storage: apps/web/tmp/mailpit/

Captures all emails sent by the application.

Verify services are running:

docker compose ps

Expected output:

NAME                    STATUS              PORTS
repo_pgsql              Up (healthy)        0.0.0.0:5432->5432/tcp
repo_pgadmin            Up                  0.0.0.0:5050->80/tcp
repo_mailpit            Up                  0.0.0.0:1025->1025/tcp, 0.0.0.0:8025->8025/tcp

The PostgreSQL healthcheck ensures the database is ready before proceeding. Wait for the “healthy” status.

Run Migrations

Create database tables by running migrations:

pnpm --filter web exec node ace migration:run

The --filter web flag tells pnpm to run the command in the apps/web workspace.

This executes migrations from the users module:

create_roles_table.ts - User roles (admin, user, etc.)
create_users_table.ts - User accounts
create_reset_password_tokens_table.ts - Password recovery
create_access_tokens_table.ts - API tokens
create_rate_limits_table.ts - Rate limiting

Verify migrations:

pnpm --filter web exec node ace migration:status

Each feature module can have its own migrations in app/{module}/database/migrations/.

Seed Database

Populate the database with initial data:

pnpm --filter web exec node ace db:seed

The default seeder (apps/web/app/users/database/seeders/user_seeder.ts) creates:

Default user roles
Admin and test user accounts
Sample data for development

Seeders are for development only. Never run seeders in production with test data.

To create custom seeders:

node ace make:seeder product -m=products

Verify Database

Access PgAdmin to verify your database setup:

Open http://localhost:5050
Login with:
- Email: [email protected]
- Password: secret
Expand Servers → PostgreSQL → Databases → app
Check Schemas → public → Tables

You should see all migrated tables.

Alternatively, use the AdonisJS REPL to query the database:

node ace repl

Then run:

await db.from('users').select('*')

Installing Dependencies

Install All Dependencies

Install dependencies for all workspaces in the monorepo:

pnpm install

pnpm automatically handles the monorepo structure defined in pnpm-workspace.yaml, installing dependencies for:

Root workspace
apps/web/
packages/ui/
packages/eslint-config/
packages/typescript-config/

This creates:

node_modules/ in each workspace
pnpm-lock.yaml lockfile
Symlinks for workspace dependencies (e.g., @workspace/ui)

Verify Installation

Check that all packages are correctly installed:

pnpm list --depth=0

Verify workspace linking:

pnpm list --depth=0 --filter web

You should see @workspace/ui listed as a dependency.

Building for Production

Build All Packages

Build all packages in the monorepo:

pnpm run build

TurboRepo orchestrates the build process:

Builds shared packages (@workspace/ui, configs)
Builds the web application
Compiles TypeScript and bundles frontend assets
Generates production-ready files in apps/web/build/

TurboRepo caches build outputs for faster subsequent builds. The cache is stored in node_modules/.cache/turbo.

Start Production Server

Run the production build:

cd apps/web
node bin/server.js

Or use the production Docker Compose setup:

pnpm run docker:prod

This uses docker-compose.prod.yaml with optimized settings.

Development Workflow

Start Development Server

Launch the development server with hot module reloading:

pnpm run dev

This starts:

AdonisJS server with hot reloading (port 3333)
Vite dev server for frontend assets (port 5173)
File watchers for automatic reload on changes

The hot-hook package enables hot reloading for controllers and middleware without full server restart.

Open http://localhost:3333 to view your application.

Run Linting

Check code quality across all workspaces:

pnpm run lint

Fix linting errors automatically:

pnpm --filter web run lint --fix

Format Code

Format code using Prettier:

pnpm run format

This formats all TypeScript, TSX, and Markdown files.

Run Tests

Execute the test suite:

pnpm --filter web run test

Run specific test suites:

pnpm --filter web exec node ace test --suite=unit

Tests are configured in adonisrc.ts and use Japa test runner.

Adding UI Components

The starter kit uses ShadCN for UI components. Add components to your project:

pnpm dlx shadcn@latest add [component-name] -c apps/web

pnpm dlx shadcn@latest add button -c apps/web

Components are installed to packages/ui/src/components/ui/ and can be used across the entire application.

Creating Feature Modules

The starter kit supports modular architecture using @adonisjs-community/modules:

Install Modules Package (if not already installed)

node ace add @adonisjs-community/modules

Create a Module

Generate a new feature module:

node ace make:module products

This creates:

apps/web/app/products/
├── controllers/
├── models/
├── services/
├── validators/
├── database/
│   ├── migrations/
│   └── seeders/
└── routes.ts

And adds an import alias to package.json:

{
  "imports": {
    "#products/*": "./app/products/*.js"
  }
}

Generate Module Resources

Create resources within a module using the --module flag:

node ace make:controller product -m=products

Troubleshooting

Docker services won't start

Port conflicts:Check if ports are already in use:

lsof -i :5432  # PostgreSQL
lsof -i :5050  # PgAdmin
lsof -i :8025  # Mailpit

Stop conflicting services or change ports in docker-compose.yaml.Docker daemon not running:Start Docker Desktop or the Docker daemon:

# Linux
sudo systemctl start docker

Migration errors

Connection refused:Ensure PostgreSQL is running and credentials match:

docker compose ps
docker compose logs pgsql

Migration already exists:Check migration status:

pnpm --filter web exec node ace migration:status

Rollback if needed:

pnpm --filter web exec node ace migration:rollback

Module resolution errors

Cannot find module ‘#users/*’:Ensure imports are defined in apps/web/package.json:

{
  "imports": {
    "#users/*": "./app/users/*.js"
  }
}

Restart your development server after adding imports.TypeScript errors:Update tsconfig.json paths if needed:

{
  "compilerOptions": {
    "paths": {
      "#users/*": ["./app/users/*"]
    }
  }
}

Build failures

Turbo cache issues:Clear TurboRepo cache:

pnpm exec turbo clean
rm -rf node_modules/.cache/turbo

Dependency issues:Remove all node_modules and reinstall:

rm -rf node_modules apps/*/node_modules packages/*/node_modules
pnpm install

Frontend not loading

Vite connection error:Ensure VITE_API_URL in .env matches your server:

VITE_API_URL=http://localhost:3333

Assets not found:Check Vite config and ensure dev server is running:

# Should see both servers starting
pnpm run dev

Next Steps

Quick Start Guide

Follow the quick start guide for a streamlined setup

AdonisJS Documentation

Learn more about AdonisJS framework features

ShadCN Components

Browse available UI components

Inertia.js Guide

Understand Inertia.js for building SPAs

Join the AdonisJS community on Discord for support and to connect with other developers.

Getting Started

Project Structure

Core Features

Development

Deployment

System Requirements

Node.js

pnpm

Docker

Git

Installing Prerequisites

Creating a New Project

Environment Configuration

Database Setup

Installing Dependencies

Building for Production

Development Workflow

Adding UI Components

Creating Feature Modules

Troubleshooting

Next Steps

Quick Start Guide

AdonisJS Documentation

ShadCN Components

Inertia.js Guide

Build docs developers (and LLMs) love

Getting Started

Project Structure

Core Features

Development

Deployment

​System Requirements

Node.js

pnpm

Docker

Git

​Installing Prerequisites

​Creating a New Project

​Environment Configuration

​Database Setup

​Installing Dependencies

​Building for Production

​Development Workflow

​Adding UI Components

​Creating Feature Modules

​Troubleshooting

​Next Steps

Quick Start Guide

AdonisJS Documentation

ShadCN Components

Inertia.js Guide

Build docs developers (and LLMs) love

System Requirements

Installing Prerequisites

Creating a New Project

Environment Configuration

Database Setup

Installing Dependencies

Building for Production

Development Workflow

Adding UI Components

Creating Feature Modules

Troubleshooting

Next Steps