ブログ

LunariaJS CLIコマンド詳解：init、build、previewを完全にマスター

LunariaJSの3つの主要CLIコマンド、lunaria init、lunaria build、lunaria previewを包括的に解説。実際の操作デモを通じて、各コマンドのパラメータオプションと使用シナリオを習得します。

LibDoc Team 2026年3月6日 LunariaJS 連載 56 分で読める
#LunariaJS #CLI #コマンドライン #ツール

LunariaJS CLIコマンド詳解：init、build、previewを完全にマスター

これまでの2つの記事で、LunariaJSのコア概念と設定方法を紹介しました。今日は、LunariaJSのコマンドラインツール（CLI）を詳しく解説し、各コマンドの使い方とベストプラクティスをマスターしましょう。

💡 公式ドキュメント：LunariaJS 日本語ドキュメント - CLI

CLI概要

LunariaJSは強力なコマンドラインツールを提供しており、以下のことができます：

  • プロジェクトの初期化：設定ファイルを素早く作成
  • ダッシュボードのビルド：ローカライズ状態の可視化ページを生成
  • ダッシュボードのプレビュー：ローカルサーバーを起動して結果を確認

実行方法

LunariaJS CLIを実行するには3つの方法があります：

# 方法1：npxを使用（推奨、インストール不要）
npx lunaria [command]

# 方法2：npm scriptsを使用（推奨）
npm run lunaria:[command]

# 方法3：直接実行（グローバルまたはプロジェクトインストールが必要）
lunaria [command]

グローバルオプション

すべてのコマンドは以下のグローバルオプションをサポートしています：

オプション短縮形説明
--help-hヘルプ情報を表示
--version-vバージョン番号を表示
--config <path>-c設定ファイルのパスを指定

ヘルプの表示

# メインコマンドのヘルプを表示
npx lunaria --help

# サブコマンドのヘルプを表示
npx lunaria init --help
npx lunaria build --help
npx lunaria preview --help

lunaria init - プロジェクトの初期化

lunaria initコマンドは、LunariaJS設定ファイルを素早く作成するために使用します。

基本的な使い方

npx lunaria init

実行すると、CLIはインタラクティブに設定情報を尋ねます：

? What is the source language of your project? (en)
? What languages do you want to support? (comma-separated, e.g., zh-cn, ja, ko)
? Where are your source files located? (e.g., docs/{slug}.md)
? Where should localized files be stored? (e.g., i18n/{lang}/{slug}.md)
? Where should the dashboard be generated? (lunaria-dashboard)

コマンドパラメータ

パラメータ説明デフォルト値
--config <path>出力設定ファイルのパスを指定lunaria.config.json
--typescriptTypeScript設定ファイルを生成false
--yes / -yインタラクションをスキップ、デフォルト値を使用false
--force / -f既存の設定ファイルを強制的に上書きfalse

インタラクティブ初期化フロー

完全なインタラクティブ初期化の例を見てみましょう：

$ npx lunaria init

🌙 LunariaJS - Localization Dashboard Generator

? What is the source language of your project? en
? What languages do you want to support? zh-cn, ja, ko
? Where are your source content files? src/content/docs/{slug}.md
? Where are your localized content files? src/i18n/{lang}/docs/{slug}.md
? Where should the dashboard be output? public/lunaria
? Dashboard title My Docs Localization Status

✨ Created lunaria.config.json

Next steps:
1. Review and adjust lunaria.config.json
2. Run `npx lunaria build` to generate your dashboard
3. Run `npx lunaria preview` to preview locally

TypeScript設定の生成

TypeScript設定ファイルを使用したい場合：

npx lunaria init --typescript

これによりlunaria.config.tsが生成されます：

// lunaria.config.ts
import { defineConfig } from '@lunariajs/core';

export default defineConfig({
  sourceLanguage: 'en',
  languages: ['en', 'zh-cn', 'ja', 'ko'],
  files: [
    {
      sourcePath: 'src/content/docs/{slug}.md',
      localizationPath: 'src/i18n/{lang}/docs/{slug}.md',
    },
  ],
  dashboard: {
    outputDir: 'public/lunaria',
    title: 'My Docs Localization Status',
  },
});

クイック初期化（インタラクションをスキップ）

--yesオプションでデフォルト設定を素早く作成：

npx lunaria init --yes

これにより、すべてのデフォルト値で設定ファイルが作成されます：

{
  "sourceLanguage": "en",
  "languages": ["en"],
  "files": [
    {
      "sourcePath": "docs/{slug}.md",
      "localizationPath": "i18n/{lang}/{slug}.md"
    }
  ],
  "dashboard": {
    "outputDir": "lunaria-dashboard"
  }
}

設定ファイルパスの指定

npx lunaria init --config ./config/lunaria.json

ベストプラクティス

  1. 初回はインタラクティブを推奨：CLIが設定をガイド
  2. 継続使用ではTypeScriptを推奨：より良い型サポートとIDEヒント
  3. バージョン管理：設定ファイルをGitリポジトリにコミット

lunaria build - ダッシュボードのビルド

lunaria buildコマンドはLunariaJSのコアコマンドで、ローカライズダッシュボードを生成します。

基本的な使い方

npx lunaria build

コマンドパラメータ

パラメータ説明デフォルト値
--config <path>設定ファイルのパスを指定lunaria.config.json
--output <dir>出力ディレクトリを指定（設定を上書き）設定のdashboard.outputDir
--silentサイレントモード、ログを出力しないfalse
--verbose詳細出力モードfalse

ビルドプロセスの詳細

lunaria buildを実行すると、LunariaJSは以下のステップを実行します：

1. 設定ファイルの読み込み

📄 Loading configuration from lunaria.config.json...

2. ソースファイルのスキャン

🔍 Scanning source files in src/content/docs/...
   Found 42 source files

3. 翻訳状態の分析

📊 Analyzing translation status...
   - en (source): 42 files
   - zh-cn: 38 done, 3 outdated, 1 missing
   - ja: 30 done, 8 outdated, 4 missing
   - ko: 25 done, 10 outdated, 7 missing

4. ダッシュボードの生成

🎨 Generating dashboard...
   - Creating HTML pages
   - Generating CSS styles
   - Building JavaScript bundle

5. 結果の出力

✅ Dashboard generated successfully!
   Output: public/lunaria/
   Files: 15 files, 128KB total

詳細出力モード

--verboseを使用してビルドの詳細を確認：

npx lunaria build --verbose

出力例：

📄 Loading configuration from lunaria.config.json

🔍 Scanning files...
   Pattern: src/content/docs/{slug}.md
   Files found:
   - src/content/docs/index.md
   - src/content/docs/getting-started.md
   - src/content/docs/configuration.md
   ...

📊 Analyzing translation status...

   File: index.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-27)
   - ja: outdated (modified: 2026-02-20, source newer)
   - ko: missing

   File: getting-started.md
   - en: source (modified: 2026-02-28)
   - zh-cn: done (modified: 2026-02-28)
   - ja: done (modified: 2026-02-25)
   - ko: outdated (modified: 2026-02-15, source newer)
   ...

🎨 Generating dashboard...
   - Writing index.html
   - Writing styles.css
   - Writing script.js
   - Writing data/status.json

✅ Build completed in 1.2s
   Output: public/lunaria/

サイレントモード

CI/CD環境では、サイレントモードを使用できます：

npx lunaria build --silent

出力ディレクトリのカスタマイズ

設定の出力ディレクトリを一時的に上書き：

npx lunaria build --output ./dist/i18n-dashboard

package.jsonとの統合

// package.json
{
  "scripts": {
    "build": "astro build && lunaria build",
    "lunaria:build": "lunaria build",
    "lunaria:build:verbose": "lunaria build --verbose"
  }
}

ビルド成果物

lunaria buildは出力ディレクトリに以下のファイルを生成します：

lunaria-dashboard/
├── index.html          # メインページ
├── assets/
│   ├── index.css       # スタイルファイル
│   └── index.js        # JavaScriptロジック
├── data/
│   └── status.json     # 翻訳状態データ
└── favicon.ico         # サイトアイコン

よくあるビルドエラー

エラー1：設定ファイルが見つからない

Error: Configuration file not found at lunaria.config.json

解決策：

# 先にinitを実行して設定を作成
npx lunaria init
# または設定ファイルのパスを指定
npx lunaria build --config ./config/lunaria.json

エラー2：ソースファイルディレクトリが存在しない

Error: Source directory "docs" does not exist

解決策：files.sourcePathの設定が正しいか確認してください。

lunaria preview - ダッシュボードのプレビュー

lunaria previewコマンドは、生成されたダッシュボードをプレビューするためのローカルサーバーを起動します。

基本的な使い方

npx lunaria preview

コマンドパラメータ

パラメータ説明デフォルト値
--config <path>設定ファイルのパスを指定lunaria.config.json
--port <number>サーバーポートを指定3000
--openブラウザを自動的に開くfalse
--hostすべてのネットワークインターフェースをリッスンfalse

プレビューサーバーの起動

$ npx lunaria preview

🌙 LunariaJS Preview Server

Local:   http://localhost:3000
Network: http://192.168.1.100:3000

Press Ctrl+C to stop

ポートの指定

npx lunaria preview --port 8080

ブラウザの自動オープン

npx lunaria preview --open

外部アクセスの許可

チーム環境で、同僚がLAN経由でアクセスできるようにする：

npx lunaria preview --host

プレビュー時の注意点

  1. 先にビルドが必要：previewコマンドは自動的にビルドを実行しないため、先にlunaria buildを実行してください
  2. ホットリロード：現在ホットリロードはサポートされておらず、設定を変更した場合は再ビルドが必要
  3. ポートの競合：デフォルトポートが使用されている場合は、--portで別のポートを指定

コマンド組み合わせの使用シナリオ

開発環境のワークフロー

# 1. 設定の初期化（初回のみ）
npx lunaria init

# 2. ダッシュボードのビルド
npx lunaria build

# 3. 結果のプレビュー
npx lunaria preview --open

Astro Starlightとの統合

// package.json
{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build && lunaria build",
    "preview": "astro preview",
    "lunaria:preview": "lunaria preview --port 3001"
  }
}

CI/CDパイプライン

# .github/workflows/i18n-check.yml
name: i18n Status Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Build Lunaria Dashboard
        run: npm run lunaria:build -- --silent

      - name: Upload Dashboard
        uses: actions/upload-artifact@v4
        with:
          name: lunaria-dashboard
          path: lunaria-dashboard/

ローカルデバッグシナリオ

# 詳細出力モードでデバッグ
npx lunaria build --verbose

# ビルドに問題がある場合、設定を確認
npx lunaria init --force  # 設定を再生成

# 再ビルド
npx lunaria build --verbose

CLI高度なテクニック

1. 環境変数の使用

# Node.js環境変数を設定
NODE_ENV=production npx lunaria build

# カスタム環境変数
LUNARIA_OUTPUT=./dist/dashboard npx lunaria build

設定ファイルでの使用：

// lunaria.config.ts
export default defineConfig({
  dashboard: {
    outputDir: process.env.LUNARIA_OUTPUT || 'lunaria-dashboard',
  },
});

2. 複数コマンドの組み合わせ

# 1つのコマンドで初期化とビルドを完了
npx lunaria init --yes && npx lunaria build

# またはnpm scriptsを使用
npm run lunaria:init && npm run lunaria:build

3. 設定問題のデバッグ

# 設定ファイルが有効か確認
npx lunaria build --verbose 2>&1 | head -20

4. バージョンチェック

# 現在のバージョンを確認
npx lunaria --version

# 新しいバージョンがあるか確認
npm outdated @lunariajs/core

CLIトラブルシューティング

Q1：コマンドが見つからない

問題：lunaria: command not found

解決策：

# npxを使用
npx lunaria [command]

# またはグローバルインストール
npm install -g @lunariajs/core

Q2：権限が拒否された

問題：EACCES: permission denied

解決策：

# ディレクトリ権限を確認
ls -la .

# またはsudoを使用（推奨されない）
sudo npx lunaria build

Q3：メモリ不足

問題：JavaScript heap out of memory

解決策：

# Node.jsのメモリ制限を増加
NODE_OPTIONS="--max-old-space-size=4096" npx lunaria build

Q4：ビルドが遅い

問題：大規模プロジェクトのビルド時間が長い

解決策：

# ファイル数を確認
npx lunaria build --verbose | grep "Files found"

# 設定を最適化し、不要なファイルを除外

まとめ

この記事では、LunariaJS CLIの3つのコアコマンドを詳しく解説しました：

コマンド機能よく使うパラメータ
lunaria init設定ファイルの初期化--typescript, --yes, --force
lunaria buildローカライズダッシュボードのビルド--output, --silent, --verbose
lunaria previewダッシュボードのローカルプレビュー--port, --open, --host

重要なポイント：

  • npx lunaria initで素早く開始
  • lunaria buildはコアコマンドで、可視化ダッシュボードを生成
  • lunaria previewはローカルデバッグとプレビューに便利
  • CLIコマンドをpackage.jsonscriptsに統合

次のステップ

次の記事では、LunariaJSローカライズダッシュボードの使用方法を詳しく解説します：

  • ダッシュボードインターフェースの詳細
  • 翻訳状態の解釈
  • ファイル状態の追跡
  • フィルタリングと検索機能
  • ダッシュボードのカスタマイズ

お楽しみに！

💡 おすすめ読書：