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

# Deploy Next.js

> Run a Next.js app on the Node.js Selector with a custom server, Passenger-friendly handler, and a production build.

Next.js doesn't ship with a Passenger-compatible startup by default. The fix: a custom server that exports a Node `http` handler.

For the underlying tool, see [Node.js](/web-hosting/virtual-containers/nodejs).

## Before you begin

* A Node.js app already created in cPanel, version 20 or 22.
* The app root contains your Next project (`package.json`, `pages/` or `app/`, `next.config.js`).
* SSH access (recommended for builds).

## Build for production

Builds can OOM under the cPanel UI on a 1 GB plan. Build over SSH:

```bash theme={}
source ~/nodevenv/myapp/22/bin/activate && cd ~/myapp
npm install
npm run build
```

Check `next` is in `dependencies`, not `devDependencies`.

## Add a Passenger-compatible server

<Steps>
  <Step title="Create server.js in the app root">
    ```js server.js theme={}
    const http = require('http');
    const next = require('next');

    const app = next({ dev: false });
    const handle = app.getRequestHandler();

    module.exports = (async () => {
      await app.prepare();
      return http.createServer((req, res) => handle(req, res));
    })();
    ```
  </Step>

  <Step title="Set the startup file">
    In cPanel, **Setup Node.js App** → **Edit** → **Application startup file**: `server.js`. Save.
  </Step>

  <Step title="Restart">
    Click **Restart**, or `touch ~/myapp/tmp/restart.txt`.
  </Step>
</Steps>

## Common issues

<AccordionGroup>
  <Accordion title="`next: command not found` during build">
    Move `next` from `devDependencies` into `dependencies` and re-run `npm install`.
  </Accordion>

  <Accordion title="Build OOMs">
    Build on a dev machine instead, then rsync `.next/` and `public/` up. Skip building on the server entirely.
  </Accordion>

  <Accordion title="API routes return 404">
    The custom server above hands every request to Next. If you wrap routes in custom Express middleware, make sure the catch-all delegates back to `handle(req, res)`.
  </Accordion>
</AccordionGroup>

## Need a hand?

<CardGroup cols={2}>
  <Card title="Open a ticket" icon="life-ring" href="https://members.noxity.io/submitticket.php">
    Best for anything that needs an account check or a config change on our end.
  </Card>

  <Card title="Live chat" icon="messages" href="https://noxity.io/contact">
    Faster for quick questions during business hours.
  </Card>
</CardGroup>