> ## Documentation Index
> Fetch the complete documentation index at: https://docs.makkii.jp/llms.txt
> Use this file to discover all available pages before exploring further.

# require によるモジュール分割

> 複数ファイルの Lua コードを require でリンクし、1 つの vehicle Lua にまとめる

StormMin は `require` で分割した複数の Lua ファイルを 1 つのソースにリンクしてから minify できます。この機能は CLI とライブラリから利用でき、**Web 版では利用できません**（Web 版は単一ファイルの貼り付けのみに対応しています）。

## プロジェクトの構造

複数モジュールのリンクには `LuaProject` という共通の入力形式を使います。

```json theme={null}
{
  "entry": "main",
  "modules": {
    "main": "local util = require(\"lib.util\")\nreturn util.f()\n",
    "lib.util": "local M = {}\nfunction M.f() return 1 end\nreturn M\n"
  }
}
```

* `entry`: エントリーモジュールのキー。`modules` のいずれかのキーと一致させます。
* `modules`: モジュールキー（`.` 区切りの Lua 識別子）から Lua ソース文字列への map です。コアはファイルパスを扱わず、キーだけを認識します。

## モジュールキーの命名規則

モジュールキーは `segment("." segment)*` の形式で、各 segment は先頭が英字か `_`、続く文字が英数字か `_` である必要があります（大文字小文字は区別されます）。区切りは `.` のみです。

CLI の `--modules-dir` でディレクトリから自動生成する場合は、ファイルパスの `/` がキーの `.` に変換されます（例: `foo/bar.lua` → `foo.bar`）。このとき次の点に注意してください。

* ファイルの拡張子は `.lua` である必要があり、`.lua` を除いたベースファイル名と途中のディレクトリ名がすべて Lua 識別子である必要があります。`a.b.lua`（`a/b.lua` とのキー衝突を防ぐため）、`dir.name/x.lua`、`1abc.lua`、`a-b.lua` などは `invalid-module-key` としてエラーになります。
* 2 つの異なるパスが同じモジュールキーに解決される場合も `invalid-module-key` エラーになります。

<Warning>
  無効なモジュールキーやキー衝突は、サイレントにスキップされるのではなく必ず `invalid-module-key` 診断として報告されます。CLI のプロジェクトモードでは、この診断が 1 件でもあると `ok: false` になり、出力コードは生成されません。
</Warning>

## CLI での指定方法

<CodeGroup>
  ```sh ディレクトリを走査 theme={null}
  stormmin compile --entry main --modules-dir src/ -o out.lua
  ```

  ```sh project.json を直接渡す theme={null}
  stormmin compile --project project.json -o out.lua
  ```
</CodeGroup>

`--modules-dir` はディレクトリを再帰走査して `LuaProject` を組み立てる簡易な方法です。`ambient`（後述）を指定したい場合は `--project` で `LuaProject` の JSON ファイルを直接渡してください。

## ライブラリでの指定方法

```js theme={null}
import { compileProject, analyze } from '@stormcat-works/stormmin';

const result = await compileProject(project, { minify: true });
```

`compileProject` はリンク＋（`minify: true` なら）minify を行います。エラー時は `{ ok: false, diagnostics }` のみを返し、`code`/`map` は含まれません。`minify: false` を指定すると、minify を行わない代わりに Source Map v3 が `map` フィールドに含まれます。

`analyze(project, options)` はリンクと静的解析だけを行います。構文エラーがあっても `ok: true` のまま `diagnostics` に報告されるため、エディタでの編集中チェックに向いています。

## require の制約

`require` はモジュールのトップレベルで呼び出す必要があります。関数の中や条件分岐の中での `require`、変数を経由した動的な `require` 呼び出しなどは、リンクエラーとして検出されます（`require-not-top-level` / `require-not-statement` / `require-dynamic` などの診断コード。一覧は [診断コードリファレンス](/stormmin/reference/diagnostics) を参照してください）。

## ambient 名前空間

`LuaProject` は任意で `ambient` フィールドを持てます。`sim.*` のような、ファイルとしては存在しないがランタイムから提供される名前空間を宣言するための仕組みです。`ambient` を使うには `--project` で `LuaProject` の JSON を直接渡す必要があります（`--modules-dir` からの自動生成では設定できません）。ambient 名前空間の扱いに関する制約も診断コードとして検出されます（`unknown-ambient-member` / `environment-only-api` / `ambient-root-escapes` / `ambient-dynamic-access` / `ambient-assigned` など）。


## Related topics

- [ライブラリ API リファレンス](/stormmin/reference/api.md)
- [ライブラリの使い方](/stormmin/guides/library-usage.md)
- [FAQ・トラブルシューティング](/stormmin/faq.md)
- [CLI の使い方](/stormmin/guides/cli-usage.md)
- [使い始め方](/stormmin/getting-started.md)