<!-- Thanks for opening a PR! Your contribution is much appreciated. To make sure your PR is handled as smoothly as possible we request that you follow the checklist sections below. Choose the right checklist for the change(s) that you're making: ## For Contributors ### Improving Documentation or adding/fixing Examples - The "examples guidelines" are followed from our contributing doc https://github.com/vercel/next.js/blob/canary/contributing/examples/adding-examples.md - Make sure the linting passes by running `pnpm build && pnpm lint`. See https://github.com/vercel/next.js/blob/canary/contributing/repository/linting.md ### Fixing a bug - Related issues linked using `fixes #number` - Tests added. See: https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ### Adding a feature - Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. (A discussion must be opened, see https://github.com/vercel/next.js/discussions/new?category=ideas) - Related issues/discussions are linked using `fixes #number` - e2e tests added (https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs - Documentation added - Telemetry added. In case of a feature if it's used or not. - Errors have a helpful link attached, see https://github.com/vercel/next.js/blob/canary/contributing.md ## For Maintainers - Minimal description (aim for explaining to someone not on the team to understand the PR) - When linking to a Slack thread, you might want to share details of the conclusion - Link both the Linear (Fixes NEXT-xxx) and the GitHub issues - Add review comments if necessary to explain to the reviewer the logic behind a change ### What? ### Why? ### How? Closes NEXT- Fixes # --> closes #48416 ### What? Standardize the "Note" format in the Next.js documentation for improved consistency and readability. ### Why? There are currently four different variations of "Note" formatting in the documentation. Standardizing to a single format will improve the overall experience for users. ### How? Update all instances of "Note" in the documentation to follow the most common format, `**Note**:` (used in 27 files). This will involve updating the following variations: - `Note` (12 files) - `Note:` (20 files) - `**Note:**` (21 files) --------- Co-authored-by: Steven <steven@ceriously.com>
5.2 KiB
description |
---|
Learn different strategies for incrementally adopting Next.js into your development workflow. |
Incrementally Adopting Next.js
Examples
Next.js has been designed for gradual adoption. With Next.js, you can continue using your existing code and add as much (or as little) React as you need. By starting small and incrementally adding more pages, you can prevent derailing feature work by avoiding a complete rewrite.
Strategies
Subpath
The first strategy is to configure your server or proxy such that, everything under a specific subpath points to a Next.js app. For example, your existing website might be at example.com
, and you might configure your proxy such that example.com/store
serves a Next.js e-commerce store.
Using basePath
, you can configure your Next.js application's assets and links to automatically work with your new subpath /store
. Since each page in Next.js is its own standalone route, pages like pages/products.js
will route to example.com/store/products
in your application.
// next.config.js
module.exports = {
basePath: '/store',
}
To learn more about basePath
, take a look at our documentation.
Rewrites
The second strategy is to create a new Next.js app that points to the root URL of your domain. Then, you can use rewrites
inside next.config.js
to have some subpaths to be proxied to your existing app.
For example, let's say you created a Next.js app to be served from example.com
with the following next.config.js
. Now, requests for the pages you’ve added to this Next.js app (e.g. /about
if you’ve added pages/about.js
) will be handled by Next.js, and requests for any other route (e.g. /dashboard
) will be proxied to proxy.example.com
.
Note
: If you use fallback: true/'blocking' in
getStaticPaths
, the catch-all fallbackrewrites
defined innext.config.js
will not be run. They are instead caught by thegetStaticPaths
fallback.
// next.config.js
module.exports = {
async rewrites() {
return {
// After checking all Next.js pages (including dynamic routes)
// and static files we proxy any other requests
fallback: [
{
source: '/:path*',
destination: `https://proxy.example.com/:path*`,
},
],
}
// For versions of Next.js < v10.1 you can use a no-op rewrite instead
return [
// we need to define a no-op rewrite to trigger checking
// all pages/static files before we attempt proxying
{
source: '/:path*',
destination: '/:path*',
},
{
source: '/:path*',
destination: `https://proxy.example.com/:path*`,
},
]
},
}
To learn more about rewrites, take a look at our documentation.
Note
: If you are incrementally migrating to a dynamic route (e.g.
[slug].js
) and usingfallback: true
orfallback: 'blocking'
along with a fallbackrewrite
, ensure you consider the case where pages are not found. When Next.js matches the dynamic route it stops checking any further routes. UsingnotFound: true
ingetStaticProps
will return the 404 page without applying the fallbackrewrite
. If this is not desired, you can usegetServerSideProps
withstale-while-revalidate
Cache-Control headers when returning your props. Then, you can manually proxy to your existing backend using something like http-proxy instead of returningnotFound: true
.
Micro-Frontends with Monorepos and Subdomains
Next.js and Vercel make it straightforward to adopt micro frontends and deploy as a monorepo. This allows you to use subdomains to adopt new applications incrementally. Some benefits of micro-frontends:
- Smaller, more cohesive and maintainable codebases.
- More scalable organizations with decoupled, autonomous teams.
- The ability to upgrade, update, or even rewrite parts of the frontend in a more incremental fashion.
Once your monorepo is set up, push changes to your Git repository as usual and you'll see the commits deployed to the Vercel projects you've connected.
Conclusion
To learn more, read about subpaths and rewrites or deploy a Next.js monorepo.