Introducing AdonisJS - Setup

In this post, we will focus on setting up the development environment and also get our code editor ready to work with Typescript and Edge (the template engine of AdonisJS)

Prerequisites

AdonisJS is a Node.js framework and therefore you must have Node.js installed on your computer.

If it's not installed, then please head over to nodejs.org and download the binary/installer for your operating system. If you are comfortable with the command line, then I recommend using volta (personal favorite) or nvm for installing Node.js.

Check Node.js version

Make sure that the installed version is greater than 12.0.0 along with npm >= 6.0.0.

node -v
npm -v

That's all you need :)

Creating a new project

Creating a new AdonisJS project is pretty straight forward. All you need to do is run the following npm init command.

npm init adonis-ts-app todo

• Here npm init is an npm specific command to install a package and run its bin command in one go.
• The package name is create-adonis-ts-app, but npm init wants us to drop the create prefix. Not sure about the history behind this decision, but the yarn has the same design as well.
• Finally todo is the path in the filesystem where you want to create the project. If the directory is missing, we will create it for you. However, if the directory already has files then we will refuse to create a project inside it.

Differences between the web and the api project structure

The project creation flow prompts you to choose between the api and the web project structure. The following are the differences between both.

• The web project structure installs the template engine and the session package of AdonisJS. Also, the support for serving static files like CSS or images is enabled.
• On the other hand, the api project structure configures the support for CORS.
• Apart from these specific changes, the rest of the project structure and files are the same.

Starting the development server

Run the following command to start the development server. Make sure that you are inside the project root before running the command.

node ace serve --watch

Here things get a bit interesting. We will talk about ace commands in the next post. But for now, ace is a command-line framework that is embedded within your app and this allows you to create project-specific commands and run them using node ace.

• The serve command starts the development server and the --watch flag continues watching the filesystem for changes and restarts the server after every change.
• Also, the serve command can run the typescript source directly. There is no intermediate compilation step and this speeds up things a little bit.

VSCode setup

To begin with, I am going to share a list of extensions that you must install for VSCode. If you are not a VSCode user, then feel free to leave comments and I will update the blog post with other editors setup too.

• The source code is written in Typescript and luckily VSCode comes with out of the box support it and hence no special plugins are required to work with Typescript.
• You must install the Edge template support plugin to have syntax highlighting for the AdonisJS template engine (Edge).
• If you don't hold strong opinions against prettier and eslint. Then I highly recommend VScode Eslint and VSCode prettier plugins to make your life a bit easier.

What's in the box?

Since AdonisJS is a fully-featured framework, you get a lot with a new application. The following features or functionality is baked right into the core of the framework.

• HTTP stack. It includes the router, request & response objects, support for middleware, global exception handler.
• Bodyparser and support for file uploads. Even stuff like directly streaming files to a third party like s3.
• Validator to validate the request data.
• Encryption and Hash modules with sensible defaults by keeping overall security in mind.
• An embedded command line framework ace.
• Support for encrypted/signed cookies and session.
• Support for serving static files from the public directory.
• And finally, a well thought project structure and out of the box support for typescript.

Closing thoughts

This post is mainly targeted towards the audience using AdonisJS or Node.js for the first time. I want to talk about every little detail without making assumptions that the reader already knows this.

If you think all this is a no-brainer for you, then stick around, things will get interesting as we will make progress 🙂

Comments

[Rodolpho Netto]

Using adonis in production projects since march and had no issues related to it, just works :)

[Arandi López]

Great job Aman!

For those who use emacs, if you need support for edge templates you can tackle it with this:

;;; adonis-edge-mode.el -*- lexical-binding: t; -*-

;; Copyright (C) 2020  Arandi Lopez

;; Author: Arandi Lopez <[e-mail]>

;; A new derived mode (adonis-edge-mode) from web-mode
(define-derived-mode adonis-edge-mode web-mode "Edge"
  "Major mode for editing Adonis' Edge templates."
  (setq web-mode-script-padding 2
        web-mode-style-padding 2
        web-mode-block-padding 2
        web-mode-engines-alist '((\"blade\"  . \"\\\\.edge\\\\.\"))))

;; Set as default mode for vuejs files
(add-to-list 'auto-mode-alist '("\\.edge\\'" . adonis-edge-mode))