Next.js

Welcome to our quick-start guide on hosting Next.js on Upsun, where we will demonstrate just how simple it is to host your Next.js projects on our PaaS. Follow the steps detailed below and you’ll have everything set up in no time.

Anything included in these guides applies not only to Next.js, but also to Express and Strapi.

If you’re new to Upsun, you might want to check out the philosophy of Upsun to get started on the best possible footing.

Before you begin

You need:

• Git. Git is the primary tool to manage everything your app needs to run. Push commits to deploy changes and control configuration through YAML files. These files describe your infrastructure, making it transparent and version-controlled.
• A Upsun account. If you don’t already have one, register for a trial account. You can sign up with an email address or an existing GitHub, Bitbucket, or Google account. If you choose one of these accounts, you can set a password for your Upsun account later.
• Required: the Upsun CLI. This lets you interact with your project from the command line. You can also do most things through the Web Console, but this guide focuses on using the CLI.

Create your local Next.js app

First things first, if you don’t have a local Next.js project, you need to create a new Next.js project locally by following the official Next.js installation guide.

Please refer to all the steps of the official Next.js installation guide for further details, but to sum it up, here are the 3 steps to create a Next.js app locally:

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

Initialize your Git repository

We need 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"

We should also ignore adding node_modules and .next folders to the Git repository. Use the following commands to do so:

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

Add a Hello World route

Please create your first Next.js page. To do so, create a new pages/index.tsx file at the root of your project. It will contain a basic Hello world script:

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

Commit your files in your Git repository

We need to commit local files, using the following command:

git add pages/index.tsx
git commit -m "adding pages/index.tsx first page"

Create a new project

The next step is to create a project on Upsun. To do this, you can either use the Upsun CLI or the Upsun Console.

upsun project:create

git remote
upsun

upsun project:set-remote <projectId>

git remote
origin
upsun

upsun project:list

Choose your Git workflow

Upsun projects can be used as a classic Git repository, where you will be able to push your source code in different ways, using either the Git CLI or the Upsun CLI. You can choose which way—or Git workflow— you would like to use for your project from the following options:

• Your project source code will be hosted on a Upsun Git repository
• Your project source code will be hosted on your own GitHub repository

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. These YAML configuration files are located into a .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 from the root of your Next.js project and follow the prompts:

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 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:   │
│     - .environment                                │
│     - .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 push

We haven’t added any services yet, but you can do so now.

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 and generate the corresponding config.yaml YAML files, like so:

applications:
  app:
    source:
      root: "/"
    type: "nodejs:18"
    web:
      commands:
        start: "npx next start -p $PORT"
    build:
      flavor: none
    dependencies:
      nodejs:
        sharp: "*"
#services:
  #  db:
#    type: postgresql:15
routes:
  "https://{default}/":
    type: upstream
    upstream: "app:http"
  # A basic redirect definition
  # More information: https://docs.upsun.com/define-routes.html#basic-redirect-definition
  "https://www.{default}/":
    type: redirect
    to: "https://{default}/"

Then commit your new files, using the following command:

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

Build your Next.js application

Your Next.js application needs to be built during the build hook. To do so, edit your .upsun/config.yaml file with the following configuration:

applications:
  app:
    hooks:
      build: |
        set -eux
        npm i
        npm exec next build        

Then commit your new files, using the following command:

git add .upsun/config.yaml
git commit -m "build Next.js app during build hook"

Set your project remote

There are slightly different ways to link your local project to your Upsun project based on the Git workflow you chose for your project, as discussed earlier in this guide.

upsun project:set-remote <projectId>

git remote
upsun
...

upsun project:list

$ upsun integration:add
* Integration type (--type)
  Enter a number to choose:
  [0 ] bitbucket
  [1 ] bitbucket_server
  [2 ] github
  [3 ] gitlab
  [4 ] webhook
  [5 ] health.email
  [6 ] health.pagerduty
  [7 ] health.slack
  [8 ] health.webhook
  [10] script
> 2

* Token (--token)
  An authentication or access token for the integration
> X1234567890AZERTYUIOP

* Repository (--repository)
  The repository (e.g. 'owner/repository')
> <owner>/<repository>

$ upsun integration:add
* Integration type (--type)
  Enter a number to choose:
  [0 ] bitbucket
  [1 ] bitbucket_server
  [2 ] github
  [3 ] gitlab
  [4 ] webhook
  [5 ] health.email
  [6 ] health.pagerduty
  [7 ] health.slack
  [8 ] health.webhook
  [10] script
> 3

* Token (--token)
  An authentication or access token for the integration
> X1234567890AZERTYUIOP

* Repository (--repository)
  The repository (e.g. 'owner/repository')
> <owner>/<repository>

$ upsun integration:add
* Integration type (--type)
  Enter a number to choose:
  [0 ] bitbucket
  [1 ] bitbucket_server
  [2 ] github
  [3 ] gitlab
  [4 ] webhook
  [5 ] health.email
  [6 ] health.pagerduty
  [7 ] health.slack
  [8 ] health.webhook
  [10] script
> 0

* Token (--token)
  An authentication or access token for the integration
> X1234567890AZERTYUIOP

* Repository (--repository)
  The repository (e.g. 'owner/repository')
> <owner>/<repository>

Deploy

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

Depending on the Git workflow you choose at the beginning of this tutorial, there are two ways to deploy your source code changes.

upsun push

git push origin

Upsun will now read your configuration files and deploy your project using default container resources. If you don’t want to use those default resources, define your own resource initialization strategy, or amend those default container resources after your project is deployed.

Et voilà, your Next.js application is live!

upsun environment:url --primary

Make changes to your project

Now that your project is deployed, you can start making changes to it. For example, you might want to fix a bug or add a new feature.

In your project, the main branch always represents the production environment. Other branches are for developing new features, fixing bugs, or updating the infrastructure.

To make changes to your project, follow these steps:

1. Create a new environment (a Git branch) to make changes without impacting production:

   Terminal

   upsun branch feat-a

   This command creates a new local feat-a Git branch based on the main Git branch and activates a related environment on Upsun. The new environment inherits the data (service data and assets) of its parent environment (the production environment here).

2. Make changes to your project.

   For example, edit the pages/index.tsx file and make the following changes:

   pages/index.tsx

   export default function Page() {
     return <h1>Hello, World! - A simple Next.js web framework template for Upsun!</h1>
   }

3. Commit your changes:

   Terminal

   git add pages/index.tsx
   git commit -m "Update Hello world"

4. Deploy your changes to the feat-a environment:

   Terminal

   upsun push

   Note that each environment has its own domain name. To open the URL of your new environment, run the following command:

   Terminal

   upsun environment:url --primary

5. Iterate by changing the code, committing, and deploying. When satisfied with your changes, merge them to the main branch, and remove the feature branch:

   Terminal

   upsun merge
     Are you sure you want to merge feat-a into its parent, main? [Y/n] y
   upsun checkout main
   git pull upsun main
   upsun environment:delete feat-a
   git fetch --prune

   Note

   Deploying to production was fast because the image built for the feat-a environment was reused.

   For a long running branch, to keep the code up-to-date with the main branch, use git merge main or git rebase main. You can also keep the data in sync with the production environment by using upsun env:sync.

Use a third-party Git provider

When you choose to use a third-party Git hosting service, the Upsun Git repository becomes a read-only mirror of the third-party repository. All your changes take place in the third-party repository.

Add an integration to your existing third-party repository:

• BitBucket
• GitHub
• GitLab

Next steps