Unverified Commit a391d328 authored by Luis Alvarez D's avatar Luis Alvarez D Committed by GitHub

Add docs for multi zones (#11348)

* Updated example

* Added single now.json

* Added Multi Zones docs

* Fix titles

* Added back the deploy button
parent 4801dcdd
# Multi Zones
<details>
<summary><b>Examples</b></summary>
<ul>
<li><a href="/examples/with-zones">With Zones</a></li>
</ul>
</details>
A zone is a single deployment of a Next.js app. You can have multiple zones and merge them as a single app.
For example, let's say you have the following apps:
- An app for serving `/blog/**`
- Another app for serving all other pages
With multi zones support, you can merge both these apps into a single one allowing your customers to browse it using a single URL, but you can develop and deploy both apps independently.
## How to define a zone
There are no special zones related APIs. You only need to do following:
- Make sure to keep only the pages you need in your app, meaning that an app can't have pages from another app, if app `A` has `/blog` then app `B` shouldn't have it too.
- Make sure to add an [assetPrefix](/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md) to avoid conflicts with static files.
## How to merge zones
You can merge zones using any HTTP proxy.
For [ZEIT Now](https://zeit.co/now), you can use a single `now.json` to deploy both apps. It allows you to easily define routing routes for multiple apps like below:
```json
{
"version": 2,
"builds": [
{ "src": "blog/package.json", "use": "@now/next" },
{ "src": "home/package.json", "use": "@now/next" }
],
"routes": [
{ "src": "/blog/_next(.*)", "dest": "blog/_next$1" },
{ "src": "/blog(.*)", "dest": "blog/blog$1" },
{ "src": "(.*)", "dest": "home$1" }
]
}
```
You can also configure a proxy server to route using a set of routes like the ones above, e.g deploy the blog app to `https://blog.example.com` and the home app to `https://home.example.com` and then add a proxy server for both apps in `https://example.com`.
......@@ -148,6 +148,10 @@
{
"title": "`src` Directory",
"path": "/docs/advanced-features/src-directory.md"
},
{
"title": "Multi Zones",
"path": "/docs/advanced-features/multi-zones.md"
}
]
},
......
......@@ -2,6 +2,11 @@
With Next.js you can use multiple apps as a single app using it's [multi-zones feature](https://nextjs.org/docs#multi-zones). This is an example showing how to use it.
- All pages should be unique across zones. For example, the `home` app should not have a `pages/blog/index.js` page.
- The `blog` app sets `assetPrefix` so that generated JS bundles are within the `/blog` subfolder.
- To also support the plain `next dev` scenario, `assetPrefix` is set dynamically based on the `BUILDING_FOR_NOW` environment variable, see [`now.json`](now.json) and [`blog/next.config.js`](blog/next.config.js).
- Images and other `/static` assets have to be prefixed manually, e.g., `` <img src={`${process.env.ASSET_PREFIX}/static/image.png`} /> ``, see [`blog/pages/blog/index.js`](blog/pages/blog/index.js).
## Deploy your own
Deploy the example using [ZEIT Now](https://zeit.co/now):
......@@ -29,31 +34,16 @@ curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2
cd with-zones
```
## Notes
In this example, we have two apps: 'home' and 'blog'. You can start each app separately, for example:
For every app, install dependencies and run the dev server:
```bash
cd blog
npm install
npm run dev
# or
yarn
yarn dev
```
Then, you can visit <http://localhost:3000> and develop your app.
## Special Notes
- All pages should be unique across zones. For example, the 'home' app should not have a `pages/blog/index.js` page.
- The 'blog' app sets `assetPrefix` so that generated JS bundles are within the `/blog` subfolder.
- To also support the plain `next dev` scenario, `assetPrefix` is set dynamically based on the `BUILDING_FOR_NOW` environment variable, see [`now.json`](now.json) and [`blog/next.config.js`](blog/next.config.js).
- Images and other `/static` assets have to be prefixed manually, e.g., `` <img src={`${process.env.ASSET_PREFIX}/static/image.png`} /> ``, see [`blog/pages/blog/index.js`](blog/pages/blog/index.js).
## Production Deployment
We only need to run `now <app>`, to deploy the app:
```bash
now blog
now home
```
The `home` app will start in the default port (http://localhost:3000), and `blog` will start on http://localhost:4000.
> The rewrite destination in your `now.json` file in the `home` app must be adjusted to point to your deployment.
Deploy it to the cloud with [ZEIT Now](https://zeit.co/import?filter=next.js&utm_source=github&utm_medium=readme&utm_campaign=next-example) ([Documentation](https://nextjs.org/docs/deployment)).
{
"build": {
"env": {
"BUILDING_FOR_NOW": "true"
}
},
"rewrites": [
{
"source": "/blog/_next$1",
"destination": "/_next$1"
}
]
}
.next
node_modules
.now
\ No newline at end of file
{
"rewrites": [
{
"source": "/blog(.*)",
"destination": "https://with-zones-blog.now.sh$1"
}
]
}
......@@ -2,7 +2,7 @@
"name": "with-zones-home",
"version": "1.0.0",
"scripts": {
"dev": "next dev -p 4001"
"dev": "next dev"
},
"dependencies": {
"next": "latest",
......
{
"version": 2,
"build": {
"env": {
"BUILDING_FOR_NOW": "true"
}
},
"builds": [
{ "src": "blog/package.json", "use": "@now/next" },
{ "src": "home/package.json", "use": "@now/next" }
],
"routes": [
{ "src": "/blog/_next(.*)", "dest": "blog/_next$1" },
{ "src": "/blog(.*)", "dest": "blog/blog$1" },
{ "src": "(.*)", "dest": "home$1" }
]
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment