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

This article covers Next.js applications configured to use standalone output. If you are using a custom server.jsconfiguration instead, see 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:

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

module.exports = nextConfig

If you use next.config.mjs, use:

const nextConfig = {
  output: 'standalone',
}

export default nextConfig

For more information, see the official Next.js output documentation.

Build your application

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

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:

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:

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:

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

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

Compress the contents of your .next/standalone directory into a ZIP file.
Log in to cPanel.
Open File Manager.
Create a directory for your application, for example:
nextapp
Upload the ZIP file to the application directory.
Extract the ZIP file.
Confirm that the generated server.js file is present in the application directory.
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:

In cPanel, open Setup Node.js App.
Click CREATE APPLICATION.
In the Node.js version list, select a version supported by your Next.js application.
Set Application mode to Production.
Set Application root to the directory containing your standalone application.
Select your domain under Application URL.
Set Application startup file to:
server.js
Add any required environment variables.
Click CREATE.
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:

Make sure sharp is included in your application’s dependencies.
Install it before creating the production build.
Build the application in an environment compatible with the production server.
Test the standalone application before uploading it.

For example:

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.

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.

Redeploy your application

When you need to deploy an updated version:

Build the updated application in your build environment.
Prepare the new standalone output.
Copy public and .next/static into the standalone directory if required.
Create a new ZIP file from the standalone output.
Upload and extract the updated files to your application directory.
Make sure the updated server.js and .next files are present.
Restart the application in Setup Node.js App.
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. For information about Sharp installation and platform compatibility, see the Sharp installation documentation.

Using hosting.com

Other hosting panels

Using your software

Unmanaged cloud servers

Resellers

Developers

Add-on services

Hosting.com products

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

Before you begin

Configure Next.js for standalone output

Build your application

Prepare the application files

Build for a compatible environment

Upload the application to cPanel

Create the Node.js application

Environment variables

Using Sharp for image processing

Application resources and limitations

Scheduled tasks

Redeploy your application

Troubleshooting

More information

​Before you begin

​Configure Next.js for standalone output

​Build your application

​Prepare the application files

​Build for a compatible environment

​Upload the application to cPanel

​Create the Node.js application

​Environment variables

​Using Sharp for image processing

​Application resources and limitations

​Scheduled tasks

​Redeploy your application

​Troubleshooting

​More information

Before you begin

Configure Next.js for standalone output

Build your application

Prepare the application files

Build for a compatible environment

Upload the application to cPanel

Create the Node.js application

Environment variables

Using Sharp for image processing

Application resources and limitations

Scheduled tasks

Redeploy your application

Troubleshooting

More information