Documentation
Request access

Creating a P1 site with Next.js on Pantheon

This tutorial walks through the creation of a brand new P1 Site using a Next.js codebase created from Pantheon's P1 Starter Kit. It will end with a fully functioning P1 Starter Kit deployed to Pantheon hosting on a domain name like dev-mysite.pantheonsite.io. On this site you can add and edit pages with P1's visual editor.

The P1 site deployed to Pantheon

Prerequisites


This tutorial is broken down in the following sections, each of which have prerequisite access or capabilities necessary.

  1. Creating a P1 site to hold your content
    The primary prerequisite is access to the P1 Beta. Request access here if you do not yet have access. Without this access you will not be able to create the P1 Site which holds your content.

  2. Create a Next.js codebase to run P1 locally
    This step requires familiarity with the command line and a Node.js package manager like npm, pnpm, or yarn, as well as Node.js 24 or higher and Git.

  3. Push your Next.js codebase to GitHub or GitLab
    Deploying Next.js to Pantheon requires that the code live on GitHub or GitLab. You will need an account with permission to create repositories there.

  4. Deploy to Pantheon
    Deploying P1 beyond your local machine requires a Pantheon account with the ability to create Next.js sites. You will need a Gold plan or higher to deploy Next.js and a connection between your Pantheon workspace and your GitHub/GitLab account. If this connection is not already present, you will need administrator level privileges to create it.

Creating a P1 site to hold your content

  1. 1

    Create your site in P1 dashboard (https://content.pantheon.io)

    A screenshot of the site creation interface
  2. 2

    Once the P1 content site is created, generate an API token and get your Site ID. These are necessary in subsequent steps for Next.js to read from the P1 API.

    Selecting Token scope

    Choose the scope you want for that first token, typically “All content included draft” for a first use.

  3. 3

    The token will only be shown once; save it to personal secrets or in a secure temporary place, or keep the modal open until you need this information in later steps.

    The display of token and site ID

Create a Next.js codebase to run P1 locally

  1. 1

    On your local environment, initialize a site using our SDK starter:

    $
    pnpm create @pantheon-systems/p1-starter-kit
  2. 2

    Answer the option questions from the CLI. For these instructions, choose pnpm if you have it installed.

    If you choose yarn or npm, then use your package manager's equivalent of pnpm commands in the following steps (they might be done differently, not necessarily just replacing the word pnpm with yarn, for example).

  3. 3

    Ensure pnpm install (or npm install) executes locally

  4. 4

    Copy environment variables you saved in the previous step to your .env.local file

    NEXT_PUBLIC_CSS_SITE_ID=1234-ABC-6789-XYZ
    CSS_API_KEY=sat_1234XYZ
  5. 5

    Run Next.js locally in development mode.

    $
    pnpm run dev
  6. 6

    Open the running Next.js site in your browser by going to http://localhost:3000 . Sign in to http://localhost:3000/p1 to confirm that you can use the editorial interface.

    A Next.js site with P1 running on localhost

    The exact port used by the local Next.js development server might not be 3000 depending on your system.

With a local site running successfully, we can now get the site running online. Next, we will put the codebase on GitHub or GitLab.

Create a GitHub/GitLab repository to hold your Next.js codebase

  1. 1

    In GitHub or GitLab, create a new repository. If your our following this tutorial purely for educational purposes, you may want to select a personal account to hold the repository.

    The GitHub repo creation screen
  2. 2

    Follow the instructions for pushing your existing local repository.

    GitHub's instructions for pushing an existing repo
    A pushed GitHub repo

With this Next.js codebase now on GitHub or GitLab, we can deploy it to Pantheon.

Deploy Next.js to a newly created hosting on Pantheon

  1. 1

    Go to Pantheon.io dashboard to create a site to host your Next.js codebase.

  2. 2

    Create a Next.js site

    Selecting Next.js for site creation
  3. 3

    Select between GitHub and GitLab

    Selecting GitHub
  4. 4

    Name your site. You may want to use the same name used for the GitHub or GitLab repository.

    Site Creation interface
  5. 5

    Select your GitHub/GitLab account. If you have difficulty in these step, see Pantheon's documentation on external repositories.

    Org Selection
  6. 6

    Be sure to select "Use existing repository" so that Pantheon does not attempt to create a new one.

    Selecting a repo
  7. 7

    Next, set the secrets used earlier so that the soon-to-be-deployed Next.js site can read from P1.

    Secret setting UI
  8. 8

    Wait for Pantheon to build the Next.js site

    Site creation progress bar
  9. 9

    Once your site has built you will see a dashboard for it. Click through to get to your deployed Next.js site.

    The dashboard for the built dev environment
    The P1 site deployed to Pantheon

At this stage, you should be able to test end-to-end P1 with a hosted site on Pantheon.

From there, you can deploy to a test or live environment if you wish, following our Next.js documentation. A live environment is required for any production use, especially to set your own domain name.