🏥 Laguntza Fisioterapia - Modern Astro Website

🌐 Live Site: www.laguntzafisioterapia.com

A production-ready, multilingual Astro website showcasing modern web development best practices

Features • Quick Start • Tech Stack • Documentation

---

📖 About This Project

Laguntza Fisioterapia is a complete, production-ready website built with Astro for a physiotherapy clinic in Urnieta, Gipuzkoa (Basque Country, Spain). This project serves as both a functional business website and a reference implementation for building modern, multilingual static sites with Astro.

What Makes This Project Special

• 🌍 Real-world Production Site - Serving actual users at laguntzafisioterapia.com
• 🎯 Complete Feature Set - From i18n to contact forms, blog, SEO, and deployment
• 📚 Educational Resource - Well-structured code demonstrating Astro best practices
• 🏗️ Scalable Architecture - Modular component system ready for expansion
• 🚀 Full CI/CD Pipeline - Automated testing, formatting, and deployment

Who Is This For?

• Astro Developers looking for a comprehensive example project
• Web Agencies needing a template for client websites
• Students learning modern static site generation
• Businesses seeking a customizable website foundation

✨ Features

Core Astro Features Demonstrated

• ⚡ Zero-JS by Default - Astro's Islands Architecture with selective hydration
• 🏝️ Component Islands - Interactive components only where needed (maps, forms)
• 📦 Content Collections - Type-safe content management (coming soon for blog posts)
• 🎨 Astro Components - Reusable .astro components with scoped styling
• 🔧 TypeScript Integration - Full type safety across the project
• 📱 MDX Support - Write content with components embedded

Internationalization (i18n)

• 🌐 Dual Language - Full Basque (eu) and Spanish (es) support
• 🔀 Language Routing - /[lang]/ route pattern with Astro's file-based routing
• 🎯 Language Toggle - Smooth client-side language switching
• 📝 Translation System - Centralized UI translations in src/i18n/
• 🌍 Locale-aware URLs - SEO-friendly multilingual routes

Production-Ready Features

• 🎯 SEO Excellence - Meta tags, Open Graph, JSON-LD structured data
• 🗺️ Interactive Maps - Leaflet integration with lazy loading
• 📝 Contact Forms - Form handling with validation
• 📰 MDX Blog System - Markdown + JSX for rich blog content
• 🎨 Theme System - Dark/light mode with CSS custom properties
• ♿ Accessibility - WCAG compliant, semantic HTML
• 📊 Analytics Ready - Structured for Google Analytics/Tag Manager

Developer Experience

• 🔥 Hot Module Replacement - Instant feedback during development
• 🎯 TypeScript - Full type safety with astro check
• 💅 Prettier - Automated code formatting
• 🐳 Docker Support - Containerized deployment with Nginx
• 🔄 CI/CD Pipeline - GitHub Actions for testing and deployment
• 📦 pnpm - Fast, efficient package management

🛠️ Tech Stack

Framework & Build Tools

• Astro v4.x - The web framework for content-driven websites
  • File-based routing
  • Component Islands architecture
  • Built-in optimization (CSS, images, fonts)
  • Static Site Generation (SSG)
• TypeScript - Type safety and better DX
• pnpm - Fast, disk-space efficient package manager

UI & Styling

• CSS Custom Properties - Theme system with CSS variables
• Modern CSS - Grid, Flexbox, Container Queries
• Responsive Design - Mobile-first approach
• No CSS Framework - Vanilla CSS for maximum control and performance

Content & Data

• MDX - Markdown with embedded components for blog posts
• Astro Content Collections - Type-safe content management (future enhancement)
• Static Assets - Optimized images and fonts

Interactive Features

• GSAP - High-performance animations
• Leaflet - Interactive maps (with Islands hydration)
• Vanilla JavaScript - Minimal client-side JS for forms and interactions

Developer Tools

• Prettier - Code formatting
• ESLint - Code linting (configurable)
• GitHub Actions - CI/CD automation

Deployment & Infrastructure

• Nginx - Web server
• Docker - Containerization
• GitHub Actions - Automated deployment pipeline
• VPS/Cloud Hosting - Production deployment

Why This Stack?

This stack prioritizes:

• ⚡ Performance - Astro ships zero JavaScript by default
• 🎯 SEO - Static HTML generation for optimal crawlability
• 🧑‍💻 Developer Experience - TypeScript, hot reload, modern tooling
• 🎨 Flexibility - No opinionated CSS framework, full control
• 💰 Cost Efficiency - Static hosting is cheap/free everywhere

🚀 Quick Start

Prerequisites

• Node.js v18.14.1 or higher (check .nvmrc for exact version)
• pnpm v8 or higher (recommended) or npm
• Git for version control

Installation

1. Clone the repository:

   git clone https://github.com/jramosg/laguntza-fisioterapia.git
   cd laguntza-fisioterapia

2. Install dependencies:

   pnpm install
   # or
   npm install

3. Start the development server:

   pnpm dev
   # or
   npm run dev

4. Open your browser:

   Navigate to http://localhost:4321

First Steps

• 📝 Edit content in src/pages/[lang]/
• 🎨 Customize theme in src/styles/theme.css
• ⚙️ Configure site settings in src/config/
• 🖼️ Add images to src/images/ or public/assets/

Project Commands

Command	Action
pnpm dev	Start local dev server at localhost:4321
pnpm build	Build production site to ./dist/
pnpm preview	Preview production build locally
pnpm format	Format all files with Prettier
pnpm format:check	Check if files are formatted
pnpm astro ...	Run Astro CLI commands

Quick Customization Checklist

• Update company info in src/config/company.ts
• Replace logo in src/images/logos/
• Update navigation in src/config/nav.ts
• Customize theme colors in src/styles/theme.css
• Add your content in src/pages/[lang]/
• Update contact form endpoint in src/components/forms/ContactForm.astro
• Configure deployment in .github/workflows/

🏗️ Development Workflow

Local Development

pnpm dev

The development server includes:

• 🔥 Hot Module Replacement (HMR)
• ⚡ Fast refresh for Astro components
• 🔍 TypeScript checking
• 📦 Automatic dependency updates

Building for Production

# Build the site
pnpm build

# Preview the production build
pnpm preview

The build process:

1. Compiles TypeScript
2. Processes and optimizes CSS
3. Optimizes images
4. Generates static HTML
5. Creates /dist directory

Code Quality

# Format all files
pnpm format

# Check formatting
pnpm format:check

# Type checking
pnpm astro check

Testing Changes

1. Make changes in src/
2. Check in browser at localhost:4321
3. Run pnpm format before committing
4. Build and preview before deploying

Adding Dependencies

# Add a package
pnpm add package-name

# Add a dev dependency
pnpm add -D package-name

# Update dependencies
pnpm update

Debugging Tips

• Use browser DevTools for client-side debugging
• Check Astro output in terminal for build errors
• Use console.log() in component frontmatter (runs at build time)
• Enable verbose logging in astro.config.mjs if needed

🔧 CI/CD Pipeline

This project demonstrates a complete CI/CD workflow using GitHub Actions.

Continuous Integration

Format Check (runs on all pushes and PRs)

- Checkout code
- Setup Node.js (from .nvmrc)
- Install pnpm
- Cache dependencies
- Install dependencies
- Run Prettier check

Benefits:

• ✅ Ensures code consistency
• ✅ Catches formatting issues early
• ✅ Fast feedback with caching

Continuous Deployment

Automated Deployment (runs on master with [deploy] tag)

- Format check passes
- Build Docker image
- Deploy to production server
- Health check verification

Workflow Triggers:

1. Automatic: Push to master with [deploy] in commit message
2. Manual: Via GitHub Actions UI

Deployment Flow:

Code Change → Push → Format Check → [deploy] tag? → Build → Deploy → Live
                          ↓
                       ❌ Fail → No deployment
                       ✅ Pass → Continue

Best Practices Demonstrated

• 🔒 Security: Secrets for deployment credentials
• ⚡ Performance: Dependency caching for faster builds
• 🎯 Reliability: Health checks after deployment
• 📊 Visibility: Clear status checks on PRs
• 🔄 Automation: Reduces manual deployment errors

Setup for Your Project

1. Add GitHub Secrets (Settings → Secrets):

   DEPLOY_HOST=your-server.com
   DEPLOY_USER=deploy-user
   DEPLOY_KEY=ssh-private-key
   

2. Customize workflows in .github/workflows/

3. Update deployment script for your infrastructure

🚢 Deployment

Docker Deployment

This project includes a production-ready Dockerfile with Nginx.

# Build the Docker image
docker build -t laguntza-fisioterapia .

# Run the container
docker run -p 8080:8080 laguntza-fisioterapia

# Access at http://localhost:8080

The Docker setup:

• Multi-stage build for minimal image size
• Nginx for efficient static file serving
• Optimized for production performance
• Configurable via nginx/nginx.conf

CI/CD with GitHub Actions

The project includes automated workflows:

1. Format Check (.github/workflows/format.yml)

• Triggers on every push and PR
• Validates code formatting with Prettier
• Uses pnpm with dependency caching

2. Deployment (.github/workflows/deploy.yml)

• Triggers on push to master with [deploy] in commit message
• Can also be triggered manually
• Builds and deploys to production server

Deployment Example:

git commit -m "Update services page [deploy]"
git push origin master

Alternative Deployment Options

Netlify

# Already configured via netlify.toml
# Connect repository to Netlify for automatic deployments

Vercel

vercel --prod

Static Hosting

Upload the dist/ folder to any static hosting service:

• GitHub Pages
• Cloudflare Pages
• AWS S3 + CloudFront
• DigitalOcean App Platform

Environment Variables

For production deployments, set these if needed:

# Example environment variables
PUBLIC_SITE_URL=https://www.laguntzafisioterapia.com
PUBLIC_ANALYTICS_ID=your-id

Add to your hosting platform's environment variables or .env file.

📁 Project Structure

laguntza-fisioterapia/
├── .github/
│   └── workflows/           # CI/CD pipelines
│       ├── format.yml       # Prettier formatting checks
│       └── deploy.yml       # Automated deployment
├── nginx/
│   └── nginx.conf          # Production Nginx configuration
├── public/                 # Static assets (copied as-is)
│   ├── robots.txt
│   ├── site.webmanifest
│   ├── assets/
│   │   └── icons/         # Favicon and app icons
│   └── fonts/             # Web fonts
├── src/
│   ├── components/        # 🧩 Reusable Astro components
│   │   ├── blog/         # Blog-specific components
│   │   │   ├── BlogPostPreview.astro
│   │   │   └── BlogPostsList.astro
│   │   ├── buttons/      # Button components
│   │   │   ├── Burger.astro
│   │   │   └── Button.astro
│   │   ├── core/         # Layout & navigation
│   │   │   ├── Header.astro
│   │   │   ├── Footer.astro
│   │   │   ├── Nav.astro
│   │   │   └── Container.astro
│   │   ├── form-fields/  # Form input components
│   │   │   ├── FormInput.astro
│   │   │   ├── FormSelect.astro
│   │   │   └── FormTextarea.astro
│   │   ├── forms/        # Complete forms
│   │   │   └── ContactForm.astro
│   │   ├── head/         # HTML <head> components
│   │   │   ├── BaseHead.astro
│   │   │   ├── OpenGraph.astro
│   │   │   ├── StructuredData.astro
│   │   │   └── FAQSchema.astro
│   │   ├── sections/     # Page sections
│   │   │   ├── AboutSection.astro
│   │   │   ├── CtaCardSection.astro
│   │   │   ├── TextSection.astro
│   │   │   └── heros/
│   │   │       ├── HeroSection.astro
│   │   │       └── TextAndImageHero.astro
│   │   └── theme-switcher/ # Dark/light mode
│   │       ├── ThemeProvider.astro
│   │       └── ThemeSwitcher.astro
│   ├── config/           # ⚙️ Configuration files
│   │   ├── company.ts    # Company information
│   │   ├── footer.ts     # Footer links
│   │   ├── nav.ts        # Navigation structure
│   │   └── settings.ts   # Site settings
│   ├── i18n/             # 🌍 Internationalization
│   │   ├── ui.ts         # Translation strings
│   │   └── utils.ts      # i18n helper functions
│   ├── icons/            # SVG icons
│   ├── images/           # Optimized images
│   │   └── logos/        # Brand logos
│   ├── layouts/          # 📄 Page layouts
│   │   ├── Base.astro    # Base HTML layout
│   │   ├── Page.astro    # Standard page layout
│   │   └── Post.astro    # Blog post layout
│   ├── pages/            # 🗂️ File-based routing
│   │   ├── index.astro   # Homepage (redirects)
│   │   ├── 404.astro     # 404 page
│   │   └── [lang]/       # Multilingual routes
│   │       ├── index.astro
│   │       ├── about.astro
│   │       ├── services.astro
│   │       ├── contact.astro
│   │       ├── gallery.astro
│   │       └── opening.astro
│   ├── styles/           # 🎨 Global styles
│   │   ├── global.css    # Global styles & utilities
│   │   ├── reset.css     # CSS reset
│   │   ├── theme.css     # Theme variables
│   │   ├── typography.css # Typography styles
│   │   └── index.css     # Style imports
│   ├── utils/            # 🔧 Utility functions
│   │   └── helpers.js
│   ├── env.d.ts          # TypeScript env definitions
│   └── types.ts          # TypeScript types
├── astro.config.mjs      # Astro configuration
├── tsconfig.json         # TypeScript configuration
├── package.json          # Dependencies & scripts
├── pnpm-lock.yaml        # Lockfile
├── Dockerfile            # Docker configuration
├── netlify.toml          # Netlify config (alternative)
└── README.md             # This file

Key Directories Explained

/src/components/

Modular, reusable Astro components organized by function. Each component is self-contained with its logic and styles.

/src/config/

Centralized configuration makes it easy to update site-wide settings without touching component code.

/src/i18n/

Translation system supporting multiple languages. Add new languages by extending ui.ts.

/src/pages/

Astro's file-based routing. Files here become routes automatically. [lang]/ creates dynamic language routes.

/src/styles/

Global CSS and theme system using CSS custom properties for easy customization.

Astro-Specific Files

• astro.config.mjs - Main Astro configuration
• src/env.d.ts - TypeScript environment types
• .astro files - Astro component format (HTML-like with frontmatter)

🎨 Customization Guide

Theme Customization

The entire visual theme is controlled by CSS custom properties in src/styles/theme.css:

:root {
  --color-primary: #your-color;
  --color-secondary: #your-color;
  --font-family-sans: 'Your Font', sans-serif;
  /* ... more variables */
}

Adding a New Language

1. Add language to astro.config.mjs:

i18n: {
  locales: ['eu', 'es', 'en'], // Add 'en'
  defaultLocale: 'eu'
}

2. Add translations to src/i18n/ui.ts:

export const ui = {
  en: {
    'nav.home': 'Home',
    // ... more translations
  }
}

3. Create pages in src/pages/en/

Customizing Navigation

Edit src/config/nav.ts:

export const navItems = {
  eu: [
    { title: 'Hasiera', slug: '/eu/' },
    { title: 'Guri buruz', slug: '/eu/about' },
    // Add your items
  ]
}

Adding a New Page

1. Create an Astro file in src/pages/[lang]/your-page.astro
2. Use an existing layout:

---
import Page from '../../layouts/Page.astro';
---

<Page title="Your Page Title">
  <!-- Your content -->
</Page>

3. Add to navigation in src/config/nav.ts

Modifying the Contact Form

The contact form is in src/components/forms/ContactForm.astro. To connect it to your backend:

1. Set the form action endpoint
2. Configure form handling (e.g., Formspree, Netlify Forms, custom API)
3. Update validation as needed

Styling Best Practices

• Use CSS custom properties for colors, spacing, and typography
• Keep component styles scoped with <style> tags in .astro files
• Use utility classes sparingly - prefer component-specific styles
• Follow mobile-first responsive design

📚 Learning Resources

Astro Documentation

• Astro Docs - Official documentation
• Astro Tutorial - Step-by-step guide
• Astro Patterns - Common patterns
• Astro Islands - Islands architecture

Key Concepts in This Project

1. File-Based Routing

src/pages/[lang]/about.astro → /{lang}/about
src/pages/[lang]/index.astro → /{lang}/

2. Component Structure

---
// Component Script (runs at build time)
const { title } = Astro.props;
---

<!-- Template (HTML) -->
<h1>{title}</h1>

<style>
  /* Scoped styles */
  h1 { color: var(--color-primary); }
</style>

3. Islands Architecture

Only hydrate interactive components:

<!-- Static (no JS) -->
<Header />

<!-- Interactive (hydrates in browser) -->
<LeafletMap client:load />

4. Internationalization Pattern

// src/i18n/utils.ts
export function useTranslations(lang: string) {
  return function t(key: string) {
    return ui[lang][key] || ui[defaultLang][key];
  }
}

Related Projects

• Astro Themes - More Astro starter themes
• Astro Blog - Official blog example
• Awesome Astro - Curated Astro resources

Performance Tips

1. Minimize JavaScript: Use static components when possible
2. Optimize Images: Use Astro's image optimization
3. Lazy Load: Use client:visible for below-fold components
4. CSS Optimization: Astro automatically scopes and optimizes CSS
5. Prefetching: Consider adding prefetch for key pages

🤝 Contributing

Contributions are welcome! Whether you're fixing a bug, adding a feature, or improving documentation.

How to Contribute

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/your-feature-name

3. Make your changes
4. Format your code

   pnpm format

5. Commit with a descriptive message

   git commit -m "Add: description of your changes"

6. Push to your fork

   git push origin feature/your-feature-name

7. Open a Pull Request

Contribution Guidelines

• ✅ Follow existing code style (use Prettier)
• ✅ Test your changes locally
• ✅ Update documentation if needed
• ✅ Keep PRs focused on a single feature/fix
• ✅ Write clear commit messages

Areas for Contribution

• 🐛 Bug fixes
• ✨ New features
• 📝 Documentation improvements
• 🌍 Additional language translations
• ♿ Accessibility enhancements
• ⚡ Performance optimizations
• 🎨 UI/UX improvements

Reporting Issues

Found a bug? Please open an issue with:

• Clear description
• Steps to reproduce
• Expected vs actual behavior
• Screenshots (if applicable)

💬 Community & Support

• 📧 Contact: info@laguntzafisioterapia.com
• 🐛 Issues: GitHub Issues
• 💬 Astro Discord: astro.build/chat

📊 Project Stats

• Lines of Code: ~5,000+
• Components: 30+
• Languages Supported: 2 (Basque, Spanish)
• Performance Score: 95+ (Lighthouse)
• Build Time: ~10 seconds
• Bundle Size: < 50KB JS (minimal)

⭐ Showcase

This project demonstrates:

• ✅ Production-Ready Astro Site - Real business website in active use
• ✅ Complete i18n Implementation - Multilingual routing and content
• ✅ Modern DevOps - CI/CD, Docker, automated deployment
• ✅ Performance First - Lighthouse scores 95+
• ✅ Accessibility - WCAG compliant
• ✅ SEO Optimized - Meta tags, Open Graph, structured data
• ✅ Developer Experience - TypeScript, hot reload, linting

🎯 Use Cases

Perfect for:

• 🏥 Healthcare/Medical Sites - Clinics, practices, health services
• 🏢 Small Business Websites - Services, contact, about pages
• 🌍 Multilingual Sites - International or regional businesses
• 📚 Learning Astro - Real-world example with best practices
• 🚀 Starter Template - Fork and customize for your needs

License

This project is licensed under the MIT License.

---

Laguntza Fisioterapia
📍 Zubitxo Plaza, 3, 20130 Urnieta, Gipuzkoa
🗺️ View on Google Maps

---

Built with ❤️ using Astro

⭐ If this project helped you, consider giving it a star!

Live Website • Report Bug • Request Feature