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. It is quite stable and ready for production use.
However, some AdonisJS v4 packages are not migrated to work with new core and few parts are missing documentation.
Creating a New Project
Node.js >= 14.5.0, along with
npm >= 6.0.0. You can check the version of Node.js and npm by running the following commands.
node -v # v14.5.X npm -v # 6.X.X
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 Projectin the boilerplate prompt.
cdinto the newly created directory.
- And run
node ace serve --watchto start the development server.
Available Project Structures
When creating a new project, you can choose between
- An API server
- Or, a 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
- The sessions module
- Support for static assets is enabled.
- The web security & CSRF protection module
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
config/cors.tsfile enables the support for CORS.
- Content negotiation is forced to JSON inside
Starting the Development Server
You can start the development server by running the following
node ace serve --watch
--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.
package.json, along with
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.
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