Feature: Custom "pages" directory w/ Example + Docs

docs/advanced-features/custom-pages-directory.md

@@ -0,0 +1,29 @@
+---
+description: Set a custom `pages` directory by adding a `pagesDir` property to your `next.config.js` file.
+---
+
+# Custom Pages Directory
+
+If you would like to further customize your `pages` directory path outside of `pages` and `src/pages`, you can also set a custom `pages` directory via your `next.config.js` file.
+
+# Example - `next.config.js`
+
+```
+const path = require('path')
+
+module.exports = {
+  pagesDir: path.join(__dirname, 'src/universal/page-components'),
+}
+
+```
+
+## Related
+
+For more information on what to do next, we recommend the following sections:
+
+<div class="card">
+  <a href="/docs/basic-features/pages.md">
+    <b>Pages:</b>
+    <small>Learn more about what pages are in Next.js</small>
+  </a>
+</div>

docs/manifest.json

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

examples/with-custom-pages-directory/README.md

@@ -0,0 +1,44 @@
+# with-custom-pages-directory
+
+Example of how to set a custom `pages` directory. The only change that is needed is add the `pagesDir` property to your `next.config.js` file.
+
+```
+const path = require('path')
+
+module.exports = {
+  pagesDir: path.join(__dirname, 'src/universal/page-components')
+}
+```
+
+## How to use
+
+### Using `create-next-app`
+
+Execute [`create-next-app`](https://github.com/zeit/next.js/tree/canary/packages/create-next-app) with [npm](https://docs.npmjs.com/cli/init) or [Yarn](https://yarnpkg.com/lang/en/docs/cli/create/) to bootstrap the example:
+
+```bash
+npx create-next-app --example with-custom-pages-directory with-custom-pages-directory-app
+# or
+yarn create next-app --example with-custom-pages-directory with-custom-pages-directory-app
+```
+
+### Download manually
+
+Download the example:
+
+```bash
+curl https://codeload.github.com/zeit/next.js/tar.gz/canary | tar -xz --strip=2 next.js-canary/examples/with-custom-pages-directory
+cd with-custom-pages-directory
+```
+
+Install it and run:
+
+```bash
+npm install
+npm run dev
+# or
+yarn
+yarn dev
+```
+
+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-custom-pages-directory/next.config.js

@@ -0,0 +1,5 @@
+const path = require('path')
+
+module.exports = {
+  pagesDir: path.join(__dirname, 'src/universal/page-components'),
+}

examples/with-custom-pages-directory/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "with-custom-pages-directory",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start"
+  },
+  "dependencies": {
+    "next": "latest",
+    "react": "16.13.1",
+    "react-dom": "16.13.1"
+  }
+}

examples/with-custom-pages-directory/src/universal/page-components/index.js

@@ -0,0 +1 @@
+export default () => <div>You have a Custom Pages Directory: Index</div>

examples/with-custom-pages-directory/src/universal/page-components/page1.js

@@ -0,0 +1 @@
+export default () => <div>You have a Custom Pages Directory: Page 1</div>

examples/with-custom-pages-directory/src/universal/page-components/page2.js

@@ -0,0 +1 @@
+export default () => <div>You have a Custom Pages Directory: Page 2</div>

packages/next/build/index.ts

@@ -164,7 +164,7 @@ export default async function build(dir: string, conf = null): Promise<void> {
   const telemetry = new Telemetry({ distDir })
 
   const publicDir = path.join(dir, 'public')
-  const pagesDir = findPagesDir(dir)
+  const pagesDir = findPagesDir(dir, config)
   let publicFiles: string[] = []
   let hasPublicDir = false
 

packages/next/lib/find-pages-dir.ts

@@ -10,14 +10,19 @@ export const existsSync = (f: string): boolean => {
   }
 }
 
-export function findPagesDir(dir: string): string {
+export function findPagesDir(dir: string, nextConfig: any): string {
   // prioritize ./pages over ./src/pages
   let curDir = path.join(dir, 'pages')
   if (existsSync(curDir)) return curDir
 
   curDir = path.join(dir, 'src/pages')
   if (existsSync(curDir)) return curDir
 
+  if (nextConfig.pagesDir) {
+    curDir = nextConfig.pagesDir
+    if (existsSync(curDir)) return curDir
+  }
+
   // Check one level up the tree to see if the pages directory might be there
   if (existsSync(path.join(dir, '..', 'pages'))) {
     throw new Error(

packages/next/server/next-dev-server.ts

@@ -82,7 +82,7 @@ export default class DevServer extends Server {
       )
     }
     this.isCustomServer = !options.isNextDevCommand
-    this.pagesDir = findPagesDir(this.dir)
+    this.pagesDir = findPagesDir(this.dir, this.nextConfig)
     this.staticPathsWorker = new Worker(
       require.resolve('./static-paths-worker'),
       {