Add docs for multi zones

docs/advanced-features/multi-zones.md

@@ -0,0 +1,47 @@
+# 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`.

docs/manifest.json

@@ -148,6 +148,10 @@
             {
               "title": "`src` Directory",
               "path": "/docs/advanced-features/src-directory.md"
+            },
+            {
+              "title": "Multi Zones",
+              "path": "/docs/advanced-features/multi-zones.md"
             }
           ]
         },

examples/with-zones/README.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)).

examples/with-zones/home/package.json

@@ -2,7 +2,7 @@
   "name": "with-zones-home",
   "version": "1.0.0",
   "scripts": {
-    "dev": "next dev -p 4001"
+    "dev": "next dev"
   },
   "dependencies": {
     "next": "latest",

examples/with-zones/now.json

@@ -0,0 +1,17 @@
+{
+  "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" }
+  ]
+}