You are viewing the legacy version of AdonisJS. Visit https://adonisjs.com for newer docs. This version will receive security patches until the end of 2021.

Installation

Installing AdonisJs is a relatively straightforward process and will only take a few minutes. Feel free to file an issue if you ever face any problems during the installation process.

Installing Node.js & Npm

Being a Node.js framework, AdonisJs has a core dependency on Node.js. Make sure the installed version of Node.js is 4.0 or greater.

Npm is a package manager for Node.js. During the development process, you will find yourself using npm install a lot. Hence all dependencies are pulled from npm only.

In October 2016 v6.x.x of Node.js will be under LTS and also the newer versions of AdonisJs will be targeted towards Node.js v6.0 or greater. So it is recommended to use one of the latest releases of Node.js. The existing version of the framework will be compatible with Node.js 4.0 or greater.

Downloading

You can download the installer for your OS from Node.js downloads page, or should make use of Nvm. Nvm is a command line tool to install and use multiple versions of Node.js on a single machine.

Verifying Installation

Once you are done with the download process, make sure to verify the installed version of Node.js and npm.

node -v
# >= v4.0.0

and for npm

npm -v
# >= 3.0.0

Installing Adonis-CLI

Adonis-CLI is a command line tool to install stable and dev releases of AdonisJs with all required dependencies. It is an npm package and needs to be installed globally.

npm i -g adonis-cli

Run the following command to verify the installation of adonis-cli. Sometimes you may have to open a new terminal tab to get it working.

adonis --help
Output
Commands
------------
Usage: index [options] [command]

  Commands:

    new [options] <name>  Scaffold a new AdonisJs application with the name provided.

  Options:

    -h, --help     output usage information
    -V, --version  output the version number

Creating New Project

Once the adonis-cli has been installed, you can make use of the adonis global from your command line. Let’s use it to create a new project.

adonis new yardstick

Using Yarn

If you are thrilled with yarn and do not want to install your dependencies using npm. Run the following command.

adonis new yardstick --yarn
Output
✔ Your current Node.js & npm version match the AdonisJs requirements!

⠋ Cloning master branch of adonisjs/adonis-app blueprint
    clone: Repository cloned

⠧ Installing dependencies using npm

new command will create a project called yardstick with pre-defined directory structure and will also install all the required dependencies from npm.

If new command fails in the middle, make sure to cd into the newly created project and manually run npm install.

Scaffold Options

You can provide number of options to mimic the scaffold process.

Flag Value Description

--skip-install

Boolean

To skip the dependecies installation from npm or yarn

--branch

String

Adonisjs makes use of master branch when creating a new project. For bleeding edge changes, you can create a project from develop branch.

--blueprint

String

Blueprint is the incremental path to the Github repo. By default AdonisJs makes use of adonisjs/adonis-app.

--yarn

Boolean

Make use of yarn for installing modules

--npm

Boolean

Make use of npm for installing modules

Getting Proxies Error

Older versions of Node.js requires --harmony_proxies flag to add support for ES2015 Proxies. If you are using Node.js < 6.0, make sure to make following changes.

Replace the scripts inside package.json file with following

package.json
"scripts": {
  "serve:dev": "nodemon --watch app --watch bootstrap --watch config --watch .env -x \"node --harmony_proxies\" server.js",
  "serve": "node --harmony_proxies server.js"
}

Replace the first line of the ace file with following .ace

#!/usr/bin/env node --harmony_proxies

Serving The App

You are all set to see your brand new project. Run the below commands to start a development server.

cd yardstick
npm run serve:dev
Output
[nodemon] starting `node server.js`
info adonis:framework serving app on http://localhost:3333

By default, AdonisJs will use port 3333 to start the server, which is configurable via .env file. Now open http://localhost:3333 to see the welcome page.

Welcome page

Manual Installation

If for any reasons you are not using Adonis CLI ( which you should ), you have to perform following steps to clone the repo from GitHub and manually install dependencies.

git clone --dissociate https://github.com/adonisjs/adonis-app yardstick
cd yardstick
Installing dependencies
npm install