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

# Package structure and manifests

> A Mini App is a regular MiniMax Plugin with a miniapp.json declaration and two runtime payloads, one for the page and one for Node.

<div className="code-docs">
  <h2 id="layout">
    Directory layout
  </h2>

  ```text theme={null}
  sales-board/
  ├── .minimax-plugin/
  │   └── plugin.json          # plugin manifest
  ├── package.json             # only the mcode extension is needed
  ├── icon.png
  ├── servers.mcp.json         # optional
  ├── skills/                  # optional
  └── miniapp/
      ├── miniapp.json         # MiniApp declaration
      ├── client/              # page payload
      │   ├── index.html
      │   └── client-api.ts    # optional: type checking only
      └── node/                # Node payload
          ├── server.mjs
          └── miniapp-api.ts   # optional: type checking only
  ```

  New packages created by `init` use this layout. The host still reads the earlier `liveboard/` format, and updating an old package doesn't require converting it.

  <h2 id="plugin-json">
    Plugin manifest: plugin.json
  </h2>

  `.minimax-plugin/plugin.json` is the single source of truth for plugin identity, metadata, icon, Skills, MCP, and Apps. Mini App authoring never reinterprets or clears these fields.

  ```json .minimax-plugin/plugin.json theme={null}
  {
    "schemaVersion": 1,
    "name": "sales-board",
    "displayName": "Sales Board",
    "version": "1.0.0",
    "description": "Shows the verified sales pipeline.",
    "author": "Your Name",
    "icon": "icon.png",
    "category": "Business",
    "exampleQueries": ["Open my sales pipeline dashboard."],
    "apps": [],
    "mcpServers": [],
    "skills": []
  }
  ```

  * `name` is a lowercase machine name of up to 80 characters that starts with a letter and may use digits and `.` `_` `-` as separators. It is the Mini App's `pluginId`.
  * `version` uses SemVer. `description`, `author`, and every `exampleQueries` entry must be non-empty.
  * `icon` points to a PNG, JPEG, or WebP inside the package. `init` provides a default icon.
  * `apps`, `mcpServers`, and `skills` keep their ordinary plugin meaning; use empty arrays for capabilities you don't have.

  <h2 id="package-json">
    Entry declaration: package.json
  </h2>

  ```json package.json theme={null}
  {
    "mcode": {
      "schemaVersion": 2,
      "miniApp": "./miniapp/miniapp.json"
    }
  }
  ```

  The root `package.json` only needs this extension. The host never reads or runs engineering metadata such as `packageManager`, lockfiles, build scripts, or dependencies.

  <h2 id="miniapp-json">
    Mini App declaration: miniapp.json
  </h2>

  ```json miniapp/miniapp.json theme={null}
  {
    "schemaVersion": 1,
    "artifacts": {
      "client": ["./miniapp/client"],
      "node": ["./miniapp/node"]
    },
    "runtime": {
      "kind": "process",
      "entry": "./miniapp/node/server.mjs",
      "lifecycle": "on-demand"
    },
    "surface": {
      "path": "/dashboard",
      "window": { "width": 960, "height": 700, "resizable": true }
    },
    "mcpEndpoints": [],
    "hostConnectorAccess": { "providers": ["notion"] },
    "agentAccess": ["session.run"],
    "agentConcurrency": 4
  }
  ```

  See [miniapp.json fields](/docs/miniapp/reference/manifest) for every field. Key points:

  * `artifacts.client` and `artifacts.node` are both required. They define what the host hashes, adopts, and publishes; they can be source directories rather than build output, and they may overlap.
  * `runtime.entry` is the Node entry, ending in `.js`, `.mjs`, or `.cjs`, inside the Node payload. `lifecycle` is always `on-demand`: enabling or scanning a plugin never starts the service.
  * `surface.path` is the page route served by the Node service.
  * `hostConnectorAccess` and `agentAccess` are explicit grants; leave them out and you don't get them. Declare them only when the runtime really needs them.

  <h2 id="payload">
    Payload rules
  </h2>

  * The host doesn't install dependencies or run builds. Ship something ready to run, and bundle or vendor third-party runtime dependencies into a payload directory. Prefer Node built-ins and browser APIs.
  * `node_modules` is build state: it is never published and must not sit inside a declared payload.
  * Use portable relative paths: no absolute paths, `..`, backslashes, or symlinks, and nothing outside the package.
  * Every file in a payload except `node_modules` goes into the digest. Delete logs, caches, temporary files, and anything else you don't want published before you publish.
</div>