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

# How to Deploy a Pre-Built Next.js App in cPanel

> If you build your Next.js application locally or in another build environment, you can deploy the pre-built production application to cPanel and run it using Setup Node.js App.

This article covers Next.js applications configured to use **standalone output**. If you are using a custom `server.js`configuration instead, see [**Migrating a Next.js application to the Node.js Selector in cPanel**](https://kb.hosting.com/docs/migrating-a-next-js-application-to-the-node-js-selector-in-cpanel).

## Before you begin

Before deploying your application, make sure:

* Your cPanel account has a Node.js version that meets your Next.js application's requirements.
* Your application builds and runs correctly in production mode.
* Your application is configured to use standalone output.
* You can build the application in an environment compatible with the cPanel server, particularly if your application uses native packages such as Sharp.
* Your application can run within the CPU, memory, process, and other resource limits of your hosting plan.

## Configure Next.js for standalone output

Next.js can generate a standalone production package containing the files and dependencies required to run your application.

In your Next.js project, add `output: 'standalone'` to your `next.config.js` or `next.config.mjs` file.

For example:

```text theme={null}
/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
}

module.exports = nextConfig
```

If you use `next.config.mjs`, use:

```text theme={null}
const nextConfig = {
  output: 'standalone',
}

export default nextConfig
```

For more information, see the official [**Next.js output documentation**](https://nextjs.org/docs/app/api-reference/config/next-config-js/output).

## Build your application

Run the production build in your local development or build environment:

```text theme={null}
npm run build
```

When the build is complete, Next.js creates a `.next/standalone` directory containing a minimal production package and a `server.js` file that can be used to start the application. The standalone output also includes the dependencies traced as required by the application.

You can test the standalone application locally by running:

```text theme={null}
cd .next/standalone
node server.js
```

Open the application in your browser and confirm that it works correctly before uploading it to cPanel.

> 📘 **Important**
>
> The `server.js` generated by the standalone build is different from the custom `server.js` used in the standard Next.js migration procedure. Use the `server.js` generated by your standalone build.

## Prepare the application files

The standalone output does not automatically include the `public` directory or `.next/static`.

If your application uses these directories, copy them into the standalone directory before deploying:

```text theme={null}
public → .next/standalone/public
.next/static → .next/standalone/.next/static
```

Your deployment directory should contain the generated `server.js`, the traced dependencies, and the required application files.

For example:

```text theme={null}
.next/standalone/
├── server.js
├── package.json
├── node_modules/
├── .next/
│   └── static/
└── public/
```

The exact structure may vary depending on your application and Next.js configuration.

> 📘 **Note**
>
> If you use a monorepo or configure `outputFileTracingRoot`, the generated `server.js` may be located in a subdirectory of `.next/standalone`. Use the location of the generated `server.js` when configuring the application in cPanel.

For more information, see the official [**Next.js output documentation**](https://nextjs.org/docs/app/api-reference/config/next-config-js/output).

## Build for a compatible environment

Standalone output includes dependencies that may contain platform-specific native binaries.

This is particularly important when your application uses packages such as **Sharp**.

For example, a build created on macOS or Windows may contain native binaries that are not compatible with a Linux hosting server.

For the most reliable deployment:

* Build the application on a Linux environment compatible with the hosting server.
* If using CI/CD, use a Linux build environment.
* Use the same Node.js major version for the build and the cPanel application where possible.
* Test the standalone output before uploading it.

Sharp provides prebuilt binaries for common operating systems and CPU architectures, but the correct platform-specific package must be available for the environment where the application runs.

## Upload the application to cPanel

1. Compress the **contents** of your `.next/standalone` directory into a ZIP file.
2. Log in to cPanel.
3. Open **File Manager**.
4. Create a directory for your application, for example:
   ```text theme={null}
   nextapp
   ```
5. Upload the ZIP file to the application directory.
6. Extract the ZIP file.
7. Confirm that the generated `server.js` file is present in the application directory.
8. If your application uses `public` or `.next/static`, confirm that these directories were copied into the standalone output before it was uploaded.

> 📘 **Important**
>
> Make sure hidden files and directories, including `.next`, are included when preparing and uploading your application.

You generally do **not** need to upload your original project or your full local `node_modules` directory. The standalone output contains the dependencies traced as required by the application.

## Create the Node.js application

After uploading your application:

1. In cPanel, open **Setup Node.js App**.
2. Click **CREATE APPLICATION**.
3. In the **Node.js version** list, select a version supported by your Next.js application.
4. Set **Application mode** to **Production**.
5. Set **Application root** to the directory containing your standalone application.
6. Select your domain under **Application URL**.
7. Set **Application startup file** to:
   ```text theme={null}
   server.js
   ```
8. Add any required **environment variables**.
9. Click **CREATE**.
10. Click **START APP**.

> 📘 **Important**
>
> Do not use **Run NPM Install** for the standalone deployment package unless your application specifically requires an additional installation step. The standalone output is designed to run using the dependencies included in the generated package.

Open your domain in a browser and confirm that the application loads correctly.

## Environment variables

Your application may require environment variables such as database connection details, API keys, or other configuration values.

Add runtime environment variables through the Node.js application's environment settings in cPanel.

If your application uses `NEXT_PUBLIC_*` variables, remember that values used by client-side code are generally included during the build process. If you change these values after building the application, you may need to rebuild the application before deploying it again.

## Using Sharp for image processing

Next.js applications may use **Sharp** for image optimization and image processing.

Sharp provides prebuilt binaries that include the required `libvips` components for many common platforms. It does not automatically mean that a separate system-level `libvips` installation is required.

If your application uses Sharp:

1. Make sure `sharp` is included in your application's dependencies.
2. Install it before creating the production build.
3. Build the application in an environment compatible with the production server.
4. Test the standalone application before uploading it.

For example:

```text theme={null}
npm install sharp
npm run build
```

If Sharp fails after deployment, check the application logs for the specific error.

Common causes include:

* An incompatible native binary
* A mismatch between the build environment and the hosting environment
* An unsupported Node.js version
* A missing platform-specific dependency

If the required binary or system dependency is not compatible with the shared hosting environment, contact Support to determine whether the application can be supported on the current server or whether another hosting environment is required.

> 📘 **Note**
>
> Do not assume that installing Sharp alone will resolve every native dependency issue. Sharp selects platform-specific binaries during installation, so the environment used to build and run the application matters.

## Application resources and limitations

Building your Next.js application locally does not remove the resources required to run it on the hosting server.

Once deployed, a standalone application still runs as a Node.js application and is subject to the resources and process limits of the hosting environment.

On shared cPanel hosting, these limits can affect applications that require significant or continuous resources, including:

* CPU usage
* Memory usage
* Number of running processes
* Concurrent requests
* Background processing
* Long-running tasks

If your application consistently requires more resources than the shared environment provides, a VPS may be more appropriate.

For more information about running continuous Node.js applications and resource considerations, see [**Creating persistent Node.js applications**](https://kb.hosting.com/docs/making-persistent-node-js-applications).

## Scheduled tasks

If your application requires scheduled maintenance or cleanup tasks, you can use cPanel **Cron Jobs**.

For example, a cron job can be used to:

* Run scheduled maintenance
* Clean up temporary files
* Remove files that are no longer required
* Run other scheduled application tasks

If a scheduled task needs to use Node.js, configure the cron command to use the Node.js environment associated with your application rather than relying on the system default Node.js installation.

For more information about running persistent Node.js applications and using Cron Jobs, see [**Creating persistent Node.js applications**](https://kb.hosting.com/docs/making-persistent-node-js-applications).

## Redeploy your application

When you need to deploy an updated version:

1. Build the updated application in your build environment.
2. Prepare the new standalone output.
3. Copy `public` and `.next/static` into the standalone directory if required.
4. Create a new ZIP file from the standalone output.
5. Upload and extract the updated files to your application directory.
6. Make sure the updated `server.js` and `.next` files are present.
7. Restart the application in **Setup Node.js App**.
8. Test the application.

When replacing an existing deployment, make sure old files do not remain if they are no longer part of the new build.

## Troubleshooting

If your standalone application does not start or does not work correctly:

| Problem | What to check |
| :- | :- |
| Application does not start | Confirm the Node.js version, application root, and `server.js` startup file |
| Error mentioning Sharp or a native binary | Confirm the application was built for a compatible Linux environment and Node.js version |
| CSS, JavaScript, or images return 404 errors | Confirm that `.next/static` and `public` were copied into the standalone directory |
| Application changes do not appear | Restart the Node.js application after deploying the updated files |
| Environment variables are not working | Confirm runtime variables are configured in cPanel and rebuild when changing build-time `NEXT_PUBLIC_*` values |
| Application crashes or becomes unavailable | Check the application logs and whether the hosting plan's CPU, memory, or process limits are being reached |
| Scheduled task does not run | Confirm the Cron Job command uses the correct Node.js environment |

## More information

For more information about standalone output, see the official [**Next.js output documentation**](https://nextjs.org/docs/app/api-reference/config/next-config-js/output).

For information about Sharp installation and platform compatibility, see the [**Sharp installation documentation**](https://sharp.pixelplumbing.com/install/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.