Get started with AstroWind to create a website using Astro and Tailwind CSS

AstroWind is a modern, feature-rich template built on Astro and Tailwind CSS that provides everything you need to create stunning websites quickly. Whether you’re building a personal blog, business website, or portfolio, AstroWind offers a solid foundation with modern tooling and best practices built-in.

In this comprehensive guide, we’ll walk through setting up AstroWind from scratch, customizing it to match your brand, and deploying it to production. By the end, you’ll have a fully functional website ready to go live.

Prerequisites

Before we begin, make sure you have the following installed on your system:

Node.js (version 18.0 or higher)
npm or pnpm package manager
Git for version control
A code editor like VS Code with the Astro extension

Getting Started with AstroWind

Step 1: Clone the AstroWind Template

The easiest way to get started is by using the AstroWind template. You can create a new project using one of these methods:

Using npm:

npm create astro@latest my-astrowind-site -- --template astrowind

Using pnpm:

pnpm create astro@latest my-astrowind-site -- --template astrowind

Or clone directly from GitHub:

git clone https://github.com/onwidget/astrowind.git my-astrowind-site
cd my-astrowind-site

Step 2: Install Dependencies

Navigate to your project directory and install the required dependencies:

cd my-astrowind-site
npm install
# or
pnpm install

Step 3: Start the Development Server

Launch the development server to see your site in action:

npm run dev
# or
pnpm dev

Open your browser and navigate to http://localhost:4321 to see your AstroWind site running locally.

Understanding the Project Structure

AstroWind follows a well-organized structure that makes it easy to customize and maintain:

src/
├── assets/          # Images, icons, and other static assets
├── components/      # Reusable Astro components
├── content/         # Markdown content for blog posts and pages
├── layouts/         # Page layout templates
├── pages/           # File-based routing (Astro pages)
├── styles/          # Global CSS styles
└── utils/           # Utility functions and helpers

Key Files to Know

astro.config.mjs - Astro configuration
tailwind.config.mjs - Tailwind CSS configuration
src/config.yaml - Site configuration (title, description, etc.)
src/navigation.js - Navigation menu configuration

Customizing Your Site

Updating Site Information

Edit src/config.yaml to customize your site’s basic information:

site:
  name: "Your Site Name"
  site: "https://yoursite.com"
  base: "/"
  trailingSlash: false

params:
  default_lang: "en"
  author: "Your Name"
  description: "Your site description"

Update src/navigation.js to customize your site’s navigation:

export const navigation = [
  { name: 'Home', href: '/' },
  { name: 'About', href: '/about' },
  { name: 'Blog', href: '/blog' },
  { name: 'Contact', href: '/contact' },
];

Customizing Colors and Styling

AstroWind uses Tailwind CSS for styling. You can customize the color scheme by editing tailwind.config.mjs:

module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          500: '#3b82f6',
          900: '#1e3a8a',
        },
      },
    },
  },
}

Adding Your Content

Creating Blog Posts

Add new blog posts by creating markdown files in src/content/post/:

---
publishDate: 2024-01-15T00:00:00Z
author: Your Name
title: "Your Blog Post Title"
excerpt: "A brief description of your post"
image: "/path/to/your/image.jpg"
category: "Tutorials"
tags:
  - astro
  - web-development
---

Your blog post content goes here...

Creating Pages

Create new pages by adding .astro files to the src/pages/ directory. For example, to create an “About” page:

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

<Layout title="About">
  <div class="container mx-auto px-4 py-16">
    <h1 class="text-4xl font-bold mb-8">About Us</h1>
    <p class="text-lg">Your about content goes here...</p>
  </div>
</Layout>

Advanced Customization

Creating Custom Components

Create reusable components in src/components/. For example, a custom button component:

---
export interface Props {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: any;
}

const { variant = 'primary', size = 'md', children } = Astro.props;

const baseClasses = 'font-medium rounded-lg transition-colors';
const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700',
  secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
};
const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-6 py-3 text-lg',
};
---

<button class={`${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`}>
  <slot />
</button>

Adding Integrations

AstroWind supports various integrations. To add a new one, install the integration and update astro.config.mjs:

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import sitemap from '@astrojs/sitemap';

export default defineConfig({
  integrations: [
    tailwind(),
    sitemap(),
  ],
});

Deployment

Deploying to Netlify

Build your site:
```
npm run build
```
Deploy the dist folder to Netlify, or connect your GitHub repository for automatic deployments.

Deploying to Vercel

Install the Vercel CLI:
```
npm i -g vercel
```
Deploy your site:
```
vercel
```

Deploying to GitHub Pages

Update astro.config.mjs:

export default defineConfig({
  site: 'https://yourusername.github.io',
  base: '/your-repo-name',
});

Add a GitHub Actions workflow (.github/workflows/deploy.yml):

name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '18'
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Best Practices and Tips

Performance Optimization

Optimize Images: Use Astro’s built-in image optimization with <Image> component
Code Splitting: Astro automatically splits your code for optimal loading
Static Generation: Use static generation for better performance and SEO

SEO Best Practices

Add proper meta tags in your layouts
Use semantic HTML elements
Include structured data (JSON-LD)
Optimize your images with alt text
Create a sitemap (AstroWind includes this)

Content Management

Use the content collections feature for better content organization
Implement proper frontmatter for all your content
Use consistent naming conventions for your files

Troubleshooting Common Issues

Build Errors

If you encounter build errors:

Clear the .astro cache: rm -rf .astro
Delete node_modules and reinstall: rm -rf node_modules && npm install
Check your Astro and Node.js versions

Styling Issues

Ensure Tailwind CSS is properly configured
Check that your classes are not being purged
Verify your custom CSS is being imported correctly

Conclusion

AstroWind provides an excellent foundation for building modern websites with Astro and Tailwind CSS. With its comprehensive feature set, you can create anything from simple blogs to complex business websites.

The key to success with AstroWind is understanding its structure and leveraging the power of Astro’s component-based architecture combined with Tailwind’s utility-first CSS approach. Start with the basics, experiment with customization, and gradually add more advanced features as you become comfortable with the framework.

Remember to keep your content organized, optimize for performance, and follow SEO best practices to ensure your website not only looks great but also performs well in search engines.