Next.js

Practical guide to host Next.js applications on Discloud.

🧭 Introduction

This step-by-step guide shows how to prepare, configure, and deploy a Next.js application on Discloud.

There are two main approaches:

• Option A (recommended) – use next build + next start without a custom server (only the built-in Next.js server).

• Option B – use a custom server with Express, useful when you need extra routes, custom middleware, or specific integrations.

Additionally, we show an alternative with static export, ideal for purely static websites.

This guide assumes you already have a Next.js project running locally.

---

📋 Requirements

A Platinum plan or higher is required to host websites or APIs.

A subdomain must be created before deployment.

Port 8080 is mandatory – applications must listen on this port.

---

🧱 Local prerequisites

Before continuing, you will need:

• Node.js installed on your machine.

• A Next.js project created (e.g. npx create-next-app).

• A Discloud account with a configured subdomain.

• Optionally: Git, VSCode, and/or the Discloud CLI to make the workflow easier.

If you are not yet familiar with the local environment, check:

NodeJS

---

🧹 Preparing project files

Before compressing your project into a .zip, create a .discloudignore file in the project root to exclude unnecessary files and folders from the upload:

node_modules/
dist/
.next/
.env
.env.local
.git
package-lock.json

The .discloudignore file works similarly to .gitignore, but it is used by Discloud to ignore files at upload time.

---

📦 package.json – recommended scripts

Inside your package.json, make sure the main Next.js scripts are defined. A basic example:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -p 8080",
    "export": "next export"
  }
}

It is important that the start script uses port 8080 (next start -p 8080), as this is the default port required by Discloud for websites.

---

✅ Option A – Deploy without custom server (Next.js "built-in")

In this option you only use the internal Next server (next start), without needing a server.js.

🔁 Basic flow

1. Run the build locally (optional but recommended):

   npm run build

2. Test locally:

   npm run start

3. If everything works, prepare the .zip and upload it to Discloud.

⚙️ discloud.config (example)

TYPE=site
BUILD=npm run build
START=npm run start
RAM=512
VERSION=latest
ID=my-nextjs-app

🧩 Option B – Custom server with Express

If you need custom routes, middleware, or to integrate other libs before delegating to Next, you can use an Express server that runs Next internally.

🧾 server.js

Create a server.js file in the project root with the following content:

const express = require("express");
const next = require("next");

const dev = process.env.NODE_ENV !== "production";
const app = next({ dev });
const handle = app.getRequestHandler();

const PORT = process.env.PORT || 8080;

app.prepare().then(() => {
  const server = express();

  server.get("/hello", (req, res) => {
    return res.send("Hello, Discloud!");
  });

  server.all("*", (req, res) => {
    return handle(req, res);
  });

  server.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
  });
});

📦 package.json (with custom server)

Update your scripts to use server.js in production:

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

⚙️ discloud.config (custom server)

TYPE=site
MAIN=server.js
BUILD=npm run build
START=npm run start
RAM=512
VERSION=latest
ID=my-nextjs-app-custom-server

Use this option only if you really need a custom server. For most projects, Option A (no custom server) is simpler and sufficient.

🧾 Alternative – Static export (Next.js as a static site)

If your project does not depend on SSR or API Routes, you can use next export to generate a fully static site.

📦 package.json (static export)

{
  "scripts": {
    "dev": "next dev",
    "build": "next build && next export",
    "start": "npx serve -s out -l 8080"
  }
}

⚙️ discloud.config (static)

TYPE=site
BUILD=npm run build
START=npm run start
RAM=256
ID=my-static-site

Static sites usually consume less RAM and are ideal for blogs, landing pages, and simple documentation.

---

🔐 Environment variables

In Next.js, public environment variables must start with NEXT_PUBLIC_.

• Define variables via the Discloud Dashboard, CLI, or API.

• Everything that starts with NEXT_PUBLIC_ is embedded into the bundle during the build.

Example:

NEXT_PUBLIC_API_URL=https://my-backend.discloud.app
API_SECRET_TOKEN=do-not-put-in-frontend

Using in components:

const apiUrl = process.env.NEXT_PUBLIC_API_URL;

---

🗂️ Recommended final project structure

A typical Next.js project structure for Discloud might look like:

my-next-app/
├─ discloud.config
├─ .discloudignore
├─ package.json
├─ next.config.js
├─ server.js        # optional (only in Option B)
├─ public/
└─ app/ or pages/
	 ├─ page.js
	 └─ api/
			└─ hello.js

---

🚀 Deploying to Discloud

You can deploy your Next.js app using any of the supported methods.

DashboardDiscord BotVisual Studio CodeCLI

---

🛠️ Troubleshooting (common errors)

App does not open / wrong port	Check if Next is using port 8080 (next start -p 8080 or PORT=8080).
Plan / permission error	Confirm that your account has the correct plan for websites/APIs.
Subdomain not configured	Make sure you followed the subdomain guide before deploying.
Build errors	Run locally: npm run build and fix any errors before uploading. Check that all dependencies are listed in package.json.
Errors when starting (START)	Verify that the start script is correct. Follow the Discloud logs to see the exact error message.