Cómo Desplegar una Aplicación Astro en Netlify Gratis (2026) How to Deploy an Astro App on Netlify for Free (2026)

1. Instalar el adaptador oficial de Netlify1. Install the Official Netlify Adapter

Astro utiliza adaptadores para generar la salida correcta según la plataforma de deployment. Para Netlify, usa el paquete oficial. Importante: la versión del adaptador debe ser compatible con tu versión de Astro: Astro uses adapters to generate the correct output for each deployment platform. For Netlify, use the official package. Important: the adapter version must be compatible with your Astro version:

• Astro 4 → @astrojs/netlify@5Astro 4 → @astrojs/netlify@5
• Astro 5 / 6 → @astrojs/netlify@7+Astro 5 / 6 → @astrojs/netlify@7+

# Para Astro 4:
npm install @astrojs/netlify@5

# Para Astro 5+:
npm install @astrojs/netlify

2. Configurar astro.config.mjs2. Configure astro.config.mjs

Actualiza tu archivo de configuración para usar el output SSR y el adaptador de Netlify: Update your configuration file to use SSR output and the Netlify adapter:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import netlify from '@astrojs/netlify';

export default defineConfig({
  output: 'server',   // SSR completo
  adapter: netlify(),
});

Si tu sitio no necesita SSR (sin APIs, sin renderizado dinámico), puedes usar output: 'static' y el adaptador no es necesario — Netlify sirve el output directamente desde dist/. If your site doesn't need SSR (no APIs, no dynamic rendering), you can use output: 'static' and no adapter is needed — Netlify serves the output directly from dist/.

3. Crear netlify.toml3. Create netlify.toml

El archivo netlify.toml en la raíz del proyecto le dice a Netlify cómo construir tu app. Para Astro 4 con SSR, la carpeta de publicación es dist/client: The netlify.toml file at the project root tells Netlify how to build your app. For Astro 4 with SSR, the publish folder is dist/client:

[build]
  command   = "npx astro build"
  publish   = "dist/client"

[build.environment]
  NODE_VERSION = "20"

Para Astro 5+ con el nuevo adaptador, la estructura de salida cambia y publish puede ser simplemente dist/. Revisa la documentación del adaptador para la versión específica. For Astro 5+ with the new adapter, the output structure changes and publish can simply be dist/. Check the adapter docs for your specific version.

4. Variables de entorno en Netlify4. Environment Variables in Netlify

Nunca subas el archivo .env al repositorio. En su lugar, configura las variables en el panel de Netlify: Never commit the .env file to your repository. Instead, configure variables in the Netlify dashboard:

1. Ve a Site configuration → Environment variables
2. Haz clic en Add a variable → Add a single variable
3. Para claves secretas (API keys): marca Secret values ✅
4. Selecciona todos los scopes (Functions, Edge, Runtime, Builds)
5. Selecciona todos los contextos de deploy (Production, Deploy previews, Branch deploys)

En Astro, las variables solo son accesibles en el servidor si NO tienen el prefijo PUBLIC_. Las variables con prefijo PUBLIC_ se exponen al cliente (browser), lo que puede ser un riesgo de seguridad si contienen claves privadas. In Astro, variables are only accessible on the server if they do NOT have the PUBLIC_ prefix. Variables prefixed with PUBLIC_ are exposed to the client (browser), which is a security risk if they contain private keys.

5. CSS no carga en producción — solución5. CSS Not Loading in Production — Fix

Este es el error más común al migrar de desarrollo a producción con Astro. Si en tu layout tienes: This is the most common error when moving from development to production with Astro. If your layout has:

<!-- ❌ Esto NO funciona en producción -->
<link rel="stylesheet" href="/src/styles/global.css" />

El path /src/styles/ solo existe en el servidor de desarrollo (Vite lo sirve). En producción, Astro compila el CSS con hashes. La solución correcta:The /src/styles/ path only exists on the dev server (Vite serves it). In production, Astro compiles CSS with hashes. The correct solution:

---
// ✅ Importar en el frontmatter — Astro lo procesa y genera el hash correcto
import '../styles/global.css';
---

6. Conectar el repositorio de GitHub6. Connect Your GitHub Repository

La forma más sencilla de hacer Continuous Deployment es conectar Netlify con tu repo de GitHub: The easiest way to enable Continuous Deployment is to connect Netlify to your GitHub repository:

1. En Netlify: Add new site → Import an existing project
2. Autoriza GitHub y selecciona el repositorio
3. Branch a deployar: main
4. Si tienes netlify.toml, los campos de build se rellenan automáticamente
5. Haz clic en Deploy site

Cada push a main disparará un nuevo deploy automáticamente. Los pull requests generan Deploy Previews con URL únicos para revisión antes de mergear. Every push to main will trigger a new deploy automatically. Pull requests generate Deploy Previews with unique URLs for review before merging.

7. Dominio personalizado gratis7. Free Custom Domain

Netlify asigna un dominio como tu-sitio.netlify.app. Puedes personalizarlo en Domain management → Custom domains. Si tienes tu propio dominio (en GoDaddy, Namecheap, etc.), apunta los nameservers a Netlify y el certificado SSL se configura automáticamente con Let's Encrypt. Netlify assigns a domain like your-site.netlify.app. You can customize it under Domain management → Custom domains. If you own a domain (from GoDaddy, Namecheap, etc.), point the nameservers to Netlify and the SSL certificate is configured automatically with Let's Encrypt.

ConclusiónConclusion

Astro + Netlify es la combinación perfecta para portfolios y proyectos con SSR: deployment gratuito, CD automático, SSL, CDN global y funciones serverless sin configuración adicional. Los únicos puntos críticos son: versión correcta del adaptador, CSS importado en el frontmatter y variables de entorno configuradas en el panel (nunca en el repo). Astro + Netlify is the perfect combination for portfolios and SSR projects: free deployment, automatic CD, SSL, global CDN and serverless functions with no extra configuration. The only critical points are: the correct adapter version, CSS imported in the frontmatter, and environment variables configured in the dashboard (never in the repo).

Si necesitas que construya y despliegue tu aplicación web en Netlify, Vercel o cualquier proveedor cloud, escríbeme aquí. Trabajo con empresas y freelancers en todo Colombia y Latinoamérica. If you need me to build and deploy your web application on Netlify, Vercel or any cloud provider, write to me here. I work with companies and freelancers across Colombia and Latin America.