A quick-start guide on hosting Next.js on Upsun

Welcome to our quick-start guide on hosting Next.js (at the time of writing, the most recent version of Next.js is 14.0.3) on Upsun where we will demonstrate just how simple it is to host Next.js projects on our PaaS. Simply follow the steps detailed below and you’ll have everything set up in no time.

Before we get started, for the purpose of this tutorial we will assume that you have already installed the Upsun CLI locally. The following steps are based on that assumption:

Get started locally

If you already have an existing Next.js GitHub repository with, at least, a Hello world route, please clone it locally using the following command and then jump to the second step: Configure your project.

$ git clone git@github.com:<YourRepoUrl>.git

If you do not yet have an existing Next.js GitHub repository, you’re in the right place—the following steps will show you how to set one up and clone it locally.

1. Initialize your local project

First things first, if you don’t have a local Next.js project yet, you need to create a new one locally following the Next.js installation guide. Please refer to all of the steps of the installation guide for full details, but to summarize, these are the three commands needed to create a Next.js app locally:

$ mkdir my-nextjs-app
$ cd my-nextjs-app
$ npm install next@latest react@latest react-dom@latest

2. Init your Git repository

Once you’ve created a new Next.js project locally, it’s then time to initialize the local Git repository and commit local files, using the following command:

$ git init
$ git add package.json package-lock.json
$ git commit -m "Init Next.js application"

$ echo "/node_modules" >> .gitignore
$ echo "/.next" >> .gitignore
$ git add .gitignore && git commit -m "adding node_modules and .next folders in .gitignore file"

3. Add a Hello World route

To ensure your Next.js application is easily testable, you need to create your first Next.js page. To do so, create a new pages/index.tsx file, it will contain a basic Hello world script, as seen below:

export default function Page() {
 return <h1>Hello world, Next.js!</h1>
}

Then commit your file using the following commands:

$ git add pages/index.tsx
$ git commit -m "adding a Hello World"

4. Create your GitHub repository

The next step is to create a GitHub repository, to do so follow the official GitHub guide which provides all of the information you need.

5. Push source code to your remote repository

The final step of the local setup is to push your source code to your remote GitHub repository, using the following command:

$ git remote add origin git@github.com:OWNER/REPOSITORY.git
$ git push -u origin main

Configure your project

To be able to host your Next.js application on Upsun, some YAML configuration files are needed at the root of your project to manage the way your application will behave. See the code below for how to automatically pre-generate them.

These YAML configuration files are located in an .upsun/ folder at the root of your source code, the architecture of which will look like this:

my-nextjs-app
├── .upsun
│   └── config.yaml
├── [.environment]
└── <project sources>

To pre-generate these YAML files, please use the following command upsun project:init from the root of your Next.js project and follow the prompts, as you can see below:

$ upsun project:init
Welcome to Upsun!
Let's get started with a few questions.

We need to know a bit more about your project. This will only take a minute!

✓ Detected stack: Next.js
✓ Detected runtime: JavaScript/Node.js
✓ Detected dependency managers: Npm
Tell us your project’s application name: [app]

                       (_/)
We're almost done...  =(^.^)=
Last but not least, unless you're creating a static website, your project uses services. Let's define them:

Select all the services you are using: []

You have not selected any service, would you like to proceed anyway? [Yes]

┌───────────────────────────────────────────────────┐
│   CONGRATULATIONS!                                │
│                                                   │
│   We have created the following files for your:   │
│     - .upsun/config.yaml                          │
│                                                   │
│   We're jumping for joy! ⍢                        │
└───────────────────────────────────────────────────┘
        │ /
        │/
        │
  ( /)
  ( . .)
  o (_(")(")
  
You can now deploy your application to Upsun!
To do so, commit your files and deploy your application using the Upsun CLI:
  $ git add .
  $ git commit -m 'Add Upsun configuration files' 
  $ upsun project:set-remote
  $ upsun push

The upsun project:init command (shortcut upsun ify) will automatically detect that you’re using a Next.js stack, ask if you want to add any services (please don’t add any for now), and generate the corresponding .upsun/config.yaml YAML files, like so:

# Complete list of all available properties: https://docs.upsun.com/create-apps/app-reference.html
applications:
 app:
   source:
     root: "/"
   type: "nodejs:20"
   mounts:
     "/.npm":
       source: "storage"
       source_path: "npm"
   web:
     commands:
       start: "npx next start -p $PORT"
     upstream:
       socket_family: tcp
    locations:
      "/":
        passthru: true
   build:
     flavor: none
   dependencies:
     nodejs:
       sharp: "*"
   hooks:
     build: |
       set -eux
       npm i
       npm exec next build
routes:
 "https://{default}/":
   type: upstream
   upstream: "app:http"
 "https://www.{default}/":
   type: redirect
   to: "https://{default}/"

Then commit your new files, using the following command, and the project configuration is complete:

$ git add .upsun/config.yaml
$ git commit -m "Upsun config files"
$ git push

Create a new Upsun project

The next step in setting up Next.js on Upsun is to create a project which is simple to do via the Console. On your console homepage (all projects), in the top right corner, please click on the create project button, as seen below:

If you do not already have an organization created to put the project into, you’ll first be instructed to create one. Once you have done so, select that organization from the dropdown, and then select Deploy with GitHub, as seen in the screen below:

Then select Connect with GitHub from the options provided as seen here:

In the next form that appears which you can see in the screen below, select your GitHub organization from the first dropdown and then select Install & Authorize and fill out the GitHub credentials. You will need to select your GitHub organization and previously created GitHub repository and select Continue.

You will then be taken to step three of this setup—as seen below—where you will fill in various details including project name, environment name, and region. Once you’ve done so, select Create project.

On the next page, while the project creation process is ongoing in the background, you will see on the left some further setup instructions, if you need them. On the right, you can follow the project creation process and you will be informed when it is complete, as seen in the screen below:

Once your project has been created, the GitHub integration process will automatically deploy your application based on your GitHub repository source code. Wait for the integration to finish deployment and it will then display your application information which you can see an example of in the screen below:

Time to deploy, right?

And just like that, it’s time to deploy! But wait…

As you already ensured your GitHub source code was Upsun-ready, your project will have been automatically deployed during project creation and your application will be live—no deployment needed and the first backup of your app will be done automatically. Check out your new Project URL which you can find at the bottom of the console interface.

The next step is to access your project console by clicking on the View project button at the bottom of the setup page, et voilà, your Next.js application is live and you can start playing around with it and adding lots of cool new features!

What about updates?

1. Resources allocation

During the first push of your production environment, Upsun will use the default size for each of your service/app containers. The default setting is set to 0.5 CPU & 0.2 GB of RAM, but that’s more than what is needed for this container so let’s lower it to something more appropriate.

If you need to define custom resources (CPU, memory, and disk) for the various containers, the process is simple. When in the environment view, click on the Configure resources link from the notification block at the top. This can also be done via the CLI.

In general, the following resources should be effective but feel free to adapt those values to your application's needs:

• CPU: 0.1, memory 64 MB
• 1 instance
• 1024 MB of Disk/Storage

After confirming your choices, Upsun will then take your selections, gather the previously built images from earlier, apply your resource selections to them, and redeploy your full application. If you need more information, please refer to our documentation on how to manage resources on Upsun.

2. Code changes

To update your application, create a new Git branch as usual via your terminal, implement the changes you wish to make, and push the branch to your GitHub repository.

$ git switch -c update-hello
// do some code changes, like changing your Hello world message
$ git add . && git commit -m “Change Hello world”
$ git push -u origin update-hello

It will automatically create a new, inactive Upsun preview environment, based on your branch source code and parent environment data (database and/or assets). This new environment is not active by default which means it does not consume resources, so you need to activate it the first time you push a new branch on your repo, using the following command:

$ upsun environment:activate
Are you sure you want to activate the environment update-hello (type: development)? [Y/n] y
Activating environment update-hello
…

Please note: As we haven’t yet configured resources for our application container, the activation process will fail—but don’t worry, this is expected. The issue will be resolved with the release of Git25 expected in January 2024 as this new Git version will gather and use the parent resource settings as they are. In the meantime, please follow the steps above to configure resources in your preview environment.

At the end of this activation, your preview environment is deployed and you can access it either using the Console by going to the corresponding environment and clicking on its front URL, or by using the following CLI command:

$ upsun environment:url -primary

And just like that, you’re ready to host your Next.js applications on Upsun. Keep your eyes peeled for plenty more guides coming soon, with new articles posted on our blog on a selection of topics every single week. Find out more about Upsun's features and capabilities.