Skip to content

fix(docs): Environment Variables Examples #10406

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 12, 2018
Merged

fix(docs): Environment Variables Examples #10406

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
faac380
Add example + fix code for ENV var doc
LekoArts Dec 11, 2018
1f12631
Address michal's suggestions
LekoArts Dec 12, 2018
ed4fd82
Update environment-variables.md
DSchau Dec 12, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions docs/docs/environment-variables.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,10 @@ In addition to these Project Environment Variables defined in `.env.*` files, yo
OS Env Vars. OS Env Vars which are prefixed with `GATSBY_` will become available in
browser JavaScript.

```shell:title=.env.*
Copy link
Contributor

@shannonbux shannonbux Dec 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh, does the name of this file actually include an asterisk?

Copy link
Contributor Author

@LekoArts LekoArts Dec 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The asterisk means that all names are possible (it's a common way to write it like that), that's why it's already used in line 46.

Copy link
Contributor

@DSchau DSchau Dec 12, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, @LekoArts I think this is reasonable.

@shannonbux for clarification, we typically use .env.development and .env.production since those credentials could (and often do) change between environments.

GATSBY_API_URL=https://dev.example.com/api
```

#### Server-side Node.js

Gatsby runs several Node.js scripts at build time, notably `gatsby-config.js` and `gatsby-node.js`.
Expand Down Expand Up @@ -77,31 +81,45 @@ Now the variables are available on `process.env` as usual.

## Example

```shell
# Example .env.development file

API_URL=https://dev.example.com/api
```shell:title=.env.development
GATSBY_API_URL=https://dev.example.com/api
API_KEY=927349872349798
```

```shell
# Example .env.production file

API_URL=https://example.com/api
```shell:title=.env.production
GATSBY_API_URL=https://example.com/api
API_KEY=927349872349798
```

These variables will be available to your site as `process.env.API_URL`:
`GATSBY_API_URL` will be available to your site (Client-side and server-side) as `process.env.GATSBY_API_URL`:

```jsx
// usage
// In any front-end code
render() {
return (
<div>
<img src={`${process.env.API_URL}/logo.png`} alt="Logo" />
<img src={`${process.env.GATSBY_API_URL}/logo.png`} alt="Logo" />
</div>
)
}
```

`API_KEY` will be available to your site (Server-side) as `process.env.API_KEY`:
Copy link
Contributor

@pieh pieh Dec 11, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not quite correct - API_KEY will be available on front-side code (if .env file is actually there). What probably need to be better documented is that people shouldn't commit .env files really and use options provided by various CD providers (for example Netlify) to define those. And because of that they should prefix things they want available for frontend with GATSBY_ as .env files won't be used by their CD when building gatsby site

Copy link
Contributor

@pieh pieh Dec 11, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

☝️ is actually verified by https://github.com/gatsbyjs/gatsby/blob/0aade74a1862f7be9875e8f3d84eb049de132c10/e2e-tests/production-runtime/.env.production /

gatsby/e2e-tests/production-runtime/cypress/integration/production.js

Lines 75 to 81 in 0aade74

it(`Uses env vars`, () => {
cy.visit(`/env-vars`).waitForAPI(`onRouteUpdate`)
cy.getTestElement(`process.env`).contains(`{}`)
cy.getTestElement(`process.env.EXISTING_VAR`).contains(`"foo bar"`)
cy.getTestElement(`process.env.NOT_EXISTING_VAR`).should(`be.empty`)
})


```js
// In any server-side code, e.g. gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-source-patronus`,
options: {
apiKey: process.env.API_KEY,
},
},
],
}
```

## Reserved Environment Variables:

> You can not override certain environment variables as some are used internally
Expand All @@ -121,8 +139,7 @@ For instance. If you would like to add a `staging` environment with a custom Goo

### Example

```shell
# .env.staging
```shell:title=.env.staging
GA_TRACKING_ID="UA-1234567890"
API_URL="http://foo.bar"
```
Expand Down