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!

Project Structure

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 resources directory.

The App Directory

The 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

The 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 public directory.

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

Using the 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 public directory.

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.

• config will house everything configuration base. As we extend our Adonis project by adding new modules, so to will the files within our config directory. We are also welcome to extend upon the config directory ourselves, just be sure not to overwrite anything Adonis requires.

• contracts contains TypeScript based items, like enums or interfaces.

• start will 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 start directory to hold our event definitions.

  To start with Adonis provides us two files, kernel.ts and routes.ts. The kernel.ts file contains middleware definitions and routes.ts contains our route definitions.

Environment Variables

Adonis provides us two different files to define our environment variables, .env and env.ts. The .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.

Getting Help

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 make:view command.

$ node ace make:view -h

Make a new view template

Usage: make:view <name>

Arguments
  name     Name of the view

  

    

      Copied!
      

        

      
    
  
  
    
    
    
    
    
  

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.edge

  

    

      Copied!
      

        

      
    
  
  
    
    
    
    
    
  

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.

What's Next?

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.