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.

---

📦 Changing Next.js build folder (.next → dist)

By default, Next.js outputs build files into the .next directory. In some cases (deployment, conventions, integrations), you may want to use a folder like dist instead.

1. Edit next.config.js

const nextConfig = {
  distDir: 'dist',
}

2. Run the build

npm run build

📁 Result

Before:

.next/

After:

dist/

---

📦 TypeScript requirement (important)

If your project uses TypeScript, make sure it is installed under dependencies instead of devDependencies.

Some deployment environments only install production dependencies, which can cause build failures if TypeScript is missing.

✅ Correct example

{
  "dependencies": {
    "typescript": "^5.0.0"
  }
}

❌ Incorrect example

{
  "devDependencies": {
    "typescript": "^5.0.0"
  }
}

---

✅ 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)

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

🧾 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)

MAIN=out/index.html
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
├─ index.ts
├─ 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.