How to Deploy a Next.js App on cPanel with Node.js Selector

This guide walks you through publishing your Next.js application on a cPanel hosting account using the Setup Node.js App feature (also called Node.js Selector). It covers getting your app ready, uploading it, configuring it in cPanel, and fixing the most common issues.

Who this is for: Anyone hosting a Next.js app (with server-side rendering or API routes) on shared, reseller, or VPS hosting that includes cPanel’s Node.js Selector.

Note: If your Next.js site is a fully static export (no server features), you don’t need Node.js Selector at all — you can host it as a regular static site. This guide is for apps that need a Node.js server to run.

---

Before You Start

Make sure:

• Your hosting plan includes Node.js Selector
• Your project is ready to upload (or you’re ready to build it)
• You know which Node.js version your app needs

---

Step 1: Build Your App on Your Own Computer First

We strongly recommend building your app on your local machine, not on the server. Here’s why:

• It’s much faster than building on shared hosting
• It avoids hitting your hosting plan’s CPU/resource limits
• It prevents timeouts during the build process
• It generally means fewer things go wrong

To build locally, open a terminal in your project folder and run:

npm install
npm run build

Once this finishes, you’ll have a .next folder — this is your compiled application, and it’s what you’ll upload to the server.

Only build directly on the server if your plan has generous resources and you’re comfortable troubleshooting if the build runs out of memory or times out.

---

Step 2: Check That Your Project Is Ready to Upload

Before uploading, make sure your project folder includes:

.next/
public/
package.json
next.config.js
server.js   (if your app uses one)

If the .next folder is missing, your app hasn’t been built yet — go back to Step 1.

Also check your package.json has a start script, for example:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "node server.js"
  }
}

(Your specific start command may differ depending on how your project is set up.)

Do not upload your node_modules folder. It’s large, unnecessary, and will be reinstalled on the server in a later step.

---

Step 3: Check Your Startup File

Most Next.js apps deployed this way use a small file — usually called server.js, app.js, or index.js — to start the server. A typical one looks like this:

const { createServer } = require("http");
const next = require("next");

const port = process.env.PORT || 3000;

const app = next({
  dev: false,
  hostname: "0.0.0.0",
  port
});

const handle = app.getRequestHandler();

app.prepare().then(() => {
  createServer((req, res) => {
    handle(req, res);
  }).listen(port);
});

Important: Your startup file should always use process.env.PORT to determine which port to listen on. Never hardcode a port number like 3000 — cPanel assigns the port automatically, and hardcoding it will cause your app to fail.

---

Step 4: Upload Your Files

Upload your project folder to your hosting account. We recommend placing it outside of public_html — cPanel will handle connecting it to your domain or subdomain in the next step.

---

Step 5: Set Up the Node.js App in cPanel

1. Log in to cPanel and open Setup Node.js App
2. Click Create Application
3. Fill in the settings:

Setting	What to Enter
Node.js Version	The version your app requires
Application Mode	Production
Application Root	The folder where you uploaded your project
Application URL	Your domain or subdomain
Startup File	server.js (or whatever your project uses)

4. Click Create

---

Step 6: Install Dependencies

Once your application is created, click Run NPM Install in the Node.js Selector interface. This installs everything your app needs to run.

(If you have SSH access, you can alternatively run npm install from your project’s directory.)

Wait for this to finish completely before moving on.

---

Step 7: Add Your Environment Variables

If your app relies on environment variables (for a database connection, authentication, an API key, etc.), you’ll need to set these up. Common examples include:

DATABASE_URL
NEXTAUTH_SECRET
NEXTAUTH_URL
API_URL

You can add these either:

• In a .env file in your application root, or
• Directly in the Environment Variables section of Node.js Selector

Whenever you add or change an environment variable, restart your application afterward so the changes take effect.

---

Step 8: Start Your Application

Back in Node.js Selector, click Restart (or Stop, then Start if it isn’t running yet).

Give it a moment, then visit your site to confirm it loads.

---

Step 9: Double-Check Everything Works

Once your site is live, go through this quick checklist:

• ✅ The website loads
• ✅ Styling (CSS) displays correctly
• ✅ Interactive features (JavaScript) work
• ✅ Images and other assets load
• ✅ API routes respond correctly
• ✅ Dynamic pages render properly
• ✅ No errors in the browser console

---

Updating Your App Later

When you make changes to your app, here’s the process:

1. Build the updated version locally: npm run build
2. Upload the changed files (including the new .next folder)
3. Run npm install again if you added new dependencies
4. Restart the application in Node.js Selector

---

Troubleshooting Common Issues

“503 Service Unavailable”

This usually means the app failed to start. Check:

• That your startup file is correctly specified in Node.js Selector
• Your application log for the specific error
• That package.json and your startup file are both present and correct
• That you selected a compatible Node.js version

“Cannot find module ‘next'” (or similar)

This means dependencies aren’t installed. Run NPM Install again from Node.js Selector, then restart the app.

The .next folder is missing

Your app was uploaded without being built. Run npm run build (locally is best) and re-upload.

Environment variables aren’t working

• Double-check spelling of variable names
• Confirm they’re saved in .env or in the Node.js Selector environment variables panel
• Restart the app after any changes — this step is easy to miss

The page loads blank

• Confirm the build completed successfully
• Confirm the app actually started (check Node.js Selector status)
• Check your browser’s console and network tab for errors

Images or other assets aren’t loading

Make sure the files exist inside your project’s public/ folder. A file at public/logo.png should be reachable at https://yourdomain.com/logo.png.

Wrong Node.js version

Confirm the Node.js version selected in cPanel is compatible with your version of Next.js. If needed, change the version, re-run NPM Install, and restart.

Port errors

Never hardcode a port number in your app (like 3000). Always use process.env.PORT, since cPanel assigns the port for you automatically.

---

Frequently Asked Questions

Do I need to upload node_modules? No — just run NPM Install in Node.js Selector after uploading, and it will install everything for you.

Do I need to upload the .next folder? Yes, if you built your app locally (which we recommend). If you didn’t build it before uploading, you’ll need to run npm run build on the server instead.

Should I build my app directly on the server? We recommend against it unless necessary. Building locally is faster, avoids resource limits on shared hosting, and leads to fewer issues overall.

Can I run Next.js without Node.js Selector? Only if your app is a fully static export with no server-side rendering or API routes. Any app using SSR or API routes needs a Node.js runtime, which is what Node.js Selector provides.

---

Still Stuck?

If you’ve gone through this guide and your app still isn’t working, open a support ticket — it’ll help us resolve things faster.