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

# Local Development Setup

> Step-by-step guide to building and running the Pastures extension locally.

<Steps>
  <Step title="Install Node.js 22+">
    We recommend [nvm](https://github.com/nvm-sh/nvm) to manage Node versions.

    ```bash theme={null}
    nvm install 22
    nvm use 22
    ```
  </Step>

  <Step title="Install Yarn">
    Pastures uses Yarn Classic (1.x).

    ```bash theme={null}
    npm install -g yarn
    ```
  </Step>

  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/IQCG/pastures-rancher.git
    cd pastures-rancher
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    yarn install --ignore-engines
    ```

    <Tip>
      The `--ignore-engines` flag is required because `@rancher/shell` may declare strict Node engine constraints that conflict with newer Node versions. The extension works correctly on Node 22+.
    </Tip>
  </Step>

  <Step title="Build the extension">
    ```bash theme={null}
    yarn build-pkg pastures
    ```

    This compiles the extension into `dist-pkg/`.
  </Step>

  <Step title="Start the package server">
    ```bash theme={null}
    yarn serve-pkgs
    ```

    The dev server starts at **[http://127.0.0.1:4500](http://127.0.0.1:4500)** and serves the built extension artifacts. If you rebuild the extension, the server picks up the new files automatically.
  </Step>

  <Step title="Start or connect to Rancher">
    **Option A — Docker (quick start):**

    ```bash theme={null}
    docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest
    ```

    **Option B — Existing instance:**
    Point your browser at your Rancher dashboard URL.
  </Step>

  <Step title="Developer Load the extension">
    1. Open the Rancher UI and navigate to **Extensions**.
    2. Click the **⋮** menu (top-right) and select **Developer Load**.
    3. Enter `http://127.0.0.1:4500` as the extension URL.
    4. The Pastures extension appears in the sidebar after a page refresh.
  </Step>

  <Step title="Enable demo mode">
    If you don't have a Pastures Engine instance, enable **Demo Mode** in **Pastures → Settings** to work with synthetic data. This lets you develop and test UI changes without a backend.
  </Step>
</Steps>

## Common Issues

<Warning>
  If `yarn serve-pkgs` fails with a port conflict, ensure no other process is using port 4500. You can check with `lsof -i :4500`.
</Warning>

| Problem                          | Solution                                                         |
| -------------------------------- | ---------------------------------------------------------------- |
| `ERR! engine` during install     | Add `--ignore-engines` to the install command                    |
| Extension not visible in Rancher | Refresh the page; confirm `serve-pkgs` is running and accessible |
| API calls failing                | Enable demo mode in Settings or configure a valid Engine URL     |