T-CREATOR

Nuxt nuxi コマンド速見表:プロジェクト作成からモジュール公開まで

Nuxt nuxi コマンド速見表:プロジェクト作成からモジュール公開まで

Nuxt 3 の開発において、nuxi コマンドは開発者の強い味方です。プロジェクトの立ち上げから本番環境へのデプロイ、さらにはカスタムモジュールの公開まで、すべてのライフサイクルを支えてくれます。

しかし、コマンドの種類が多く、どのタイミングで何を使えばいいのか迷ってしまうこともあるでしょう。本記事では、nuxi コマンドを体系的に整理し、実務で即活用できる速見表として提供します。初心者の方も、この記事を読めば自信を持って Nuxt プロジェクトを進められるようになりますよ。

nuxi コマンド早見表

まず、よく使う nuxi コマンドを一覧でご紹介します。開発フェーズごとに分類していますので、必要なコマンドをすぐに見つけられます。

フェーズ 1: プロジェクト初期化

#コマンド説明使用例
1nuxi init新規プロジェクト作成yarn dlx nuxi@latest init my-app
2nuxi module addモジュールを追加yarn nuxi module add @nuxtjs​/​tailwindcss

フェーズ 2: 開発

#コマンド説明使用例
1nuxi dev開発サーバー起動yarn nuxi dev --port 4000
2nuxi prepare型定義ファイル生成yarn nuxi prepare
3nuxi devtoolsDevTools の有効化yarn nuxi devtools enable

フェーズ 3: ビルド・デプロイ

#コマンド説明使用例
1nuxi build本番環境向けビルドyarn nuxi build
2nuxi generate静的サイト生成(SSG)yarn nuxi generate
3nuxi previewビルド後のプレビューyarn nuxi preview
4nuxi analyzeバンドルサイズ分析yarn nuxi analyze

フェーズ 4: コード生成・メンテナンス

#コマンド説明使用例
1nuxi add各種ファイル自動生成yarn nuxi add page about
2nuxi cleanupキャッシュクリアyarn nuxi cleanup
3nuxi typecheckTypeScript 型チェックyarn nuxi typecheck --watch
4nuxi upgradeNuxt バージョンアップyarn nuxi upgrade
5nuxi info環境情報の表示yarn nuxi info

フェーズ 5: モジュール公開

#コマンド説明使用例
1nuxi module initモジュールプロジェクト作成yarn dlx nuxi@latest module init my-module
2nuxi module buildモジュールをビルドyarn nuxi module build

よく使うオプション一覧

#オプション対応コマンド説明
1--port <番号>dev, previewポート番号を指定
2--host <ホスト>dev, previewホストを指定
3--httpsdevHTTPS で起動
4--opendevブラウザを自動で開く
5--prerenderbuild静的サイト生成
6--analyzebuildバンドルサイズ分析
7--watchtypecheckファイル変更を監視
8--forceinit, upgrade強制実行

この早見表を参考に、開発フェーズに応じた適切なコマンドを選択できます。それでは、各コマンドの詳細を見ていきましょう。

背景

Nuxt 3 における nuxi コマンドの位置づけ

Nuxt 3 では、フレームワーク全体の設計が大きく刷新されました。その中核を担うのが nuxi という CLI(コマンドラインインターフェース)です。

Nuxt 2 では nuxt コマンドが使われていましたが、Nuxt 3 では機能拡張性やメンテナンス性の向上を目的に、nuxi として再設計されました。nuxi は単なる開発サーバーの起動ツールではなく、以下のような幅広い役割を担っています。

  • プロジェクトの初期化・セットアップ
  • 開発サーバーの起動とホットリロード
  • 本番環境向けのビルドと最適化
  • TypeScript の型生成と自動補完サポート
  • カスタムコンポーネント・レイヤー・モジュールの生成
  • モジュールの検証とパブリッシュ準備

これらの機能が統一されたコマンド体系で提供されることで、開発者は効率的かつ一貫性のあるワークフローを構築できるのです。

nuxi の内部構造と動作フロー

nuxi は内部的に、Nuxt のコア機能と連携しながら動作します。以下の図は、nuxi コマンドがどのように Nuxt プロジェクトと連携するかを示したものです。

mermaidflowchart TB
  dev_cmd["開発者"] -->|"nuxi コマンド実行"| nuxi["nuxi CLI"]
  nuxi -->|"プロジェクト初期化"| init["nuxi init"]
  nuxi -->|"開発サーバー起動"| devserver["nuxi dev"]
  nuxi -->|"本番ビルド"| build["nuxi build"]
  nuxi -->|"型生成"| prepare["nuxi prepare"]
  nuxi -->|"コード生成"| add["nuxi add"]

  devserver --> nitro["Nitro サーバー"]
  build --> output[(".output ディレクトリ")]
  prepare --> types["TypeScript 型定義"]
  add --> components["コンポーネント/<br/>composables"]

この図からわかるように、nuxi は Nuxt の各機能へのゲートウェイとして機能し、開発者の意図を適切な処理に振り分けています。

課題

多様なコマンドによる混乱

Nuxt 3 の nuxi は非常に多機能ですが、その分コマンド数も増加しました。公式ドキュメントには詳細な説明がありますが、情報が分散しており、以下のような課題が生じています。

  • どのコマンドをいつ使うべきか判断しづらい
  • 似た名前のコマンドの違いが不明瞭(例:nuxi generatenuxi build --prerender
  • オプションやフラグの組み合わせがわかりにくい
  • 開発フェーズごとに必要なコマンドが整理されていない

これらの課題により、開発初期段階での試行錯誤が増え、学習コストが高まってしまいます。

コマンド実行時のエラー対応

また、コマンド実行時には以下のようなエラーに遭遇することがあります。

#エラーの種類発生タイミング
1モジュール解決エラーnuxi dev 起動時
2TypeScript 型エラーnuxi prepare 実行後
3ビルド最適化失敗nuxi build
4ポート競合エラーnuxi dev 起動時

これらのエラーに対して、どのコマンドやオプションで対処すべきかが明確でないと、解決に時間がかかってしまうでしょう。

解決策

コマンドをフェーズ別に整理する

本記事では、nuxi コマンドを開発フェーズ別に分類し、それぞれの用途と使い方を明確にします。具体的には以下の 5 つのフェーズに分けて整理します。

mermaidflowchart LR
  phase1["1. プロジェクト<br/>初期化"] --> phase2["2. 開発"]
  phase2 --> phase3["3. ビルド/<br/>デプロイ"]
  phase3 --> phase4["4. コード生成/<br/>メンテナンス"]
  phase4 --> phase5["5. モジュール<br/>公開"]

図で理解できる要点

  • 開発の流れが左から右へ進む
  • 各フェーズで使うコマンドが明確になる
  • 循環的に「開発」と「ビルド」を繰り返すことも多い

この分類により、今自分がどのフェーズにいて、どのコマンドを使うべきかが一目瞭然になります。

よく使うオプションを併記する

各コマンドには便利なオプションが用意されていますが、すべてを覚える必要はありません。実務でよく使うものだけをピックアップし、速見表形式で提供します。

また、エラー発生時の対処法も併記することで、トラブルシューティングの時間を大幅に短縮できるでしょう。

具体例

ここからは、各フェーズごとに nuxi コマンドの具体的な使い方を見ていきます。


フェーズ 1: プロジェクト初期化

nuxi init

新しい Nuxt プロジェクトを作成する基本コマンドです。対話形式でプロジェクト名やテンプレートを選択できます。

bashyarn dlx nuxi@latest init my-nuxt-app

このコマンドを実行すると、以下の流れでプロジェクトが初期化されます。

mermaidsequenceDiagram
  participant Dev as 開発者
  participant CLI as nuxi CLI
  participant Registry as npm レジストリ
  participant FS as ファイルシステム

  Dev->>CLI: nuxi init 実行
  CLI->>Registry: テンプレート取得
  Registry-->>CLI: スターターテンプレート
  CLI->>FS: プロジェクトディレクトリ作成
  CLI->>FS: package.json 生成
  CLI->>FS: nuxt.config.ts 生成
  CLI-->>Dev: 初期化完了

図で理解できる要点

  • テンプレートは npm レジストリから取得される
  • 必要なファイルが自動的に生成される
  • 開発者は設定ファイルをカスタマイズできる状態になる

主なオプション

#オプション説明
1--template使用するテンプレートを指定(例:--template v3
2--force既存ディレクトリを上書き
3--offlineオフラインモードで初期化

実行例:特定のテンプレートを使う

bashyarn dlx nuxi@latest init my-app --template ui

nuxi module add

既存プロジェクトに Nuxt モジュールを追加します。package.jsonnuxt.config.ts の両方を自動更新してくれる便利なコマンドです。

bashyarn nuxi module add @nuxtjs/tailwindcss

処理の流れ

  1. 指定されたモジュールを npm レジストリから検索
  2. package.json の dependencies にモジュールを追加
  3. nuxt.config.tsmodules 配列にモジュールを登録
  4. 必要に応じて設定ファイルを生成(例:tailwind.config.js

エラー対処:モジュールが見つからない場合

vbnetError: Module "@nuxtjs/tailwindcss" not found

エラーコード: MODULE_NOT_FOUND

発生条件

  • モジュール名のタイプミス
  • npm レジストリへの接続障害
  • モジュールが非公開または削除済み

解決方法

  1. モジュール名のスペルを確認する
  2. Nuxt Modules で公式モジュールを検索する
  3. 手動でインストールしてから nuxt.config.ts に追加する
bashyarn add @nuxtjs/tailwindcss

その後、nuxt.config.ts を手動編集します。

typescriptexport default defineNuxtConfig({
  modules: ['@nuxtjs/tailwindcss'],
});

フェーズ 2: 開発

nuxi dev

開発サーバーを起動し、ホットリロード(HMR)を有効にします。コードの変更がリアルタイムでブラウザに反映されるため、開発効率が飛躍的に向上します。

bashyarn nuxi dev

主なオプション

#オプション説明
1--portポート番号を指定(デフォルト:3000)
2--hostホストを指定(デフォルト:localhost)
3--httpsHTTPS で起動
4--openブラウザを自動的に開く

実行例:ポート 4000 で起動

bashyarn nuxi dev --port 4000

実行例:HTTPS で起動

bashyarn nuxi dev --https

HTTPS で起動すると、自己署名証明書が自動生成され、https:​/​​/​localhost:3000 でアクセスできます。これは PWA や Service Worker のテスト時に便利です。

エラー対処:ポート競合エラー

perlError: listen EADDRINUSE: address already in use :::3000

エラーコード: EADDRINUSE

発生条件

  • ポート 3000 が既に別のプロセスで使用されている
  • 前回の開発サーバーが正常に終了していない

解決方法

  1. 別のポートを指定する
bashyarn nuxi dev --port 3001
  1. 既存のプロセスを終了する
bashlsof -ti:3000 | xargs kill -9

nuxi prepare

TypeScript の型定義ファイルを生成します。IDE での自動補完やコード補完を有効にするために、プロジェクト開始時や依存関係更新後に実行します。

bashyarn nuxi prepare

生成されるファイル

このコマンドを実行すると、.nuxt ディレクトリ内に以下のファイルが生成されます。

  • nuxt.d.ts:Nuxt の型定義
  • components.d.ts:自動インポートされるコンポーネントの型
  • imports.d.ts:composables やユーティリティの型

実行タイミング

#タイミング理由
1プロジェクト初回起動時型定義を初期化
2モジュール追加後新しい型を反映
3components​/​ にファイル追加後コンポーネントの型を生成
4composables​/​ にファイル追加後composable の型を生成

エラー対処:TypeScript 型エラー

luaTypeError: Cannot find module '#app' or its corresponding type declarations.

エラーコード: TS2307

発生条件

  • .nuxt ディレクトリが存在しない
  • 型定義ファイルが古い
  • IDE が型ファイルを正しく読み込んでいない

解決方法

  1. nuxi prepare を実行して型定義を再生成
bashyarn nuxi prepare
  1. .nuxt ディレクトリを削除して再生成
bashrm -rf .nuxt && yarn nuxi prepare
  1. IDE(VS Code など)を再起動する

nuxi devtools

Nuxt DevTools を起動します。DevTools はブラウザ上で動作する強力な開発支援ツールで、コンポーネントツリーの可視化、パフォーマンス分析、ルーティング情報の確認などができます。

bashyarn nuxi devtools enable

DevTools の主な機能

  • Pages:ルーティング情報とページコンポーネントの確認
  • Components:登録されているコンポーネント一覧
  • Imports:自動インポートされる関数・composables
  • Modules:インストール済みモジュールの管理
  • Hooks:Nuxt ライフサイクルフックの実行状況
  • Virtual Files:仮想ファイルシステムの内容

無効化する場合

bashyarn nuxi devtools disable

フェーズ 3: ビルド・デプロイ

nuxi build

本番環境向けにプロジェクトをビルドします。コードの最適化、圧縮、Tree Shaking が自動的に行われ、.output ディレクトリに成果物が出力されます。

bashyarn nuxi build

ビルドプロセスの流れ

mermaidflowchart TB
  start["nuxi build 実行"] --> analyze["依存関係解析"]
  analyze --> compile["TypeScript コンパイル"]
  compile --> bundle["Vite/Webpack バンドル"]
  bundle --> optimize["コード最適化/<br/>Tree Shaking"]
  optimize --> minify["圧縮・Minify"]
  minify --> output[".output ディレクトリ<br/>に出力"]
  output --> done["ビルド完了"]

図で理解できる要点

  • 複数の最適化ステップが自動実行される
  • 最終成果物は .output に集約される
  • このディレクトリをデプロイすれば本番環境で動作する

主なオプション

#オプション説明
1--prerender静的サイト生成(SSG)
2--dotenv環境変数ファイルを指定
3--analyzeバンドルサイズ分析

実行例:バンドルサイズを分析

bashyarn nuxi build --analyze

このコマンドを実行すると、各モジュールのサイズが可視化され、最適化のヒントが得られます。

エラー対処:ビルド最適化失敗

javascriptError: Rollup failed to resolve import "~/utils/helper" from "pages/index.vue"

エラーコード: UNRESOLVED_IMPORT

発生条件

  • インポートパスが間違っている
  • ファイルが存在しない
  • TypeScript のパスエイリアス設定が不正

解決方法

  1. インポートパスを確認する
typescript// 誤り
import { helper } from '~/utils/helper';

// 正しい(拡張子を含める)
import { helper } from '~/utils/helper.ts';
  1. nuxt.config.ts のエイリアス設定を確認
typescriptexport default defineNuxtConfig({
  alias: {
    '~': '.',
    '@': '.',
  },
});
  1. .nuxt ディレクトリを削除してリビルド
bashrm -rf .nuxt && yarn nuxi build

nuxi generate

静的サイト生成(SSG)を実行します。すべてのページを事前レンダリングし、HTML ファイルとして出力します。

bashyarn nuxi generate

nuxi build --prerender との違い

#項目nuxi generatenuxi build --prerender
1用途完全な静的サイト生成ハイブリッド(一部を静的化)
2サーバー不要Nitro サーバーが起動可能
3動的ルートすべて事前生成必要な部分のみ生成

使い分けの目安

  • ブログ、ドキュメントサイトnuxi generate
  • E コマース、ダッシュボードnuxi build --prerender(一部のみ静的化)

nuxi preview

ビルド後の成果物をローカルでプレビューします。本番環境と同じ環境で動作確認ができるため、デプロイ前の最終チェックに最適です。

bashyarn nuxi preview

このコマンドは、.output ディレクトリ内の Nitro サーバーを起動し、http:​/​​/​localhost:3000 でアクセスできるようにします。

主なオプション

#オプション説明
1--portポート番号を指定
2--hostホストを指定

実行例:ポート 8080 でプレビュー

bashyarn nuxi preview --port 8080

フェーズ 4: コード生成・メンテナンス

nuxi add

新しいページ、コンポーネント、composable、ミドルウェアなどを生成します。ボイラープレートコードを自動生成してくれるため、開発速度が向上します。

基本構文

bashyarn nuxi add <type> <name>

生成可能なタイプ

#タイプ説明生成先
1componentVue コンポーネントcomponents​/​
2composableComposable 関数composables​/​
3layoutレイアウトコンポーネントlayouts​/​
4pageページコンポーネントpages​/​
5pluginプラグインplugins​/​
6middlewareミドルウェアmiddleware​/​
7apiAPI ルートserver​/​api​/​

実行例:ページを生成

bashyarn nuxi add page about

このコマンドを実行すると、pages​/​about.vue が生成されます。

vue<template>
  <div>
    <!-- About ページの内容 -->
  </div>
</template>

<script setup lang="ts">
// ページロジック
</script>

実行例:API ルートを生成

bashyarn nuxi add api users

server​/​api​/​users.ts が生成されます。

typescriptexport default defineEventHandler((event) => {
  // API ロジック
  return {
    message: 'Hello from users API',
  };
});

実行例:composable を生成

bashyarn nuxi add composable useCounter

composables​/​useCounter.ts が生成されます。

typescriptexport const useCounter = () => {
  const count = ref(0);

  const increment = () => {
    count.value++;
  };

  return {
    count,
    increment,
  };
};

nuxi cleanup

キャッシュや生成されたファイルをクリーンアップします。ビルドエラーが発生した際の対処法として有効です。

bashyarn nuxi cleanup

削除されるディレクトリ・ファイル

  • .nuxt:Nuxt の内部キャッシュ
  • .output:ビルド成果物
  • node_modules​/​.cache:依存関係のキャッシュ

実行タイミング

#タイミング理由
1ビルドエラーが解決しない時キャッシュが原因の可能性
2モジュール更新後古いキャッシュを削除
3型定義がおかしい時型ファイルを再生成

注意点

  • このコマンド実行後は、nuxi preparenuxi dev を再実行する必要があります。
bashyarn nuxi cleanup && yarn nuxi prepare && yarn nuxi dev

nuxi typecheck

TypeScript の型チェックを実行します。ビルド前に型エラーを検出できるため、品質向上につながります。

bashyarn nuxi typecheck

主なオプション

#オプション説明
1--watchファイル変更を監視
2--strict厳密モードで型チェック

実行例:継続的に型チェック

bashyarn nuxi typecheck --watch

これにより、ファイルを保存するたびに自動的に型チェックが実行されます。

nuxi upgrade

Nuxt とその依存関係を最新バージョンにアップグレードします。

bashyarn nuxi upgrade

主なオプション

#オプション説明
1--forceキャッシュを無視して強制アップグレード

アップグレード後の推奨手順

  1. 依存関係を再インストール
bashyarn install
  1. キャッシュをクリーンアップ
bashyarn nuxi cleanup
  1. 型定義を再生成
bashyarn nuxi prepare
  1. 開発サーバーを起動して動作確認
bashyarn nuxi dev

フェーズ 5: モジュール公開

nuxi module build

カスタム Nuxt モジュールをビルドします。自作のモジュールを npm に公開する前に、このコマンドでビルドを実行します。

bashyarn nuxi module build

ビルド対象

  • src​/​:モジュールのソースコード
  • playground​/​:テスト用プロジェクト(ビルドに含まれない)

生成されるファイル

  • dist​/​:ビルド済みモジュールコード
  • dist​/​module.mjs:ESM 形式のエントリポイント
  • dist​/​module.cjs:CommonJS 形式のエントリポイント
  • dist​/​types.d.ts:TypeScript 型定義

nuxi module init

新しい Nuxt モジュールプロジェクトを初期化します。モジュール開発のスターターテンプレートが生成されます。

bashyarn dlx nuxi@latest module init my-module

生成されるディレクトリ構造

rubymy-module/
├── src/
│   ├── module.ts        # モジュールエントリポイント
│   └── runtime/         # ランタイムコード
├── playground/          # テスト用 Nuxt アプリ
│   ├── nuxt.config.ts
│   └── app.vue
├── package.json
└── tsconfig.json

モジュール開発の基本フロー

mermaidflowchart LR
  init["nuxi module init"] --> dev["playground で開発"]
  dev --> test["動作確認"]
  test --> build["nuxi module build"]
  build --> publish["npm publish"]

図で理解できる要点

  • playground でモジュールをテストしながら開発
  • ビルド後に npm へ公開
  • 他のプロジェクトから yarn add でインストール可能になる

カスタムモジュールの作成例

ここでは、簡単なカスタムモジュールを作成してみましょう。例として、グローバルに使えるユーティリティ関数を提供するモジュールを作ります。

1. モジュールを初期化

bashyarn dlx nuxi@latest module init nuxt-utils
cd nuxt-utils

2. モジュールコードを編集

src​/​module.ts を開いて、以下のように記述します。

typescriptimport {
  defineNuxtModule,
  addImports,
  createResolver,
} from '@nuxt/kit';

export default defineNuxtModule({
  meta: {
    name: 'nuxt-utils',
    configKey: 'nuxtUtils',
  },
  setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);

    // composable を自動インポート
    addImports({
      name: 'useFormatDate',
      as: 'useFormatDate',
      from: resolver.resolve(
        './runtime/composables/useFormatDate'
      ),
    });
  },
});

3. composable を作成

src​/​runtime​/​composables​/​useFormatDate.ts を作成します。

typescriptexport const useFormatDate = () => {
  const format = (date: Date, locale = 'ja-JP'): string => {
    return new Intl.DateTimeFormat(locale, {
      year: 'numeric',
      month: 'long',
      day: 'numeric',
    }).format(date);
  };

  return {
    format,
  };
};

4. playground でテスト

playground​/​app.vue でモジュールを使ってみます。

vue<template>
  <div>
    <p>{{ formattedDate }}</p>
  </div>
</template>

<script setup lang="ts">
const { format } = useFormatDate();
const formattedDate = format(new Date());
</script>

5. 開発サーバーで確認

bashyarn dev

ブラウザで http:​/​​/​localhost:3000 にアクセスし、日付が正しくフォーマットされていることを確認します。

6. モジュールをビルド

bashyarn nuxi module build

7. npm に公開

bashnpm publish

これで、他のプロジェクトから以下のようにインストールできます。

bashyarn add nuxt-utils

そして、nuxt.config.ts に追加します。

typescriptexport default defineNuxtConfig({
  modules: ['nuxt-utils'],
});

便利な応用コマンド

nuxi info

現在の Nuxt プロジェクトの環境情報を表示します。バグ報告時やトラブルシューティング時に役立ちます。

bashyarn nuxi info

出力例

diff- Operating System: Darwin (macOS)
- Node Version: v20.11.0
- Nuxt Version: 3.11.2
- Nitro Version: 2.9.6
- Package Manager: yarn@4.1.1
- Builder: vite
- User Config: modules, devtools, typescript
- Runtime Modules: @nuxtjs/tailwindcss@6.11.4

この情報を GitHub Issue に貼り付けると、問題の再現性が高まります。

nuxi analyze

ビルド後のバンドルサイズを詳細に分析します。パフォーマンス最適化の第一歩として非常に有効です。

bashyarn nuxi analyze

実行すると、ブラウザが自動的に開き、以下のような情報が可視化されます。

  • 各モジュールのサイズ
  • Tree Map 形式の可視化
  • 圧縮前後のサイズ比較

最適化のヒント

分析結果から以下のような改善策が見つかることがあります。

#問題対策
1特定のライブラリが大きい軽量な代替ライブラリに変更
2未使用コードが含まれているTree Shaking を有効化
3重複したコードコード分割を見直す

まとめ

本記事では、Nuxt 3 の nuxi コマンドを開発フェーズごとに整理し、実務で即活用できる速見表として提供しました。

重要なポイント

  • プロジェクト初期化: nuxi init でプロジェクトを作成し、nuxi module add でモジュールを追加
  • 開発: nuxi dev でホットリロード開発、nuxi prepare で型定義を生成
  • ビルド・デプロイ: nuxi build で本番ビルド、nuxi generate で静的サイト生成
  • コード生成: nuxi add で各種ファイルを自動生成
  • メンテナンス: nuxi cleanup でキャッシュクリア、nuxi typecheck で型チェック
  • モジュール公開: nuxi module init でモジュール開発を開始、nuxi module build でビルド

これらのコマンドを使いこなすことで、Nuxt 3 の開発効率が飛躍的に向上します。エラーが発生した際も、本記事の対処法を参考にすれば、素早く解決できるでしょう。

ぜひこの速見表をブックマークして、日々の開発にお役立てください。

関連リンク