Getting started with Adonis v6

Sun Jan 14 2024

adonis-v6

With the launch of Adonis v6 just around the corner, here's a guide to getting up and running the latest version.

Using v5? Check out my getting started guide here

Before we get started, check your system is running a node version higher than 20. To test this, run node -v.

If your system isn't running v20 or higher, install an appropriate version directly from node.js or use a tool like Node Version Manager.

Whilst running through this article, I experienced issues with Adonis v6 on node v20. To fix this, install node v21 or higher

Starter Kits

Adonis v6 ships with starter kits to speed up the setup process of a new project; each starter kit contains different packages out of the box, for this guide we're using the Web starter kit which includes the following packages:

  • @adonisjs/core - The frameworks core
  • @adonisjs/lucid - An SQL ORM maintained by the Adonis team
  • @adonisjs/auth - Authentication package configured to use sessions
  • @adonisjs/shield - Security primitives to keep the web app safe
  • @adonisjs/static - Middleware to serve assets from /public directory
  • edge.js - The edge template engine for composing HTML pages
  • vite - For compiling frontend assets

To install the starter kit, run npm init adonisjs@latest [my-app]

This will install the create-adonis initializer package on your system. Once installed, you'll be prompted to select a starter kit, in which we'll select the Web Starter Kit.

During setup, you will be asked if you'd like to install dependencies and initialize a git repository. Upon the process finished, the CLI will print instructions on how to get the app running.

VS code extension

Before we start writing any code, it's recommended to install and use the Adonis.js extension, as well as the Edge and Japa extensions too. All three are available here:

https://marketplace.visualstudio.com/items?itemName=jripouteau.adonis-extension-pack

Installing TailwindsCSS

To install tailwindCSS with Adonis, run the following commands:

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

Next, open the newly created tailwind.config.js in the root of your app and add the following to the content section:

content: [
    "./index.html",
    "./resources/**/*.edge",
]

Then in your resources/css/app.css, replace the existing code with 

@tailwind base;
@tailwind components;
@tailwind utilities;

Finally, refresh your app and check that the changes taken place.

Creating your first controller

So far, the app is rendering the page located in ./resources/pages/home.edge from the start/routes.ts file. This is perfect file to place endpoints if your app is going to be small, however, if you start adding several endpoints it may be worth adding controllers to separate code by concern.

To create your first controller, run node ace make:controller Posts. This will create a new file in /app/controllers called posts_controller.ts.

Open this file up, in here we'll add the following code inside the PostsController class:

...
  public async index({ view }: HttpContext) {
    return view.render('posts/index')
  }
...

Here, we're telling the endpoint to render the edge file at /resources/posts/index.edge, however, that file currently doesn't exist. So lets get into some views!

Views, Partials, Components and Layouts

As I mentioned in the previous version of this article, I reorganise the resources/views folder and add layout and partials directories here to better organise and reuse code across view files. This is purely optional, but is recommended to ensure a maintainable web project.

Firstly, create a component called main.edge in /resources/views/components/layouts . This will be our main layout that we'll use to render all our apps pages.

main.edge

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title> AdonisJS - A fully featured web framework for Node.js </title>

    @vite(['resources/js/app.js'])
</head>

<body>
    { { { await $slots.main() } } }
</body>

</html>

Next, create the index page mentioned earlier using node ace make:views posts/index and open this file.

In here, we'll set the page up to use the main.edge layout using the following:

@ layouts.main()
<h1>Posts!</h1>
@ end

This will render the Posts! H1 tag inside the <body> tag shown above using the layout as a component.

To learn more information about the edge template engine, check out the docs! https://edgejs.dev/docs/introduction

Adding the posts route

Finally, we'll add the posts route to /start/routes.ts like so

import router from '@adonisjs/core/services/router'

import PostsController from '#controllers/posts_controller'

router.on('/').render('pages/home')
router.get('/posts', [PostsController, 'index'])

If you refresh your app and head to http://localhost:3333/posts, you'll see the newly created page rendered in your browser!

That's a wrap!

Thanks for reading through this getting started guide for Adonis v6! I'll see you next week for more v6 related content 😎

Table of Contents