Migration guide

In this guide we gonna cover everything you need to know to migrate your AdonisJS v5 application to v6. First, let's introduce the upgrade-kit CLI tool.

Upgrade Kit

The Upgrade Kit is a CLI tool that will help you migrate your AdonisJS v5 application to v6. It is built on using ts-morph so it is able to parse and modify your Typescript files directly. It probably won't be cover all the work needed to migrate your application, but it will take care of the most tedious and boring parts.

The upgrade kit has multiples patches that must be applied in a specific order. After executing a patch, make sure to review the changes, commit them, and then execute the next patch.

Some codemods are difficult to write perfectly, because we have to take into account a lot of different cases of writing code. So, it is possible that some patches will not be able to migrate your code correctly. In this case, you can always fix the code manually, by following the the instructions for each patch just below. Otherwise, feel free to also open an issue on the Upgrade Kit repository and we will try to fix it as soon as possible.

Installation

First you need to install the upgrade kit globally :

npm i -g @adonisjs/upgrade-kit

pnpm i -g @adonisjs/upgrade-kit

yarn global add @adonisjs/upgrade-kit

Usage

To use the upgrade kit, you can run the following command.

npx @adonisjs/upgrade-kit@latest {patchName} --path=/path/to/your/project

pnpm dlx @adonisjs/upgrade-kit@latest {patchName} --path=/path/to/your/project

• {patchName} should be replaced by the name of one of the patches listed below
• --path should be replaced by the path to your project. This is optional, if not provided, the current directory will be used.

Patches

Here is the list of patches. They are ordered by the order in which they should be applied.

Upgrade packages

Patch name : upgrade-packages

Will update official AdonisJS packages to their new version.

See Upgrade packages

Update module system

Patch name : upgrade-module-system

Move from CommonJS to ESM by updating tsconfig.json and package.json.

See Update module system

Update ESLint and Prettier setup

Patch name : upgrade-eslint-prettier

Update ESLint and Prettier setup.

See Update ESLint and Prettier setup

Update Env validations code

Patch name : upgrade-env-config

Move to the new Env API.

See Update Env validations code

Migrate to Node.js sub-path imports

Patch name : upgrade-aliases

Move from the old aliases to Node.js subpaths imports.

See Migrate to Node.js sub-path imports

Migrate to newer AdonisJS imports

Patch name : migrate-ioc-imports

Move from @ioc: imports to standard imports.

See Migrate to newer AdonisJS imports

Fix relative imports to use file extensions

Patch name : fix-relative-imports

Fix relative imports and add .js extensions ( needed for ESM ).

See Fix relative imports to use file extensions

Move to newer file structure for entry point files

Patch name : upgrade-entrypoints

Add new entrypoints needed for Adonis.js v6

See Move to newer file structure for entry point files

Upgrade config files

Patch name : upgrade-config-files

Update config/*.ts files to use their new APIs.

See Upgrade config files

Upgrade command options

Patch name : upgrade-command-options

Update the command options property to use the new API.

See Upgrade command options

Upgrade AdonisRC file (Should be the last patch)

Patch name : upgrade-rcfile

Move from .adonisrc.json to adonisrc.ts.

See Upgrade AdonisRC file

Next steps

After applying all patches, you are ready to make last manual changes.