Before we begin learning how to use Adonis, let's first review the project structure. Then, later in this lesson we'll discuss Adonis' CLI solution called Ace. Once we get these two things out of the way we'll be ready to dive into Adonis!
Below you'll find an overview of Adonis' project structure, as outlined on Adonis' Directory Structure page. A lot of these files and directories you may never touch, especially not until later on in your Adonis journey. So, today let's focus on what's important to know sooner rather than later.
. ├── app ├── commands ├── config ├── contracts ├── providers ├── public ├── resources │ └── views ├── start │ ├── kernel.ts │ └── routes.ts ├── .env ├── .adonisrc.json ├── ace ├── ace-manifest.json ├── env.ts ├── package-lock.json ├── package.json ├── server.ts └── tsconfig.json
Two directories you'll definitely be working within will be the
app directory and the
The App Directory
app directory is going to contain all of the business logic for our back-end. It'll contain items like controllers, models, services, exceptions, and middleware.
The Resources Directory
resources directory is the opposite, it's everything related to our front-end. It'll contain items like views, layouts, emails markup, and our uncompiled assets. Once we compile our assets, we'll want those to go into our
Everything view related will go inside a sub-directory in resources called
views. Adonis will start us with a simple welcome page at
/resources/views/welcome.edge. Note the edge file extension. Edge is the template engine Adonis uses. If you're familiar with Laravel, it'll feel very familiar to Blade. Out of the box, Visual Studio Code doesn't include Edge support for syntax highlighting. However, the "Edge template support" extension will fix that right up.
The Public Directory
public directory we can reference assets directly off our application's root path. So, for example if we had a
main.css file at
/public/css/main.css we can reference this CSS file at
https://example.com/css/main.css. The same applies for any file stored within the
The Database Directory
Another important directory is the database directory. This will contain everything database related; migrations, factories, seeds, etc. This will be added to our project later on when we add and setup Lucid, Adonis' ORM.
Other Directories to Know About
Let's quickly cover some of the other directories just so you're aware of them and their purpose.
configwill house everything configuration base. As we extend our Adonis project by adding new modules, so to will the files within our
configdirectory. We are also welcome to extend upon the
configdirectory ourselves, just be sure not to overwrite anything Adonis requires.
contractscontains TypeScript based items, like enums or interfaces.
startwill contain modules that we want to be defined only once within our application's boot process. For example, whenever we begin covering events within Adonis, we'll use the
startdirectory to hold our event definitions.
To start with Adonis provides us two files,
kernel.tsfile contains middleware definitions and
routes.tscontains our route definitions.
Adonis provides us two different files to define our environment variables,
.env file contains the actual key/value pairs of our environment variables. This file is pretty standard within most Node applications. However, Adonis also has this nifty
env.ts file. This file allows us to define what we expect our
.env file to contain, as well as the type the value should be. What this provides us is really nice autocomplete and TypeScript support whenever we go to read and use our environment variables within our project.
Ace, the Adonis CLI
Before we round out this lesson, let's quickly cover Ace; how to use it, it's options, and help structure.
To start out, we can run an Ace command by entering
node ace [command] in our terminal. If we just run
node ace it'll list out all the available commands we currently have.
Now, this list is dynamic based off the Adonis modules we have installed, and we can also define commands ourselves. For example, whenever we add the Lucid ORM module we'll get a couple new commands. One of which will be called
make:model. Right now we don't have this, but once we add Lucid to our project it'll dynamically be available to us.
Like most other CLIs, Ace also includes the standard
-h help flag. You can append this to any command and Ace will display to you some useful information for the command.
For example, let's get some help with how to use the
$ node ace make:view -h Make a new view template Usage: make:view <name> Arguments name Name of the viewCopied!
When we run the above command we'll get back from Ace a description of the command, an example usage of the command, and any arguments the command accepts. In this case,
make:view accepts a single argument called
name, which is the name of the view that will be created.
Testing Out the CLI
To give you an example of what a full Ace command looks like, let's use the CLI to add a new view to our project.
$ node ace make:view test CREATE: resources/views/test.edgeCopied!
This should create a new view within our
/resources/views directory called
test.edge. Now, whenever we use the CLI to create new views, the view file will begin empty. Don't fret, this is one of, if not the only, CLI use-case where the file generated is empty. Most everything else will start us with boilerplate contents. For example, creating a new controller will stub out our controller's class.
Now that you know your way around Adonis a little, we can begin by learning about individual concepts. In the next lesson, we'll be covering routing and the various different options available to us.