Web Hosting

How to Deploy a Node.js Application on Plesk

Deploy your Node.js or Next.js application on your Winheberg Plesk web hosting, automatic configuration, source protection, LTS version, dependencies, build, variables and secrets.

November 1, 2026 Winheberg
Documentation›Web Hosting›How to Deploy a Node.js Application on Plesk

Context

Winheberg web hosting runs on Plesk and supports Node.js applications, whether an API, a backend or a Next.js project. Deployment differs from a classic PHP website, because the application runs in its own process managed by Phusion Passenger, not as a set of files served directly by the web server.

As soon as your files are in place, Plesk reads your package.json, recognises the application type and offers an automatic configuration. It generates the startup file Passenger expects and shows you the list of changes before applying them.

This guide follows that automatic path, then details the manual configuration for cases where detection does not succeed.

The Winheberg Plesk panel is displayed in French. Menu, field and button names are quoted below exactly as they appear on screen, followed by their English meaning.

Prerequisites

SSH access is not available on web hosting plans. Every operation described here is done from the Plesk interface, npm commands included.

1. Test the project locally

Before uploading anything, check that your application builds and starts on your machine.

npm install
npm run build
npm run start

If any of these commands fails locally, it will fail on the server too. Fix it before going further, troubleshooting is far easier on your own machine. If your project has no build step, only the first and last commands apply.

2. Upload the application files

Compress your sources into a .zip archive, without the node_modules and .next folders. They will be regenerated on the server, and uploading them causes platform incompatibilities on top of a needlessly long transfer.

Open Fichiers (Files) in the side menu, go into httpdocs, click + then Téléverser le fichier (Upload file). Once the archive is uploaded, select it and extract it in place from the Archive menu.

Upload file menu of the Plesk file manager in httpdocs

After extraction, check that the package.json file sits directly in httpdocs and not in an intermediate subfolder.

The order of these steps matters. Plesk only detects the application type and offers automatic configuration when package.json is already in place. On an empty domain, you will have to fill everything in by hand.

3. Run the automatic configuration

From Sites Web & Domaines (Websites & Domains), open your domain, the Démarrer (Get started) tab, then Node.js. Plesk displays the Type d'application (Application type) detected from package.json and the Configurer automatiquement (Configure automatically) button.

Detected application type and Configure automatically button in Node.js

Click Configurer automatiquement. Plesk lists what it is about to change before applying anything, for instance the creation of the .plesk.startup.cjs startup file that loads your entry point, and setting aside a static index.html that would otherwise be served instead of your application.

Configure hosting automatically window with the Apply and restart button

Review that list, then click Appliquer et redémarrer (Apply and restart). The original index.html file is kept as index.html.autoconfig-bak.

There is no need to change the port written in your code. Passenger intercepts your application's listen() call and binds it to its own channel, whatever port is set. The .plesk.startup.cjs file says so in a comment, do not edit or delete it.

4. Protect your source files

With the automatic configuration, the Racine du document (Document root) often stays the same as the Root d'application (Application root), namely /httpdocs. The web server then serves any file in that folder directly, including package.json and your application code, which anyone can download by knowing its name.

Plesk itself points this out on the dashboard as long as Node.js is not enabled, recommending a document root set to a subfolder of the application root, such as public/.

Create a public folder inside httpdocs from the file manager. On the Node.js dashboard, then click the folder icon next to Racine du document, select public under httpdocs in the tree, and click Enregistrer (Save). Only put in that folder the files meant to be served as they are, such as images or stylesheets.

Never hard code a password or an API key in your code. Use the Secrets of the Environnement (Environment) tab, covered in step 8.

5. Check the version and application mode

Once the configuration is applied, the dashboard shows the Redémarrer l'app (Restart app), Arrêter l'app (Stop app) and Désactiver Node.js (Disable Node.js) buttons. If the Activer Node.js (Enable Node.js) button is still there, click it.

Then click the pencil next to Version de Node.js (Node.js version), pick the version your project needs, and Enregistrer. While you are there, check that Mode d'application (Application mode) is set to production, this setting drives your application's NODE_ENV and PASSENGER_APP_ENV variables.

Node.js version selector and production application mode

Which version to pick

The versions on offer are not equal. An LTS version receives security fixes for several years, whereas odd versions such as 23.x or 21.x never became LTS and are no longer maintained.

Node.js versions offered by Plesk, status as of November 1, 2026
Version Status End of support
26.x Active LTS since October 28, 2026 April 30, 2029
24.x Maintenance LTS since October 20, 2026 April 30, 2028
23.x No longer maintained June 1, 2025
22.x Maintenance LTS April 30, 2027
21.x No longer maintained June 1, 2024
20.x No longer maintained April 30, 2026
18.x No longer maintained April 30, 2025

Go for 26.x on a new project, it is the active LTS branch. Keep 24.x if one of your dependencies is not compatible yet, it keeps receiving fixes until April 2028.

The 23.x, 21.x, 20.x and 18.x branches no longer receive security fixes. Avoid them for an application exposed to the Internet, even if your code runs on them.

A version that is too old also makes most recent frameworks fail to build, with a message that does not always name the culprit version. Next.js 16, for instance, requires at least Node.js 20.9.

6. Install the dependencies

Click Installer NPM (NPM install), or open the Exécuter les commandes Node.js (Run Node.js commands) tab and pick install from the list. Plesk reads your package.json and rebuilds the node_modules folder on the server.

Run Node.js commands tab with the list of package.json scripts and npm commands

The Sortie de la commande (Command output) shows the result. Wait for the operation to finish before moving on, on a large project the installation takes several minutes.

npm install command output in Plesk

Plesk also supports Yarn and pnpm. Click the pencil next to Gestionnaire de packages (Package manager) on the dashboard to pick npm, yarn or pnpm.

7. Run the build

Click Démarrer le script (Run script). Plesk opens the Exécuter les commandes Node.js tab, whose Scripts du package.json (package.json scripts) list shows your project scripts. Pick run build.

For a Next.js project, this step generates the .next folder, the one you deliberately did not upload. Building on the server rather than uploading a build made on your machine avoids architecture incompatibilities.

For Next.js, this step is mandatory. Starting the application without a build produces the error Could not find a production build in the '.next' directory.

8. Declare the environment variables

Open the Environnement tab. It separates two kinds of values passed to your application.

Node.js Environment tab with environment variables and secrets
Variables in the Environment tab
Section on screen Use
Variables d'environnement (Environment variables) Non sensitive settings, visible to anyone who opens this page
Secrets Passwords, API keys and tokens, stored encrypted and write only, their value is never displayed again once saved
Variables prédéfinies (Predefined variables) NODE_ENV, PASSENGER_APP_ENV, NODE_PATH and IN_PASSENGER, set by Passenger, a variable with the same name declared above takes precedence

Add your values with Ajouter un champ (Add field), click Enregistrer, then Redémarrer l'app from the dashboard so the application picks them up.

With Next.js, variables prefixed with NEXT_PUBLIC_ are embedded in the code at build time. Put them in a .env.production file at the application root before running step 7, and only keep there values you accept to make public.

9. Start the application

Click Redémarrer l'app, then open your domain in a browser. As long as nobody has visited it, the Statut (Status) reads Inactif (Idle), the application starts on the first request. It then switches to En cours d'exécution (Running), with the process count and the start time.

Active Node.js dashboard with the Restart app, NPM install and Run script buttons

Manual configuration

If your package.json was not in place when you opened the Node.js page, or if detection did not recognise your project, fill in the fields yourself from the Node.js dashboard.

Fields to fill in
Field on screen Value Role
Root d'application /httpdocs The folder holding package.json
Racine du document /httpdocs/public The folder of files served as they are, kept apart from your sources
Fichier de démarrage d'application (Application startup file) The file Passenger runs, app.js by default Your application entry point

Passenger starts a JavaScript file, it does not run npm start. When an application is usually launched through an npm command, open package.json and find the file passed to node, that is the one to declare. For an Express application or any hand written Node.js code, that file already exists, often app.js, server.js or index.js.

For Next.js, it does not exist. The next start command calls a framework binary, not a file from your project. Create a start.js file at your application root with the following content.

process.env.NODE_ENV = 'production';

const app = require('next/dist/cli/next-start');

app.nextStart({
  port: process.env.PORT || 3000,
});

Then declare start.js in Fichier de démarrage d'application and click Redémarrer l'app.

If your package.json contains "type": "module", the require statement above fails. Name your file start.cjs instead of start.js, the .cjs extension forces CommonJS interpretation, then declare that name in the startup file field.

Troubleshooting

❌ Could not find a production build in the '.next' directory

The build was not run, or it failed without you noticing.

  • Run run build again from Démarrer le script and read the Sortie de la commande to the end
  • Check that the .next folder exists in the application root
  • Make sure Root d'application points to the folder holding package.json

❌ require() of ES Module is not supported

Your project is declared as an ES module, which makes the require statement unusable in a .js startup file.

  • Rename your startup file with the .cjs extension
  • Report that new name in Fichier de démarrage d'application
  • Restart the application with Redémarrer l'app

❌ The application process exited prematurely

The process failed to start.

  • Check that the startup file really exists at the application root
  • Make sure the dependencies were installed, the install Sortie de la commande must show no error
  • Look for a missing environment variable or secret in the Environnement tab
  • Confirm that Mode d'application is set to production

❌ Your source files show up in the browser

The Racine du document is the same as the Root d'application, so the web server serves your sources directly.

  • Create a public folder in the application root
  • Set /httpdocs/public as Racine du document from the Node.js dashboard
  • Restart the application, then open your website with /package.json added at the end of its address, the file must no longer show up

Best practices

  • Upload your files before opening the Node.js page, that is what enables detection and automatic configuration
  • Always validate npm run build locally before uploading anything
  • Keep node_modules and .next out of your uploads, they are regenerated on the server
  • Run the build again then Redémarrer l'app after every code update
  • Stay on an LTS version of Node.js and switch branch before its end of support
  • Store passwords and API keys in the Secrets, never in the code nor in a file served by the website
  • If you change framework, run Configurer automatiquement again so Plesk regenerates the startup file
  • Serve your application over HTTPS with the free certificate described in our guide How to Generate a Let's Encrypt SSL Certificate for Your Website
  • To hand the deployment over to a developer without opening your whole account, give them a dedicated access with our guide How to Create a User in Plesk

Need help?

If your application still does not start after these checks, open a ticket with our support from your client area, Technical department, filling in the Related Product field with the hosting concerned.

Attach the full error message along with the build output. Our team can also read the Passenger log on the server side, which often holds the exact cause of a failed start.

Your application is live 🚀

Need a Web Hosting server?

Discover our offers tailored to your needs and get started now.

View offers