How to deploy Next.js on Saplo

Today, Next.js is the default choice if you're building a React website or app that needs to load quickly and perform well in search results. Server-side rendering and App Router make a difference that a classic SPA application, made up of just a static build, can't provide. The problem is that such an application needs a running Node.js process in the background, not just a directory with HTML files, so setting it up on regular shared hosting usually fails. On Saplo, you set up Next.js like any other application from the catalog, and Saplo immediately runs it as a managed service with automatic restarts. Below, we show you how to do this from scratch, including connecting your own Git repository.

Who is Next.js on Saplo for?

Before you start the installation, check if it's the right choice for your project:

• You have or are building a Next.js project with App Router - Saplo detects the project structure and runs next start as a service; you don't need to write pm2 or systemd configs yourself.
• You need SSR or ISR, not just a static build - If your site is fully static, a React or Astro stack from the same App catalog will be cheaper and lighter.
• You want deployments with git push instead of manual file uploads - You connect the repository once, and every push to the production branch automatically builds and deploys a new version.
• Your hosting bill for a project currently on Vercel or Netlify is growing - You migrate the code one-to-one, next.config.* remains unchanged, and you pay for Box instead of function usage.

If your project is pure frontend without the need for server-side rendering, check out the React or Astro stack in the App catalog; both are lighter and cheaper to maintain.

Requirements

To set up Next.js on Saplo, you need:

• A Box on the L plan or higher - Saplo officially recommends this level for Next.js, because server-side rendering requires more RAM than a regular static site. Lower plans are only sufficient for very small test traffic.
• A minimum of 512 MB of free RAM and 2 GB of disk space for the application process itself.
• A domain or subdomain *.saploapp.pl included with every plan, where the application will be hosted.
• A Git repository on GitHub, GitLab, or Bitbucket if you want to use automatic deployment (optional to start, you can also upload the application as an archive .zip via the panel).
• You usually do not need a separate database, unless your application connects to one. Saplo does not impose this on you.

Step-by-step installation

1. In your Saplo panel, go to App catalog and select Next.js (under the "Frameworks" category).
2. Select a Box plan L or higher, and an application name. This will create a default subdomain <name>.saploapp.pl. You can add your own Domain now or later.
3. Confirm the installation. The engine provisions the module on Box and launches the Next.js starter boilerplate (equivalent to create-next-app), so you have something to see under your Domain right away, before you deploy your own code.
4. Saplo runs the application as a managed service with automatic restarts, and nginx on Box directs traffic from the Domain to the Next.js process port.
5. After the installation is complete, the Domain from step 2 will show a running homepage. From this point on, you can deploy your own project to it.

Deploying Your Own Code via Git

1. In the app details, find the Git / CI-CD section and click "Connect GitHub". Confirm the installation of the "Saplo Deploy" app on your account or organization and select the repository with your Next.js project.
2. The saplo.yaml file must be in the root directory of the repository. You can generate it with the command saplo init or write it manually (example below).
3. Commit and push the saplo.yaml file to your production branch (by default main, you can change it in the branches.production section of the same file).
4. Each subsequent git push to this branch triggers an automatic build and deployment. You can see the status in the Deployments tab of the panel, and as a green or red marker next to the commit on GitHub.
5. If the build or health check fails, the previous working version of the application remains in place; Saplo does not replace it with a broken one.

Example of a minimal saplo.yaml file for Next.js:

name: my-project
stack: nextjs
runtime:
  node: "22"
build:
  install: npm ci
  command: npm run build
start:
  command: npm start
  port: 3000

Pushing this file looks like any other commit:

git add saplo.yaml
git commit -m "add saplo.yaml"
git push origin main

Next.js on Saplo vs. alternatives

FAQ

Do I have to connect Git right away, or can I start without it? You can start without Git. Installing from the app catalog sets up a working Next.js skeleton, and you can make the first deployment of your own code by uploading a .zip archive in the panel. You can connect Git at any time later.

Why is Box L recommended, not a lower plan? Because server-side rendering (SSR) keeps the Node.js process constantly in memory and responds to each request anew, unlike a static page, which once built, sits on the disk. Lower plans are sufficient for testing, but under real production traffic, they will lack sufficient RAM.

What happens if the saplo.yaml file is missing from the repository? During the first deployment without this file, the deploy will end with an error. For subsequent deployments, if the file disappears from a specific commit, Saplo will use the configuration from the last successful deployment.

Do I have to set the application port manually? You don't have to, the default port is 3000, and most Next.js projects don't require changing it. If your application changes it, set it in the start.port section of the saplo.yaml file.

Can I have several Next.js applications side-by-side on one Box? Yes, the app catalog allows you to set up multiple modules on one Box, each with its own subdomain or domain, as long as there is enough RAM and disk space allocated to the plan.

You can set up Next.js on Saplo from scratch to a working domain in minutes, and each subsequent git push deploys a new version without your intervention. If you are migrating an existing project from Vercel or Netlify and something is not working as it should, write to us, we will help you choose the configuration in saplo.yaml.