Deployment Guide - Proyecto Renacer

Overview

Proyecto Renacer is built with Astro, which generates a static site that can be deployed to any static hosting service. This guide covers the build process, deployment options, and production optimizations.

Build Process

Development Commands

The project uses npm scripts for development and building:

npm run dev

Available Scripts

package.json

{
  "scripts": {
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview",
    "astro": "astro"
  }
}

npm run dev

Starts the development server at localhost:4321 with hot module reloading

npm run build

Builds the production site to ./dist/ directory

npm run preview

Previews the production build locally before deploying

npm run astro

Access Astro CLI commands for advanced operations

Building for Production

Step 1: Install Dependencies

Ensure all dependencies are installed:

npm install

The project has minimal dependencies:

package.json

{
  "dependencies": {
    "@tailwindcss/vite": "^4.2.1",
    "astro": "^5.17.1",
    "tailwindcss": "^4.2.1"
  }
}

Step 2: Run the Build

Generate the static site:

npm run build

The build process will:

Compile all .astro files to static HTML
Process and optimize CSS with Tailwind
Bundle JavaScript and assets
Generate a static site in the ./dist/ directory

Step 3: Test the Build Locally

Preview the production build before deploying:

npm run preview

This starts a local server serving the dist/ directory, allowing you to test the production build.

Static Site Output

Output Structure

After running npm run build, the dist/ directory will contain:

dist/
├── index.html
├── proyecto/
│   └── index.html
├── requisitos/
│   └── index.html
├── como-ser-socio/
│   └── index.html
├── noticias/
│   └── index.html
├── contacto/
│   └── index.html
├── _astro/
│   ├── *.css
│   └── *.js
└── assets/
    └── [images, fonts, etc.]

Astro generates clean URLs by creating a directory for each page with an index.html file inside. This allows URLs like /proyecto instead of /proyecto.html.

Build Output

The build command will show output similar to:

17:42:50 [build] output: "static"
17:42:50 [build] directory: /home/user/renacer/dist/
17:42:50 [build] Collecting build info...
17:42:50 [build] ✓ Completed in 125ms.
17:42:50 [build] Building static entrypoints...
17:42:51 [build] ✓ Completed in 1.2s.

 @astrojs/check ✓ Getting diagnostics for Astro files in /home/user/renacer...
 Result (5 files): 
 - 0 errors
 - 0 warnings
 - 0 hints

Deployment Options

Option 1: Netlify (Current Setup)

The project is currently deployed on Netlify at:

https://proyectoviviendarenacer.netlify.app

Netlify Configuration

Create a netlify.toml in the root directory:

netlify.toml

[build]
  command = "npm run build"
  publish = "dist"

[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200

Deploy Steps

Connect Repository

Connect your GitHub/GitLab repository to Netlify

Configure Build Settings

Build command: npm run build
Publish directory: dist
Node version: 18 or higher

Deploy

Netlify will automatically build and deploy on every push to the main branch

Automatic Deployments: Netlify can automatically deploy when you push to your Git repository. Enable this in your Netlify site settings.

Option 2: Vercel

Vercel offers excellent Astro support with zero configuration:

Install Vercel CLI (Optional)

npm install -g vercel

Deploy

vercel

Or connect your repository through the Vercel dashboard. Vercel will auto-detect:

Framework: Astro
Build command: npm run build
Output directory: dist

Option 3: GitHub Pages

Deploy to GitHub Pages using GitHub Actions:

.github/workflows/deploy.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Build
        run: npm run build
      
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Update astro.config.mjs for GitHub Pages:

astro.config.mjs

import { defineConfig } from 'astro/config';
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  site: 'https://yourusername.github.io',
  base: '/repository-name',
  vite: {
    plugins: [tailwindcss()],
  },
});

Option 4: Cloudflare Pages

Deploy to Cloudflare Pages:

Connect Repository

Go to Cloudflare Pages dashboard and connect your repository

Configure Build

Framework preset: Astro
Build command: npm run build
Build output directory: dist

Deploy

Click “Save and Deploy”

Option 5: Traditional Web Hosting

For traditional hosting (cPanel, FTP):

Build Locally

npm run build

Upload Files

Upload the entire dist/ directory to your web server’s public HTML folder

Configure Server

Ensure your server is configured to serve index.html for directory requests

Environment Configuration

Environment Variables

Astro supports environment variables through .env files:

.env

PUBLIC_SITE_URL=https://proyectoviviendarenacer.netlify.app
PUBLIC_ANALYTICS_KEY=your-analytics-key
PUBLIC_WHATSAPP_NUMBER=593999730617

Important: Variables prefixed with PUBLIC_ are exposed to the client. Never put sensitive secrets in PUBLIC_ variables.

Using Environment Variables

Example Usage

---
const siteUrl = import.meta.env.PUBLIC_SITE_URL;
const whatsapp = import.meta.env.PUBLIC_WHATSAPP_NUMBER;
---

<a href={`https://wa.me/${whatsapp}`}>Contactar</a>

Platform-Specific Variables

For production deployments, set environment variables in your hosting platform:

Netlify
Vercel
Cloudflare

Site Configuration → Environment Variables

PUBLIC_SITE_URL = https://proyectoviviendarenacer.netlify.app

Project Settings → Environment Variables

PUBLIC_SITE_URL = https://proyecto-renacer.vercel.app

Pages → Settings → Environment Variables

PUBLIC_SITE_URL = https://proyecto-renacer.pages.dev

Production Optimizations

Astro Built-in Optimizations

Astro automatically provides:

Static HTML

Pages are pre-rendered to static HTML for fast load times

CSS Optimization

Tailwind CSS is purged and minified automatically

Asset Optimization

Images and assets are optimized during build

Zero JS by Default

Only ships JavaScript when needed

Custom Optimizations

1. Image Optimization

Use Astro’s built-in Image component for optimized images:

---
import { Image } from 'astro:assets';
import heroImage from '../assets/hero.jpg';
---

<Image 
  src={heroImage} 
  alt="Proyecto Renacer" 
  width={1200} 
  height={600}
  format="webp"
/>

2. Font Loading Strategy

The project already uses optimized font loading:

src/layouts/Layout.astro

<link
  href="https://fonts.googleapis.com/css2?family=Public+Sans:wght@300;400;500;600;700;800;900&display=swap"
  rel="stylesheet"
/>

The display=swap ensures text remains visible during font load.

3. Analytics

The project includes Ahrefs analytics:

src/layouts/Layout.astro

<script
  src="https://analytics.ahrefs.com/analytics.js"
  data-key="sASfd12IOBxOqgA/S0QsDQ"
  async
></script>

The async attribute ensures analytics don’t block page rendering.

Performance Checklist

Minimize External Resources

Use system fonts when possible
Self-host critical fonts
Lazy load non-critical scripts

Optimize Images

Use WebP format
Provide appropriate sizes for different viewports
Use lazy loading for below-fold images

CSS Optimization

Tailwind automatically purges unused CSS
Avoid large custom CSS files
Use CSS variables for theme values

Reduce HTTP Requests

Combine similar resources
Use CSS instead of images when possible
Leverage browser caching

Continuous Deployment

Git-Based Workflow

For automated deployments:

Make Changes

Edit content, components, or styles locally

Test Locally

npm run dev

Build and Preview

npm run build
npm run preview

Commit and Push

git add .
git commit -m "Update content"
git push origin main

Automatic Deployment

Your hosting platform automatically builds and deploys

Branch Previews

Most platforms support preview deployments for pull requests:

Netlify: Automatic deploy previews for PRs
Vercel: Preview deployments for every push
Cloudflare Pages: Branch previews available

Troubleshooting

Common Build Issues

Build Fails - Module Not Found

Solution: Clear node_modules and reinstall

rm -rf node_modules package-lock.json
npm install
npm run build

Styles Not Applied in Production

Solution: Ensure Tailwind is properly configured and imported

src/styles/global.css

@import "tailwindcss";

404 on Page Refresh

Solution: Configure your hosting to redirect all routes to index.html (SPA mode) or ensure proper static file generation

Assets Not Loading

Solution: Use relative paths or configure base URL in astro.config.mjs

Monitoring and Analytics

Current Analytics Setup

The site uses Ahrefs analytics for tracking:

<script
  src="https://analytics.ahrefs.com/analytics.js"
  data-key="sASfd12IOBxOqgA/S0QsDQ"
  async
></script>

Adding Google Analytics

To add Google Analytics:

src/layouts/Layout.astro

<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Domain Configuration

Current Domain

The site is deployed at:

https://proyectoviviendarenacer.netlify.app

Setting Up a Custom Domain

Purchase Domain

Add to Hosting Platform

Add the custom domain in your hosting platform’s dashboard

Configure DNS

Point your domain to the hosting platform’s nameservers or IP

Enable HTTPS

Most platforms automatically provision SSL certificates

Update Site Configuration

Update canonical URLs and Open Graph tags to use the new domain

Next Steps

Content Management

Learn how to update content

Styling Guide

Customize the design

Astro Deployment

Official Astro deployment guide

Performance Tips

Optimize your site further

Get Started

Project Structure

Guides

Documentation Index

​Overview

​Build Process

​Development Commands

​Available Scripts

npm run dev

npm run build

npm run preview

npm run astro

​Building for Production

​Step 1: Install Dependencies

​Step 2: Run the Build

​Step 3: Test the Build Locally

​Static Site Output

​Output Structure

​Build Output

​Deployment Options

​Option 1: Netlify (Current Setup)

​Netlify Configuration

​Deploy Steps

​Option 2: Vercel

​Option 3: GitHub Pages

​Option 4: Cloudflare Pages

​Option 5: Traditional Web Hosting

​Environment Configuration

​Environment Variables

​Using Environment Variables

​Platform-Specific Variables

​Production Optimizations

​Astro Built-in Optimizations

Static HTML

CSS Optimization

Asset Optimization

Zero JS by Default

​Custom Optimizations

​1. Image Optimization

​2. Font Loading Strategy

​3. Analytics

​Performance Checklist

​Continuous Deployment

​Git-Based Workflow

​Branch Previews

​Troubleshooting

​Common Build Issues

​Monitoring and Analytics

​Current Analytics Setup

​Adding Google Analytics

​Domain Configuration

​Current Domain

​Setting Up a Custom Domain

​Next Steps

Content Management

Styling Guide

Astro Deployment

Performance Tips

Build docs developers (and LLMs) love

Overview

Build Process

Development Commands

Available Scripts

Building for Production

Step 1: Install Dependencies

Step 2: Run the Build

Step 3: Test the Build Locally

Static Site Output

Output Structure

Build Output

Deployment Options

Option 1: Netlify (Current Setup)

Netlify Configuration

Deploy Steps

Option 2: Vercel

Option 3: GitHub Pages

Option 4: Cloudflare Pages

Option 5: Traditional Web Hosting

Environment Configuration

Environment Variables

Using Environment Variables

Platform-Specific Variables

Production Optimizations

Astro Built-in Optimizations

Custom Optimizations

1. Image Optimization

2. Font Loading Strategy

3. Analytics

Performance Checklist

Continuous Deployment

Git-Based Workflow

Branch Previews

Troubleshooting

Common Build Issues

Monitoring and Analytics

Current Analytics Setup

Adding Google Analytics

Domain Configuration

Current Domain

Setting Up a Custom Domain

Next Steps