Environment variables are configuration values defined in the environment your code runs in. Sites often need different database connections for live, staging and local setups, and hard-coding those details in files like wp-config.php makes them harder to keep secret and harder to keep in source control. Moving the values outside the code solves both problems, and .env files are a common place to define them — typically kept out of source control via .gitignore, since they often hold secret keys and connection strings. Tools like dotenv and phpdotenv scoop those values up from a .env file, a Docker script or a deploy script, so the same code works regardless of where they are defined.
Setting up the Eleventy project
The tutorial uses a bare-bones Eleventy starter: download the provided zip, unzip it, run npm install and then npm start, and the site is available at http://localhost:8080. In addition, create an empty .env file in the root of the project folder.
A human-friendly interface
Environment variables are usually all caps and shouty. A JavaScript interface can consume them and export human-friendly, namespaced values, so the code makes clear that environment variables are in play. Given HELLO=hi there in the .env file, the raw access is process.env.HELLO — which gets tiresome and needs a fallback when the value is undefined. A small module can use the OR operator (||) to supply defaults, after which templates can use {{ env.hello }}.
The starter includes an empty src/_data/env.js file inside a src/_data directory. Because the data file is named env.js, templates access it with the env prefix; renaming it environment.js would change the prefix to environment. This relies on Eleventy JavaScript Data Files, which run JavaScript and return the output as static data, and which also support asynchronous code. See the Eleventy documentation on data files for more.
The exported object holds a hello value and an otherSiteUrl value, the latter used to show different versions of the site based on environment configuration. In src/index.md, adding {{ env.hello }} at the bottom of the file demonstrates that variables work right in content; changing HELLO in .env and restarting the npm start task updates the output.
Example output includes a {% raw %} wrapper. This is a Nunjucks tag marking sections Nunjucks should ignore; without it, Nunjucks would try to evaluate the example {{ env.hello }}.
Switching image base paths
Production images are often served through a CDN so you get performance gains and broader image format support, while local development still needs local images. A CDN serves images directly from your site, such as from an /images folder, and has no access to the local site, so being able to switch between the two is useful. With Eleventy and dotenv this is almost trivial, because undefined environment variables at the point of usage throw no errors.
New properties are added to the object in src/_data/env.js. imageBase defaults to /images/ so local images resolve when IMAGE_BASE is not defined; imageProps gets no default because it can be empty unless needed. In _includes/base.njk, after the <h1>{{ title }}</h1> line, markup is added that loads /images/mountains.jpg by default. Adding IMAGE_BASE to .env, stopping Eleventy (Ctrl+C) and running npm start again, then viewing source in the browser, renders the CDN-hosted image variant — for example, to use CodePen asset optimizations only when wanted.
Conditional rendering for private content
Environment variables also support rendering content conditionally by mode, such as private mode. Content platforms built on Eleventy — including a paid course and a CSS book — use this: service workers and APIs do the heavy lifting, but core to it is conditional rendering driven by env.mode.
Adding mode to the object in src/_data/env.js makes the default public. With extra content appended to src/index.md, a local refresh shows nothing new, which is the intended protection. Adding the mode value to .env, restarting Eleventy and reloading reveals the content. The same conditional rendering can be applied in the template itself — for instance, making page content private and rendering a paywall instead; a course page without a license presents a call to action to buy.
Fun mode
The final exercise makes a “fun mode” that fully changes the design. In src/_includes/base.njk, just before the closing </head> tag, a snippet checks whether the funMode environment variable is true and, if so, adds some “fun” CSS. Just before the opening <article> tag, the same logic renders a fun banner when funMode is true. The funMode property is then added to the exported object in src/_data/env.js. If it is not defined it acts as false, because undefined is a falsy value. Adding the value to .env, restarting Eleventy and reloading the browser yields the loud alternative design.
Three sites, one codebase
The exercise produces three versions of the same site running identical code, differing only in environment variables — defined in the Netlify dashboard for this example:



