[Docs] Environment Variables (#12696)

docs/api-reference/next.config.js/environment-variables.md

@@ -4,6 +4,8 @@ description: Learn to add and access environment variables in your Next.js appli
 
 # Environment Variables
 
+> Since the release of Next.js 9.4 we now have a more intuitive and ergonomic experience for [adding environment variables](/docs/basic-features/environment-variables.md). Give it a try!
+
 <details>
   <summary><b>Examples</b></summary>
   <ul>
@@ -54,3 +56,10 @@ return <h1>The value of customKey is: {'my-value'}</h1>
     <small>Learn more about the configuration file used by Next.js.</small>
   </a>
 </div>
+
+<div class="card">
+  <a href="/docs/basic-features/environment-variables.md">
+    <b>Built-in support for Environment Variables:</b>
+    <small>Learn more about the new support for environment variables.</small>
+  </a>
+</div>

docs/basic-features/environment-variables.md

@@ -0,0 +1,107 @@
+---
+description: Learn to add and access environment variables in your Next.js application.
+---
+
+# Environment Variables
+
+> This document is for Next.js versions 9.4 and up. If you’re using an older version of Next.js, refer to [Environment Variables in next.config.js](/docs/api-reference/next.config.js/environment-variables.md).
+
+Next.js comes with built-in support for environment variables, which allows you to do the following:
+
+- [Inline variables starting with `NEXT_PUBLIC_`](#inlined-environment-variables)
+- [Use `.env` to add custom environment variables](#exposing-environment-variables)
+
+## Inlined Environment Variables
+
+Next.js will inline any environment variable that starts with `NEXT_PUBLIC_` in your application. Inlining means replacing the variable with the value. For example, the following page:
+
+```jsx
+export default function Page() {
+  return <h1>The public value is: {process.env.NEXT_PUBLIC_EXAMPLE_KEY}</h1>
+}
+```
+
+Will end up being:
+
+```jsx
+export default function Page() {
+  return <h1>The public value is: {'my-value'}</h1>
+}
+```
+
+Next.js replaced `process.env.NEXT_PUBLIC_EXAMPLE_KEY` with its value, that in this case is `'my-value'`.
+
+You can use the shell or any other tool that runs before the [Next.js CLI](/api-reference/cli) to add environment variables. For example, using bash:
+
+```bash
+NEXT_PUBLIC_EXAMPLE_KEY=my-value npx next dev
+```
+
+Or using [cross-env](https://github.com/kentcdodds/cross-env) for Windows and Unix support:
+
+```bash
+npx cross-env NEXT_PUBLIC_EXAMPLE_KEY=my-value next dev
+```
+
+### Caveats
+
+- Trying to destructure `process.env` variables won't work due to the limitations of webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/).
+- To avoid exposing secrets, do not use the `NEXT_PUBLIC_` prefix for them. Instead, [expose the variables using `.env`](#exposing-environment-variables).
+
+## Exposing Environment Variables
+
+Next.js allows you to expose variables using an environment variables file (`.env`), with included support for multiple environments. It works like this:
+
+- `.env` - Contains environment variables for all environments
+- `.env.local` - Local variable overrides for all environments
+- `.env.[environment]` - Environment variables for one environment. For example: `.env.development`
+- `.env.[environment].local` - Local variable overrides for one environment. For example: `.env.development.local`
+
+> **Note**: `.env` files **should be** included in your repository, and **`.env*.local` should be in `.gitignore`**, as those files are intended to be ignored. Consider `.local` files as a good place for secrets, and non-local files as a good place for defaults.
+
+The supported environments are `development`, `production` and `test`. The environment is selected in the following way:
+
+- [`next dev`](/docs/api-reference/cli#development) uses `development`
+- [`next build`](/docs/api-reference/cli#build) and [`next-start`](/docs/api-reference/cli#production) use `production`
+
+If the same environment variable is defined multiple times, the priority of which variable to use is decided in the following order:
+
+- Already defined environment variables have the higher priority. For example: `MY_KEY=value next dev`
+- `.env.[environment].local`
+- `.env.[environment]`
+- `.env.local`
+- `.env`
+
+For example, consider the file `.env.local` with the following content:
+
+```bash
+API_KEY='my-secret-api-key'
+NEXT_PUBLIC_APP_LOCALE='en-us'
+```
+
+And the following page:
+
+```jsx
+export default function Page() {
+  return <h1>The locale is set to: {process.env.NEXT_PUBLIC_APP_LOCALE}</h1>
+}
+
+export async function getStaticProps() {
+  const db = await myDB(process.env.API_KEY)
+  // ...
+}
+```
+
+`process.env.NEXT_PUBLIC_APP_LOCALE` will be replaced with `'en-us'` in the build output. This is because variables that start with `NEXT_PUBLIC_` will be [inlined at build time](#inlined-environment-variables).
+
+`process.env.API_KEY` will be a variable with `'my-secret-api-key'` at build time and runtime, but the build output will not contain this key. This is because `process.env.API_KEY` is only used by [`getStaticProps`](/docs/basic-features/data-fetching.md#getstaticprops-static-generation) which [runs only on the server](/docs/basic-features/data-fetching.md#write-server-side-code-directly) — and only the props returned by `getStaticProps` are included in the client build. Same goes for our other [data fetching methods](/docs/basic-features/data-fetching.md).
+
+Now, if you add a `.env` file like this one:
+
+```bash
+API_KEY='default-api-key'
+CLIENT_KEY='default-client-key'
+NEXT_PUBLIC_APP_LOCALE='en-us'
+```
+
+Both `API_KEY` and `NEXT_PUBLIC_APP_LOCALE` will be ignored as `.env.local` has a higher priority, but `CLIENT_KEY` will become available.

docs/manifest.json

@@ -28,6 +28,10 @@
             {
               "title": "TypeScript",
               "path": "/docs/basic-features/typescript.md"
+            },
+            {
+              "title": "Environment Variables",
+              "path": "/docs/basic-features/environment-variables.md"
             }
           ]
         },