What to Expect of AdonisJS 6?

[RomainLanz]

If you have been following us on Twitter, you might have seen us talking about AdonisJS v6 - “A new major version of the AdonisJS framework”. We’ve spent four years in the AdonisJS v5 era, and it’s time to move to the AdonisJS v6 era with some fresh ideas.

But don’t worry. Migrating your apps to AdonisJS v6 will be easy. It might take a few hours or a couple of days, depending on the size of your application. We will also provide a command line tool to help move your code to the new version.

AdonisJS is a modular framework with a feature-rich core (i.e., the @adonisjs/core package) and a collection of officially maintained packages. Each package follows its own release cycle and semver versioning. We are significantly updating the framework core in this release (i.e., AdonisJS v6).

The main goal of this update is to work more closely with the platform. We want to use new features of JavaScript and Node.js, ensure your apps have better type safety, and keep improving the framework performance.

Updating minimum requirements

Because we’re using new features from Node.js, your system needs to have at least Node.js version 18 or higher. This version is the current Long-Term Support release.

Note You can easily manage and upgrade your Node.js version with tools like Volta.

Switching to ECMAScript Modules (ESM)

The most significant change in this update is that we’re moving to ECMAScript modules (ESM). Right now, AdonisJS uses and compiles to CommonJS (CJS) format. Moving to ESM lets us use new language features and stay updated with the ecosystem.

What does this mean for your app?

Your apps will be able to use the new platform features that work in ESM, like the Top-Level-Await statement and Node.js subpath imports.

The good part is ESM applications can load and use CommonJS packages. But not the other way around. Therefore moving to ESM is a must.

New asset bundler

Many of you have asked for this, so we’re excited to announce that AdonisJS 6 will include Vite as the default asset bundler.

Note: We will continue to maintain the Webpack Encore as well. Therefore, if you are not ready to move to Vite, you can use Webpack Encore.

Better documentation

There are some lapses in the current documentation of AdonisJS. For example, topics like IoC Container, Service providers, and Package development are undocumented. Also, the docs should be more comprehensive.

With AdonisJS v6, we have spent significant time covering all the framework aspects within the documentation. Here's a sneak-peak of some newly added topics.

• The fundamentals section covers the usage of IoC Container, service providers, and package development in-depth.
• Ace documentation is rewritten from scratch covering everything you need to know when creating custom ace commands.
• The testing section includes documentation for browser testing (via Playwright) and command-line testing.

An important thing to note is that the documentation is a reference guide explaining how the framework works and the available APIs. We imagine the framework users reference documentation when they want complete information about a topic.

The documentation will not teach you how to build an app from scratch. For that, we plan to write step-by-step tutorials that teach you how to build a specific app using the framework.

In the meanwhile, let us introduce you to Adocasts and AdonisJS Mastery if you want tutorial-based learning content. Both of these platforms have been creating content on AdonisJS for years.

Changes to the import module names

As of today (i.e., AdonisJS v5), you will witness many imports prefixed with the @ioc keyword. For example, The router is imported from the @ioc:Adonis/Core/Route module and the Event emitter is imported from the @ioc:Adonis/Core/Event module.

The @ioc keyword is a convention we follow to communicate that this import will be resolved from the IoC Container of AdonisJS. When you compile your code from TypeScript to JavaScript, we use a TypeScript transformer to convert this import into an IoC Container lookup method call.

For instance, if you were importing the Route module like this.

import Route from '@ioc:Adonis/Core/Route

The compiled output will roughly look as follows.

const Route_1 = global[Symbol.for('ioc.use')]("Adonis/Core/Route")

Taking this approach has some downsides.

1. You must always compile your code using the TypeScript official compiler because the transformer was written for tsc only.
2. The import syntax is unfamiliar to a JavaScript developer's eye.
3. Developers had to write module definitions separately from the implementation.
4. Users cannot CTRL-click the import to see the implementation.

Starting with v6, we will remove @ioc keyword imports with regular ESM imports and still be able to look up dependencies inside the AdonisJS dependency container.

Here's what the router import looks like in both v5 and v6. In v6, if you CTRL+click on the router value, you will see a standard JavaScript module resolving the singleton router instance from the IoC Container and exporting it as a variable.

# In v5
import Route from '@ioc:Adonis/Core/Route'

# In v6
import router from '@adonisjs/core/services/router'

To conclude, in v6, there are no compiler magic converting imports to IoC Container lookup method calls. Everything is straightforward and easy to reason about.

You can learn more about the AdonisJS IoC Container used in v6 from the following links.

• IoC Container package README file.
• An article covering Why you need an IoC container?
• Live stream We did showcase the AdonisJS IoC Container outside of an AdonisJS app.

New Encryption module

AdonisJS encryption module currently encrypts data using a single static algorithm, i.e., aes-256-cbc. We have received a few requests to support additional algorithms in the form of drivers.

AdonisJS v6 will allow you to register custom encryption drivers, and we will bundle drivers for the following encryption algorithms.

• aes-256-cbc
• aes-256-gcm
• chacha20-poly1305

Changes to file system naming conventions

Moving forward, the AdonisJS official starter kits will use the snake_case format for naming files and folders. Currently (in v5), we use lowercase names for root-level directories and PascaleCase for sub-directories.

In the JavaScript ecosystem, there is no general agreement on naming conventions. Some sub-communities use PascalCase for files that export a class and snake_case or dash-case for files that export functions or objects.

We decided to take a simple approach and consistently name all files and folders without relying on what is exported from the file. The snake_case format is inspired from Dart, and Google TypeScript style guide.

To learn more about this decision, check out the article “List of rules and conventions I follow when writing code” by Aman Virk.

Flexible stub system

The scaffolding ace commands under the make namespace are used to create files with the initial boilerplate quickly. For example, You can use the make:controller command to create a controller, the make:model command to create a model, and so on.

Until now, the templates used by these commands were within the package's source code, and there was no way to customize them.

Moving forward (with V6), you can eject the scaffolding templates (stubs) to your application codebase and modify them per your requirements. Next time, when you run the make commands, AdonisJS will use the ejected template.

Here's what the controller template looks like.

{{#var controllerName = generators.controllerName(entity.name)}}
{{#var controllerFileName = generators.controllerFileName(entity.name)}}
---
to: {{ app.httpControllersPath(entity.path, controllerFileName) }}
---
// import { HttpContext } from '@adonisjs/core/http'

export default class {{ controllerName }} {
}

• We use the generators object to define variables in the first two lines.
• From lines 3-5, we use the YAML front matter to define the destination path of the file we are about to create. This will allow you to create controllers and models in any directory of your choice.
• And finally, we define the initial content of the controller.

New Validation Library

The current validation module of AdonisJS has served us well, but it desperately needs some improvements. Right now:

• It lacks a union data type. There is no way to validate a field as a string or a number.
• The API to create custom rules is rough. We have witnessed many individuals struggling to create custom rules.
• The state of the package codebase was not great. It made it harder for us to make big changes confidently. A significant rewrite was needed.

Finally, we developed a framework agnostic validation library called VineJS. VineJS will be the official validation system for AdonisJS v6.

VineJS is much faster than the version used in V5, and it's also more comprehensive. It makes it easy to create custom rules, schema types and validate complex schemas.

You can learn more about VineJS in our introduction live stream. https://www.youtube.com/watch?v=YdBt0s8NA4I

Note
You can continue to use the existing validation module in your v6 projects. There is no need to migrate immediately to VineJS.

In fact, you can use VineJS and the existing validation module together in an AdonisJS application. This will allow you to migrate one validator at a time.

Other Changes

Numerous other changes have been made for the release of AdonisJS 6, both in the core and in some modules.

Following are some highlights:

• The VSCode extension has been completely revamped to work with AdonisJS 5 and AdonisJS 6. It introduces new features, such as Inertia support, component-as-tag support in Edge, and auto-fixable issues.
• The new core will also use the latest version of pino, the logging package. This allows you to make the most of worker threads to enhance performance.
• The new router will allow you to import controllers and bind them directly to a route. The string-based controller reference is still there but not recommended. Importing and binding controllers directly provides better type-safety and refactoring capabilities.
• The new event emitter lets you declare events with classes for better type-safety and refactoring capabilities.
• The new mail module will include drivers for sendingblue and resend.

All these updates are designed to help you write better, more efficient, and safer code with AdonisJS v6.

The present and the future

We have completed all the changes in the framework core and are ready to migrate official packages to work with AdonisJS v6.

We will not introduce any breaking changes in our official packages. The goal is to keep the breaking changes' surface area as small as possible and help you quickly migrate your apps to v6.

Conclusion

To conclude, the goal of AdonisJS v6 is to remove magic and stay up to date with the language and the platform changes.

We want to make AdonisJS a more robust, efficient, and developer-friendly framework. Trust us; we are so happy with v6 internally and super pumped to release it. Let me share screenshots of an internal conversation we had.

Finally, we thank everyone for using AdonisJS and for sharing their feedback. Having the motivation and energy to work on the framework comes directly from all of you.

--

Your core team

[quangthienit1994]

Please supports GraphQL, NoSQL, and Serverless for the API. Currently, I can't set up the Adonis with Serverless.

[ndianabasi]

I don't use neither of them for any work, so I might not be the best person to spear-head. However, I think what is needed is to write an adapter for each NoSQL engine we want to support

[Julien-R44]

if by "serverless" you mean lambdas, then i believe that would be a mistake. Running an Adonis application in a lambda seems to me to be a very bad idea. You're going to get some sick cold-starts

these are totally different philosophies. lambdas are generally functions that do one thing. sometimes more ( see the Lambdalith / Monolambda patterns ). But even in the second case, the idea is not to host an entire API in a single lambda function.

Otherwise, @RomainLanz already shared some insights on what you need is a PaaS and not FaaS

[nazarii-kretovych]

serverless is evil. Don't use it

[lenikhilsingh]

I use mongodb in one of my adonisjs projects. I've created a mongoose provider which is really simple to begin with, actually.

[charlie-s]

@nazarii-kretovych I have found my people.

I’d love to get more involved with Adonis for v6.

[Barbapapazes]

Absolutely amazing! Can't wait to read new documentation and give a try to the v6

[bencagri]

maybe, annotations could be considered.

[dimitrisnl]

Do you mean decorators? I really hope not. Nest.js does it and you can have 7-8 decorators in each controller, resolving in the reverse reading order. Madness.

[thetutlage]

Ohh yeah. Not a big fan of decorators at all. They are good for some stuff here and there, but building the entire framework on decorators is not my taste.

[mr-feek]

Nest's use of decorators is one of the primary reasons I chose adonis!

[dimitrisnl]

Great stuff! Amazing work.

My only reservation is using snake_case. I understand Ruby & Python doing it but not Javascript. I would go for either cameCase just like the writing convention of JS is, or its sibling dash-case.

[grantholle]

He references the Google TS style guide.

Module namespace imports are lowerCamelCase while files are snake_case...

I think airbnb has an interesting convention of matching the name with the default export. Google says not to use default exports, though. /shrug

[thetutlage]

@dimitrisnl Just give it a run, you will love it. Also, If we were not clear, the snake_case is in the file naming convention, not the source code.

Using camelCase in directory structure is prone to case sensitivity. For example: If you develop on mac, then your file system is not case sensitive by default. However, Linux is case sensitive. So your imports can break if they mis-type a camelCase file import.

[dimitrisnl]

@thetutlage Yeah, I'm sure it will be an upgrade 💪🏻 - I agree that case sensitivity can be a problem, no strong opinion though, I like the change eitherway

[Julien-R44]

i have to admit that i wasn't a fan of the change in the first place too. but I couldn't give any arguments why. except that I found the camelCase more aesthetically pleasing. and yeah in JS world, we're not used to seeing snake_case, so it can be disturbing at first

Then I tried it. now I just do everything in snake_case. Even migrated codebases to snake_case. cool not to have to worry about how naming a file anymore

[mattkenefick]

Google says not to use default exports, though

Google makes a good number of questionable decisions though. I wouldn't personally look at their standards as a bible.

[ms-mousa]

Very exciting stuff. I'm pretty lucky to start using Adonis at the cusp of new release. 🎉

I also saw @thetutlage playing around with some TSX support on twitter. Is that something that would be included or supported in any official capacity?

[thetutlage]

Most probably yes, but we have not started any real work on it, except playing with the idea

[bitkidd]

Great news! So many new things, is there any ETA available?

[thetutlage]

Unfortunately not 😐

[IARI]

Understandable!
Any super-rough estimate though? Are we talking days, weeks, months?
Or is there a way to track 'what's left to do' if I'm excited about it?

[bitkidd]

I think the core team is not ready to give any ETA just to feel a little bit more free in terms of pressure. So, obviously, it is way better to take more time to make a better product than to release it and have fun giving answers to lots of unnecessary questions.

[mattstrayer]

Core team has been doing a wonderful job pushing out consistent a great quality work over the past couple months. It seems like the velocity is increasing too, over the past month. If you join the discord you can see the #releases channel get lit up pretty regularly with new features.

I'm as excited as the rest of y'all, but I trust they'll push out a great update when it is ready.

[thetutlage]

As @bitkidd said, we avoid giving any dates, because it creates unnecessary pressure. The best I can say is, we are working almost everyday to release v6.

[francelwebdev]

Add support for documenting rest api. currently package are bad.

[iyashpal]

Great News. AdonisJS is great just like Laravel. In this release I am more excited about vite. And I would love to know the release date. Also, is there a way to install the pre-released V6?

[Melchyore]

Can't wait to test this new version and create new modules! I'm pretty sure the experience will be quite exciting! 😍😍

[renzosunico]

Excited for Adonisjsv6! 🥳😍 It was mentioned that validator will be receiving a major revamp and I'm just curious if validation reporting will be going to be a focus as well? I do remember struggling in creating custom reporter for my validator and ended up with just a flat list of validation errors. (I wanted it to be structured the same as the input.)

[thetutlage]

Can you start a new discussion explaining the exact issue you have? I think, even with current error reporting system you should be able to format error messages as you want

[SirMishaa]

Imo, the validator of Symfony works really well and is one of the best i've seen.
It can also be used for form or api.

It could be a good model for inspiration.

use Symfony\Component\Validator\Constraints as Assert;

class ProductReviewDto
{
    public function __construct(
        #[Assert\NotBlank]
        #[Assert\Length(min: 10, max: 500)]
        public readonly string $comment,

        #[Assert\GreaterThanOrEqual(1)]
        #[Assert\LessThanOrEqual(5)]
        public readonly int $rating,
    ) {
    }
}

use Symfony\Component\HttpKernel\Attribute\MapRequestPayload;

class ProductApiController
{
    public function __invoke(
        #[MapRequestPayload] ProductReviewDto $productReview,
    ): Response {

        // here, $productReview is a fully typed representation of the request data

    }
}

The controller may not be called if the validation fail.

• Validation Errors: will produce an HTTP 422 error response with a violation list object
• Malformed Data: will produce an HTTP 400 Bad Request error response.
• Unsupported Deserialization Formats: will produce an HTTP 415 error response.

[wizdomjeffreysimbulan]

I have a webapp that is running adonisjs4.1 is there a way to migrate to v5 or v6?
if none, why is there nothing? is it just a complete abandon of v4.1?

[RomainLanz]

The best way would be to start a new project and copy your code part by part.

[avenikolay]

I would like to see the official Adonis documentation website be multilingual. I am willing to translate the documentation into Russian myself.

[RomainLanz]

Feel free to use tools like DeepL or Google Translate if you have a hard time understanding something.

Managing a multilingual website is a hard task. Especially when the content is updated regularly.

[thetutlage]

Managing multiple documentation website is a very time consuming task, given the person who created the original translations might not be available.

We will have to create dedicated workflows to ensure that each PR to docs also goes through the volunteers, who might or might not be available few years down the line.

So, this is something we do not want to spend our time on. However, our documentation is under MIT and you can fork the repo, translate docs and publish it yourself on your domain.

[ndianabasi]

I like how realistic we are and not promising things just to please users.

If @avenikolay will commit to maintain the Russian version after the initial translation, then I think we can give it a try after V6 is release.

[McSneaky]

What if there's some domain for community packages? Like russian.adonis-community-docs.com, spanish.adonis-community-docs.com etc. Better name, but something like that

Ofc it can be there only when there's enuf actual community contributors. Would need several people initially for each language

[dimitrisnl]

The implementation is not the problem. English isn't my native language, but I'll read an English doc 100% of the time. The most important concepts are always in English either way, so what are we translating exactly?

[guoyunhe]

Will v6 have built-in integration with ElasticSearch or OpenSearch?

[Julien-R44]

not super familiar with elasticsearch. but I wonder what an integration package with Adonis could do more than the Elasticsearch client ?

[guoyunhe]

@Julien-R44 Something like this:

class Post extends BaseModel {
  // what properties to save in ElasticSearch / OpenSearch
  toSearch() {
    const { id, title, content } = this;
    return { id, title, content };
  }
}

// When you save a model, ElasticSearch / OpenSearch is auto updated
const post = await Post.find(1);
post.title = 'hello world';
post.save();

// You can search post from the model
// It will return models instead of ElasticSearch / OpenSearch documents
Post.search().match({ title: 'hello' });

[ndianabasi]

This definitely requires an adapter. Would you like to start something even with v5 as it can easily be migrated to v6?

[Julien-R44]

okay, that makes sense, thanks @guoyunhe
yeah, I believe it should be a community package

and as a side note, i would also recommend taking a look at pg_trgm as an "alternative" to Elasticsearch. for simple use-cases, it will work just fine and is more than enough

[guoyunhe]

@Julien-R44 the problem with MySQL/Postgres' full text index etc. is that they don't support Chinese/Japanese languages (these languages don't use white spaces to break words).

[eidellev]

This is very exciting. I'm especially happy about ESM support and the switch to vite. When can we expect v6 to become available?
(Apologies if it's been answered elsewhere)

[Barbapapazes]

They doesn't wznt to give an ETA. So v6 will arrive soon bit we have to stay patient!

[eidellev]

It's a shame. As a package maintainer I'd like to be ready for the new release.

[thetutlage]

@eidellev We will notify you well in advance. Also, planning to write a guide for package maintainers

[eidellev]

Thanks @thetutlage
Looking forward to it

[Fidel-C]

Adonis JS v6 seems to be great. Is there any plan to make Adonisjs compatible with Adminjs for integrating quick admin panels? Or are there alternative packages for the same purpose?

[guoyunhe]

It doesn't sound right to make a general purpose framework compatible with a customized tool. You can make a package to integrate that, though.

[Fidel-C]

All major NodeJs frameworks have Adminjs adapters. And since this is a discussion on the features of Adonis6, it's not out of place to make the suggestion. And so did I. Besides, it's easier to find use cases for admin panels than not. Something like that would give Adonis6 a major boost.

[Julien-R44]

we already have a community package for that

[thetutlage]

If I look at their docs, most of the integrations are created by the AdminsJS team and the community plugins section has AdonisJS as well. So, those adapters are not created by framework creators.

[dangnhdev]

The only thing preventing me from using Adonis is the lack of support for the Edge template engine in WebStorm.

[RomainLanz]

Feel free to upvote the feature request in WebStorm tracker: https://youtrack.jetbrains.com/issue/WEB-41625/AdonisJS-.edge-template-engine-support

For the moment, you can have partial support by adding the TextMate syntax file directly.
➡️ https://adocasts.com/lessons/how-to-add-adonisjs-edge-support-to-your-webstorm-environment

[toksdotdev]

If possible, less opinionated folder structure (similar to the concept of apps in Django and modules in NestJS). I've used Adonis for a handful for production apps where the codebase ended up growing significantly in size, which made it harder to find related files and further increased context switching. With a modular system, domains can be separated, maintenance is improved, and multiple teams can work independently. When there are only a few people, it's easy to manage the codebase, but it becomes harder with the introduction of teams.

We can add a template creation feature for this structure through the CLI to avoid major changes (doesn't have to support everything). Then gradually adjust things internally to fully support a full-fledged modular system, while still keeping the existing structure as the default. Using a modular alternative could be beneficial for big projects with many teams, potentially increasing Adonis popularity. All the existing concepts like providers, IOC etc will still remain the same, but just that they can exist within a module.

[RomainLanz]

You are (and have always been) free to choose your preferred folder structure.

[tavaresgerson]

Maybe big codebase is subjective, but my team is working in project with 99 tables and integrate with 5 webservices without problem in deadline on sprint. 🤔

[hscstudio]

It would be great, if AdonisJS in the future has features for integration with Swagger, as is done in large frameworks.

generate routing & swagger docs just by defining them in the controller. similar to what NestJs does

[mattstrayer]

@Melchyore is working on this, but could use some help from a funding perspective. Any bit of financial support you can provide him will expedite the release. 🙏

[ramabie]

hopefully in the latest version there will be some kind of livewire in adonisjs.

and there is also a change in pagination, because I have difficulty using pagination when there are a large number of records.

[RomainLanz]

What kind of difficulty did you have with pagination?

[ramabie]

this is what happened when I followed the adonisjs documentation on pagination

[ramabie]

up

[GabrielNBDS]

It's up to you to handle it. I made a util for handling it here.

[ezequidias]

I'd love to see integration with the oauth2 protocol like laravel passport!

[RomainLanz]

You mean be able to build an OAuth server?

[ezequidias]

Yes, exactly!

[ezequidias]

WhereRelation in ORM?

whereHas

await User.query().whereHas('posts', (postsQuery) => {
  postsQuery.where('status', 'published')
})

whereRelation

await User.query().whereRelation('posts', 'status', 'published')
or
await User.query().whereRelation('posts', 'number', '>=', 50)

• WhereRelation

• orWhereRelation

I missed Polymorphic Relationships in the orm
morphOne or morphMany

[hiteshmungpara]

SurrealDB support?

[timyourivh]

Would love to see this too, but I think we'd have to look at knex instead and create a Dialect for it.

There is already an issue related to this here:
https://github.com/knex/documentation/issues/471
and here:
knex/knex#5532

[timyourivh]

Would love to see something similar to Laravel Sail in the future! To make developing with Docker easier, opinionated and stable.

[RomainLanz]

You mean this https://github.com/Julien-R44/adonis-sail ?

[timyourivh]

YES! I was unaware of it's existence, sorry.

It wouldn't come my mind that it would be called sail too! The only mentions of Docker are on this page which doesn't mention adonis-sail. So I will change my suggestion to an improvement in the documentation on this very subject! 😄 (and possible improvement in the package to make it more like sail)

Thanks for letting me know!

[dimitrisnl]

So pumped for the release ✊🏻

[DZ8540]

Model column typing in model query builder.

Example:

SomeModel
  .query()
  .where('typedColumn', someValue) // Here is typed column

And more other methods with columns.

[DZ8540]

In general more typing with columns

[KelvinSan]

With the upgrade to a better version of pino, will you be able to use new transports for logging to external services ?

[AimForNaN]

I just came across adonisjs. I noticed once upon a time websockets were supported. I can't find anything about websockets in the v5 docs about their support. Will v6 include support for websockets?

[httzipdev]

I love AdonisJS <3

[costearnaud]

Hi everyone / Salut tout le monde

I just saw yesterday (24/01/24) the very last v6.2.1 version of Adonis BUT no way to install and configure properly @eidellev/inertia-adonisjs which was working perfectly with Adonis v5.9
Any news regarding this blocking issue (for my project)?
=> node ace configure @eidellev/inertia-adonisjs do not work anymore with the August 23 version (8.1)

Par avance merci @RomainLanz and others !
Arnaud

[ramabie]

I just found out there is something like this, has anyone tried this? and have you been successful or not?

https://socket.dev/npm/package/adonisjs-livewire

npm install adonisjs-livewire