From cb9f3726474f524cc9377e4b6e3130281f123663 Mon Sep 17 00:00:00 2001 From: Steve Persch Date: Fri, 14 Nov 2025 15:06:44 -0600 Subject: [PATCH 1/5] limitations during beta --- source/content/nextjs/limitations.md | 117 ++++++++++++++++++ .../submenus/webInfrastructure.js | 1 + 2 files changed, 118 insertions(+) create mode 100644 source/content/nextjs/limitations.md diff --git a/source/content/nextjs/limitations.md b/source/content/nextjs/limitations.md new file mode 100644 index 0000000000..2cc8a89533 --- /dev/null +++ b/source/content/nextjs/limitations.md @@ -0,0 +1,117 @@ +--- +title: Next.js on Pantheon: Limitations during Beta +description: Functionality under development or under consideration during the Next.js Private Beta on Pantheon +reviewed: "2025-11-14" +contenttype: [doc] +innav: [true] +audience: [development] +product: [--] +integration: [--] +permalink: docs/nextjs/limitations + +--- + + + +While in the Beta phase, some aspects of our support for Next.js are still under development. + +We want your input to inform when, how, and if we build any given feature. + +## **CDN and caching** + +Pantheon has differentiated itself in the WordPress and Drupal ecosystem with a number of performance optimizations especially around the interaction between CMS and CDN. In the current Beta phase for our Next.js support, Next.js runs behind our Global CDN but we have not yet replicated all of that functionality for Next.js. + +Here are our current limitations with links to further discussions of how we intend to close these gaps. + +### **Package for shared, persistent cache** + +Next.js provides [many layers of caching](https://nextjs.org/docs/app/guides/caching#overview). The "Full Route Cache" and "Data Cache" are meant to be persistent caches. Those caches hold information generated in the build process and can be changed over time by the behavior of [Incremental Static Regeneration](https://nextjs.org/docs/pages/guides/incremental-static-regeneration). + +Pantheon will be providing guidance on how sites can implement a cache handler to share these persistent caches across the horizontally scaled containers which hold the runtime code. Let us know if you have thoughts on whether this functionality should go in a [deployment adapter,](https://github.com/pantheon-systems/documentation/issues/9732) a [stand-alone package, or something else](https://github.com/pantheon-systems/documentation/issues/9727). + +### **Clearing CDN caches by tag** + +Content Delivery Networks cache webpages so that responses reach visitors faster and with resilience to traffic spikes. That benefit can come with the downside of serving old, outdated content. Mitigating the risk of outdated content by clearing all caches in response to content changes then defeats the benefit of caching in the first place. + +Pantheon, and most other modern providers, can balance the competing needs for fast and fresh web pages by "tagging" web pages with the relevant data that produced them. When a given piece of content changes, only the web pages that used that piece of content are cleared from the CDN cache. Our ["Pantheon Advanced Page Cache" plugin for WordPress](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and a [module for Drupal](https://www.drupal.org/project/pantheon_advanced_page_cache) enable this functionality by passing tags from the origin CMS to the CDN. When CRUD operations (create, read, update, delete) fire within the CMS, these packages can then reach out from origin infrastructure to the CDN to purge the appropriate caches. + +We will create the same capacity for Next.js to clear CDN caches itself in response to appropriate events like [revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag). If you have thoughts or feedback please share it here in [this thread specific to the question of tag-based clearing](https://github.com/pantheon-systems/documentation/issues/9762) or [the general question of deployment adapters](https://github.com/pantheon-systems/documentation/issues/9732). + +### **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](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and [module](https://www.drupal.org/project/pantheon_advanced_page_cache). + +For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of [\](https://react.dev/reference/react/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](https://github.com/pantheon-systems/documentation/issues/9767) if you have thoughts on how to provide guidance around situations where full page caching in the CDN. is still preferable to streaming. + +## **Drupal and WordPress reference implementations** + +As Pantheon developed our now-sunsetting [Front-End Sites](https://docs.pantheon.io/guides/decoupled) 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](https://github.com/pantheon-systems/decoupled-kit-js)" 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](https://github.com/pantheon-systems/documentation/issues/9770). + +## **Parity with CMS infrastructure** + +### **Terminus command and Next.js** + +Many of the commands in Pantheon's CLI will return an error if run against a Next.js site. For instance, the command "backup:create" will create separate archive files for the database, uploaded files (jpgs, pdfs, etc), and codebase for a WordPress or Drupal site. Our Next.js offering is currently tailored to sites where data is canonically stored elsewhere (like a separate CMS) and the code is stored on GitHub. So "backup:create" will return an error message. 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](https://github.com/pantheon-systems/terminus/issues). + +### **Telemetry / Application Performance Monitoring** + +Pantheon supplies [automatic integration with New Relic](https://docs.pantheon.io/guides/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](https://github.com/pantheon-systems/documentation/issues/9768). + +### **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](https://github.com/pantheon-systems/documentation/issues/9727) first before providing multiple cache handler options. + +### **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](https://docs.pantheon.io/guides/custom-upstream) 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](https://pantheon.io/redirect/nextjs/request-access-cta). + +### **What options exist in pantheon.yml for Next.js sites?** + +The pantheon.yml file is currently unsupported on Next.js sites, and is ignored if present. + +### **Which Quicksilver hooks run for Next.js sites?** + +[Quicksilver](https://docs.pantheon.io/guides/quicksilver) is currently unsupported on Next.js sites. + +## **Compatibility & Requirements** + +* Node versions: + * During Beta, Pantheon supports [Node.js](http://Node.js) 22.21.0. In the future, we will provide support for the latest 3 LTS versions. Pantheon derives which one to use by looking at the engines property in package.json, so ensure this is set in your project’s configuration. +* Next.js versions: + + * During Beta, Pantheon supports Next.js 15.3.1. In the future, we will provide support for the latest 2 LTS versions. + +* Package managers: + * Pantheon will use npm, yarn, or pnm depending on which lock file you have present in your repository. Having a lock file for more than one package manager can create unpredictable behavior. +* External version control integration: + * Next.js sites can only run on Pantheon if the code comes from a GitHub repository. Eventually we will expand that capability to BitBucket and GitLab. + +## **General** + +### **Webhooks / Build hooks to trigger the build and deployment process** + +[Pantheon's previous Front-End Sites product](https://docs.pantheon.io/guides/decoupled/wp-backend-starters/build-hooks), 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](https://github.com/pantheon-systems/documentation/issues/9769). + +### **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](https://pantheon.io/redirect/nextjs/request-access-cta).. + +### **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 with very minimal modification to our tech stack. 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](https://pantheon.io/redirect/nextjs/request-access-cta) and tell us more about your projects. diff --git a/src/components/omniSidebarNav/submenus/webInfrastructure.js b/src/components/omniSidebarNav/submenus/webInfrastructure.js index ea99938f19..98fd78b404 100644 --- a/src/components/omniSidebarNav/submenus/webInfrastructure.js +++ b/src/components/omniSidebarNav/submenus/webInfrastructure.js @@ -151,6 +151,7 @@ const webInfrastructure = () => { simpleLink('/nextjs', 'Next.js', [ simpleLink('/nextjs', 'Next.js Overview'), + simpleLink('/nextjs/limitations', 'Limitations during Beta'), simpleLink('/nextjs/architecture', 'Architecture and Git Workflow', [ simpleLink('/nextjs/architecture', 'Architecture'), simpleLink('/nextjs/multidev', 'Multidev environments'), From 24e8f605356cb8557e644bc4db04d95a9f665fd9 Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Sun, 16 Nov 2025 21:36:41 -0600 Subject: [PATCH 2/5] Fix build --- source/content/nextjs/limitations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/content/nextjs/limitations.md b/source/content/nextjs/limitations.md index 2cc8a89533..7ebe3ffb4e 100644 --- a/source/content/nextjs/limitations.md +++ b/source/content/nextjs/limitations.md @@ -1,5 +1,5 @@ --- -title: Next.js on Pantheon: Limitations during Beta +title: "Next.js on Pantheon: Limitations during Beta" description: Functionality under development or under consideration during the Next.js Private Beta on Pantheon reviewed: "2025-11-14" contenttype: [doc] From 51ae05071a513ff8e0b4b47095a7d0d75721b0eb Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Mon, 17 Nov 2025 05:41:55 -0600 Subject: [PATCH 3/5] Copy edits, reorg sections --- source/content/nextjs/limitations.md | 123 +++++++++--------- source/content/nextjs/overview.md | 22 +--- .../submenus/webInfrastructure.js | 2 +- 3 files changed, 73 insertions(+), 74 deletions(-) diff --git a/source/content/nextjs/limitations.md b/source/content/nextjs/limitations.md index 7ebe3ffb4e..bf8aa02567 100644 --- a/source/content/nextjs/limitations.md +++ b/source/content/nextjs/limitations.md @@ -1,117 +1,124 @@ --- -title: "Next.js on Pantheon: Limitations during Beta" -description: Functionality under development or under consideration during the Next.js Private Beta on Pantheon -reviewed: "2025-11-14" +title: "Known issues and considerations for Next.js Beta" +description: Learn about current limitations of Next.js Beta functionality on Pantheon, and how to weigh in to inform feature development. +reviewed: "2025-11-17" contenttype: [doc] innav: [true] audience: [development] product: [--] integration: [--] -permalink: docs/nextjs/limitations - +permalink: docs/nextjs/considerations --- -While in the Beta phase, some aspects of our support for Next.js are still under development. +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 to inform when, how, and if we build any given feature. + -## **CDN and caching** +We want your input! Help inform when, how, and if we build any given feature. -Pantheon has differentiated itself in the WordPress and Drupal ecosystem with a number of performance optimizations especially around the interaction between CMS and CDN. In the current Beta phase for our Next.js support, Next.js runs behind our Global CDN but we have not yet replicated all of that functionality for Next.js. +See instructions for submitting your input below, provided in context of the given topic. Otherwise, [open a new issue](https://github.com/pantheon-systems/documentation/issues/new?title=Known%20issues%20and%20considerations%20for%20Next.js%20Beta%20Feedback&body=Re%3A%20%5BKnown%20issues%20and%20considerations%20for%20Next.js%20Beta%5D(https%3A%2F%2Fdocs.pantheon.io%2Fnextjs/considerations)%0A%0APriority%3A%20Low%2FMedium%2FHigh%20(choose%20one%2C%20remove%20the%20other%20options)%0A%0A%23%23%20Issue%20Description%3A%0A%0A%23%23%20Suggested%20Resolution&labels=Topic%3A%20Next.js) for discussions not covered below. -Here are our current limitations with links to further discussions of how we intend to close these gaps. + -### **Package for shared, persistent cache** +## Parity with CMS infrastructure -Next.js provides [many layers of caching](https://nextjs.org/docs/app/guides/caching#overview). The "Full Route Cache" and "Data Cache" are meant to be persistent caches. Those caches hold information generated in the build process and can be changed over time by the behavior of [Incremental Static Regeneration](https://nextjs.org/docs/pages/guides/incremental-static-regeneration). +### Site dashboard +Certain dashboard functionality is not currently supported for Next.js sites: +* Status reports +* Errors +* Domains & HTTPS, Upgrading site plan -Pantheon will be providing guidance on how sites can implement a cache handler to share these persistent caches across the horizontally scaled containers which hold the runtime code. Let us know if you have thoughts on whether this functionality should go in a [deployment adapter,](https://github.com/pantheon-systems/documentation/issues/9732) a [stand-alone package, or something else](https://github.com/pantheon-systems/documentation/issues/9727). +### Core Terminus commands -### **Clearing CDN caches by tag** +Many of [the core Terminus commands](/terminus/commands) will return an error if run against a Next.js site. -Content Delivery Networks cache webpages so that responses reach visitors faster and with resilience to traffic spikes. That benefit can come with the downside of serving old, outdated content. Mitigating the risk of outdated content by clearing all caches in response to content changes then defeats the benefit of caching in the first place. +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. -Pantheon, and most other modern providers, can balance the competing needs for fast and fresh web pages by "tagging" web pages with the relevant data that produced them. When a given piece of content changes, only the web pages that used that piece of content are cleared from the CDN cache. Our ["Pantheon Advanced Page Cache" plugin for WordPress](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and a [module for Drupal](https://www.drupal.org/project/pantheon_advanced_page_cache) enable this functionality by passing tags from the origin CMS to the CDN. When CRUD operations (create, read, update, delete) fire within the CMS, these packages can then reach out from origin infrastructure to the CDN to purge the appropriate caches. +However commands like `env:clear-cache` will clear caches (like the CDN) for sites of all frameworks (WordPress, Drupal, Next.js) -We will create the same capacity for Next.js to clear CDN caches itself in response to appropriate events like [revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag). If you have thoughts or feedback please share it here in [this thread specific to the question of tag-based clearing](https://github.com/pantheon-systems/documentation/issues/9762) or [the general question of deployment adapters](https://github.com/pantheon-systems/documentation/issues/9732). +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](https://github.com/pantheon-systems/terminus/issues). -### **HTTP streaming** +### New Relic -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](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and [module](https://www.drupal.org/project/pantheon_advanced_page_cache). +Pantheon supplies [automatic integration with New Relic](/guides/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](https://github.com/pantheon-systems/documentation/issues/9768). -For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of [\](https://react.dev/reference/react/Suspense) components as a performance optimization. +### 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](https://github.com/pantheon-systems/documentation/issues/9727) first before providing multiple cache handler options. -While we intend to remove the limitation on streaming for Next.js sites, [join the discussion in this GitHub issue](https://github.com/pantheon-systems/documentation/issues/9767) if you have thoughts on how to provide guidance around situations where full page caching in the CDN. is still preferable to streaming. +See also [this related caching section](#package-for-shared-persistent-cache) below. -## **Drupal and WordPress reference implementations** +### Autopilot -As Pantheon developed our now-sunsetting [Front-End Sites](https://docs.pantheon.io/guides/decoupled) 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](https://github.com/pantheon-systems/decoupled-kit-js)" have not been actively maintained recently and have largely been surpassed by newer packages in the community. +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. -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](https://github.com/pantheon-systems/documentation/issues/9770). +### Custom Upstreams -## **Parity with CMS infrastructure** +We do not yet support the creation of [Custom Upstreams](/guides/custom-upstream) 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](https://pantheon.io/nextjs-beta). -### **Terminus command and Next.js** +### Advanced site configurations -Many of the commands in Pantheon's CLI will return an error if run against a Next.js site. For instance, the command "backup:create" will create separate archive files for the database, uploaded files (jpgs, pdfs, etc), and codebase for a WordPress or Drupal site. Our Next.js offering is currently tailored to sites where data is canonically stored elsewhere (like a separate CMS) and the code is stored on GitHub. So "backup:create" will return an error message. However commands like "env:clear-cache" will clear caches (like the CDN) for sites of all frameworks (WordPress, Drupal, Next.js) +* The [`pantheon.yml` configuration file](/pantheon-yml) is not currently supported on Next.js sites, and is ignored if present. +* [Quicksilver](/guides/quicksilver) hooks are not currently supported on Next.js sites. -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](https://github.com/pantheon-systems/terminus/issues). +## CDN and caching -### **Telemetry / Application Performance Monitoring** +Pantheon has differentiated itself in the WordPress and Drupal ecosystem with a number of performance optimizations especially around the interaction between CMS and CDN. -Pantheon supplies [automatic integration with New Relic](https://docs.pantheon.io/guides/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](https://github.com/pantheon-systems/documentation/issues/9768). +In the current Beta phase for our Next.js support, Next.js runs behind our Global CDN but we have not yet replicated all of that functionality for Next.js. Here are our current limitations with links to further discussions of how we intend to close these gaps. -### **Redis** +### Package for shared, persistent cache -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](https://github.com/pantheon-systems/documentation/issues/9727) first before providing multiple cache handler options. +Next.js provides [many layers of caching](https://nextjs.org/docs/app/guides/caching#overview). The "Full Route Cache" and "Data Cache" are meant to be persistent caches. Those caches hold information generated in the build process and can be changed over time by the behavior of [Incremental Static Regeneration](https://nextjs.org/docs/pages/guides/incremental-static-regeneration). -### **Autopilot** +Pantheon will be providing guidance on how sites can implement a cache handler to share these persistent caches across the horizontally scaled containers which hold the runtime code. Let us know if you have thoughts on whether this functionality should go in a [deployment adapter,](https://github.com/pantheon-systems/documentation/issues/9732) a [stand-alone package, or something else](https://github.com/pantheon-systems/documentation/issues/9727). -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. +### Clearing CDN caches by tag -### **Custom Upstreams** +Content Delivery Networks cache webpages so that responses reach visitors faster and with resilience to traffic spikes. That benefit can come with the downside of serving old, outdated content. Mitigating the risk of outdated content by clearing all caches in response to content changes then defeats the benefit of caching in the first place. + +Pantheon, and most other modern providers, can balance the competing needs for fast and fresh web pages by "tagging" web pages with the relevant data that produced them. When a given piece of content changes, only the web pages that used that piece of content are cleared from the CDN cache. Our ["Pantheon Advanced Page Cache" plugin for WordPress](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and a [module for Drupal](https://www.drupal.org/project/pantheon_advanced_page_cache) enable this functionality by passing tags from the origin CMS to the CDN. When CRUD operations (create, read, update, delete) fire within the CMS, these packages can then reach out from origin infrastructure to the CDN to purge the appropriate caches. + +We will create the same capacity for Next.js to clear CDN caches itself in response to appropriate events like [revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag). If you have thoughts or feedback please share it here in [this thread specific to the question of tag-based clearing](https://github.com/pantheon-systems/documentation/issues/9762) or [the general question of deployment adapters](https://github.com/pantheon-systems/documentation/issues/9732). + +### HTTP streaming -We do not yet support the creation of [Custom Upstreams](https://docs.pantheon.io/guides/custom-upstream) 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](https://pantheon.io/redirect/nextjs/request-access-cta). +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](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and [module](https://www.drupal.org/project/pantheon_advanced_page_cache). -### **What options exist in pantheon.yml for Next.js sites?** +For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of [\](https://react.dev/reference/react/Suspense) components as a performance optimization. -The pantheon.yml file is currently unsupported on Next.js sites, and is ignored if present. +While we intend to remove the limitation on streaming for Next.js sites, [join the discussion in this GitHub issue](https://github.com/pantheon-systems/documentation/issues/9767) if you have thoughts on how to provide guidance around situations where full page caching in the CDN. is still preferable to streaming. -### **Which Quicksilver hooks run for Next.js sites?** +## General -[Quicksilver](https://docs.pantheon.io/guides/quicksilver) is currently unsupported on Next.js sites. +### Compatibility and Requirements +See the following page for Next.js compatibility and requirements on Pantheon: +* [Next.js Overview](/nextjs#compatibility--requirements) -## **Compatibility & Requirements** +### **Bun, Deno, and other runtimes beyond Node.js** -* Node versions: - * During Beta, Pantheon supports [Node.js](http://Node.js) 22.21.0. In the future, we will provide support for the latest 3 LTS versions. Pantheon derives which one to use by looking at the engines property in package.json, so ensure this is set in your project’s configuration. -* Next.js versions: +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](https://pantheon.io/nextjs-beta). - * During Beta, Pantheon supports Next.js 15.3.1. In the future, we will provide support for the latest 2 LTS versions. +### **Astro, Remix, and other frameworks beyond Next.js** -* Package managers: - * Pantheon will use npm, yarn, or pnm depending on which lock file you have present in your repository. Having a lock file for more than one package manager can create unpredictable behavior. -* External version control integration: - * Next.js sites can only run on Pantheon if the code comes from a GitHub repository. Eventually we will expand that capability to BitBucket and GitLab. +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 with very minimal modification to our tech stack. 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. -## **General** +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](https://pantheon.io/nextjs-beta) and tell us more about your projects. -### **Webhooks / Build hooks to trigger the build and deployment process** +### Webhooks and build triggers -[Pantheon's previous Front-End Sites product](https://docs.pantheon.io/guides/decoupled/wp-backend-starters/build-hooks), 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. +[Pantheon's previous Front-End Sites product](/guides/decoupled/overview/manage-settings/#build-hooks), 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](https://github.com/pantheon-systems/documentation/issues/9769). -### **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](https://pantheon.io/redirect/nextjs/request-access-cta).. +### Environment variables +[Pantheon's previous Front-End Sites product](/guides/decoupled/overview/manage-settings/#site-environment-variables) provided a dashboard interface for setting environment variables. The new Next.js support on Pantheon uses [Secrets Manager](/guides/secrets) to set environment variables. For steps to switch, see our related [migration guide](/nextjs/migrating-from-front-end-sites#replicate-environment-variables-as-pantheon-secrets). -### **Astro, Remix, and other frameworks beyond Next.js** +### Drupal and WordPress reference implementations -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 with very minimal modification to our tech stack. 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. +As Pantheon developed our now-sunsetting [Front-End Sites](/guides/decoupled/overview) 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](https://github.com/pantheon-systems/decoupled-kit-js)" have not been actively maintained recently and have largely been surpassed by newer packages in the community. -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](https://pantheon.io/redirect/nextjs/request-access-cta) and tell us more about your projects. +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](https://github.com/pantheon-systems/documentation/issues/9770). \ No newline at end of file diff --git a/source/content/nextjs/overview.md b/source/content/nextjs/overview.md index 2e916470dd..91da188238 100644 --- a/source/content/nextjs/overview.md +++ b/source/content/nextjs/overview.md @@ -1,7 +1,7 @@ --- title: Next.js Overview description: How Next.js works on Pantheon -reviewed: "2025-10-31" +reviewed: "2025-11-17" contenttype: [doc] innav: [true] audience: [development] @@ -22,10 +22,12 @@ Pantheon's product engineering team is rolling out new functionality often while ### Compatibility & Requirements * **Node versions:** - * Pantheon provides the latest 3 LTS versions of Node.js. Pantheon derives which one to use by looking at the `engines` property in `package.json`. + * During Beta, Pantheon supports Node.js `22.21.0`. In the future, we will provide support for the latest **3 LTS versions**. Pantheon derives which one to use by looking at the engines property in `package.json`, so ensure this is set in your project’s configuration. +* **Next.js versions:** + * During Beta, Pantheon supports Next.js `15.3.1`. In the future, we will provide support for the latest **2 LTS versions**. * **Package managers:** * Pantheon will use `npm`, `yarn`, or `pnm` depending on which lock file you have present in your repository. Having a lock file for more than one package manager can create unpredictable behavior. -* **GitHub:** +* **External version control:** * Next.js sites can only run on Pantheon if the code comes from a GitHub repository. Eventually we will expand that capability to BitBucket and GitLab. ### Usage @@ -49,15 +51,5 @@ While Next.js is fundamentally a server-side application, it does not dicate whe By running Next.js on Pantheon, you can combine it with Drupal, WordPress or Content Publisher to provided a unified approach to content management and delivery. ## Considerations -The following are known limitations for Next.js on Pantheon: -* These Site Dashboard features are not supported for Next.js at this time: - * Status reports - * Errors - * Domains & HTTPS, Upgrading site plan -* Performance addons are not supported for Next.js at this time, regardless of site plan: - * New Relic - * Redis - * Solr -* The following Workspace features are not supported for Next.js at this time: - * Autopilot - * Custom Upstreams \ No newline at end of file +See the following page for current limitations of Next.js Beta functionality on Pantheon: +* [Known issues and considerations for Next.js Beta](/nextjs/considerations) \ No newline at end of file diff --git a/src/components/omniSidebarNav/submenus/webInfrastructure.js b/src/components/omniSidebarNav/submenus/webInfrastructure.js index 98fd78b404..84af255bc8 100644 --- a/src/components/omniSidebarNav/submenus/webInfrastructure.js +++ b/src/components/omniSidebarNav/submenus/webInfrastructure.js @@ -151,7 +151,7 @@ const webInfrastructure = () => { simpleLink('/nextjs', 'Next.js', [ simpleLink('/nextjs', 'Next.js Overview'), - simpleLink('/nextjs/limitations', 'Limitations during Beta'), + simpleLink('/nextjs/considerations', 'Considerations'), simpleLink('/nextjs/architecture', 'Architecture and Git Workflow', [ simpleLink('/nextjs/architecture', 'Architecture'), simpleLink('/nextjs/multidev', 'Multidev environments'), From 7631430b6dad8a7a1d9316c7cd9b3871e9b30008 Mon Sep 17 00:00:00 2001 From: Rachel Whitton Date: Mon, 17 Nov 2025 12:56:52 -0600 Subject: [PATCH 4/5] Apply feedback from coworking earlier --- source/content/nextjs/limitations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/content/nextjs/limitations.md b/source/content/nextjs/limitations.md index bf8aa02567..631daf86c0 100644 --- a/source/content/nextjs/limitations.md +++ b/source/content/nextjs/limitations.md @@ -86,7 +86,7 @@ We will create the same capacity for Next.js to clear CDN caches itself in respo 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](https://wordpress.org/plugins/pantheon-advanced-page-cache/) and [module](https://www.drupal.org/project/pantheon_advanced_page_cache). -For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of [\](https://react.dev/reference/react/Suspense) components as a performance optimization. +For many teams this restriction is counterproductive. That is especially true in the Next.js ecosystem which is investing further in usage of [``](https://react.dev/reference/react/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](https://github.com/pantheon-systems/documentation/issues/9767) if you have thoughts on how to provide guidance around situations where full page caching in the CDN. is still preferable to streaming. @@ -102,7 +102,7 @@ Node.js is the most common run time for Next.js. Bun and Deno both have compelli ### **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 with very minimal modification to our tech stack. 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. +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](https://pantheon.io/nextjs-beta) and tell us more about your projects. From 5f2a8a2c42f86a7da0a431b955aedc89b27a53bb Mon Sep 17 00:00:00 2001 From: Rachel Date: Tue, 18 Nov 2025 17:22:09 -0600 Subject: [PATCH 5/5] Revert compatibility copy edits for node, remove nextjs bullet --- source/content/nextjs/overview.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/content/nextjs/overview.md b/source/content/nextjs/overview.md index 91da188238..c0185d9bff 100644 --- a/source/content/nextjs/overview.md +++ b/source/content/nextjs/overview.md @@ -22,9 +22,7 @@ Pantheon's product engineering team is rolling out new functionality often while ### Compatibility & Requirements * **Node versions:** - * During Beta, Pantheon supports Node.js `22.21.0`. In the future, we will provide support for the latest **3 LTS versions**. Pantheon derives which one to use by looking at the engines property in `package.json`, so ensure this is set in your project’s configuration. -* **Next.js versions:** - * During Beta, Pantheon supports Next.js `15.3.1`. In the future, we will provide support for the latest **2 LTS versions**. + * Pantheon provides the latest 3 LTS versions of Node.js. Pantheon derives which one to use by looking at the engines property in `package.json`, so ensure this is set in your project’s configuration. * **Package managers:** * Pantheon will use `npm`, `yarn`, or `pnm` depending on which lock file you have present in your repository. Having a lock file for more than one package manager can create unpredictable behavior. * **External version control:** @@ -52,4 +50,4 @@ By running Next.js on Pantheon, you can combine it with Drupal, WordPress or Con ## Considerations See the following page for current limitations of Next.js Beta functionality on Pantheon: -* [Known issues and considerations for Next.js Beta](/nextjs/considerations) \ No newline at end of file +* [Known issues and considerations for Next.js Beta](/nextjs/considerations)