Next.js Framework Guide
Introduction
Next.js is the most popular open source React-based framework. It allows developers to use all the features you need for production in a front-end framework: hybrid static & server rendering, TypeScript support, smart bundling, route pre-fetching, and more.
Check out their documentation for guides to all these key features.
Deploy Steps
To ensure enhanced support for certain Next.js features, include @wpengine/atlas-next in your dependencies and modify your next.config.js configuration as outlined in this documentation.
After completing the steps in the guide mentioned above, you can get started by running the following command to create a new Next.js project. Then, follow the steps in the automatic setup guide:
$ npx create-next-app@latest*This guide is for the legacy Next.js 12 Pages Router. When you pull down the Next.js package with @latest, you will be prompted to choose what version you want to use in the CLI. You can select “No” when asked if you want to use the App Router and this will tell Next that you want to use the Pages Router.*
Or, if you want to start with a template designed specifically for headless WordPress, you can clone one of these starter templates:
$ git clone https://github.com/colbyfayock/next-wordpress-starter$ git clone https://github.com/colbyfayock/next-wpgraphql-basic-starter$ git clone https://github.com/JEverhart383/crash-course-headless-wp-next-wpgraphqlPush Initial Commits to Your Repository
To deploy your project to our Headless Platform, it will need to be available on a remote GitHub or Bitbucket repository. The Next.js installation process lets us initialize a local repository for the project.
Create a new remote repository, and then run the following commands to initialize and configure your local and remote repositories:
# Add remote repository
$ git remote add origin https://<your-git-provider>/<username>/<repo>
# Stage all changed files
$ git add -A
# Commit the files to the current branch
$ git commit -m "initial commit"
# Push changes to remote repository
$ git push -u origin main
Build Details
Our Headless Platform detects that it is a Next.js app and runs the build scripts and configs necessary for the build details.
One thing to note is the next/cache folder within your Next.js project. Our Headless Platform caches common framework assets between builds to optimize build times. The build step will not override the folder.
Deploy Your Repository
Once your project is in your repository, you can follow the directions in our getting started guide to deploy your project to our Headless Platform.
Best Practices
Next Image
The Next.js Image component, next/image, is an extension of the HTML <img> element, evolved for the modern web.
It includes a variety of built-in performance optimizations to help you achieve good Core Web Vitals.
Keep in mind that when you switch your domains over to our Headless Platform, you must declare them in the next.js.config file, otherwise the images will not render. Please reference Next Image Docs for guidance.
Known Limitations
Incremental Static Regeneration
Incremental Static Regeneration is supported in our Headless Platform through the @wpengine/atlas-next package (see documentation).
Edge Runtime/Middleware
Because our Headless Platform does not rely on serverless functions/edge functions, such functionality currently runs on the origin Node server. It is important to note that this means that such functions will run only on requests that terminate at the origin; any requests served from the edge will continue to serve whatever response is cached at the edge for that path.
The Next.js documentation has more in-depth details on framework features.
Next.js 14
Next.js 14 is a React framework for building full-stack web applications. It uses React Server Components to build user interfaces, while providing additional features and optimizations. In Next.js 14, the App Router is introduced as the new folder and routing structure. However, a limitation is that our Headless Platform does not currently support its full range of functionality and features.