Geben Sie Ihrer Eleventy-Website Superkräfte mit Umgebungsvariablen

Eleventy erfreut sich wachsender Beliebtheit, da es uns ermöglicht, schöne, einfache Websites zu erstellen, aber auch – weil es so entwicklerfreundlich ist. Wir können damit auch umfangreiche, komplexe Projekte realisieren. In diesem Tutorial werden wir diese expansive Fähigkeit demonstrieren, indem wir eine leistungsstarke und menschenfreundliche Lösung für Umgebungsvariablen zusammenstellen.

Was sind Umgebungsvariablen?

Umgebungsvariablen sind nützliche Variablen/Konfigurationswerte, die in der Umgebung definiert sind, in der sich Ihr Code befindet.

Nehmen wir zum Beispiel an, Sie haben eine WordPress-Website: Wahrscheinlich möchten Sie sich mit einer Datenbank auf Ihrer Live-Site und mit einer anderen für Ihre Staging- und lokalen Sites verbinden. Wir können diese Werte in wp-config.php fest verdrahten, aber ein guter Weg, die Verbindungsinformationen geheim zu halten *und* es einfacher zu machen, Ihren Code in der Quellcodeverwaltung wie Git zu verwalten, ist, diese *außerhalb Ihres Codes* zu definieren.

Hier ist ein Standard-Snippet von wp-config.php für WordPress mit fest verdrahteten Werten

<?php 

define( 'DB_NAME', 'my_cool_db' );
define( 'DB_USER', 'root' );
define( 'DB_PASSWORD', 'root' );
define( 'DB_HOST', 'localhost' );

Unter Verwendung desselben Beispiels einer wp-config.php-Datei können wir ein Tool wie phpdotenv einführen und es stattdessen in etwas wie das hier ändern und die Werte *außerhalb* des Codes definieren.

<?php 

$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();

define( 'DB_NAME', $_ENV['DB_NAME'] );
define( 'DB_USER', $_ENV['DB_USER'] );
define( 'DB_PASSWORD', $_ENV['DB_PASSWORD'] );
define( 'DB_HOST', $_ENV['DB_HOST'] );

Eine Möglichkeit, diese Umgebungsvariablen zu definieren, ist die Verwendung einer .env-Datei, einer Textdatei, die üblicherweise **von der Quellcodeverwaltung ignoriert wird**.

Dann holen wir uns diese Werte – die Ihrem Code standardmäßig möglicherweise nicht zur Verfügung stehen – mithilfe eines Tools wie dotenv oder phpdotenv. Tools wie dotenv sind super nützlich, da Sie diese Variablen in einer .env-Datei, einem Docker-Skript oder einem Deploy-Skript definieren können und es dann einfach *funktioniert* – was meine bevorzugte Art von Tool ist!

Der Grund, warum wir diese in der Quellcodeverwaltung (über .gitignore) normalerweise ignorieren, ist, dass sie oft geheime Schlüssel oder Datenbankverbindungsinformationen enthalten. Idealerweise möchten Sie diese von jedem Remote-Repository wie GitHub fernhalten, um die Details so sicher wie möglich zu halten.

Erste Schritte

Für dieses Tutorial habe ich einige Startdateien erstellt, um uns allen etwas Zeit zu sparen. Es handelt sich um eine Basis-Eleventy-Website mit allen langweiligen Teilen, die für uns erledigt sind.

Schritt eins dieses Tutorials ist es, die Startdateien herunterzuladen und sie dort zu entpacken, wo Sie damit arbeiten möchten. Sobald die Dateien entpackt sind, öffnen Sie den Ordner in Ihrem Terminal und führen Sie npm install aus. Sobald Sie das getan haben, führen Sie npm start aus. Wenn Sie Ihren Browser unter https://:8080 öffnen, sollte er so aussehen

Erstellen wir während des Setups auch eine neue, leere Datei namens .env und legen Sie sie **im Stammverzeichnis Ihres Basisordners** ab.

Erstellung einer freundlichen Benutzeroberfläche

Umgebungsvariablen sind oft *wirklich schreiend*, da wir alles in Großbuchstaben verwenden, was ärgerlich werden kann. Was ich stattdessen gerne tue, ist, eine JavaScript-Schnittstelle zu erstellen, die diese Werte verbraucht und sie als etwas menschenfreundliches und namensraumbezogenes exportiert, so dass Sie allein durch den Blick auf den Code wissen, dass Sie Umgebungsvariablen verwenden.

Nehmen wir einen Wert wie HELLO=hi there, der in unserer .env-Datei definiert sein könnte. Um darauf zuzugreifen, verwenden wir process.env.HELLO, was nach ein paar Aufrufen etwas mühsam wird. Was ist, wenn dieser Wert nicht definiert ist? Es ist praktisch, für diese Szenarien einen Fallback bereitzustellen. Mit einem JavaScript-Setup können wir so etwas tun

require('dotenv').config();

module.exports = {
  hello: process.env.HELLO || 'Hello not set, but hi, anyway 👋'
};

Was wir hier tun, ist, nach dieser Umgebungsvariablen zu suchen und bei Bedarf einen Standardwert festzulegen, indem wir den OR-Operator (||) verwenden, um einen Wert zurückzugeben, wenn er nicht definiert ist. Dann können wir in unseren Vorlagen {{ env.hello }} verwenden.

Jetzt, wo wir wissen, wie diese Technik funktioniert, wollen wir sie umsetzen. In unserem Ordner mit den Startdateien befindet sich ein Verzeichnis namens src/_data mit einer leeren Datei env.js darin. Öffnen Sie sie und fügen Sie den folgenden Code hinzu

require('dotenv').config();

module.exports = {
  otherSiteUrl:
    process.env.OTHER_SITE_URL || 'https://eleventy-env-vars-private.netlify.app',
  hello: process.env.HELLO || 'Hello not set, but hi, anyway 👋'  
};

Da unsere Datendatei env.js heißt, können wir mit dem Präfix env darauf in unseren Vorlagen zugreifen. Wenn wir möchten, dass unsere Umgebungsvariablen mit environment präfixiert werden, würden wir den Namen unserer Datendatei in environment.js ändern. Sie können mehr in der Eleventy-Dokumentation lesen.

Wir haben hier unseren hello-Wert und auch einen otherSiteUrl-Wert, den wir verwenden, um Leuten zu zeigen, wie unterschiedlich unsere Website basierend auf ihren Umgebungsvariablen-Konfigurationen ist. Dieses Setup verwendet Eleventy JavaScript Data Files, die es uns ermöglichen, JavaScript auszuführen und die Ausgabe als statische Daten zurückzugeben. Sie unterstützen sogar asynchronen Code! Diese JavaScript-Datendateien sind wahrscheinlich mein Lieblingsteil von Eleventy.

Jetzt, da wir diese JavaScript-Schnittstelle eingerichtet haben, gehen wir zu unseren Inhalten und implementieren einige Variablen. Öffnen Sie src/index.md und fügen Sie am Ende der Datei Folgendes hinzu

Here’s an example: The environment variable, HELLO is currently: “{{ env.hello }}”. This is called with {% raw %}{{ env.hello }}{% endraw %}.

Ziemlich cool, oder? Wir können diese Variablen **direkt in unserem Inhalt** mit Eleventy verwenden! Wenn Sie nun den Wert von HELLO in Ihrer .env-Datei definieren oder ändern *und* den npm start-Task neu starten, sehen Sie, wie sich der Inhalt aktualisiert.

Ihre Website sollte jetzt so aussehen

Sie fragen sich vielleicht, was {% raw %} überhaupt ist. Es ist ein Nunjucks-Tag, der es Ihnen ermöglicht, Bereiche zu definieren, die es ignorieren soll. Ohne ihn würde Nunjucks versuchen, den Beispielteil {{ env.hello }} auszuwerten.

Anpassen von Bildbasis-Pfaden

Das erste Beispiel, das wir gemacht haben, war cool, aber fangen wir wirklich an zu erforschen, wie dieser Ansatz nützlich sein kann. Oft möchten Sie, dass Ihre Produktionsbilder von einer Art CDN bedient werden, aber Sie möchten wahrscheinlich auch, dass Ihre Bilder lokal laufen, wenn Sie Ihre Website entwickeln. Das bedeutet, dass wir zur Verbesserung der Leistung und der Unterstützung verschiedener Bildformate oft ein CDN verwenden, um unsere Bilder zu liefern, und diese CDNs greifen oft direkt auf Ihre Website zu, z. B. auf Ihren /images-Ordner. Genau das mache ich auf Piccalilli mit ImgIX, aber diese CDNs haben keinen Zugriff auf die lokale Version der Website. Die Möglichkeit, zwischen CDN- und lokalen Bildern zu wechseln, ist daher praktisch.

Die Lösung dieses Problems ist mit Umgebungsvariablen fast *trivial* – insbesondere mit Eleventy und dotenv, denn wenn die Umgebungsvariablen zum Zeitpunkt der Verwendung nicht definiert sind, werden keine Fehler ausgelöst.

Öffnen Sie src/_data/env.js und fügen Sie dem Objekt die folgenden Eigenschaften hinzu

imageBase: process.env.IMAGE_BASE || '/images/',
imageProps: process.env.IMAGE_PROPS,

Wir verwenden einen Standardwert für imageBase von /images/, sodass unsere lokalen Bilder gefunden werden können, wenn IMAGE_BASE nicht definiert ist. Dasselbe tun wir nicht für imageProps, da diese leer sein können, es sei denn, wir benötigen sie.

Öffnen Sie _includes/base.njk und fügen Sie nach dem Teil <h1>{{ title }}</h1> Folgendes hinzu

<img src="{{ env.imageBase }}mountains.jpg{{ env.imageProps }}" alt="Some lush mountains at sunset" />

Standardmäßig wird /images/mountains.jpg geladen. Cool! Öffnen Sie nun die .env-Datei und fügen Sie Folgendes hinzu

IMAGE_BASE=https://assets.codepen.io/174183/
IMAGE_PROPS=?width=1275&height=805&format=auto&quality=70

Wenn Sie Eleventy stoppen (Strg+C im Terminal) und dann npm start erneut ausführen, *dann* die Quellansicht in Ihrem Browser aufrufen, sollte das gerenderte Bild so aussehen

<img src="https://assets.codepen.io/174183/mountains.jpg?width=1275&height=805&format=auto&quality=70" alt="Some lush mountains at sunset" />

Das bedeutet, wir können die CodePen-Asset-Optimierungen nur dann nutzen, wenn wir sie benötigen.

Anzeigen von privaten und Premium-Inhalten mit Eleventy

Wir können Umgebungsvariablen auch verwenden, um Inhalte bedingt zu rendern, basierend auf einem Modus wie dem privaten Modus. Dies ist für mich persönlich eine wichtige Fähigkeit, da ich einen Eleventy-Kurs und ein CSS-Buch habe, **beide von Eleventy angetrieben**, die Premium-Inhalte nur denen anzeigen, die dafür bezahlt haben. Hinter den Kulissen gibt es allerlei technische Magie mit Service Workers und APIs, aber im Kern ist es, dass Inhalte bedingt gerendert werden können, basierend auf env.mode in unserer JavaScript-Schnittstelle.

Fügen wir das nun unserem Beispiel hinzu. Öffnen Sie src/_data/env.js und fügen Sie der Objektdefinition Folgendes hinzu

mode: process.env.MODE || 'public'

Dieses Setup bedeutet, dass der mode standardmäßig **public** ist. Öffnen Sie nun src/index.md und fügen Sie am Ende der Datei Folgendes hinzu

{% if env.mode === 'private' %}

## This is secret content that only shows if we’re in private mode.

This is called with {% raw %}`{{ env.mode }}`{% endraw %}. This is great for doing special private builds of the site for people that pay for content, for example.

{% endif %}

Wenn Sie Ihre lokale Version aktualisieren, können Sie den gerade hinzugefügten Inhalt nicht sehen. Das funktioniert *perfekt* für uns – besonders, da wir ihn schützen wollen. Zeigen wir ihn also nun an, indem wir Umgebungsvariablen verwenden. Öffnen Sie .env und fügen Sie Folgendes hinzu

MODE=private

Starten Sie nun Eleventy neu und laden Sie die Website neu. Sie sollten nun etwas wie das hier sehen

Sie können dieses bedingte Rendering auch direkt in der Vorlage durchführen. Zum Beispiel könnten Sie den gesamten Seiteninhalt privat machen und stattdessen eine Paywall rendern. Ein Beispiel dafür ist, wenn Sie zu meinem Kurs ohne Lizenz gehen, wird Ihnen eine Handlungsaufforderung zum Kauf angezeigt.

Spaß-Modus

Dies waren hoffentlich bisher wirklich nützliche Inhalte für Sie, also erweitern wir das Gelernte und haben etwas Spaß damit!

Ich möchte abschließend einen „Spaß-Modus“ erstellen, der das Design komplett verändert, um es etwas… *spaßiger* zu machen. Öffnen Sie src/_includes/base.njk und fügen Sie kurz vor dem schließenden </head>-Tag Folgendes hinzu

{% if env.funMode %}
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lobster&display=swap" />
  <style>
    body {
      font-family: 'Comic Sans MS', cursive;
      background: #fc427b;
      color: #391129;
    }
    h1,
    .fun {
      font-family: 'Lobster';
    }
    .fun {
      font-size: 2rem;
      max-width: 40rem;
      margin: 0 auto 3rem auto;
      background: #feb7cd;
      border: 2px dotted #fea47f;
      padding: 2rem;
      text-align: center;
    }
  </style>
{% endif %}

Dieser Ausschnitt prüft, ob unsere Umgebungsvariable funMode true ist und wenn ja, fügt er etwas „spaßiges“ CSS hinzu.

Immer noch in base.njk, kurz vor dem öffnenden <article>-Tag, fügen Sie den folgenden Code hinzu

{% if env.funMode %}
  <div class="fun">
    <p>🎉 <strong>Fun mode enabled!</strong> 🎉</p>
  </div>
{% endif %}

Dieser Code verwendet die gleiche Logik und rendert ein Spaß-Banner, wenn funMode true ist. Lassen Sie uns nun unsere Umgebungsvariablen-Schnittstelle dafür erstellen. Öffnen Sie src/_data/env.js und fügen Sie der exportierten Objektdefinition Folgendes hinzu

funMode: process.env.FUN_MODE

Wenn funMode nicht definiert ist, verhält es sich wie false, da undefined ein falsy value ist.

Öffnen Sie als Nächstes Ihre .env-Datei und fügen Sie Folgendes hinzu

FUN_MODE=true

Starten Sie nun die Eleventy-Aufgabe neu und laden Sie Ihren Browser neu. Er sollte nun so aussehen

Ziemlich laut, oder?! Auch wenn dieses Design ziemlich *schrecklich* aussieht (lesen Sie: radikal), hoffe ich, dass es zeigt, wie viel Sie mit diesem Umgebungssetup ändern können.

Zusammenfassung

Wir haben drei Versionen derselben Website erstellt, die den gleichen Code ausführen, um all die Unterschiede zu sehen

1. Standard-Website
2. Private Inhalte sichtbar
3. Spaß-Modus

All diese Websites werden mit identischem Code betrieben, wobei der einzige Unterschied zwischen jeder Website einige Umgebungsvariablen sind, die ich in diesem Beispiel in meinem Netlify-Dashboard definiert habe.

Ich hoffe, dass diese Technik Ihnen alle möglichen Möglichkeiten eröffnet, mit dem besten Static Site Generator, Eleventy!