> ## 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.

# Getting started

> Install a template, get it loading, see it hot-reload

<Steps>
  <Step title="Get a key">
    Every expansion is verified when it loads. Create a secret for the id you are going to use, for example `my_expansion`. You will paste it into `meta.json` as `apiKey`.<br />[https://lodemc.net/devs/dashboard/secrets](https://lodemc.net/devs/dashboard/secrets)

    The id and the key belong together: a key issued for one id will not load an expansion using a different one. See [Publishing](/publishing) for what happens before your expansion is published.
  </Step>

  <Step title="Copy a template">
    Templates live in the app repository under `packages/sdk-templates/`:

    * `ts` for TypeScript
    * `js` for JavaScript

    Copy one into your Expansions folder, under any name you like:

    <Tabs>
      <Tab title="Windows">
        ```
        Documents\LodeMC\LDStudio\Expansions\
        ```
      </Tab>

      <Tab title="macOS">
        ```
        ~/Documents/LodeMC/LDStudio/Expansions/
        ```
      </Tab>

      <Tab title="Linux">
        ```
        ~/.local/share/LodeMC/LDStudio/Expansions/
        ```
      </Tab>
    </Tabs>

    The folder name does not matter. `meta.json`'s `id` is what identifies your expansion.
  </Step>

  <Step title="Fill in meta.json">
    ```json meta.json theme={null}
    {
      "id": "my_expansion",
      "name": "My Expansion",
      "version": "1.0.0",
      "description": "Does cool things",
      "author": "You",
      "apiKey": "nmk_...",
      "sdkVersion": "^2.0.0",
      "permissions": [],
      "dependencies": {}
    }
    ```

    `id` is lowercase letters, digits and `_`. Full rules in the [manifest guide](/manifest).
  </Step>

  <Step title="Open the app">
    The app picks the folder up without a restart. Open **Project Settings → Expansions** and you should see your expansion listed.

    * If it declares permissions, it waits at **Needs approval** until you press *Review permissions*.
    * Before it is published on NMCrate it loads marked **Untrusted**, which is normal during development.
    * If something is wrong, the card says what, and the **logs** button shows the expansion's own log.

    Then open a project. Your sidebar button appears there.
  </Step>

  <Step title="Edit and watch it reload">
    Save any file in the folder. The app rebuilds and swaps the expansion in place: no restart, no reopening the project. What changed is re-run, the rest keeps its state. See [Lifecycle](/lifecycle).
  </Step>

  <Step title="Editor setup">
    Nothing to install. When the app loads your folder it writes:

    ```
    MyExpansion/.ldstudio/sdk.d.ts              types for sdk, sdk/ui, CSS and assets
    MyExpansion/.ldstudio/react.d.ts            a small stand-in for @types/react
    MyExpansion/.ldstudio/tsconfig.libs.json    path mappings for your lib/ folders
    ```

    The template's `tsconfig.json` already points at them. They come from the app that runs your code, so they can never be out of date. Delete them and they come back on the next load.

    For real React typing (correct DOM props, proper JSX), run `npm i -D @types/react` in your expansion folder. The app then stops writing the shim and leaves your types alone. `node_modules` is only ever your editor's: it is never bundled into your expansion, and it is left out of a packed `.nxe`.
  </Step>
</Steps>

## Next

<CardGroup cols={3}>
  <Card title="Modules and imports" icon="folder-tree" href="/modules">
    How files, CSS and assets come together
  </Card>

  <Card title="sdk reference" icon="plug" href="/sdk-reference">
    Everything you can add to the app
  </Card>

  <Card title="Examples" icon="code" href="/examples">
    Working expansions to read
  </Card>
</CardGroup>