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

# Manifest

> meta.json and config.json, field by field

Two files describe an expansion: `meta.json` is who it is, `config.json` is how to run it. Neither contains code, and both are read before anything of yours runs.

Every problem in them is reported at once, naming the file and the field, so you fix the list rather than one error per reload:

```
meta.json: "id" must be lowercase a-z, 0-9 and _, got "My-Exp"
meta.json: "sdkVersion" is required, e.g. "^2.0.0"
config.json: start file "src/main.ts" does not exist
```

## meta.json

```json meta.json theme={null}
{
  "id": "my_expansion",
  "name": "My Expansion",
  "version": "1.0.0",
  "description": "Does cool things",
  "author": "Developer",
  "apiKey": "nmk_...",
  "sdkVersion": "^2.0.0",
  "permissions": ["project:read"],
  "dependencies": {}
}
```

| Field                   | Required | Rules                                                                                                                                                                        |
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | yes      | Lowercase `a-z`, `0-9` and `_`, at most 64 characters. Your expansion's only identity: the folder name is ignored, and two installed expansions cannot share one.            |
| `name`                  | yes      | Shown in the app.                                                                                                                                                            |
| `version`               | yes      | Semantic version, `1.0.0`.                                                                                                                                                   |
| `apiKey`                | yes      | Your NMCrate secret for this `id`. See [Publishing](/publishing).                                                                                                            |
| `sdkVersion`            | yes      | The SDK range you built against, e.g. `^2.0.0`. Ranges understood: `*`, `2`, `2.x`, `1.2.3`, `^1.2.3`, `~1.2.3`, comparators like `>=2.0.0 <3.0.0`, and `\|\|` between them. |
| `description`, `author` | no       | Strings, shown in the app and used by NMCrate.                                                                                                                               |
| `permissions`           | no       | From the catalog in [Permissions](/permissions). Anything else is an error.                                                                                                  |
| `dependencies`          | no       | Must be `{}` for now. Reserved for the NMCrate library system; your own [libraries](/libraries) need no entry here.                                                          |

<Note>
  Unknown keys are kept out of the way with a warning rather than failing the load. `"type": "library"` is reserved and currently refused.
</Note>

### id and version, in practice

* The `id` appears in the routes of your pages (`custom/my_expansion.home`) and prefixes everything you register, so two expansions can both have a `home` page.
* Changing `id` after release means NMCrate sees a different expansion, and per-project state saved under the old id is no longer read.
* `version` is what the store shows and what an update compares against.

## config.json

```json config.json theme={null}
{ "start": "src/index.ts" }
```

| Field   | Required | Rules                                                                                                                                                   |
| ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `start` | no       | The file the app runs first, relative to the expansion folder. Defaults to `src/index.ts`, then `src/index.js`. It must exist and be inside the folder. |

A missing `config.json` is accepted with a warning and the defaults.

These keys are reserved, accepted with a warning and otherwise ignored today: `settings`, `locales`, `background`, `build`, `main`.

## Compatibility

`sdkVersion` is checked against the SDK the app provides, **2.0.0**:

* satisfied: loads normally
* not satisfied: does not load, and the Expansions page says

```
Built for SDK ^3.0.0, but this app provides SDK 2.0.0. Update the app or the expansion.
```

Prereleases only match a range that mentions one, as in npm.