Migrating an Existing Node.js Application

If you're moving a Node.js application that was originally developed on your local machine or on a VPS, you’ll likely need to make a few small adjustments before it will run successfully under cPanel’s Node.js Selector.

This is because the Node.js Selector runs your app within a managed hosting environment that uses Phusion Passenger to handle both routing and process management. Unlike local setups where your app may run its own web server and binds to a custom port like 3000, this environment:

• Does not allow custom ports — apps cannot listen on 3000, 8080, etc.
• Does not use your npm start script — it uses the startup file you define in cPanel
• Requires your app to export a handler, not run a standalone HTTP server

Additionally, some apps written using ES module syntax (import/export) may need changes depending on the Node.js version in use and how the app is structured.

This guide will walk you through how to adapt your existing app to work in this environment — including setting it up correctly, modifying the startup script if needed, and handling route paths if you're deploying under a subdirectory.

By the end, your app should run smoothly under the Node.js Selector, just like it did locally or on your previous host.

Navigation

• Step 1: Create the App First
• Step 2: Upload Your Application
• Step 3: Adjust the Startup Script
  • Remove Hardcoded Ports
    • Option A: Export the App
    • Option B: Use a Dynamic Port
  • Switch import to require (if needed)
• Step 4: Finalise and Restart
• Tips for Route Handling
  • What Can Go Wrong
  • Fix 1: Prefix Routes Manually
  • Fix 2: Use a Router with a Mount Point

Step 1: Create the App First

Even if you have all your files ready to go:

• Start by creating a new application in cPanel using the Node.js Selector, or set up your app via commandline.
• Define the Application Root as the directory you'll upload your app into.
• Specify the Startup File — e.g. app.js or server.js. The startup script you define here must match the actual filename of your app’s main entry point.

This ensures your environment is ready before uploading code, avoiding conflicts or permission errors.

Step 2: Upload Your Application

Once the app is created:

• Use File Manager, Git, SFTP (etc.) to upload your application files into the application root directory you selected in Step 1.
• Make sure to include your package.json.

Step 3: Adjust the Startup Script

Most apps developed elsewhere will:

• Try to bind to a specific port (e.g. 3000 or 3001)
• Use ES module syntax (import) instead of require

Remove Hardcoded Ports

You must not use app.listen(3000) or any other port in your code under Passenger.

Instead, you have two options:

Option A: Export the App

This is the recommended and cleanest approach:

const express = require('express');
const app = express();

app.get('/', (req, res) => res.send('Hello World!'));

// Don't listen! Just export.
module.exports = app;

Passenger will automatically start your app and connect incoming requests to it.

Option B: Use a Dynamic Port

If you absolutely need to call app.listen() (e.g. the framework expects it), you can tell Node to choose a port dynamically:

const express = require('express');
const app = express();

app.get('/', (req, res) => res.send('Hello World!'));

const server = app.listen(0, () => {
    console.log('App running on port', server.address().port);
});

0 tells Node.js to pick any available port, which satisfies Passenger without causing conflicts.

Switch import to require (if needed)

If your app uses ES module syntax (e.g. import express from 'express';), and you encounter errors:

Replace import with require:

// Old:
import express from 'express';

// New:
const express = require('express');

This change improves compatibility across different Node.js versions.

Step 4: Finalise and Restart

• Check for a package.json file
  Your application should include a package.json file in the root directory (the one you set as the Application Root in cPanel). This file lists the packages (like Express) that your app depends on.
• Run NPM Install in cPanel
  Go to Setup Node.js App in cPanel, click the pencil icon to edit your app, then click Run NPM Install. This installs all dependencies listed in your package.json into your app's private environment.
• Restart the Application
  Still in the Node.js Selector screen, click Restart to ensure your changes take effect and your app is reloaded with the correct environment.
• Visit Your Application URL
  Load your app in the browser using the Application URL you configured. If everything is set up correctly, you should see your application running.

Tips for Route Handling

If your application is configured to run from a subdirectory — for example, https://example.com/myapp — then your routes must match that structure.

This is because the Node.js Selector mounts your application at the exact URL path you define in the Application URL field. It doesn’t treat / as the root path by default — it treats /myapp as the entry point.

What Can Go Wrong

If your route is written like this:

app.get('/', (req, res) => res.send('Hello!'));

It will only respond to requests at https://example.com/ — but if your app is mounted at https://example.com/myapp, this route will not be reached. Instead, you'll see an error like:

Cannot GET /myapp

Fix 1: Prefix Routes Manually

You can rewrite your routes to include the subdirectory:

app.get('/myapp', (req, res) => res.send('Hello from myapp!'));
app.get('/myapp/test', (req, res) => res.send('This is /test'));

Fix 2: Use a Router with a Mount Point

A cleaner way is to use a router and mount it at the subdirectory path:

const express = require('express');
const app = express();
const router = express.Router();

router.get('/', (req, res) => res.send('Hello from root!'));
router.get('/test', (req, res) => res.send('This is /test'));

app.use('/myapp', router);

This keeps your routing code clean and avoids repeating /myapp throughout.