My Journey with Astro: Learning, Failing, and Building My Portfolio

Why I Chose Astro

One thing is developing a website; another is doing it using a framework I had never heard of before. That adventure was just ready to start. Astro drew my attention because of its quickness and promise for improved developer experience. Shipping less JavaScript while allowing React components seems to be the ideal mix for my requirements.

Like any new technology, though, the path was not always clear-cut.

The First Hurdles: Errors and Debugging

Setting up my Astro project was fairly straightforward:

1. Cloning the repository: I started by following a standard setup, cloning my project and running bun install (yes, I decided to experiment with Bun instead of npm initially).
2. Environment Variables: Copying .env.template to .env and setting up the necessary keys.
3. Running Development Mode: bun dev, though I later had to switch to npm run dev for better compatibility.【23†source】

That’s when the first set of errors appeared.

One of the early challenges was dealing with Astro’s integrations. I had added @astrojs/react, @astrojs/netlify, and @astrojs/db, but didn’t fully understand their configurations.【21†source】 Debugging missing dependencies in astro.config.mjs was a fun challenge (read: frustrating) until I realized I needed to explicitly configure my aliases for authentication.

Understanding Astro’s Hybrid Approach

Coming from a React-heavy background, adapting to Astro’s partial hydration approach was a shift in mindset. I was used to thinking in terms of full React components, but with Astro, I had to be more strategic.

For example, my index.astro page contains a product listing with client-side pagination【26†source】:

<ProductList products={products} client:idle />

This client:idle directive ensures that the component only hydrates when needed. It was a small change but a crucial one for optimizing performance.

Authentication Troubles

Astro’s flexibility is great, but authentication was another puzzle. I used auth-astro for authentication, but setting up the login page required more than just a simple component. I had to integrate authentication logic with actions from astro:actions and ensure my form submissions worked as expected.【27†source】

My biggest mistake? Not checking browser console errors. Debugging authentication felt like a black box until I finally started logging everything.

const { signIn } = await import('auth-astro/client');

form.addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(form);

  const resp = await signIn('credentials', {
    email: formData.get('email'),
    password: formData.get('password'),
  });

  console.log({ resp });
});

Adding simple console.log statements changed everything!

Styling and Tailwind Integration

I love Tailwind, but configuring it with Astro was another adventure. While Tailwind is supported via Vite, my tailwind.config.js required explicit paths to scan for styles【24†source】:

export default {
  content: ['./src/**/*.{astro,html,js,jsx,ts,tsx,vue}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

After some tweaking, my styles started appearing correctly. Lesson learned: always check if Tailwind is purging the right files and check the documentation you will always find the answer there.

Lessons from the Journey

1. Break down errors methodically: Google the error, check Astro’s documentation, and log everything.
2. Astro’s partial hydration is powerful but requires a new way of thinking.
3. Authentication is always tricky—logging every step helps.
4. Configuration files matter: Double-check paths, aliases, and dependencies.
5. Read the documentation: The answer is always closer than you think.

Image by Jordi, Made with AI

What’s Next?

This website you’re reading is the result of my learning journey with Astro. I’ll keep updating it as I refine my skills, and who knows? Maybe I’ll add some fancy animations next.

If you’re on a similar journey, my advice is: embrace the errors, debug with patience, and keep building!