Newly created Adonis projects actually come with the Ace CLI packed in. The Ace CLI is Adonis' command-line interface (CLI). It allows us to conveniently create various types of files, startup our starter, get overview information about our project. It's also easily expandable by both installed packages and us the developers.
The first command you're probably going to utilize is called node ace serve
, this is the command we use to start our server up. The serve command is what allows us to view our application in the browser at http://localhost:3333.
Ace Command Anatomy
Let's digest that serve command a little bit to get a better understanding of what we're doing. In the command node ace serve
, the actual command name is serve
while node ace
is instructing Node that we'd like to communicate with the Ace CLI, made available via the ace
file within our project. So, node ace
gives us access to the Ace CLI, while serve
is the actual command we're running.
Node Ace
If we initiate the Ace CLI using node ace
, but don't give it a command the Ace CLI will print back to us a listing of all the currently available commands within our project.
Now, as we add additional packages to our application those packages can register additional commands for us to use to the Ace CLI. We too can also add additional commands as well by utilizing the node ace make:command
command.
Initial Command Options
So, let's briefly run through the initial commands Adonis comes with out of the box and what those commands are for.
Available Commands
build
This will build out your applications, converting it from TypeScript to JavaScript. If we have frontend assets, it'll also build those assets using Webpack Encore.configure
We'll use this to configure additional packages that we install within our application. Packages can include instructions on how that package needs to be added within a particular application to be used successfully. Configure will take those instructions and execute them on our application so the package is configured for us.repl
This will allow us to communicate with our application via the command line. For example, we can import a Model and execute a query with that Model without touching our codebase inside a REPL session.serve
This starts up our HTTP server.
Dump
dump:rcfile
This will dump the contents of ouradonisrc.json
file.
Generate
generate:key
This will generate a freshAPP_KEY
value, which is stored within your.env
file.generate:manifest
This will generate or refresh a manifest file containing our Ace CLI commands.
List
list:routes
This will list all the configured routes in our application within a table inside our terminal. It'll also contain information about the route, like what's handling the route, its registered middleware, name, and so on.
Make
make:command
We can use this command to create a new command within our application. Each created command will get its own file within thecommands
directory.make:controller
We can use this command to create a new controller within our application. These will be created within ourapp/Controllers/Http
directory by default.make:exception
We can use this command to create a new exception handler. These will be created within theapp/Exceptions
directory.make:listener
We can use this command to create a new event listener. These will be created within theapp/Listeners
directory.make:middleware
This allows us to create a new middleware. These will be created within theapp/Middleware
directory. Don't forget to register your new middleware file within yourstart/kernel.ts
file.make:prldfile
This allows us to create a new preload file. These will be created within thestart
directory. Don't forget to register your new preload files within youradonisrc.json
file.make:provider
This allows us to create a new provider. These will be created within theproviders
directory.make:validator
This allows us to create a new validator class file. These will be created within theapp/Validators
directory.make:view
This allows us to create a new view file. These will be created within theresources/views
directory.
Global Flags
-h
,--help
This will provide a list of all the currently registered commands available within your project. Additionally, you can run the
-h
or--help
flag on any command to get additional information about that command. For example,node ace serve -h
.-v
,--version
This will provide information about your application's version, your Adonis version, and your assembler version.
Creating A New Ace CLI Command
We can use the Ace CLI to easily create a new Ace CLI command. Let's take a look at the options the make:command
command has by running it with the help flag.
node ace make:command -h
# Make a new ace command
#
# Usage: make command <name>
#
# Arguments
# name Name of the command class
#
# Flags
# -e, --exact boolean Create the command with the exact name as provided
So, here we can see the anatomy of the make:command
is to run it as node ace make:command <name>
, where <name>
is the name we'd like the new command to have.
Adonis Naming Normalization
Now, Adonis conveniently normalizes class and file names when we create them using the Ace CLI. As you'll see later in the series when we make new controllers those controller names will be plural because controllers manage multiple records. Whereas, when we make Model names, they'll be singular because a Model represents a single record.
Adonis also does something similar with file name capitalizations.
The -e
or --exact
flag can be used to state that we'd like to bypass Adonis' normalization and have the file and classes named exactly as we specify.
Creating Our Command
Okay, so let's go ahead and create our command. For right now, let's just call this command Example
, we're just going to create it so we can take a look at the process of adding a custom command.
node ace make:command Example
# CREATE: commands/Example.ts
Once executed, Adonis will create an Example.ts
file within our commands
directory. If we take a look at this newly created file we'll see the below.
// commands/Example.ts
import { BaseCommand } from '@adonisjs/core/build/standalone'
export default class Example extends BaseCommand {
/**
* Command name is used to run the command
*/
public static commandName = 'example'
/**
* Command description is displayed in the "help" output
*/
public static description = ''
public static settings = {
/**
* Set the following value to true, if you want to load the application
* before running the command
*/
loadApp: false,
/**
* Set the following value to true, if you want this command to keep running until
* you manually decide to exit the process
*/
stayAlive: false,
}
public async run () {
this.logger.info('Hello world!')
}
}
You can see we have properties to be able to specify the command name, command description, and command settings.
The command name is what will appear within our Ace CLI command list. The description is the blurb that appears next to the command.
loadApp
can be set to true to specify that the command needs to load the application prior to executing.
stayAlive
can be set to true to specify that the command should remain alive until manually exited.
Finally, run
is the method where we actually define what it is our command will do. By default, it'll use the logger to log an info block into our terminal or application log if it's executed in production.
Registering The Command
If you run node ace
to look at your currently available commands, you'll notice our example
command isn't yet displaying in our command list. This is because Adonis reads our commands from an ace-manifest.json
file, which we haven’t yet updated.
To update the ace-manifest.json
file with our new command, all we need to do is run the below in our terminal.
node ace generate:manifest
# CREATE: ace-manifest.json
You'll also want to run the generate:manifest
command anytime you update a command's name, description, or settings as all of these values are stored within and read from the ace-manifest.json
file.
Running Our Custom Command
Now that we've updated our ace-manifest.json
file, if we run node ace
again to list out our available commands we should now see our example
command listed along with a description if you provided one.
Let's go ahead and execute this command by running the following.
node ace example
# [ info ] Hello world!
You should see [ info ] Hello world!
printed out into your terminal, unless you changed your command at all, meaning our command ran successfully.
Wrapping Up
We've covered the initial list of commands the Ace CLI comes with, what the anatomy of a command looks like, the help panel, and how to create a new command.
Although our custom command only logged information into our terminal, we'll see later on in the series how we can further utilize custom commands to keep our database clean of old outdated data.
Join The Discussion! (2 Comments)
Please sign in or sign up for free to join in on the dicussion.
Anonymous (ElephantJaine761)
Thanks for wonderful article on Adonis Ace !!
Please sign in or sign up for free to reply
jony254
Lesson 3 done ✅
Please sign in or sign up for free to reply