Quick Start
Welcome to AdonisJS! The guides are designed to help you get up and running with AdonisJS, even if this is your first time using it. Couple of points to note, before we get started.
- The guides only covers the topics which are ready and shipped for the v5 preview release.
- The code examples are in TypeScript, so we expect you to have some familarity with it.
The core of the framework is under the preview release is quite stable and ready for production use. It's just that some of the old AdonisJS packages are not migrated to work with new core.
Creating a New Project
AdonisJS requires Node.js >= 12.0.0
, along with npm >= 6.0.0
. You can check the version of Node.js and npm by running the following commands.
node -v
# v12.14.1
npm -v
# 6.13.7
You can create a new AdonisJS project by using npm init or yarn create.
Both of these tools are meant to install a package and then immediately execute the main command exposed by the installed package. So think of it as a shortcut to install a package globally and then run it as an executable.
- The command will setup a new project structure and installs all required dependencies.
- If you are creating an API server, then do choose
API Project
in the boilerplate prompt. cd
into the newly created directory.- And run
node ace serve --watch
to start the development server.
Available Project Structures
When creating a new project, you can choose between
- An API server
- Or, a Web application
Web Application
A web application project structure is packed with all the required components to create a fully fledged server render application. Along with the framework core, it comes with
- The AdonisJS template engine
@adonisjs/view
- The sessions module
@adonisjs/session
- Support for static assets is enabled.
- The web security & CSRF protection module
@adonisjs/shield
.
API Server
On the other hand, the API server is more tailored towards creating JSON API servers and doesn't include all of the above mentioned packages. Also, the following configuration options are tweaked
- The
config/cors.ts
file enables the support for CORS. - Content negotiation is forced to JSON inside
config/app.ts
file, usingforceContentNegotiationToJSON
flag.
Starting the Development Server
You can start the development server by running the following ace
command.
node ace serve --watch
The serve
command will start the HTTP server and performs in-memory compilition of Typescript to Javascript. The --watch
flag is meant to watch the file system for changes and re-start the server automatically.
Compiling For Production
AdonisJS uses the concept of standalone builds. It means, you can deploy the compiled output without moving the source files to the production server. The standalone builds are really helpful in creating slim docker images.
Run the following command to create a production build.
node ace build --production
The above command performs the following steps in sequence.
- Compile TypeScript source files to Javascript.
- Copy
metaFiles
mentioned inside.adonisrc.json
to thebuild
folder. - Copy
package.json
, along withpackage-lock.json
oryarn.lock
inside thebuild
folder.
At this stage, you can upload the build
folder to your production server, install the dependencies and run node server.js
to start the server.
CLI Help
You can view the help for all the available commands by running the following ace command.
node ace --help
The help for an individual command can be seen as follows:
node ace make:controller --help