インストール
新しいアプリケーションを作成する前に、コンピュータにNode.jsとnpmがインストールされていることを確認してください。AdonisJSはNode.js >= 20.6が必要です。
Node.jsは公式のインストーラーまたはVoltaを使用してインストールできます。Voltaはクロスプラットフォームのパッケージマネージャーであり、コンピュータに複数のNode.jsバージョンをインストールして実行できます。
node -v
# v22.0.0
視覚的な学習が好きですか？ - Adocastsの友達たちが提供するLet's Learn AdonisJS 6無料のスクリーンキャストシリーズをチェックしてみてください。
新しいアプリケーションの作成
npm initを使用して新しいプロジェクトを作成できます。これらのコマンドはcreate-adonisjsイニシャライザーパッケージをダウンロードし、インストールプロセスを開始します。
次のCLIフラグのいずれかを使用して、初期プロジェクトの出力をカスタマイズできます。
-
--kit: プロジェクトのスターターキットを選択します。web、api、slim、またはinertiaのいずれかを選択できます。 -
--db: 使用するデータベースの方言を指定します。sqlite、postgres、mysql、またはmssqlのいずれかを選択できます。 -
--git-init: Gitリポジトリを初期化します。デフォルトはfalseです。 -
--auth-guard: 使用する認証ガードを指定します。session、access_tokens、またはbasic_authのいずれかを選択できます。
npm init adonisjs@latest hello-world
npm initコマンドを使用してCLIフラグを渡す場合は、二重ダッシュを2回使用する必要があります。そうしないと、npm initはフラグをcreate-adonisjsイニシャライザーパッケージに渡さないため、正しく動作しません。
例:
# プロジェクトを作成し、すべてのオプションについてプロンプトを表示する
npm init adonisjs@latest hello-world
# MYSQLでプロジェクトを作成する
npm init adonisjs@latest hello-world -- --db=mysql
# PostgreSQLとAPIスターターキットでプロジェクトを作成する
npm init adonisjs@latest hello-world -- --db=postgres --kit=api
# APIスターターキットとアクセストークンガードでプロジェクトを作成する
npm init adonisjs@latest hello-world -- --kit=api --auth-guard=access_tokens
スターターキット
スターターキットはAdonisJSを使用してアプリケーションを作成するための出発点となります。これらには、意見のあるフォルダ構造、事前に設定されたAdonisJSパッケージ、および開発中に必要なツールが含まれています。
公式のスターターキットはESモジュールとTypeScriptを使用しています。この組み合わせにより、モダンなJavaScriptの構造を使用し、静的型の安全性を活用できます。
Webスターターキット
Webスターターキットは、従来のサーバーレンダラーウェブアプリケーションを作成するためにカスタマイズされています。キーワード**"traditional"**に惑わされないでください。限られたフロントエンドの相互作用を持つWebアプリを作成する場合は、このスターターキットをオススメします。
Edge.jsを使用してサーバー上でHTMLをレンダリングするシンプルさは、いくつかのHTMLをレンダリングするための複雑なビルドシステムに対処する必要がないため、生産性を向上させます。
後で、Hotwire、HTMX、またはUnpolyを使用してアプリケーションをSPAのようにナビゲートし、Alpine.jsを使用してドロップダウンやモーダルなどのインタラクティブなウィジェットを作成できます。
npm init adonisjs@latest -- -K=web
# データベースの方言を切り替える
npm init adonisjs@latest -- -K=web --db=mysql
Webスターターキットには、次のパッケージが含まれています。
| パッケージ | 説明 |
|---|---|
@adonisjs/core |
バックエンドアプリケーションを作成する際に必要な基本機能を提供するフレームワークのコアです。 |
edge.js |
HTMLページを構成するためのedgeテンプレートエンジンです。 |
@vinejs/vine |
VineJSは、Node.jsエコシステムで最も高速なバリデーションライブラリの1つです。 |
@adonisjs/lucid |
Lucidは、AdonisJSコアチームによってメンテナンスされているSQL ORMです。 |
@adonisjs/auth |
フレームワークの認証レイヤーです。セッションを使用するように設定されています。 |
@adonisjs/shield |
CSRFやXSSなどの攻撃からWebアプリを安全に保つためのセキュリティプリミティブのセットです。 |
@adonisjs/static |
アプリケーションの/publicディレクトリから静的アセットを提供するミドルウェアです。 |
vite |
Viteは、フロントエンドアセットをコンパイルするために使用されます。 |
APIスターターキット
APIスターターキットは、JSON APIサーバーを作成するためにカスタマイズされています。これはwebスターターキットの簡略版です。ReactやVueを使用してフロントエンドアプリを構築する予定の場合は、APIスターターキットを使用してAdonisJSバックエンドを作成できます。
npm init adonisjs@latest -- -K=api
# データベースの方言を切り替える
npm init adonisjs@latest -- -K=api --db=mysql
このスターターキットでは、次のことを行っています。
- 静的ファイルの提供をサポートしません。
- ビューレイヤーとviteの設定を行いません。
- XSSとCSRFの保護をオフにし、CORSの保護を有効にします。
- ContentNegotiationミドルウェアを使用してJSONでHTTPレスポンスを送信します。
APIスターターキットはセッションベースの認証で構成されています。ただし、トークンベースの認証を使用する場合は、--auth-guardフラグを使用できます。
npm init adonisjs@latest -- -K=api --auth-guard=access_tokens
Slimスターターキット
最小限主義者のために、slimスターターキットを作成しました。これにはフレームワークのコアとデフォルトのフォルダ構造のみが含まれています。AdonisJSの余分な機能は必要ない場合に使用できます。
npm init adonisjs@latest -- -K=slim
# データベースの方言を切り替える
npm init adonisjs@latest -- -K=slim --db=mysql
Inertiaスターターキット
Inertiaは、サーバードリブンのシングルページアプリケーションを構築する方法です。お気に入りのフロントエンドフレームワーク（React、Vue、Solid、Svelte）を使用して、アプリケーションのフロントエンドを構築できます。
--adapterフラグを使用して使用するフロントエンドフレームワークを選択できます。利用可能なオプションはreact、vue、solid、svelteです。
また、サーバーサイドレンダリングをオンまたはオフにするために--ssrおよび--no-ssrフラグを使用することもできます。
# サーバーサイドレンダリングを使用したReact
npm init adonisjs@latest -- -K=inertia --adapter=react --ssr
# サーバーサイドレンダリングを使用しないVue
npm init adonisjs@latest -- -K=inertia --adapter=vue --no-ssr
独自のスターターキットを持ち込む
スターターキットは、GitHub、Bitbucket、またはGitlabなどのGitリポジトリプロバイダでホストされた事前に構築されたプロジェクトです。また、次のようにして独自のスターターキットを作成してダウンロードすることもできます。
npm init adonisjs@latest -- -K="github_user/repo"
# GitLabからダウンロード
npm init adonisjs@latest -- -K="gitlab:user/repo"
# BitBucketからダウンロード
npm init adonisjs@latest -- -K="bitbucket:user/repo"
gitモードを使用してGit+SSH認証でプライベートリポジトリをダウンロードすることもできます。
npm init adonisjs@latest -- -K="user/repo" --mode=git
最後に、タグ、ブランチ、またはコミットを指定することもできます。
# ブランチ
npm init adonisjs@latest -- -K="user/repo#develop"
# タグ
npm init adonisjs@latest -- -K="user/repo#v2.1.0"
開発サーバーの起動
AdonisJSアプリケーションを作成したら、node ace serveコマンドを実行して開発サーバーを起動できます。
Aceは、フレームワークのコアにバンドルされたコマンドラインフレームワークです。--hmrフラグはファイルシステムを監視し、コードベースの一部に対してホットモジュールリプレースメント（HMR）を実行します。
node ace serve --hmr
開発サーバーが実行されると、ブラウザでアプリケーションを表示するためにhttp://localhost:3333にアクセスできます。
本番用のビルド
AdonisJSアプリケーションはTypeScriptで書かれているため、本番で実行する前にJavaScriptにコンパイルする必要があります。
node ace buildコマンドを使用してJavaScriptの出力を作成できます。JavaScriptの出力はbuildディレクトリに書き込まれます。
Viteが設定されている場合、このコマンドはViteを使用してフロントエンドアセットをコンパイルし、出力をbuild/publicフォルダに書き込みます。
参照: TypeScriptのビルドプロセス。
node ace build
開発環境の設定
AdonisJSはエンドユーザーアプリケーションのビルドを担当してくれますが、開発プロセスを楽しむために追加のツールが必要になる場合があります。また、コーディングスタイルの一貫性を保つために、コードのリントに**ESLintを使用し、コードのフォーマットにPrettier**を使用することを強くオススメします。
コードのリントには**ESLintを使用し、コードのフォーマットのためにPrettier**を使用することを強くオススメします。
公式のスターターキットには、ESLintとPrettierの両方が事前に設定されており、AdonisJSコアチームの意見に基づいたプリセットが使用されています。これについては、ドキュメントのツール設定セクションで詳しく説明しています。
最後に、コードエディタにESLintとPrettierのプラグインをインストールすることをオススメします。これにより、アプリケーション開発中のフィードバックループがより密になります。また、次のコマンドを使用してコマンドラインからコードを「リント」および「フォーマット」することもできます。
# ESLintを実行
npm run lint
# ESLintを実行し、問題を自動修正
npm run lint -- --fix
# Prettierを実行
npm run format
VSCode拡張機能
AdonisJSアプリケーションはTypeScriptをサポートする任意のコードエディタで開発できます。ただし、開発体験をさらに向上させるために、いくつかのVSCode拡張機能を開発しました。