AdonisJS is, as they state, a fully-featured web framework for NodeJS. It's going to allow us to create either a Model View Controller (MVC) or an Application Programming Interface (API) server application.
MVC applications are where we have our business logic and our font-end wrapped up all in one monolithic project. An API server would be where you'd use separate projects for your front-end and back-end; Adonis being your back-end, handling your application's business logic.
Whichever project structure you utilize Adonis for, Adonis comes loaded with all the features you'll need to easily build and scale your application. It has its own routing system, controller and service support, file upload support, it has its own object-relational mapper (ORM), validator, command-line interface (CLI), template engine, and more. It also supports both email + password and social authentication as well as authorization.
Its ORM, called Lucid, has a really nice query builder that's easily customizable, which is built off KnexJS. It also works extremely well with SQL-based relational databases. It's CLI, called Ace, it's also very easily customizable allowing you to create your own commands. It's also type-safe with TypeScript. Need I say more?
About This Series
So, throughout this series, we're going to be stepping through each of these features in an incremental fashion, not necessarily in the way you'd typically approach a project, but more so to learn things in a stepped process.
So, we're going to start out here with getting a new project set up and running. Then, in the next lesson, we're going to take a look at the project structure. Then, we'll learn about Adonis's HttpContext, then we'll spend a few lessons on routing, and so on and so forth.
As a brief aside, I'm also going to be starting other series alongside this one where we specifically focus on building particular projects. So, if you're interested in that, be sure to check those out as they release.
The goal of this series is to help you approach and build projects at a much faster rate by having strong familiarity with Adonis and its ecosystem.
Adonis has two prerequisites, both dealing with Node. We're going to need NodeJS version 14.15.4 or greater and NPM version 6.0.0 or greater. If you don't have Node and you don't have Node Version Manager (NVM) or Nodenv you can get node by either installing NVM or Nodenv and installing Node that way or by heading over to nodejs.org and downloading the latest version directly from Node. The download from nodejs.org installs Node and NPM just like a typical application on your system, so it'll walk you through the steps. Note that NPM comes along with Node, so installing Node should take care of NPM for you. NPM stands for Node Package Manager.
Again, those prerequisites are:
NodeJS version 14.15.4 or greater
NPM version 6.0.0 or greater
Once you have Node and NPM installed, you can verify you meet the requirements by running
node -v and
npm -v in your terminal.
Creating Our Project
Once you're all set with Node and NPM, we're ready to create our Adonis project! To create a new Adonis project, we'll enter the following command in our terminal
npm init adonis-ts-app@latest [project_name] where
[project_name] is the name you'd like your project to be.
adonis-ts-app is the
npm init command to specifically create an Adonis 5 application. The
@latest is telling the command to use the latest available version of Adonis for our project.
I'll be calling my project
lets-learn-adonis-5, so I'll be entering the following command to create my Adonis project.
npm init adonis-ts-app@latest lets-learn-adonis-5
Once we enter the above command to create our project Adonis is going to ask us a couple of questions to help us get up and running quicker.
Select the project structure > Web
API (Tailored for creating a REST API server) This will set us up with an API server where we'd have separate front-end and back-end projects, where Adonis would be our back-end.
Web (Traditional web application with server rendered templates) This will set up a monolithic application where our front-end and back-end are all in one and Adonis handles both the front and back end.
Slim (A smallest possible AdonisJS application) This will create a minimalist application, with no extras baked in.
We'll be selecting Web.
Enter the project name > lets-learn-adonis-5
Provide whatever you'd like here, default is fine.
Setup eslint? > n
I'll be skipping eslint, but feel free to select as you'd wish. hit y for yes and n for no. Eslint will help keep the code within your project consistent.
Configure webpack encore for compiling frontend assets? > y
From here Adonis will begin creating our project, then it'll install the needed dependencies based on our selections.
Starting Our Server
The last thing to do is start our server up to ensure everything is installed and configured okay. So, let's first change into our project directory within our terminal.
cd [project_name]. So, for me, I'll want to run
cd lets-learn-adonis-5 since
lets-learn-adonis-5 was the name of my newly created project.
This will move us into our project directory, essentially double-clicking into our project if we were viewing it in Finder or Windows Explorer, except for the terminal.
Lastly, let's boot up our server. To do this we'll execute our first Ace CLI command. Ace CLI is Adonis's command-line interface. So, let's run
node ace serve --watch in our terminal.
This will start up our server. Specifically,
node ace is how we'll run Ace CLI commands.
serve is the command name we're running, then
--watch is telling the serve command to also watch our project for changes. When we watch for changes, if we change our codebase at all, Adonis will update our running server code and those changes will be reflected immediately without us needing to restart our server to pick up every little change.