Colonel Server - Infrastructure Server Hosting

This article explains how to prepare and migrate a Next.js application so it can run using the Node.js Selector in cPanel. The procedure covers project preparation, packaging, and application setup inside cPanel.

Scope and requirements

• Node.js Selector must be available on the hosting account
• The application must use a custom Node.js server
• Next.js requires Node.js version 18.17 or newer

This workflow applies to application hosting environments such as cPanel hosting, and may require adjustments depending on the application structure.

Preparing a Next.js project for migration

If you already have an existing Next.js project, start from step 5.

Creating a sample project

1. Make sure Node.js and npm are installed locally.
2. Open a terminal and create a new project:

npx create-next-app@latest

3. Name the project nextapp and accept the default options.

Creating a custom server

Next.js must run with a custom server to work with the Node.js Selector.

1. In the project root, create a file named server.js.
2. Add the following code:

const { createServer } = require('http')
const { parse } = require('url')
const next = require('next')

const dev = process.env.NODE_ENV !== 'production'
const hostname = 'localhost'
const port = 3000
const app = next({ dev, hostname, port })
const handle = app.getRequestHandler()

app.prepare().then(() => {
  createServer(async (req, res) => {
    try {
      const parsedUrl = parse(req.url, true)
      const { pathname, query } = parsedUrl

      if (pathname === '/a') {
        await app.render(req, res, '/a', query)
      } else if (pathname === '/b') {
        await app.render(req, res, '/b', query)
      } else {
        await handle(req, res, parsedUrl)
      }
    } catch (err) {
      res.statusCode = 500
      res.end('internal server error')
    }
  }).listen(port)
})

3. Save the file.

Updating the start script

1. Open package.json.
2. Replace the start script with the following:

"start": "NODE_ENV=production node server.js"

3. Save the file.

Building and packaging the project

1. Build the application:

npm run build

2. Create a ZIP archive, excluding unnecessary files:

zip -r ../nextapp.zip . --exclude "node_modules/*" ".git/*" .gitignore README.md

The archive will be created in the parent directory.

Uploading files to cPanel

1. Log in to cPanel.
2. Open File Manager.
3. Upload nextapp.zip to your account.
4. Create a directory named nextapp inside public_html.
5. Extract the ZIP file into public_html/nextapp.

Creating the Node.js application

1. On the Tools page, click Setup Node.js App.
2. Click Create Application.
3. Select a Node.js version compatible with Next.js.
4. Set Application mode to Production.
5. Set Application root to nextapp.
6. Select your domain and leave the path empty.
7. Set Application startup file to server.js.
8. Click Create.

Installing dependencies and starting the app

1. Click Stop App if it is running.
2. Click Run NPM Install.
3. After installation completes, click Start App.

If the NPM install option is unavailable, reload the Node.js Selector page to refresh the application list.

Verifying deployment

Open your domain in a browser. The Next.js application should load successfully.

Hosting considerations

Node.js applications with higher traffic or scaling requirements may perform better on cloud servers. For workloads that require full system level control, a dedicated server provides maximum flexibility for Node.js runtime tuning.