Insights from building my portfolio with Astro

For years, whenever I needed to share my work, I relied on my Linktree link. It was fine when I had just a few pieces to showcase. However, as my portfolio grew, managing the increasing number of links became more cumbersome and less user-friendly.

Some organizations I wrote for provided an author profile, which made sharing my work easy. However, others didn’t, which meant I had to add each article to Linktree manually—I even started wondering if Linktree had a link limit!

It became clear that I needed to fine-tune my approach. But that raised several questions, like:

1. How should I handle content from the different publisher sites like Hygraph or Cloudinary?
2. Should I build or use WordPress?
3. If the response to question 2 is “build,” what tools should I use to build, host, and maintain my portfolio?

Solving question one

To address the first question, I decided to build my own “Linktree Pro Max.” The idea is simple: from my portfolio, I link directly to the platforms where each piece is hosted. Easy peasy, lemon squeezy!

At the surface level, question one is solved. However, exploring the solution deeper raised another question: What about my personal articles? (like this one you’re reading) Should I publish them directly on my portfolio or…?

I went with the “or.” Why?

Before I started writing for other organizations, I had already published my work on platforms like Dev.to, Hackernoon, and Medium, each serving different purposes. Instead of over-engineering what was meant to be a simple portfolio—and to keep my audience on the external blogging platforms—I decided to continue using these existing accounts.

For example, just like this article is published on Dev.to, other personal works will be posted on the relevant platforms and linked from my portfolio.

Yes, that’s a lot of links to manage. Still, it solves my problem with Linktree while also giving my portfolio the personal touch I want. Did I say I am building Linktree Pro Max?

Maybe I’ll wake up tomorrow with a different idea, but as of September 2024, this is where I am at!

Solving question two

This was the easiest to answer. I chose to build—no long stories.

Solving question three

Now, onto question 3: What tool should I use to build my portfolio? As a Software Engineer turned Technical Writer, I must admit that my hands still itch to build things. Plus, I’m always learning something new, and I always want to flex the latest tech I’ve been playing around with.

Sure, I could have gone the easy route with WordPress. But why use WordPress when I can build it myself? Right, right! But then, what tool/tech do I use?

• My all-time favorite, Vue/Nuxt?
• Next.js to stay with the “cool kids”?
• Plain HTML and CSS (going full vanilla)?
• Or one of the latest kids on the block—Astro?

My portfolio’s use case was so simple that I could have easily used HTML, CSS, and JavaScript. But how would I then tell you about Astro, an underrated yet incredible JavaScript framework? I even recently wrote an article for Hygraph about Astro and its versatility as an all-in-one framework.

So, you’ve probably guessed it by now: I went with Astro.

If you haven’t tried Astro yet, you probably think, “Get this lady out of my face.” But if you have, you’ll understand why I chose it. Either way, let me tell you why.

Why I chose to build with Astro

Extensibility with other JavaScript libraries
Astro allows you to integrate any JavaScript library or framework seamlessly into your project. Unlike other tools like Next.js or Nuxt, which limit you to their specific ecosystems, Astro provides flexibility. If, later in the future, I decide to use React, Vue, or any other library, I can progressively add it to my site with little to no hassle.

I can even concurrently use different libraries in different app parts as needed—there are no restrictions.

Optimized for content-driven sites
My portfolio consists mostly of text and links, with minimal JavaScript. Astro's approach to rendering pages—where you can opt in or out of JavaScript—was perfect for my needs. I didn’t need a bunch of unnecessary libraries or frameworks to display links and text.

Sure, I could have used Jekyll or a similar tool, but Astro goes further by defaulting to lightweight HTML and stripping out unnecessary JavaScript, making it an ideal choice for a site like mine.

Easy content management with markdown
While I publish my personal articles on platforms like Dev.to, Hackernoon, and Medium, adding an in-app publishing feature directly to my site is just as easy with Astro. I can write content in Markdown (.md) or MDX (Markdown with JSX support) with no complex setups or dependencies.

Furthermore, integrating with other content management systems like Hygraph, Sanity, and Storyblok is also easy.

It makes one wonder that given that such a significant portion of the web is based on text and links, perhaps more companies should consider using content-centric tools like Astro or Jekyll.

If you’re curious about Astro, I recommend checking out the official documentation and reading my Hygraph blog post.

Now, let’s move on to the main crux of this article: the gotchas I encountered and the things I liked while using Astro.

Astro highlights: favorite features and gotcha

I will begin this section by using a line from the Astro documentation.

"If you know HTML, you already know enough to write your first Astro component."

Except, this is incorrect. Here is how I think it ought to have been written:

"If you know HTML, then you know enough to write Astro - not just its component."

With good HTML knowledge, you can create magic with Astro.

Capitalization matters

This was one of the first problems I encountered - what I expected wasn’t getting displayed on the UI. On further investigation, I found out that I used this import statement in my frontmatter:

import Layout from '../layouts/default.astro'

Then, later in my file, I used the Layout like so:

<layout>
  <h1>Welcome to my portfolio</h1>
</layout>

You might wonder if changing the import statement to use a lowercase layout would solve the issue:

import layout from '../layouts/default.astro';

Unfortunately, this still won’t work.

In Astro, all components—whether built-in or custom—must be capitalized. When a component is declared in lowercase, Astro interprets it as a regular HTML tag instead of a component. So, in my example, using <layout> instead of <Layout> caused Astro to render it as an HTML element (<layout>) rather than processing it as a component.

Switching the <layout> to use uppercase fixed the problem. This may seem like an obvious error, but it got me nonetheless.

Using slot in Astro

I would argue that Astro was designed to enhance developer experience. It wasn't created to replace any libraries you may already be using; rather, it allows you to leverage your existing libraries and knowledge and apply them effectively. As a result, many concepts in Astro may feel familiar if you have experience with other libraries or tools.

One such concept is the <slot />, which you might recognize from HTML5 or Vue. Slots serve as placeholders for content that can be injected dynamically, functioning similarly in both frameworks.

However, a unique aspect of Astro is that you must use a slot to display content within a layout component. This can be especially useful if you want to define a consistent structure or style but still allow flexible, context-specific content for each page.

As I said, most of what you need for Astro is good HTML knowledge.

Scoped CSS

Vue, is that you (again)?! Within a specific .astro file, you can declare scoped CSS by adding a <style> tag at the end of your file. This means that the styles defined in that Astro file will only apply to that specific file, keeping your styles contained and organized.

If you later decide these styles should be accessible globally, you can add the is:global attribute to the <style> tag, allowing other .astro files to use these styles. This approach is quite similar to Vue’s scoped CSS feature, making it intuitive if you come from a Vue background.

NB: Astro styles are scoped by default.

Classes are just class

Astro, for the most part, doesn’t require learning new syntax to get started. You can dive right in, using familiar HTML and CSS conventions as you build.

For example, when declaring inline styles, you use class just as you would in standard HTML, instead of className as you would in React. This makes applying styles straightforward. Here’s an example:

<h1 class="title">Welcome to My Astro Site</h1>

And just like that, your styles are applied.

No key needed when using map

If you’ve worked with React or Vue, you know how important it is to add a unique key when using the map() function. In those frameworks, the key helps React and Vue identify each item uniquely, allowing efficient updates, additions, and removals without re-rendering the entire list. Without keys, you may encounter issues with component state and rendering.

In Astro, however, there’s no need to add a key. Astro renders content at build time to static HTML, so there’s no dynamic reactivity on the client side, meaning the structure doesn’t change after the page loads. This makes the key attribute unnecessary in Astro.

In React, you would typically use a key like this:

const items = ['JavaScript', 'Java', 'Elixir'];
  return (
    <ul>
      {items.map((item, index) => (
        <li key={index}>{item}</li>
      ))}
    </ul>
  );

In contrast, mapping in Astro looks like this:

---
const items = ['JavaScript', 'Java', 'Elixir'];
---
<ul>
  {items.map((item) => (
    <li>{item}</li>
  ))}
</ul>

As you can see, in Astro, you don’t need to worry about the key attribute—just declare your map, and it will work.

I could go on and on talking about the intriguing things about using Astro, but I’ll wrap it up here, hoping that what I’ve shared has sparked your interest in exploring Astro if you haven’t already.

At the time of writing, I’ve built two fully functioning, content-based websites with Astro in less than two months—and I’m very pleased with the results!

Have you used Astro recently? I'd love to hear about your experience!
If you haven’t tried it yet, I’d be excited to hear your thoughts once you do.