Commands reference

In this guide, we cover the usage of all the commands shipped with the framework core and the official packages. You may also view the commands help using the node ace list command or the node ace <command-name> --help command.

node ace list

serve

The serve uses the @adonisjs/assembler package to start the AdonisJS application in development environment. You can optionally watch for file changes and restart the HTTP server on every file change.

node ace serve --hmr

The serve command starts the development server (via the bin/server.ts file) as a child process. If you want to pass node arguments to the child process, you can define them before the command name.

node ace --no-warnings --inspect serve --hmr

In both --watch and --hmr modes, the development server restarts when one of the environment files loaded by your application changes, such as .env or .env.local. Files loaded from a custom ENV_PATH directory are watched as well, so you do not have to restart the command manually after editing environment variables.

When running in an interactive terminal, the development server also listens for keyboard shortcuts. Press r to restart the server, c to clear the console, o to open the application in your browser, and h to list the shortcuts.

Following is the list of available options you can pass to the serve command. Alternatively, use the --help flag to view the command's help.

build

The build command uses the @adonisjs/assembler package to create the production build of your AdonisJS application. See Creating the production build for the steps performed during the build.

node ace build

Following is the list of available options you can pass to the build command. Alternatively, use the --help flag to view the command's help.

node ace build --tsconfig=tsconfig.build.json

codegen

The codegen command uses the @adonisjs/assembler package to regenerate the contents of the .adonisjs directory without starting the HTTP server.

node ace codegen

During normal development, Assembler refreshes generated files as part of other workflows. The development server, test runner, and bundler generate file-based indexes, while the development server also generates route-derived types. The codegen command runs both stages explicitly, making it useful in CI before typechecking.

npm ci
node ace codegen
npm run typecheck

The command writes index files first because preload files import them. It then warms up the application, collects its registered routes, and generates route types. The HTTP server is never started and provider ready hooks do not run. Provider start hooks do run, so they must respect the application mode before starting workers or other long-running side effects.

See the code generation guide to learn what AdonisJS generates and whether to commit those files.

add

The add command combines the npm install <package-name> and node ace configure commands. So, instead of running two separate commands, you can install and configure the package in one go using the add command.

The add command will automatically detect the package manager used by your application and use that to install the package. However, you can always opt for a specific package manager using the --package-manager CLI flag.

# Install and configure the @adonisjs/lucid package
node ace add @adonisjs/lucid

# Install the package as a development dependency and configure it
node ace add my-dev-package --dev

If the package can be configured using flags, you can pass them directly to the add command. Every unknown flag will be passed down to the configure command.

node ace add @adonisjs/lucid --db=sqlite

configure

Configure a package after it has been installed. The command accepts the package name as the first argument.

node ace configure @adonisjs/lucid

eject

Eject stubs from a given package to your application stubs directory. In the following example, we copy the make/controller stubs to our application for modification.

See also: Customizing stubs

# Copy stub from @adonisjs/core package
node ace eject make/controller

# Copy stub from @adonisjs/bouncer package
node ace eject make/policy --pkg=@adonisjs/bouncer

generate:key

Generate a cryptographically secure random key and write to the .env file as the APP_KEY environment variable.

See also: App key

node ace generate:key

make commands

The make:* commands shipped with the framework core accept the following flags in addition to their command-specific flags.

node ace make:controller users --force

node ace make:service invoice --contents-from=stubs/custom/invoice_service.ts

make:controller

Create a new HTTP controller class. Controllers are created inside the app/controllers directory and use the following naming conventions.

• Form: plural
• Suffix: controller
• Class name example: UsersController
• File name example: users_controller.ts

node ace make:controller users

You also generate a controller with custom action names, as shown in the following example.

# Generates controller with "index", "show", and "store" methods
node ace make:controller users index show store

make:middleware

Create a new middleware for HTTP requests. Middleware are stored inside the app/middleware directory and uses the following naming conventions.

• Form: singular
• Suffix: middleware
• Class name example: BodyParserMiddleware
• File name example: body_parser_middleware.ts

node ace make:middleware bodyparser

node ace make:middleware bodyparser --stack=router

make:event

Create a new event class. Events are stored inside the app/events directory and use the following naming conventions.

• Form: NA
• Suffix: NA
• Class name example: OrderShipped
• File name example: order_shipped.ts
• Recommendation: You must name your events around the lifecycle of an action. For example: MailSending, MailSent, RequestCompleted, and so on.

node ace make:event orderShipped

make:validator

Create a new VineJS validator file. The validators are stored inside the app/validators directory, and each file may export multiple validators.

• Form: singular
• Suffix: NA
• File name example: user.ts
• Recommendation: You must create validator files around the resources of your application.

# A validator for managing a user
node ace make:validator user

# A validator for managing a post
node ace make:validator post

node ace make:validator post --resource

make:listener

Create a new event listener class. The listener classes are stored inside the app/listeners directory and use the following naming conventions.

• Form: NA
• Suffix: NA
• Class name example: SendShipmentNotification
• File name example: send_shipment_notification.ts
• Recommendation: The event listeners must be named after the action they perform. For example, a listener that sends the shipment notification email should be called SendShipmentNotification.

node ace make:listener sendShipmentNotification

node ace make:listener sendShipmentNotification --event=shipment_received

make:service

Create a new service class. Service classes are stored inside the app/services directory and use the following naming conventions.

• Form: singular
• Suffix: service
• Class name example: InvoiceService
• File name example: invoice_service.ts

node ace make:service invoice

make:exception

Create a new custom exception class . Exceptions are stored inside the app/exceptions directory.

• Form: NA
• Suffix: exception
• Class name example: CommandValidationException
• File name example: command_validation_exception.ts

node ace make:exception commandValidation

make:transformer

Create a new transformer class. Transformers are stored inside the app/transformers directory and use the following naming conventions.

• Form: singular
• Suffix: transformer
• Class name example: UserTransformer
• File name example: user_transformer.ts

node ace make:transformer user

make:command

Create a new Ace command. By default, the commands are stored inside the commands directory at the root of your application.

Commands from this directory are imported automatically by AdonisJS when you try to execute any Ace command. You may prefix the filename with an _ to store additional files that are not Ace commands in this directory.

• Form: NA
• Suffix: NA
• Class name example: ListRoutes
• File name example: list_routes.ts
• Recommendation: Commands must be named after the action they perform. For example, ListRoutes, MakeController, and Build.

node ace make:command listRoutes

make:view

Create a new Edge.js template file. The templates are created inside the resources/views directory.

• Form: NA
• Suffix: NA
• File name example: posts/view.edge
• Recommendation: You must group templates for a resource inside a subdirectory. For example: posts/list.edge, posts/create.edge, and so on.

node ace make:view posts/create
node ace make:view posts/list

make:page

Create a new Inertia page component inside the inertia/pages directory. The command is registered by the @adonisjs/inertia package. It detects the frontend framework from the existing pages and prompts you when it cannot decide.

• Form: NA
• Suffix: NA
• File name example: posts/index.tsx or posts/index.vue

node ace make:page posts/index
# ./inertia/pages/posts/index.tsx

node ace make:page posts/index --vue
# ./inertia/pages/posts/index.vue

node ace make:page posts/index --contents-from=stubs/page.tsx

make:provider

Create a service provider file . Providers are stored inside the providers directory at the root of your application and use the following naming conventions.

• Form: singular
• Suffix: provider
• Class name example: AppProvider
• File name example: app_provider.ts

node ace make:provider app

node ace make:provider app -e=web -e=console

make:preload

Create a new preload file . Preload files are stored inside the start directory.

node ace make:preload view

node ace make:preload view app -e=web -e=console

make:test

Create a new test file inside the tests/<suite> directory.

• Form: NA
• Suffix: .spec
• File name example: posts/list.spec.ts, posts/update.spec.ts

node ace make:test --suite=unit

make:mail

Create a new mail class inside the app/mails directory. The mail classes are suffixed with the Notification keyword. However, you may define a custom suffix using the --intent CLI flag.

• Form: NA
• Suffix: Intent
• Class name example: ShipmentNotification
• File name example: shipment_notification.ts

node ace make:mail shipment
# ./app/mails/shipment_notification.ts

node ace make:mail shipment --intent=confirmation
# ./app/mails/shipment_confirmation.ts

node ace make:mail storage --intent=warning
# ./app/mails/storage_warning.ts

node ace make:mail shipment --contents-from=./stubs/shipment_mail.ts

make:policy

Create a new Bouncer policy class. The policies are stored inside the app/policies folder and use the following naming conventions.

• Form: singular
• Suffix: policy
• Class name example: PostPolicy
• File name example: post_policy.ts

node ace make:policy post

Pass action names after the policy name to pre-define them as methods. The --model flag defines the model imported by the policy. It defaults to the policy name.

node ace make:policy post view edit delete --model=Article

inspect:rcfile

View the contents of the adonisrc.ts file after merging the defaults. You may use this command to inspect the available configuration options and override them per your application requirements.

See also: AdonisRC file

node ace inspect:rcfile

list:routes

View list of routes registered by your application. This command will boot your AdonisJS application in the console environment.

node ace list:routes

You may pass a keyword to only display the routes whose name, pattern, or controller name matches it.

node ace list:routes users

Also, you can see the routes list from the VSCode activity bar if you are using our official VSCode extension .

env:add

The env:add command allows you to add a new environment variables to the .env, .env.example files and will also define the validation rules in the start/env.ts file.

You can just run the command and it will prompt you for the variable name, value, and validation rules. Or you can pass them as arguments.

# Will prompt for the variable name, value, and validation rules
node ace env:add

# Define the variable name, value, and validation rule
node ace env:add MY_VARIABLE value --type=string

node ace env:add MY_VARIABLE foo --type=enum --enum-values=foo --enum-values=bar