You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/docs/cli-feedback.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,8 @@
2
2
title: Gatsby CLI Feedback
3
3
---
4
4
5
-
Gatsby users will be prompted every 3 months (at the most) to give feedback to Gatsby on our products and services. This feedback is incredibly valuable and will help us shape Gatsby.
5
+
Gatsby users will be prompted every 3 months (at the most) to give feedback on Gatsby's products and services. This feedback is incredibly valuable and will help the team shape Gatsby.
6
6
7
7
## How to opt-out
8
8
9
-
Users may always opt-out from the feedback prompts with `gatsby feedback --disable` or by setting the environment variable `GATSBY_TELEMETRY_DISABLED` to `1`
9
+
Users may always opt-out from the feedback prompts with `gatsby feedback --disable` or by setting the [environment variable](/docs/environment-variables/)`GATSBY_TELEMETRY_DISABLED` to `1`.
Copy file name to clipboardexpand all lines: docs/docs/environment-variables.md
+25-24
Original file line number
Diff line number
Diff line change
@@ -2,28 +2,28 @@
2
2
title: Environment Variables
3
3
---
4
4
5
-
## Environments and Environment Variables
6
-
7
-
You can provide environment variables to your site to customise its behavior in different environments.
5
+
You can provide environment variables to your site to customize its behavior in different environments.
8
6
9
7
Environment variables can be distinguished between different types.
8
+
10
9
There are environment variables that are defined in special places intended to be used in different deployment environments. You can call these “Project Env Vars”.
10
+
11
11
And there are true OS-level environment variables that might be used in command-line calls. You can call these “OS Env Vars”.
12
12
13
13
In both cases you want to be able to access the relevant value of these variables for the environment you are in.
14
14
15
-
By default gatsby supports only 2 environments:
15
+
By default Gatsby supports 2 environments:
16
16
17
-
- If you run `gatsby develop`, then you will be in the 'development' environment.
18
-
- If you run `gatsby build` or `gatsby serve`, then you will be in the 'production' environment.
17
+
-**Development.**If you run `gatsby develop`, then you will be in the 'development' environment.
18
+
-**Production.**If you run `gatsby build` or `gatsby serve`, then you will be in the 'production' environment.
19
19
20
-
If you want to define other environments then you'll need to do a little more work. See ["Additional Environments" below](#additional-environments-staging-test-etc). You can also have a look at our[environment variables codesandbox](https://codesandbox.io/s/6w9jjrnnjn) while reading the examples below.
20
+
If you want to define other environments then you'll need to do a little more work. See ["Additional Environments" below](#additional-environments-staging-test-etc). You can also have a look at the[environment variables CodeSandbox](https://codesandbox.io/s/6w9jjrnnjn) while reading the examples.
21
21
22
22
## Accessing Environment Variables in JavaScript
23
23
24
24
All of the Project and OS Env Vars are only directly available at build time, or
25
-
when Node.Js is running. They aren't immediately available at run time of the client code; they
26
-
need to be actively captured and embedded into our client-side JavaScript.
25
+
when Node.js is running. They aren't immediately available at run time of the client code; they
26
+
need to be actively captured and embedded into client-side JavaScript.
27
27
This is achieved during the build using Webpack's [DefinePlugin](https://webpack.js.org/plugins/define-plugin/).
28
28
29
29
Once the environment variables have been embedded into the client-side code, they are accessible from the
@@ -39,8 +39,7 @@ or rebuild your site after changing them.
39
39
40
40
For Project Env Vars that you want to access in client-side browser JavaScript, you can define
41
41
an environment config file, `.env.development` and/or `.env.production`, in your root folder.
42
-
Depending on your active environment, the correct one will be found and its values embedded as environment variables in the
43
-
browser JavaScript.
42
+
Depending on your active environment, the correct one will be found and its values embedded as environment variables in the browser JavaScript.
44
43
45
44
In addition to these Project Environment Variables defined in `.env.*` files, you could also define
46
45
OS Env Vars. OS Env Vars which are prefixed with `GATSBY_` will become available in
Gatsby runs several Node.js scripts at build time, notably `gatsby-config.js` and `gatsby-node.js`.
56
55
OS Env Vars will already be available when Node is running, so you can add environment variables the
57
-
normal ways e.g. by adding environment variables through your hosting/build tool, your OS, or when
56
+
typical ways, e.g. by adding environment variables through your hosting/build tool, your OS, or when
58
57
calling Gatsby on the command line.
59
58
60
59
In Linux terminals this can be done with:
@@ -67,8 +66,8 @@ In Windows it's a little more complex. [Check out this Stack Overflow article fo
67
66
68
67
Project environment variables that you defined in the `.env.*` files will _NOT_ be immediately available
69
68
in your Node.js scripts. To use those variables, use NPM package [dotenv](https://www.npmjs.com/package/dotenv) to
70
-
examine the active `.env.*` file and attached those values,
71
-
It's already a dependency of Gatsby, so you can require it in your `gatsby-config.js` or `gatsby-node.js` like this:
69
+
examine the active `.env.*` file and attach those values.
70
+
`dotenv` is already a dependency of Gatsby, so you can require it in your `gatsby-config.js` or `gatsby-node.js` like this:
72
71
73
72
```javascript:title=gatsby-config.js
74
73
require("dotenv").config({
@@ -78,9 +77,9 @@ require("dotenv").config({
78
77
79
78
Now the variables are available on `process.env` as usual.
80
79
81
-
## Example
80
+
## Example of using an environment variable
82
81
83
-
Please note that you shouldn't commit `.env.*` files to your source control and rather use options given by your CD provider (e.g. Netlify with its [build environment variables](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables)).
82
+
Please note that you shouldn't commit `.env.*` files to your source control and rather use options given by your Continuous Deployment (CD) provider. An example is Netlify with its [build environment variables](https://www.netlify.com/docs/continuous-deployment/#build-environment-variables).
84
83
85
84
```text:title=.env.development
86
85
GATSBY_API_URL=https://dev.example.com/api
@@ -93,6 +92,7 @@ API_KEY=927349872349798
93
92
```
94
93
95
94
Note: since Gatsby uses the [Webpack DefinePlugin](https://webpack.js.org/plugins/define-plugin/) to make the environment variables available at runtime, they cannot be destructured from `process.env`; instead, they have to be fully referenced.
95
+
96
96
`GATSBY_API_URL` will be available to your site (Client-side and server-side) as `process.env.GATSBY_API_URL`.:
97
97
98
98
```jsx
@@ -106,7 +106,7 @@ render() {
106
106
}
107
107
```
108
108
109
-
In Node, your site has access to your `API_KEY` (Server-side) using the identifier `process.env.API_KEY`. To access it client-side, you can use a `.env.*` file containing `API_KEY`. However, we **strongly**advise against checking these files into source control as it's a security issue to expose the API key. As a more secure alternative, you can prefix your variable with `GATSBY_` (as shown above). With this prefix, Gatsby automatically embeds the variable as process.env.GATSBY\_\* in compiled JS making it available in the browser context without exposing it elsewhere.
109
+
In Node, your site has access to your `API_KEY` (Server-side) using the identifier `process.env.API_KEY`. To access it client-side, you can use a `.env.*` file containing `API_KEY`. However, you are **strongly**advised against checking these files into source control as it's a security issue to expose the API key. As a more secure alternative, you can prefix your variable with `GATSBY_` (as shown above). With this prefix, Gatsby automatically embeds the variable as `process.env.GATSBY\_\*` in compiled JS making it available in the browser context without exposing it elsewhere.
110
110
111
111
```js
112
112
// In any server-side code, e.g. gatsby-config.js
@@ -125,7 +125,7 @@ module.exports = {
125
125
## Reserved Environment Variables:
126
126
127
127
> You can not override certain environment variables as some are used internally
128
-
> for optimizations during build
128
+
> for optimizations during build, such as:
129
129
130
130
-`NODE_ENV`
131
131
-`PUBLIC_DIR`
@@ -136,26 +136,27 @@ Gatsby also allows you to specify another environment variable when running the
136
136
137
137
If set to true, this will expose a `/__refresh` webhook that is able to receive `POST` requests to _refresh_ the sourced content. This exposed webhook can be triggered whenever remote data changes, which means you can update your data without re-launching the development server.
138
138
139
-
You can trigger this endpoint locally for example on Unix-based operating systems (like Ubuntu and MacOS) you can use`curl -X POST http://localhost:8000/__refresh`.
139
+
You can trigger this endpoint locally, for example, on Unix-based operating systems (like Ubuntu and MacOS) using`curl -X POST http://localhost:8000/__refresh`.
140
140
141
141
## Build Variables
142
142
143
143
Gatsby uses additional environment variables in the build step to fine-tune the outcome of a build. You may find these helpful for more advanced configurations, such as using [CI/CD](https://en.wikipedia.org/wiki/CI/CD) to deploy a Gatsby site.
144
144
145
145
For example, you can set `CI=true` as an environment variable to allow Gatsby's build script to tailor the terminal output to an automated deployment environment. Some CI/CD tooling may already set this environment variable. This is useful for limiting the verbosity of the build output for [dumb terminals](https://en.wikipedia.org/wiki/Computer_terminal#Dumb_terminals), such as terminal in progress animations.
146
146
147
-
Gatsby detects an optimal level of parallelism for the render phase of `gatsby build` based on the reported number of physical CPUs. For builds that are run in virtual environments, you may need to adjust the number of worker parallelism with the `GATSBY_CPU_COUNT` environment variable. See [Multi-core builds](https://www.gatsbyjs.org/docs/multi-core-builds/).
147
+
Gatsby detects an optimal level of parallelism for the render phase of `gatsby build` based on the reported number of physical CPUs. For builds that are run in virtual environments, you may need to adjust the number of worker parallelism with the `GATSBY_CPU_COUNT` environment variable. See [Multi-core builds](/docs/multi-core-builds/).
148
148
149
-
## Additional Environments (Staging, Test, etc)
149
+
## Additional Environments (Staging, Test, etc.)
150
150
151
151
As noted above `NODE_ENV` is a reserved environment variable in Gatsby as it is needed by the build system to make key optimizations when compiling React and other modules. For this reason it is necessary to make use of a secondary environment variable for additional environment support, and manually make the environment variables available to the client-side code.
152
152
153
153
You can define your own OS Env Var to track the active environment, and then to locate the relevant Project Env Vars to load. Gatsby itself will not do anything with that OS Env Var, but you can use it in `gatsby-config.js`.
154
-
Specifically, you can use `dotenv` and your individual OS Env Var to locate the `.env.myCustomEnvironment` file, and then use module.exports to store those Project Env Vars somewhere that the client-side JavaScript can access the values (via GraphQL queries).
155
154
156
-
For instance: if you would like to add a `staging` environment with a custom Google Analytics Tracking ID, and a dedicated `apiUrl`. You can add `.env.staging` at the root of your project with the following modification to your `gatsby-config.js`
155
+
Specifically, you can use `dotenv` and your individual OS Env Var to locate the `.env.myCustomEnvironment` file, and then use `module.exports` to store those Project Env Vars somewhere that the client-side JavaScript can access the values (via GraphQL queries).
156
+
157
+
### Google Analytics env var example
157
158
158
-
### Example
159
+
If you would like to add a `staging` environment with a custom Google Analytics Tracking ID, and a dedicated `apiUrl` you can add `.env.staging` at the root of your project. In order to do so, use the following modification to your `gatsby-config.js`:
0 commit comments