Deployment Guide

This guide covers building, deploying, and hosting Version Counter on various platforms. The application is built with Astro and optimized for static hosting.

Build Configuration

Version Counter uses Astro’s static site generation. The build configuration is defined in astro.config.mjs:

astro.config.mjs

import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";
import tailwindcss from "@tailwindcss/vite";
import react from "@astrojs/react";

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
  site: "https://version-counter.netlify.app",
  integrations: [react(), sitemap()],
});

Key Configuration Options

Site URL

The site property defines your production URL:

site: "https://version-counter.netlify.app"

This is used for:

Generating absolute URLs in the sitemap
Social media meta tags
Canonical links

Update this to your actual domain before deploying to production.

Integrations

The project uses two Astro integrations:

integrations: [react(), sitemap()]

@astrojs/react: Enables React components (used for the Counter component)
@astrojs/sitemap: Automatically generates sitemap.xml for SEO

Vite Plugins

Tailwind CSS is configured as a Vite plugin:

vite: {
  plugins: [tailwindcss()],
}

This enables Tailwind v4’s new architecture with faster builds and smaller bundle sizes.

Building for Production

Install Dependencies

Ensure all packages are installed:

npm install

The project uses these core dependencies:

package.json

{
  "dependencies": {
    "@astrojs/react": "^4.4.2",
    "@astrojs/sitemap": "^3.7.0",
    "@tailwindcss/vite": "^4.1.18",
    "astro": "^5.16.7",
    "react": "^19.2.3",
    "react-dom": "^19.2.3",
    "tailwindcss": "^4.1.18"
  }
}

Run the Build

Generate the production build:

npm run build

This command:

Compiles all .astro files to HTML
Bundles React components with Vite
Processes Tailwind CSS
Optimizes images and assets
Generates the sitemap

Output is written to the dist/ directory.

Preview Locally

Test the production build before deploying:

npm run preview

This serves the dist/ folder on http://localhost:4321 (or another port if 4321 is in use).

Always preview the build locally to catch issues before deploying. Check that:

All routes work correctly
Images load properly
JavaScript is functioning (countdown timers)
The sitemap is generated at /sitemap.xml

Deployment Platforms

Version Counter can be deployed to any static hosting platform. Here are the most popular options:

Netlify (Recommended)

The project is currently deployed on Netlify. It offers:

Automatic deployments from Git
Free SSL certificates
Global CDN
Instant cache invalidation

Connect Repository

Push your code to GitHub, GitLab, or Bitbucket
Log in to Netlify
Click Add new site → Import an existing project
Select your Git provider and repository

Configure Build Settings

Netlify will auto-detect Astro. Verify these settings:

Build command: npm run build
Publish directory: dist
Node version: 18.x or higher (set in netlify.toml or environment variables)

Create a netlify.toml file in your project root:

netlify.toml

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

[build.environment]
  NODE_VERSION = "20"

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

The redirect rule is necessary for client-side routing, though Version Counter uses server-rendered routes.

Deploy

Click Deploy site. Netlify will:

Clone your repository
Run npm install
Execute npm run build
Deploy the dist/ folder to the CDN

Your site will be live at a *.netlify.app subdomain.

Custom Domain (Optional)

To use a custom domain:

Go to Site settings → Domain management
Click Add custom domain
Follow the DNS configuration instructions
SSL will be automatically provisioned

Vercel

Vercel provides excellent Astro support with zero configuration:

Install Vercel CLI

npm install -g vercel

Deploy

From your project directory:

vercel

Follow the prompts to link your project and deploy.

Production Deployment

For production deploys:

vercel --prod

Or connect your Git repository in the Vercel dashboard for automatic deployments.

Vercel Configuration

Create a vercel.json for advanced settings:

vercel.json

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "framework": "astro"
}

Cloudflare Pages

Cloudflare Pages offers excellent performance with their global edge network:

Connect Repository

Log in to Cloudflare Dashboard
Go to Workers & Pages → Create application → Pages
Connect your Git repository

Configure Build

Set these build settings:

Build command: npm run build
Build output directory: dist
Root directory: / (or your monorepo path)

Environment Variables

Set Node version:

Variable name: NODE_VERSION
Value: 20

GitHub Pages

For free hosting on GitHub:

Update astro.config.mjs

Set the correct base path:

astro.config.mjs

export default defineConfig({
  site: "https://username.github.io",
  base: "/repository-name",  // If using project pages
  // ... other config
});

Create GitHub Action

Add .github/workflows/deploy.yml:

.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 ci

      - name: Build
        run: npm run build

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

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

Enable GitHub Pages

In your repository settings:

Go to Settings → Pages
Set Source to “GitHub Actions”
Push to trigger the workflow

Environment Variables

If you need environment variables (for API keys, feature flags, etc.):

Create .env file

.env

PUBLIC_API_URL=https://api.example.com
SECRET_KEY=your-secret-here

Only variables prefixed with PUBLIC_ are exposed to client-side code. Never prefix secrets with PUBLIC_.

Access in Astro

---
const apiUrl = import.meta.env.PUBLIC_API_URL;
const secretKey = import.meta.env.SECRET_KEY;  // Server-side only
---

Set in Hosting Platform

Add environment variables in your platform’s dashboard:

Netlify: Site settings → Environment variables
Vercel: Project settings → Environment Variables
Cloudflare Pages: Settings → Environment variables

Performance Optimization

Image Optimization

Version Counter uses external CDN images. To optimize:

Use modern formats (WebP, AVIF) when possible
Compress images before uploading to CDN
Consider lazy loading for below-the-fold images
Use responsive images with srcset for different screen sizes

For local images, use Astro’s built-in <Image> component:

---
import { Image } from 'astro:assets';
import myImage from '../assets/image.png';
---
<Image src={myImage} alt="Description" />

Code Splitting

Astro automatically splits code by route. For React components:

<Counter client:load />      <!-- Loads immediately -->
<Counter client:visible />   <!-- Loads when visible -->
<Counter client:idle />      <!-- Loads when browser is idle -->

Use client:visible or client:idle for non-critical components.

Caching Strategy

Configure cache headers in your hosting platform:Netlify (netlify.toml):

[[headers]]
  for = "/assets/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[headers]]
  for = "/*.html"
  [headers.values]
    Cache-Control = "public, max-age=0, must-revalidate"

Vercel (vercel.json):

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Sitemap and SEO

The @astrojs/sitemap integration automatically generates a sitemap. Ensure:

The site URL in astro.config.mjs is correct
All pages have proper meta tags
Submit the sitemap to Google Search Console

Verify the sitemap at: https://your-domain.com/sitemap.xml

Monitoring and Analytics

Add analytics to track usage:

Google Analytics

src/layouts/Layout.astro

<head>
  <!-- Google Analytics -->
  <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>
</head>

Plausible Analytics (Privacy-Friendly)

src/layouts/Layout.astro

<head>
  <script defer data-domain="your-domain.com" src="https://plausible.io/js/script.js"></script>
</head>

Continuous Deployment

Most platforms support automatic deployments:

Push to main branch → Automatic production deploy
Push to other branches → Deploy preview (Netlify/Vercel)
Pull requests → Deploy preview for testing

Configure branch deploy settings in your platform’s dashboard.

Troubleshooting

Build Failures

Common issues:

Node version mismatch: Ensure Node 18+ is specified
Missing dependencies: Check that all packages are in dependencies (not devDependencies)
TypeScript errors: Run npm run build locally to catch issues before deploying
Environment variables: Verify all required env vars are set in the platform

Runtime Errors

JavaScript not working:

Check browser console for errors
Verify React components use correct client directives
Ensure date strings are in valid ISO 8601 format

Countdown not updating:

Verify fecha_inicio and duracion_dias in games.json
Check that Counter component has client:load directive
Test in preview mode before deploying

Performance Issues

Use Lighthouse to identify bottlenecks
Check image sizes and formats
Review bundle size with npm run build -- --verbose
Minimize the use of backdrop-filter (GPU-intensive)

Post-Deployment Checklist

Next Steps

Adding Games

Learn how to add new games to the dashboard

Customizing Themes

Customize game themes and colors

Get Started

Guides

Components

Build Configuration

Key Configuration Options

Building for Production

Deployment Platforms

Netlify (Recommended)

Vercel

Cloudflare Pages

GitHub Pages

Environment Variables

Performance Optimization

Monitoring and Analytics

Google Analytics

Plausible Analytics (Privacy-Friendly)

Continuous Deployment

Troubleshooting

Post-Deployment Checklist

Next Steps

Adding Games

Customizing Themes

Build docs developers (and LLMs) love

Get Started

Guides

Components

​Build Configuration

​Key Configuration Options

​Building for Production

​Deployment Platforms

​Netlify (Recommended)

​Vercel

​Cloudflare Pages

​GitHub Pages

​Environment Variables

​Performance Optimization

​Monitoring and Analytics

​Google Analytics

​Plausible Analytics (Privacy-Friendly)

​Continuous Deployment

​Troubleshooting

​Post-Deployment Checklist

​Next Steps

Adding Games

Customizing Themes

Build docs developers (and LLMs) love

Build Configuration

Key Configuration Options

Building for Production

Deployment Platforms

Netlify (Recommended)

Vercel

Cloudflare Pages

GitHub Pages

Environment Variables

Performance Optimization

Monitoring and Analytics

Google Analytics

Plausible Analytics (Privacy-Friendly)

Continuous Deployment

Troubleshooting

Post-Deployment Checklist

Next Steps