Skip to content

lucky-media/astrostarter

Repository files navigation

AstroStarter

A modern, feature-rich Astro starter template with TypeScript, Tailwind CSS, Alpine.js, and comprehensive developer tooling.

Astro TypeScript Tailwind CSS Alpine.js

✨ Features

  • 🚀 Astro 5 - The modern web framework for content-focused websites
  • 🎨 Tailwind CSS 4 - Latest utility-first CSS framework with modern features
  • Alpine.js - Lightweight JavaScript framework for interactive components
  • 📱 Responsive Design - Mobile-first approach with flexible layouts
  • 🔍 SEO Optimized - Built-in SEO components with Open Graph support
  • 🎯 TypeScript - Full TypeScript support with strict configuration
  • 🎨 Component Library - Pre-built components with variant support
  • 🔧 Developer Tools - ESLint, Prettier, Husky, and Commitlint
  • 📦 Path Aliases - Clean imports with @/ prefix
  • 🌐 Sitemap Generation - Automatic sitemap generation
  • 🔗 Link Prefetching - Optimized navigation with prefetch enabled
  • 🎨 Favicon Management - Comprehensive favicon handling component

🚀 Quick Start

Prerequisites

  • Node.js 18+
  • npm, yarn, or pnpm

Installation

  1. Clone the repository or use this template
  2. Install dependencies:
npm install
  1. Set up your favicon files:

    • Create a public/favicon/ directory
    • Add your favicon.ico file (required)
    • Optionally add other favicon formats (see Favicon Component section)
  2. Update the site URL in astro.config.mjs:

export default defineConfig({
  site: "https://yourdomain.com", // Change this!
  // ... rest of config
});
  1. Start the development server:
npm run dev

Visit http://localhost:4321 to see your site!

🗂️ Project Structure

├── public/
│   └── favicon/              # Favicon files
│       ├── favicon.ico       # Required
│       ├── favicon-16x16.png
│       ├── favicon-32x32.png
│       ├── apple-touch-icon.png
│       ├── android-chrome-*.png
│       └── site.webmanifest
├── src/
│   ├── assets/              # Static assets
│   ├── components/          # Reusable components
│   │   ├── Button.astro     # Styled button component
│   │   └── Favicon.astro    # Favicon management
│   ├── layouts/
│   │   └── Layout.astro     # Main layout with SEO
│   ├── pages/
│   │   ├── index.astro      # Homepage
│   │   └── about.astro      # About page
│   ├── styles/
│   │   └── global.css       # Global styles and utilities
│   └── utils/
│       ├── cn.ts           # Class name utility
│       └── mergeDeep.ts    # Deep merge utility
├── astro.config.mjs        # Astro configuration
├── tailwind.config.js      # Tailwind configuration
├── tsconfig.json          # TypeScript configuration
└── package.json           # Dependencies and scripts

🧞 Available Commands

All commands are run from the root of the project:

Command Action
npm install Install dependencies
npm run dev Start development server at localhost:4321
npm run build Build production site to ./dist/
npm run preview Preview build locally
npm run prettier Format code with Prettier
npm run lint Lint and fix code with ESLint

Button Component

A flexible, accessible button component with multiple variants and sizes using Class Variance Authority (CVA).

Features:

  • Multiple variants: primary, outline
  • Multiple sizes: xs, sm, base, md, lg
  • Can render as button or anchor element
  • Full TypeScript support with proper props interface
  • Tailwind CSS styling with hover effects

Usage:

---
import Button from "@/components/Button.astro";
---

<!-- Basic buttons -->
<Button>Click me</Button>
<Button variant="outline">Outline button</Button>

<!-- Different sizes -->
<Button size="lg">Large button</Button>
<Button size="sm">Small button</Button>

<!-- As a link -->
<Button href="/about">Go to About</Button>

Favicon Component

A comprehensive favicon management system that automatically detects and renders favicon meta tags.

Features:

  • Automatically scans public/favicon/ directory
  • Renders appropriate meta tags for detected favicon formats
  • Throws helpful errors for missing files or directories
  • Supports all modern favicon formats and sizes
  • Includes additional meta tags for better browser support

Supported Files:

  • favicon.ico (required)
  • favicon-16x16.png, favicon-32x32.png
  • apple-touch-icon.png
  • android-chrome-192x192.png, android-chrome-512x512.png
  • site.webmanifest
  • safari-pinned-tab.svg

Usage: The component is already integrated into the main layout. Simply add your favicon files to public/favicon/.

🎨 Styling System

Tailwind CSS 4

The project uses the latest Tailwind CSS v4 with modern features:

  • Vite Plugin: Integrated via @tailwindcss/vite
  • Custom Utilities: Container utility with auto margins
  • Base Styles: Consistent border colors and button cursor
  • Modern Syntax: Using the new @import "tailwindcss" syntax

Class Name Utilities

cn() Function: A utility for merging CSS classes with conflict resolution:

import { cn } from "@/utils/cn";

// Merges classes and resolves conflicts
const className = cn("p-4 bg-red-500", "bg-blue-500"); // Results in "p-4 bg-blue-500"

🧠 State Management

Alpine.js Integration

Pre-configured Alpine.js setup for interactive components:

// src/alpine.ts - Add your Alpine components here
Alpine.data("demo", () => {
  return {
    toggle: () => {
      console.log("toggle");
    },
  };
});

Use in templates:

<div x-data="demo">
  <button x-on:click="toggle">Click me</button>
</div>

🔧 Developer Experience

TypeScript Configuration

  • Strict Mode: Uses Astro's strict TypeScript configuration
  • Path Aliases: Clean imports with @/ prefix for components, layouts, utils, and styles
  • Type Safety: Full type support for Astro components and props

Code Quality Tools

ESLint Configuration:

  • JavaScript/TypeScript linting
  • Astro-specific rules
  • JSX accessibility checks
  • Automatic fixing with npm run lint

Prettier Setup:

  • Astro plugin support
  • Tailwind CSS class sorting
  • 100 character line length
  • Automatic formatting with npm run prettier

Git Hooks (Husky):

  • Pre-commit: Runs Prettier and ESLint automatically
  • Commit linting with conventional commits

VS Code Integration

Recommended Extensions:

  • Astro VS Code extension
  • TypeScript support
  • Tailwind CSS IntelliSense

Launch Configuration:

  • One-click development server start
  • Integrated debugging support

🌐 SEO & Performance

Built-in SEO

The layout includes comprehensive SEO features:

  • Meta Tags: Automatic title, description, and Open Graph tags
  • Sitemap: Auto-generated sitemap for search engines
  • Performance: Link prefetching enabled for faster navigation
  • PWA Ready: Web manifest support for progressive web apps

SEO Usage

---
import Layout from "@/layouts/Layout.astro";
---

<Layout
  seo={{
    title: "About Us",
    description: "Learn more about our project",
    openGraph: {
      basic: {
        title: "Custom OG Title",
        type: "article",
      },
    },
  }}
>
  <!-- Your content -->
</Layout>

🔧 Configuration

Environment Setup

  1. Site URL: Update astro.config.mjs with your production URL
  2. Favicon: Add your favicon files to public/favicon/
  3. SEO Defaults: Modify default SEO settings in src/layouts/Layout.astro

Customization

Adding New Components:

---
// src/components/YourComponent.astro
export interface Props {
  title: string;
  variant?: "default" | "highlighted";
}

const { title, variant = "default" } = Astro.props;
---

<div class={cn("base-styles", { "highlighted-styles": variant === "highlighted" })}>
  {title}
</div>

Adding Alpine.js Components:

// src/alpine.ts
Alpine.data("yourComponent", () => ({
  // Your component data and methods
}));

📦 Deployment

Build for Production

npm run build

The built site will be available in the ./dist/ directory.

Deployment Platforms

This project is ready to deploy on:

  • Vercel - Zero configuration deployment
  • Netlify - Automatic builds and deploys
  • GitHub Pages - Static site hosting
  • Cloudflare Pages - Fast edge deployment

🤝 Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes using conventional commits
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is open source and available under the MIT License.


Created by Lucky Media

About

An opinionated Starter Kit for Astro

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •