Variables de Entorno
Las variables de entorno te permiten configurar tu frontend sin hardcodear valores en el código. Úsalas para URLs de API, claves públicas (Stripe publishable, Google Maps, etc.), feature flags y cualquier cosa que cambie entre proyectos o entornos.
La página Variables (Ship → Frontend → Variables, ruta /variables) tiene dos pestañas:
- Backend Secrets (pestaña por defecto) — secretos de runtime cifrados que referencias por nombre en tus endpoints y workflows. Nunca se envían al navegador. Mira Backend Secrets.
- Frontend (Build) — las variables públicas de build de esta página, integradas en tu bundle de cliente.
Las variables Frontend (Build) son públicas
Las env vars Frontend (Build) se incluyen en tu build y se envían al navegador. Nunca pongas secretos aquí — ni claves privadas de API, ni credenciales de base de datos, ni secretos JWT. Para secretos de runtime usa Backend Secrets; para claves tipadas de terceros usa Credenciales.
Añadir variables
Abre la pestaña Variables
En el dashboard de tu proyecto ve a Frontend → Variables y cambia a la pestaña Frontend (Build).
Añade pares clave-valor
Haz clic en Añadir variable. Introduce la clave (por ejemplo VITE_STRIPE_KEY) y el valor. La mayoría de frameworks requieren un prefijo específico — consulta la tabla de abajo.
Redespliega
Las env vars se integran en tiempo de build. Haz clic en Redeploy (o lanza un nuevo deploy desde tu IDE) para aplicar los cambios.
Prefijo requerido por framework
Tu framework solo expone al navegador las env vars con un prefijo concreto. Esto evita filtrar accidentalmente variables del backend.
| Parameter | Type | Description |
|---|---|---|
Vite / Vue / SvelteKit | VITE_* | Se acceden como import.meta.env.VITE_MI_CLAVE en tu código |
Create React App | REACT_APP_* | Se acceden como process.env.REACT_APP_MI_CLAVE |
Next.js (cliente) | NEXT_PUBLIC_* | Se acceden como process.env.NEXT_PUBLIC_MI_CLAVE |
Astro | PUBLIC_* | Se acceden como import.meta.env.PUBLIC_MI_CLAVE |
Las variables sin el prefijo correcto no se incluyen en el build — serán undefined en el navegador.
Variables automáticas
HeroMate configura algunas variables por ti automáticamente. No hace falta añadirlas manualmente:
| Variable | Valor |
|---|---|
VITE_DYPAI_URL | La URL base de la API de tu proyecto |
VITE_DYPAI_PROJECT_ID | El UUID de tu proyecto |
El @dypai-ai/client-sdk las lee automáticamente cuando llamas a createClient().
Configuración típica
# Endpoints de API y claves públicas
VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
VITE_GOOGLE_MAPS_KEY=AIza...
VITE_POSTHOG_KEY=phc_...
# Feature flags
VITE_ENABLE_BETA_DASHBOARD=true
# URLs de terceros
VITE_SUPPORT_URL=https://help.tuapp.com
Luego en tu código:
const stripeKey = import.meta.env.VITE_STRIPE_PUBLISHABLE_KEY
const mapsKey = import.meta.env.VITE_GOOGLE_MAPS_KEY
Editar o eliminar variables
- Editar: Haz clic en el icono de lápiz junto a la variable, cambia el valor, guarda. Redespliega para aplicar.
- Eliminar: Haz clic en el icono de papelera. La variable se elimina en el siguiente deploy.
Tres sitios para configurar
HeroMate tiene tres almacenes distintos. Elige el correcto para cada valor:
| Almacén | Dónde | Visibilidad | Úsalo para |
|---|---|---|---|
| Variables Frontend (Build) | Frontend → Variables → Frontend (Build) | Público — integrado en el bundle del navegador | URL base de API, claves públicas (pk_), feature flags |
| Backend Secrets | Frontend → Variables → Backend Secrets | Privado — cifrado, nunca llega al navegador | Secretos de runtime por nombre, leídos en endpoints como ctx.secrets.X / ${ secrets.X } |
| Credenciales | Build → Credentials | Privado — cifrado, tipado | Claves de proveedores de terceros (Stripe sk_, OpenAI, Slack…) usadas por los nodos de integración |
El nodo de código usa env_vars, no Credenciales
El nodo de workflow javascript_code lee sus propias env_vars en texto plano vía ctx.env — no puede seleccionar Credenciales tipadas. Para valores sensibles de runtime, usa mejor Backend Secrets.
Límites
- Las claves deben ser
UPPER_SNAKE_CASE - Los valores Frontend (Build) se exponen en el bundle del cliente en tiempo de build — nunca pongas secretos ahí
- Los Backend Secrets se cifran con Fernet, son de solo escritura y nunca se envían al navegador — úsalos para todo lo sensible
Dónde NO usar env vars
| Tipo de valor | Guárdalo en… |
|---|---|
| Clave pública de API (Stripe pk_, Google Maps, PostHog) | ✅ Variable Frontend (Build) |
| URL base de API | ✅ Variable Frontend (Build) |
| Feature flag | ✅ Variable Frontend (Build) |
| Clave secreta de Stripe (sk_) | ❌ Credenciales |
| Secreto genérico de runtime (clave de firma de webhook, token interno) | ❌ Backend Secrets |
| Contraseña de base de datos | ❌ Nunca la necesitas — HeroMate se encarga |
| Clave de API de OpenAI | ❌ Credenciales (usadas por el nodo Agent) |
| Secreto de firma JWT | ❌ Nunca lo necesitas — HeroMate se encarga |