Environment Variables

This page documents every environment variable used by each package in the monorepo, explains how Next.js loads .env files, and lists which variables are security-sensitive.

How Next.js loads environment variables

Next.js loads .env files in the following order (later files override earlier ones):

1. .env — base defaults, can be committed
2. .env.local — local overrides, never committed (gitignored)
3. .env.development / .env.production — per-environment defaults
4. .env.development.local / .env.production.local — per-environment local overrides

[!NOTE] Variables are resolved at server startup (development) or build time (production). Changing a .env file requires restarting the dev server or rebuilding.

NEXT_PUBLIC_ prefix

Any variable prefixed with NEXT_PUBLIC_ is inlined into the JavaScript bundle at build time and exposed to the browser. Never put secrets in NEXT_PUBLIC_ variables.

NODE_ENV behavior

The frontend envConfig.ts conditionally sets the production API URL based on NODE_ENV:

// Pseudocode — actual implementation in frontend-app/app/config/envConfig.ts
const apiBase =
  process.env.NODE_ENV === "production"
    ? "https://api.tolosaerronka.es/api"
    : process.env.NEXT_PUBLIC_API_BASE_URL;

This means you do not need NEXT_PUBLIC_API_BASE_URL in a production build unless you want to override the default domain.

backend-js variables

Source of truth: backend-js/.env.example
Config loader: src/app/config/envConfig.ts

Place your values in backend-js/.env.local for local development.

Database

[!WARNING] The four MySQL variables can be undefined at runtime if .env.local is missing or misspelled. The MySQL pool will accept undefined values without throwing at startup, but every query will fail. Always verify the pool connects on first request.

JWT

[!WARNING] JWT_SECRET ships with a hardcoded fallback value in src/app/config/envConfig.ts. This fallback is visible in the public repository. Any attacker can use it to forge valid JWT tokens. Always override this variable in production.

Email

Google Maps

[!NOTE] GOOGLE_DIRECTIONS_API_KEY uses a TypeScript non-null assertion (!) in envConfig.ts, which suppresses compile-time errors but allows undefined to slip through at runtime. The key must be present or route creation and geocoding will throw uncaught errors.

Application URLs

Tokens and users

[!WARNING] DEFAULT_USER_PASSWORD also has a hardcoded fallback. Every user created while this fallback is active can be accessed with the known default password until they change it.

frontend-app variables

Config loader: frontend-app/app/config/envConfig.ts
Committed defaults: frontend-app/.env

[!NOTE] All three frontend variables are prefixed with NEXT_PUBLIC_ and therefore embedded in the client bundle. They are visible to anyone who inspects the page source. This is expected for URL configuration; it is only a concern if you accidentally add a secret key here.

docs variables

The docs package (@repo/docs) does not define its own .env variables. It runs a standard Next.js + Nextra build with no runtime secrets. The predev and prebuild scripts regenerate the search index (scripts/generate-search-index.mjs) automatically — no extra configuration is needed.

Security rules

What MUST NOT go in .env or version control

• MYSQL_PASSWORD
• JWT_SECRET
• DEFAULT_USER_PASSWORD
• RESEND_API_KEY
• GOOGLE_DIRECTIONS_API_KEY
• Any SSL certificates or private keys

What .env.local is for

.env.local is gitignored and is the right place for:

• Local database credentials
• Local copies of secret API keys for development

What .env (committed) is for

Only non-secret defaults that are safe to share publicly:

• MYSQL_HOST=localhost (acceptable — obvious for local dev)
• NEXT_PUBLIC_* variables (by design, these are public)
• JWT_ACCESS_EXPIRES_IN=15m (safe configuration)

Never put secrets in NEXT_PUBLIC_*

Variables starting with NEXT_PUBLIC_ are inlined into the JavaScript bundle and sent to every browser. Even if the variable is not rendered visibly, it can be extracted by anyone with DevTools.

Quick reference — all variables

* HERE Maps keys are client-side by design and can be domain-restricted in the HERE developer console. They are not secret in the traditional sense, but should be restricted to your domain.