> ## Documentation Index
> Fetch the complete documentation index at: https://nextjs-egg.nyxel.my.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get your Next.js app running on Pterodactyl or Pelican in minutes.

## Before you begin

Make sure you have already imported the egg and created a server. If not, complete the [Installation](/installation) guide first.

Your Next.js project must meet these requirements:

* A valid `package.json` with `next` listed as a dependency.
* Your `next.config.js` must **not** hardcode a port. The egg passes the panel-allocated port via the `-p` flag at runtime.

## Configure and start your server

<Steps>
  <Step title="Import the egg and create a server">
    If you have not done so yet, follow the [Installation](/installation) guide to import `next-js-egg.json` and create a server. Return here once your server exists in the panel.
  </Step>

  <Step title="Set your Git repository URL">
    On the server's **Startup** tab, set `GIT_URL` to the full HTTPS URL of your repository:

    ```
    https://github.com/your-username/your-nextjs-app
    ```

    The egg clones this URL on first start. On subsequent starts it either pulls new commits (if `AUTO_UPDATE=1`) or skips the pull.

    <Note>
      If you prefer to upload your project files manually instead of using Git, leave `GIT_URL` empty and upload your files via the panel File Manager. The egg will skip cloning and use whatever files are already in the server volume, as long as a `package.json` is present.
    </Note>
  </Step>

  <Step title="Set the branch">
    Set `GIT_BRANCH` to the branch you want to deploy. The default is `main`. Leave it empty to let Git use the repository's default branch.

    ```
    main
    ```
  </Step>

  <Step title="Choose a run environment">
    Set `NODE_RUN_ENV` to control how Next.js starts:

    <CodeGroup>
      ```text Production (recommended for live sites) theme={null}
      production
      ```

      ```text Development (hot-reload, for testing) theme={null}
      development
      ```
    </CodeGroup>

    In `production` mode the egg runs `next build` followed by `next start`. This produces an optimised build suitable for real traffic.

    In `development` mode the egg skips the build step and runs `next dev`, giving you hot-reload. Use this only for active development — it is slower and not optimised for production traffic.
  </Step>

  <Step title="Choose a package manager">
    Set `PACKAGE_MANAGER` to control how dependencies are installed:

    | Value                  | Behaviour                                                                              |
    | ---------------------- | -------------------------------------------------------------------------------------- |
    | `auto` *(recommended)* | Detects from lockfile: `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, otherwise npm.     |
    | `npm`                  | Always uses npm. Uses `npm ci` if `package-lock.json` exists, otherwise `npm install`. |
    | `pnpm`                 | Always uses pnpm. Installs pnpm globally if not present.                               |
    | `yarn`                 | Always uses Yarn. Installs Yarn globally if not present.                               |

    `auto` is the safest choice — it uses whichever lockfile you committed to your repo.
  </Step>

  <Step title="Start the server">
    Click **Start** in the panel. The egg will:

    1. Clone your repository (first start) or pull latest changes (if `AUTO_UPDATE=1`).
    2. Copy `.env.pterodactyl` to `.env` if the file exists in the server volume.
    3. Install dependencies using your chosen package manager.
    4. Run `next build` (production mode only).
    5. Start Next.js on the panel-allocated port.

    The panel marks the server as **Running** when it detects one of these strings in stdout:

    ```
    ready on
    started server on
    Local:        http://
    Compiled successfully
    ▲ Next.js
    ```

    <Warning>
      If your startup script suppresses or redirects stdout, the panel may never detect the ready signal and the server will stay in "Starting..." indefinitely. Make sure Next.js output reaches stdout.
    </Warning>
  </Step>
</Steps>

## Working with private repositories

If your repository is private, set two additional variables on the **Startup** tab before starting the server:

| Variable       | Value                                     |
| -------------- | ----------------------------------------- |
| `USERNAME`     | Your GitHub or GitLab username            |
| `ACCESS_TOKEN` | A personal access token with `repo` scope |

The egg injects these into the clone URL automatically. Do not embed them in `GIT_URL` itself.

<Note>
  To create a GitHub personal access token, go to **Settings → Developer settings → Personal access tokens → Tokens (classic)** and generate a token with the `repo` scope.
</Note>

## Injecting environment variables

If your app requires a `.env` file (API keys, database URLs, etc.), do not put secrets directly into panel variables. Instead:

1. Create your `.env` file locally with all required keys and values.
2. Rename it to `.env.pterodactyl`.
3. Upload it to the server's root directory (`/home/container/`) via the panel **File Manager**.
4. Start (or restart) the server — the egg copies it to `.env` before your app starts.

<Tip>
  You only need to re-upload `.env.pterodactyl` when your environment variables change. The file persists across restarts; you do not need to re-upload it every time.
</Tip>

## Auto-update behaviour

The `AUTO_UPDATE` variable controls what happens on every server start after the first clone:

| `AUTO_UPDATE`   | Behaviour                                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| `1` *(default)* | Runs `git reset --hard` then `git pull` to bring the repo up to date before installing and building.      |
| `0`             | Skips the pull. The egg installs dependencies and builds from whatever files are currently in the volume. |

Set `AUTO_UPDATE=0` if you want full control over which commit is deployed — for example, if you pin a specific commit or tag manually.