Creating a project

A new project is created with one command. It downloads a starter kit — an application skeleton with packages already configured — and installs the dependencies.

The create command

Open a terminal in the folder where your projects live and run:

npm init adonisjs@latest blog

The program asks a few questions. The main one is which starter kit to use:

For the blog, pick Web. You can also pass the kit as a flag: npm init adonisjs@latest blog -- --kit=web. Then the program asks for a database — SQLite is fine to start with, it needs no separate server — and a login method: choose session.

Running it

cd blog
node ace serve --hmr

The command starts the development server. Open http://localhost:3333 — the AdonisJS welcome page appears. The --hmr flag means that after you edit a file the server picks up the change without a restart. Stop the server with Ctrl+C. The same command is stored in package.json as npm run dev.

Project folders

blog/
├── app/
│   ├── controllers/     controllers
│   ├── exceptions/      error handler
│   ├── middleware/      middleware
│   ├── models/          Lucid models
│   └── validators/      form validation rules
├── bin/                 entry files: server.ts, console.ts, test.ts
├── config/              package settings
├── database/
│   └── migrations/      migrations
├── resources/
│   ├── views/           Edge templates
│   ├── css/  js/        styles and scripts for Vite
├── start/
│   ├── routes.ts        routes
│   ├── kernel.ts        the middleware list
│   └── env.ts           environment variable checks
├── tests/               tests
├── .env                 settings for this machine
├── adonisrc.ts          settings of the framework itself
├── ace.js               entry to the Ace console
└── package.json

Some folders, such as validators, may be missing at first: they appear when you create the first file of that kind.

Short imports

package.json has an imports section. It defines short paths that start with #:

// app/controllers/posts_controller.ts
import Post from '#models/post'
import { createPostValidator } from '#validators/post'

#models/post means the file app/models/post.ts. This saves you from long paths like ../../models/post.js.

Common mistake

node ace serve works only inside the project folder, because that is where ace.js lives. Run it from the parent folder and Node.js reports that it cannot find the module ace.js. Go into the project first with cd blog.