Marek Miláček
5th week with astro

5th week with astro

Week 5: AstroWind Installation & Structure

November 10-16, 2025

Big shift this week - stopped building from scratch and started working with a real template. Installed AstroWind and spent the week trying to understand how it’s all put together.

Installation

Cloned the repo, ran npm install, and suddenly had a complete professional website running locally. Way more complex than anything I’ve built so far.

First impression: “how the hell does all this work?”

Directory structure

AstroWind organizes things differently than my simple portfolio:

src/
├── assets/       (optimized images, processed by Astro)
├── components/   
│   ├── ui/       (buttons, forms, basic stuff)
│   └── widgets/  (header, hero, features - bigger sections)
├── content/      (blog posts and data)
├── layouts/      (page wrappers)
├── pages/        (actual routes)
└── utils/        (helper functions)

The split between ui/ and widgets/ makes sense now - ui components are tiny reusable pieces, widgets are complete sections that use those ui components.

Component hierarchy

Figured out there’s a clear hierarchy:

  1. UI components - buttons, forms (most basic)
  2. Widgets - hero sections, headers, features (composed from UI components)
  3. Layouts - wrap entire pages
  4. Pages - combine layouts and widgets into routes

A typical page flow:

index.astro (page)
├── PageLayout (wraps everything)
│   ├── Header widget
│   ├── Page content (Hero, Features, etc.)
│   └── Footer widget

Way more organized than my “components” folder where I just threw everything.

Documentation

Made two things this week:

Visual map in Excalidraw - boxes and arrows showing how components connect. Helped me see the big picture instead of getting lost in individual files.

Written documentation - went through every directory and major component, wrote down what they do and how they’re used. Documented props for key components.

This took longer than expected but now I can actually navigate the codebase without constantly getting lost.

Patterns I noticed

  • Everything uses Tailwind CSS classes instead of scoped styles
  • Props are heavily used - components are super configurable
  • Lots of abstraction - even simple things go through multiple layers
  • Content is separated from code (in /content folder)
  • Way more files than my project but each file does less

What didn’t work

  • Initially overwhelmed by the number of files (like 50+ components)
  • Kept opening the wrong files looking for things
  • Took me a while to understand the ui vs widgets distinction
  • Got confused between /public/assets and /src/assets - still not 100% clear on when to use which
  • My Excalidraw diagram was a mess at first, had to redo it more organized

Comparison to my work

My Week 1-4 portfolio:

  • ~10 components, flat structure
  • Everything in one components folder
  • Simple, but doesn’t scale

AstroWind:

  • 50+ components, organized hierarchy
  • Clear separation of concerns
  • More complex but way more maintainable

I can see why professional templates are structured this way now.

What’s next

Week 6 apparently dives into specific components and modifying them. At least now I know where to find things.

Time invested: about 12 hours (documentation took forever)