Instalação

Antes de criar um novo aplicativo, você deve garantir que tenha o Node.js e o npm instalados no seu computador. O AdonisJS precisa de Node.js >= 20.6.

Você pode instalar o Node.js usando os instaladores oficiais ou Volta. O Volta é um gerenciador de pacotes multiplataforma que instala e executa várias versões do Node.js no seu computador.

# Verifique a versão do Node.js
node -v
# v22.0.0

DICA

Você é mais um aprendiz visual? - Confira a série de screencasts gratuitos Vamos aprender AdonisJS 6 dos nossos amigos da Adocasts.

Criando um novo aplicativo

Você pode criar um novo projeto usando npm init. Esses comandos baixarão o pacote inicializador create-adonisjs e iniciarão o processo de instalação.

Você pode personalizar a saída inicial do projeto usando um dos seguintes sinalizadores CLI.

• starter kit para o projeto. Você pode escolher entre web, api, slim ou inertia.

• --db: Especifique o dialeto de banco de dados de sua escolha. Você pode escolher entre sqlite, postgres, mysql ou mssql.

• --git-init: Inicia o repositório git. O padrão é false.

• --auth-guard: Especifique o guarda de autenticação de sua escolha. Você pode escolher entre session, access_tokens ou basic_auth.

npm

npm init adonisjs@latest hello-world

Ao passar sinalizadores CLI usando o comando npm init, certifique-se de usar traços duplos duas vezes. Caso contrário, npm init não passará os sinalizadores para o pacote inicializador create-adonisjs. Por exemplo:

# Crie um projeto e seja solicitado para todas as opções
npm init adonisjs@latest hello-world

# Crie um projeto com MySQL
npm init adonisjs@latest hello-world -- --db=mysql

# Crie um projeto com PostgreSQL e API starter kit
npm init adonisjs@latest hello-world -- --db=postgres --kit=api

# Crie um projeto com API starter kit e access tokens guard
npm init adonisjs@latest hello-world -- --kit=api --auth-guard=access_tokens

Kits iniciais

Os kits iniciais servem como um ponto de partida para criar aplicativos usando AdonisJS. Eles vêm com uma estrutura de pastas opinativa, pacotes AdonisJS pré-configurados e as ferramentas necessárias durante o desenvolvimento.

NOTA

Os kits iniciais oficiais usam módulos ES e TypeScript. Essa combinação permite que você use construções JavaScript modernas e aproveite a segurança do tipo estático.

Kit inicial da Web

O kit inicial da Web é personalizado para criar aplicativos da Web de renderização de servidor tradicionais. Não deixe que a palavra-chave "tradicional" o desencoraje. Recomendamos este kit inicial se você criar um aplicativo da Web com interatividade limitada no frontend.

A simplicidade de renderizar HTML no servidor usando Edge.js aumentará sua produtividade, pois você não precisará lidar com sistemas de construção complexos para renderizar algum HTML.

Mais tarde, você pode usar Hotwire, HTMX ou Unpoly para fazer seus aplicativos navegarem como um SPA e usar Alpine.js para criar widgets interativos como um menu suspenso ou um modal.

npm init adonisjs@latest -- -K=web

# Trocar dialeto do banco de dados
npm init adonisjs@latest -- -K=web --db=mysql

O kit inicial da Web vem com os seguintes pacotes.

Pacote	Descrição
@adonisjs/core	O núcleo do framework tem os recursos básicos que você pode usar ao criar aplicativos de backend.
edge.js	O mecanismo de modelo edge para compor páginas HTML.
@vinejs/vine	VineJS é uma das bibliotecas de validação mais rápidas no Node.js ecossistema.
@adonisjs/lucid	Lucid é um ORM SQL mantido pela equipe principal do AdonisJS.
@adonisjs/auth	A camada de autenticação do framework. Ele é configurado para usar sessões.
@adonisjs/shield	Um conjunto de primitivas de segurança para manter seus aplicativos da web protegidos contra ataques como CSRF e XSS.
@adonisjs/static	Middleware para servir ativos estáticos do diretório /public do seu aplicativo.
vite	Vite é usado para compilar os ativos do frontend.

---

Kit inicial da API

O kit inicial da API é personalizado para criar servidores JSON API. É uma versão reduzida do kit inicial web. Se você planeja construir seu aplicativo frontend usando React ou Vue, você pode criar seu backend AdonisJS usando o kit inicial da API.

npm init adonisjs@latest -- -K=api

# Trocar dialeto do banco de dados
npm init adonisjs@latest -- -K=api --db=mysql

Neste kit inicial:

• Removemos o suporte para servir arquivos estáticos.
• Não configure a camada de visualizações e vite.
• Desative a proteção XSS e CSRF e ative a proteção CORS.
• Use o middleware ContentNegotiation para enviar respostas HTTP em JSON.

O kit inicial da API é configurado com autenticação baseada em sessão. No entanto, se você deseja usar autenticação baseada em tokens, você pode usar o sinalizador --auth-guard.

Veja também: Qual proteção de autenticação devo usar?

npm init adonisjs@latest -- -K=api --auth-guard=access_tokens

---

Kit inicial Slim

Para minimalistas, criamos um kit inicial slim. Ele vem apenas com o núcleo do framework e a estrutura de pastas padrão. Você pode usá-lo quando não quiser nenhum enfeite do AdonisJS.

npm init adonisjs@latest -- -K=slim

# Trocar dialeto do banco de dados
npm init adonisjs@latest -- -K=slim --db=mysql

---

Kit inicial Inertia

Inertia é uma maneira de construir aplicativos de página única orientados a servidor. Você pode usar seu framework de frontend favorito ( React, Vue, Solid, Svelte ) para construir o frontend do seu aplicativo.

Você pode usar o sinalizador --adapter para escolher o framework de frontend que deseja usar. As opções disponíveis são react, vue, solid e svelte.

Você também pode usar os sinalizadores --ssr e --no-ssr para ativar ou desativar a renderização do lado do servidor.

# React com renderização do lado do servidor
npm init adonisjs@latest -- -K=inertia --adapter=react --ssr

# Vue sem renderização do lado do servidor
npm init adonisjs@latest -- -K=inertia --adapter=vue --no-ssr

---

Traga seu kit inicial

Os kits iniciais são projetos pré-criados hospedados em um provedor de repositório Git como GitHub, Bitbucket ou Gitlab. Você também pode criar seus kits iniciais e baixá-los da seguinte forma.

npm init adonisjs@latest -- -K="github_user/repo"

# Baixar do GitLab
npm init adonisjs@latest -- -K="gitlab:user/repo"

# Baixar do BitBucket
npm init adonisjs@latest -- -K="bitbucket:user/repo"

Você pode baixar repositórios privados usando autenticação Git+SSH usando o modo git.

npm init adonisjs@latest -- -K="user/repo" --mode=git

Finalmente, você pode especificar uma tag, branch ou commit.

# Branch
npm init adonisjs@latest -- -K="user/repo#develop"

# Tag
npm init adonisjs@latest -- -K="user/repo#v2.1.0"

Iniciando o servidor de desenvolvimento

Depois de criar um aplicativo AdonisJS, você pode iniciar o servidor de desenvolvimento executando o comando node ace serve.

Ace é uma estrutura de linha de comando empacotada dentro do núcleo da estrutura. O sinalizador --hmr monitora o sistema de arquivos e executa substituição de módulo a quente (HMR) para certas seções da sua base de código.

node ace serve --hmr

Depois que o servidor de desenvolvimento for executado, você pode visitar http://localhost:3333 para visualizar seu aplicativo em um navegador.

Construindo para produção

Como os aplicativos AdonisJS são escritos em TypeScript, eles devem ser compilados em JavaScript antes de serem executados em produção.

Você pode criar a saída JavaScript usando o comando node ace build. A saída JavaScript é gravada no diretório build.

Quando o Vite é configurado, este comando também compila os ativos frontend usando o Vite e grava a saída na pasta build/public.

Veja também: Processo de compilação do TypeScript.

node ace build

Configurando o ambiente de desenvolvimento

Embora o AdonisJS cuide da construção dos aplicativos do usuário final, você pode precisar de ferramentas adicionais para aproveitar o processo de desenvolvimento e ter consistência em seu estilo de codificação.

Recomendamos fortemente que você use ESLint para lintar seu código e use Prettier para reformatar seu código para consistência.

Os kits iniciais oficiais vêm pré-configurados com ESLint e Prettier e usam as predefinições opinativas da equipe principal do AdonisJS. Você pode aprender mais sobre eles na seção Configuração de ferramentas dos documentos.

Por fim, recomendamos que você instale os plugins ESLint e Prettier para seu editor de código para que você tenha um loop de feedback mais apertado durante o desenvolvimento do aplicativo. Além disso, você pode usar os seguintes comandos para lint e format seu código a partir da linha de comando.

# Executa ESLint
npm run lint

# Executa ESLint e corrige problemas automaticamente
npm run lint -- --fix

# Executa mais bonito
npm run format

Extensões VSCode

Você pode desenvolver um aplicativo AdonisJS em qualquer editor de código que suporte TypeScript. No entanto, desenvolvemos várias extensões para VSCode para aprimorar ainda mais a experiência de desenvolvimento.

• AdonisJS - Visualize rotas de aplicativos, execute comandos ace, migre o banco de dados e leia a documentação diretamente do seu editor de código.
• Edge - Turbine seu fluxo de trabalho de desenvolvimento com suporte para realce de sintaxe, preenchimento automático e snippets de código.
• Japa - Execute testes sem sair do seu editor de código usando atalhos de teclado ou execute-os diretamente da barra lateral de atividades.