Zmienne Środowiskowe
Create T3 App korzysta z paczki Zod↗ w celu walidacji twoich zmiennych środowiskowych podczas runtime’u oraz budowania aplikacji. Dołączane są z tego powodu dodatkowe pliki w folderze env
:
📁 src/env
┣ 📄 client.mjs
┣ 📄 schema.mjs
┣ 📄 server.mjs
Ich zawartość może na początku wyglądać strasznie, ale nie martw się. Nie jest to tak skomplikowane, jak może Ci się wydawać. Przyjrzyjmy się każdemu z nich po kolei i przejdźmy przez proces dodawania nowej zmiennej środowiskowej.
TLDR; Jeżeli chcesz dodać nową zmienną środowiskową, musisz dodać ją zarówno do pliku .env
jak i zdefiniować walidator w pliku env/schema.mjs
.
schema.mjs
Jest to plik, który faktycznie będziesz edytować. Zawiera dwa schematy, jeden dla zmiennych środ. po stronie serwera, a drugi dla tych po stronie klienta (obiekt clientEnv
).
export const serverSchema = z.object({
// DATABASE_URL: z.string().url(),
});
export const clientSchema = z.object({
// NEXT_PUBLIC_WS_KEY: z.string(),
});
Schemat Dla Serwera
Zdefiniuj tutaj zmienne środowiskowe dla serwera.
Koniecznie nie prefixuj tutejszych kluczy NEXT_PUBLIC_
. Jeżeli to zrobisz, walidacja nie zadziała, pomagając ci w wykryciu niewłaściwej konfiguracji.
Schemat Dla Klienta
Zdefiniuj tutaj zmienne środowiskowe dla klienta.
Aby ujawnić zmienne dla klienta dodaj prefix NEXT_PUBLIC
. Jeżeli tego nie zrobisz, walidacja nie zadziała, pomagając ci w wykryciu niewłaściwej konfiguracji.
// ❌ To nie zadziała, musimy ręcznie "rozbić" `process.env`
const schema = z.object({
NEXT_PUBLIC_WS_KEY: z.string(),
});
const validated = schema.parse(process.env);
server.mjs & client.mjs
To tutaj zachodzi walidacja i eksport poprawnych obiektów. Nie powinna zajść potrzeba ich edycji.
Korzystanie Ze Zmiennych Środowiskowych
Jeżeli chcesz skorzystać ze swoich zmiennych środowiskowych, możesz zaimportować je z pliku env/client.mjs
lub env/server.mjs
, w zależności od tego, gdzie chcesz używać tych zmiennych:
import { env } from "../../env/server.mjs";
// `env` jest w pełni typesafe i pozwala na autouzupełnianie
const dbUrl = env.DATABASE_URL;
.env.example
Ponieważ plik .env
nie jest wrzucany na system kontroli wersji, dołączamy także plik .env.example
, w którym - jesli chcesz - możesz zawrzeć kopię pliku .env
z usuniętymi secretami. Nie jest to wymagane, jednak polecamy trzymać aktualną kopię przykładowego pliku, aby ułatwić potencjalnym kontrybutorom rozpoczęcie pracy w ich środowisku.
Niektóre frameworki i narzędzia do budowania, takie jak Next.js, zalecają przechowywanie sekretnych wartości w pliku .env.local
i commitowanie plików .env
do projektu. Nie jest to przez nas jednak rekomendowane, ponieważ może to łatwo prowadzić do przypadkowego ujawnienia tych wartości. Polecamy natomiast przechowywanie sekretnych wartości w pliku .env
, trzymanie pliku tego w .gitignore
i commitowanie jedynie plików .env.example
.
Dodawanie Zmiennych Środowiskowych
Aby upewnić się, że twój projekt nie zbuduje się bez wymaganych zmiennych środ., będziesz musiał dodać nową zmienną w dwóch miejscach:
📄 .env
: Wprowadź swoją zmienną środ. tak, jak to zwykle robisz (np. KLUCZ=WARTOŚĆ
)
📄 schema.mjs
: Dodaj odpowiadającą jej logikę walidacji definiując schemat Zod, np. KLUCZ: z.string()
Opcjonalnie możesz zaktualizować plik .env.example
:
📄 .env.example
: Wprowadź swoją zmienną środ., upewnij się jednak że nie nie posiada ona wartości, która jest sekretna, np. KLUCZ=WARTOŚĆ
lub KLUCZ=
Przykład
Chcę dodać mój token do API Twittera jako zmienną środowiskową po stronie serwera
- Dodaj zmienną środ. do pliku
.env
:
TWITTER_API_TOKEN=1234567890
- Dodaj zmienną środowiskową do pliku
schema.mjs
:
export const serverSchema = z.object({
// ...
TWITTER_API_TOKEN: z.string(),
});
UWAGA: Pusty string to dalej string, więc z.string()
zaakceptuje każdy pusty tekst jako poprawną wartość. Jeżeli chcesz, by wartość była wymagana (i nie pusta!), możesz użyć z.string().min(1)
.
- opcjonalnie: Dodaj zmienną środowiskową do
.env.example
. Usuń jednak token.
TWITTER_API_TOKEN=