Limitations and considerations for Next.js Beta
Learn about current limitations of Next.js Beta functionality on Pantheon, and how to weigh in to inform feature development.
This documentation describes support for Next.js that is under active development and is available only to customers who have been individually approved as part of our Private Beta program.
To request an invite, submit this form.
If you are migrating an existing Next.js site from our Front-End Sites offering please see our guide on migrating from Front-End Sites.
While in the Beta phase, some aspects of Next.js on Pantheon are still under active development. This page tracks known limitations worthy of consideration for early adopters.
We want your input! Help inform when, how, and if we build any given feature.
See instructions for submitting your input below, provided in context of the given topic. Otherwise, open a new issue for discussions not covered below.
Parity with CMS infrastructure
Site dashboard
Certain dashboard functionality is not currently supported for Next.js sites:
- Status reports
- Errors
- Domains & HTTPS, Upgrading site plan
Core Terminus commands
Many of the core Terminus commands will return an error if run against a Next.js site.
For instance, the backup:create command creates a backup consisting of 3 separate archives (database, files, and code) when used with WordPress or Drupal. This command returns an error for Next.js on Pantheon. Since Next.js sites are maintained in an external version control source like GitHub there is nothing to backup on Pantheon.
However commands like env:clear-cache will clear caches (like the CDN) for sites of all frameworks (WordPress, Drupal, Next.js)
If you encounter a command that does not work as you expect for Next.js, or have other feedback or questions, please use the Terminus issue queue.
New Relic
Pantheon supplies automatic integration with New Relic for WordPress and Drupal for all sites except those on the Basic plan. We do not yet have any such integration for Next.js. If you have input on how monitoring and telemetry should work, please join this discussion.
Redis
All WordPress and Drupal sites (except those on the Basic plan) can access their own Redis cache. While some teams do choose to use Redis as a cache handler with Next.js, we want more input and testing of a baseline cache handler first before providing multiple cache handler options.
See also this related caching section below.
Autopilot
Autopilot currently functions only with sites that use the Pantheon-supplied Git repository. Autopilot support for sites using Pantheon's GitHub Application (all Next.js sites and some WordPress/Drupal sites) will be added in a future release.
Custom Upstreams
We do not yet support the creation of Custom Upstreams for Next.js sites. If your team would benefit from something like Custom Upstreams for Next.js, please tell us more when you fill out the form to request access to the Beta program.
Advanced site configurations
- The
pantheon.ymlconfiguration file is not currently supported on Next.js sites, and is ignored if present. - Quicksilver hooks are not currently supported on Next.js sites.
HTTP streaming
Layers of our CDN and load balancing currently prevent HTTP Streaming for WordPress, Drupal, and Next.js. We introduced that limitation many years ago because we wanted to encourage teams to use full page caching in combination with Surrogate Keys for fine-grained purging. In WordPress and Drupal, that approach to CDN caching is accommodated by our Pantheon Advance Page cache plugin and module.
For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of <Suspense> components as a performance optimization.
While we intend to remove the limitation on streaming for Next.js sites, join the discussion in this GitHub issue if you have thoughts on how to provide guidance around situations where full page caching in the CDN. is still preferable to streaming.
GitHub App installation requirements
The Pantheon GitHub Application must be installed by a user who is both:
- A GitHub organization admin
- A member of the corresponding Pantheon workspace
Other workspace members cannot install the app themselves. The GitHub organization admin must complete the installation first, and then any workspace member can create Next.js sites using repositories the app has access to.
Options for the GitHub organization admin
The GitHub organization admin does not need to create a site to install the app. They can choose one of the following approaches:
Option 1: Install the app without creating a site
Run the following Terminus command to install the GitHub App on the organization without creating a site:
Replace <workspace> with the Pantheon workspace name, label, or ID. This installs the app and connects it to the GitHub organization. The GitHub organization admin can stop here — no site creation is required.
Option 2: Start site creation and stop after app installation
The GitHub organization admin can begin the site creation process through the Pantheon dashboard. During this process, the GitHub App installation is triggered. The GitHub organization admin can cancel the site creation after the app is installed, without completing the full workflow.
After the app is installed
Once the GitHub App is installed on the organization, any member of the Pantheon workspace can create a Next.js site — through the dashboard or Terminus — using any repository the app has access to.
General
Compatibility and Requirements
See the following page for Next.js compatibility and requirements on Pantheon:
Bun, Deno, and other runtimes beyond Node.js
Node.js is the most common run time for Next.js. Bun and Deno both have compelling performance and security advantages that may make them preferable for some teams. If you want Pantheon to offer Bun, Deno, or any other runtime for JavaScript/TypeScript, please let us know when you fill out the Beta request form.
Yarn
Pantheon infrastructure supports Yarn but as of now, that requires using a separate build target in package.json: gcp-build. We expect to unify this in regular build script in the near future but as of now, please add gcp-build as a new script so your codebase can be built in Pantheon Next.js infrastructure.
Astro, Remix, and other frameworks beyond Next.js
Pantheon began many years ago as a Drupal-only platform. But the nature of our free trial allowed many customers to try other LAMP stack frameworks, many of which worked. In 2014 we made our support for WordPress official. We made that policy change because our ecosystem has so much overlapping usage between WordPress and Drupal and because we value the success of web teams, and the web as a whole over the success of any given framework.
Similarly, the technology we now use to run Next.js is capable of serving many other frameworks. However, to increase the likelihood of success for teams in our Beta period, we are focusing our attention on Next.js specifically. If you have a strong need to run a non-Next.js framework on Pantheon, please request access to our Beta program and tell us more about your projects.
Webhooks and build triggers
Pantheon's previous Front-End Sites product, and many other providers, offer a way to directly retrigger a CI build from within a content management system. We have not yet replicated this functionality and would like input on how we might do it differently.
The normal use case for build hooks is to give them to a Content Management System so that any change in content can set off a full execution of the build and deployment process which will read in the changed content. This overall approach is extremely inefficient and unsatisfying for content editors accustomed to seeing content changes live within a single second. Waiting one (or many more) minutes for a full continuous integration process is often unacceptable. That tension propelled the development of the Incremental Static Regeneration functionality in Next.js.
Since we are sunsetting support for static-first systems like Gatsby we'd like input on whether we should recreate the functionality directly in our platform, document how to retrigger builds through GitHub or something else. If you have opinions, please share them here.
Environment variables
Pantheon's previous Front-End Sites product provided a dashboard interface for setting environment variables. The new Next.js support on Pantheon uses Secrets Manager to set environment variables. For steps to switch, see our related migration guide.
Drupal and WordPress reference implementations
As Pantheon developed our now-sunsetting Front-End Sites offering, we also created a number of packages and reference implementations for WordPress and Drupal with Next.js. These packages made under the name "Decoupled Kit" have not been actively maintained recently and have largely been surpassed by newer packages in the community.
If you have thoughts on which of the many starters and packages we should test and document for use on Pantheon, please share your thoughts in this thread.