Forem: Darko Bozhinovski

The Joy of Astro

Darko Bozhinovski — Tue, 15 Oct 2024 14:56:34 +0000

Told from the perspective of a person building demo integrations for SuperTokens - and how it's an absolute joy to create with.

My love for Astro and the web platform is well documented. I've contributed to the docs, I've built some integrations and themes. I recently rediscovered the joy of building with Astro when I made a demo integration with SuperTokens. The ultimate goal for it was to become a part of the create-supertokens-app CLI (published here).

We'll start with a brief introduction to Astro and the parts relevant to this story and then move on to the integration (including the not-so-nice parts).

So, let's have a look at what makes Astro an absolute joy to build web stuff with!

It's just the web platform - with a nicer API

Astro doesn't reinvent wheels. It gives you a nice and consistent API (or a set of APIs, if you want it pedantic) to work with. You can import anything from plain HTML (via .astro components) to CSS, components, and scripts... if you can imagine it, Astro can probably import it.

Everything is static HTML unless you tell it otherwise (more on that later). You get to work with the basic building blocks of the web - HTML, CSS, and JS. But here's the catch - you can make it as complex or as simple as you desire (or your project requires). Want to write TypeScript? It's a CLI command away. Need a modern UI library or framework (don't get me started) for writing components? Take your pick; you can use whatever you like. Yes, Astro supports almost all of them, which is important for integrating SuperTokens.

Let's have a look at an Astro component:


---
// This is the frontmatter section where you can define component props and import other components or modules. This is server-side rendered.
const { name } = Astro.props;
---

<!-- style tag are scoped to the component, unless you tell them otherwise -->
<style>
  .greeting {
    font-family: Arial, sans-serif;
    color: #333;
    background-color: #f0f0f0;
    padding: 20px;
    border-radius: 5px;
    text-align: center;
  }
</style>

<div class="greeting">
  <h1>Hello, {name}!</h1>
  <p>Welcome to your first Astro component.</p>
</div>

<script>
  // This is an optional script section where you can add interactivity to your component.
  document.querySelector('.greeting').addEventListener('click', () => {
    alert('You clicked the greeting!');
  });
</script>

Remember that static-unless-told-otherwise bit from above? The frontmatter section above illustrates that well - basically, whatever is between those dashes gets executed on the server. You can use the variables defined there inside the HTML. <script> tags are sort of the exception here - any client-side code there still runs on the client.

Of course, if you prefer writing CSS in separate files, you can easily use a style tag to import the stylesheet or even use an import statement in the frontmatter to access those styles inside the component.

So, in a sense, Astro is just a nicer layer over the standard web platform APIs. But it's also much, much more. If you want it to be.

Components. Yes, all of them.

Whether you're a fan of React, Vue, Svelte, Solid - Astro's got you. A quick npx astro add my-framework-of-choice is all you need. Let's take React as an example.

First, you need to add it to an existing Astro project:

npx astro add react

Once you've done this, you can create React components in your Astro project and use them via the import statement wherever you like (yes, even inside .astro components).

To slightly tweak our example above - let's first move the greeting markup to a React component:

// src/components/Greeting.tsx
import React from "react";

export const Greeting = ({ name }: { name: string }) => {
  return (
    <div
      className="greeting"
      onClick={() => alert("You clicked the greeting!")}
    >
      <h1>Hello, {name}!</h1>
      <p>Welcome to your first Astro component using React.</p>
    </div>
  );
};

With the change above, our .astro component ends up looking something like this:

---
// Import the React component
import { Greeting } from '../components/Greeting';

// Define the props for the Astro component
const { name } = Astro.props;
---

<style>
  .greeting {
    font-family: Arial, sans-serif;
    color: #333;
    background-color: #f0f0f0;
    padding: 20px;
    border-radius: 5px;
    text-align: center;
  }
</style>

<!-- Use the React component inside the Astro component -->
<Greeting name={name} />

But here's our first surprise: once we click on the greeting div, we no longer see the alert. This is a feature. As you might remember from above, everything in Astro is static unless we tell it otherwise. That means Astro renders the component on the server and doesn't hydrate any JavaScript along with the component.

That can be useful, but we still want the alert, right? Astro has a concept called directives for this and an architectural paradigm called islands (too long to get into here, here's a source for a deeper dive). In practice, if we want the component to produce an alert when we click it, we need to add a client:load (or similar depending on your use case) directive to the React component:

---
// Import the React component
import { Greeting } from '../components/Greeting';

// Define the props for the Astro component
const { name } = Astro.props;
---

<style>
  .greeting {
    font-family: Arial, sans-serif;
    color: #333;
    background-color: #f0f0f0;
    padding: 20px;
    border-radius: 5px;
    text-align: center;
  }
</style>

<!-- Use the React component inside the Astro component, interactive -->
<Greeting name={name} client:load />

SSG and SSR

By default, an Astro project compiles to a static site. However, to integrate an auth solution like SuperTokens, we need a server. Luckily, Astro comes with an SSR mode, which allows us to do server-side processing, too.

With the SSR mode in place, we have all the Astro-specific pieces we need to integrate SuperTokens with Astro.

Integrating SuperTokens' prebuilt UI in Astro

Generally speaking, SuperTokens has two ways of integrating: using the pre-built UI or going the custom route (i.e., using functions and your own UI). The pre-built UI further forks down to two options: the React SDK and the universal pre-built UI. The universal pre-built UI is based on the React one, but it's compiled down to a standalone JS library that can be imported into just about anything.

Whenever I write an integration for the create-supertokens-app CLI, I usually pick the universal pre-built UI when working with a non-react frameworks. But remember the bit about Astro working with all components out there? Yep, that means we can use SuperTokens' regular React SDK to make it work with Astro.

The necessary pieces for a React SDK integration are:

A route to render the auth screen/components
A (server) route to handle the calls to the SuperTokens auth core
A home component to show some session info once we're logged in

Let's have a look at how easy it is to fit that in with Astro.

The good

Astro can be a React framework. And on top of that, Astro can do SSR and API routes without making your head spin. Given the list of requirements above, I just went ahead and copied some files from an existing Remix integration:

superTokensHelpers.ts - a list of utility functions that help with common tasks. I usually copy and paste this file in most integrations I do, React or otherwise.
Root.tsx - a wrapper component, which helps with all things auth on the frontend (specifically, for React components).
Home.tsx and Auth.tsx - the formed renders the Home screen (authenticated state) and gives you some session info if you're authenticated. The latter renders the authentication screen.
tryRefreshClientComponent.ts- granted, it's named a bit unconventionally, but it plays a key role in the whole setup - it tries to refresh an existing auth session.

All of these, together with the config worked quite literally out of the box (and I copy-pasted most of it).

The server was a bit of a different story, however 😅

The not-so-good

Now, it wasn't bad per se. It's just that multi-level catch-all routes don't seem to be a thing in Astro (yet). For example, I couldn't find a way to properly define a * route in non-file-based routing in Astro.

Initially, I tried using middleware, but that went nowhere. It led to weird responses, where the middleware caught the route being triggered every time, but that didn't reflect in the response. Getting a valid response and token from the auth core and returning a 404 to the client isn't what I'd call working here.

Luckily, there is a hacky but easy fix for this - define the multi-level catch-all routes the long way. A picture is a thousand words, so this will certainly explain it better:

In Astro, the pages directory is where pages (routes) live. Due to how I had SuperTokens configured, it expected to have full ownerships of the /auth/** route for frontend and /api/auth/** for backend calls. However, it also expects to be able to find a route at any of those levels.

Ultimately, it worked fine, but it took some hacking to make it work. Caveat - I may have misunderstood something, so feel free to ping me on Twitter with what I did wrong. Also, PRs open if that's more your jam 😉

A possible alternative

Doing SSR with Astro requires something called an adapter. The default is node. Now, in theory, you could just add those routes to the node context. Or, as a quick Google search showed me, you can simply change the adapter to fastify to get more routing flexibility. I'll likely try that next!

Takeaways

Astro can be whatever you want it to be - even a react framework. In a talk, I once called it a meta-metaframework - in a sense, you can build a framework of your own inside Astro. And you can pick products like SuperTokens off the shelf and integrate them easily.

So, I'll leave you with this: Use the standards and the platform where they make sense; don't fight them. Webdev can be simpler than we're used to.

A Better Hammer?

Darko Bozhinovski — Wed, 02 Oct 2024 12:30:58 +0000

It hasn't replaced us. Not yet. But I'm finding ways to make my work easier and faster. Yes, I'm talking about AI.

We can probably agree that the “untimely death” of the software development profession has, in fact, been grossly exaggerated—no wonder - the hype cycle's gonna hype cycle. I still write software, by every definition of the concept imaginable. I'm using an editor, CLI, and searching through docs. But what changed is that I'm now using another tool to help me out. AI—often a glorified intellisense, sometimes a contextual snippet machine, and infrequently a decent debugger.

Things have improved since we first considered integrating an LLM into an IDE (or text editor), but, is it good enough to fully replace a developer? Not by a long shot. This approach has many nuances and caveats, so let's dig in.

...And along came the influencers

Instead of writing on how influencers made it worse, I can leave this pic and call it a day:

Sarcasm aside, if I see one more post on how AI will replace me tomorrow, I swear... Here's what's NOT going to happen:

You won't just be replaced with AI (no matter what the hottest new AI startup claims)
AI won't fully write code instead of you (yep, that includes agents. Fight me.)

To be honest, I looked forward to AI being able to migrate a Next 11 app over to 14 by itself. I'm talking about an app with a couple tens of thousands of lines of (not particularly pretty) code. To date, it hasn't happened, and I don't think it will happen for a while.

That begs the question, - is it going to? Or better yet, will it replace us as software developers in our lifetimes?

The grossly exaggerated death of the software development profession

I think statements that include "replacing" developers or "killing the entire profession" are just sensational headlines. I don't think software development, as a craft, trade, or whatever you want to call it, is going anywhere, but it will change.

Before elaborating further, let me ask you a few questions - has the invention of CAD software replaced engineers and architects? Not really, but it did make them more efficient. Has the invention of tractors replaced farmers? You can tell where I'm going with this. My thesis is - AI will make us more efficient, but much like tractors haven't replaced farmers, AI, as we currently know it will not replace developers. Barring an AGI breakthrough, I don't think anyone's getting replaced with anything. Quite frankly, LLMs feel like they have peaked (I might have to eat those words, but we'll see), given the decreasing hype in the last few months.

However, it will change the way we work—in fact, I'd say it already has.

A new way of interacting with code

Up until a few weeks ago, I was a content user of VSCode. I like that it's FOSS and has a huge ecosystem, and I was okay with paying for Copilot. Additionally, it works on Linux, so I can't complain. That setup was already good—at the very least, it had a better autocomplete than what we previously had. Better autocomplete = more time saved, which in turn means more time available for other pursuits.

It all changed when I decided to sit in on an engineering weekly we had at SuperTokens one day. I'm not a part of the team, but I have to be up to date with what they do, so I listen in on their weeklies when I can. The exciting thing discussed there was https://cursor.sh. Rishabh, our CTO, was going on about how good it was making things more productive, so I thought, fine, I'll bite. It wasn't the first time I was told Cursor was really good. I have a friend who's been going on about Cursor for months (hi Vlad), and I was kinda skeptical. So, Vlad, you were right. Cursor is… well, pretty impressive.

From the get-go, it was obvious that it's different from how VSCode works with AI. While both aim to enhance productivity, Cursor takes several steps further in its AI features:

Multi-line Auto-completions:
Unlike VSCode's Copilot, which typically offers single-line suggestions, Cursor provides more extensive multi-line auto-completions. This feature can significantly speed up coding by suggesting larger blocks of relevant code.
Contextual Awareness:
Cursor's AI seems to have a deeper understanding of the project context. It considers not just the current file, but also related files and project structure, leading to what feels like more accurate and relevant suggestions.
Enhanced Chat Functionality:
The chat feature in Cursor feels more robust compared to Copilot in VSCode. It can handle more complex queries, provide explanations, and even assist with debugging.
Composer Mode:While I haven't had much luck with it, Cursor's Composer mode is a unique feature not present in VSCode. It aims to assist with project-wide tasks such as:
- Generating entire files or file structures
- Performing large-scale refactoring
- Creating boilerplate code for new projects

What I had luck with, however, was having Cursors generate a front-end app for an invoice generation CLI I had. The CLI itself is a fairly simple idea:

You feed it JSON.
You run a script.
It outputs nicely formatted PDFs to be used as invoices (source here).

To test it's merit, I did two experiments:

Interactive CLI—Basically, I asked Cursor to make me an interactive CLI from the really simple one in which I wrote JSON files by hand. It managed to do it pretty smoothly, with a single intervention from my part—styles, which, for some reason, it omitted. Otherwise, my utility suddenly became one that you can run in the CLI, input your data, and get a PDF on the other end. It is certainly an improvement over the initial manual JSON version.
Web App - after that, I asked Cursor to make me a web app based on the CLI. It started off by generating a non-denominational React app, but I had something different in mind - I asked it to make it using Astro and SolidJS instead. While the end result wasn't turnkey, it was really close to being usable. I may have gotten lucky, but I'll repeat the experiment several times to determine whether the experience is consistent. Either way, it was pretty impressive - and stay tuned, that invoicing app is going FOSS very soon 😉

But Cursor itself aside, these interactions made me realize something else—I'm still creating software. With some more advanced tooling, generated code, and, overall, a better hammer at my disposal—or perhaps a multi-tool of some kind?

Is AI a better hammer? Or a new tool entirely?

In its current state? absolutely. The more I think about it, the more I realize that "hammer" might be a misnomer. It's more of a multi-tool, a Swiss army knife of sorts. It helps you with:

Better auto-completions
Contextual hints
Scaffolding things better
Debugging stuff
Being a sounding board for your ideas
...

So, yes, it's a smart tool that helps with multiple modalities of your work. More importantly, it affects how we interact with code. We used to write stuff by hand, now, hitting tab a few times amounts to the same result. It's more efficient, but given the amount of weird or downright wrong suggestions I've had, we're very far from the tool replacing the operator.

But here's the kicker - you still have to understand what's going on to make good use of even the smartest tool. LLMs, given they're primarily statistical machines, can make mistakes, and hallucinate... it's still up to the operator to fix that.

Can a tool fully replace the operator?

Following the examples throughout history, it certainly hasn't been the rule. Better tools reduce the amount of people needed to perform a task. Farmers, for one, still exist, and we've had huge technological advancements in agriculture since we started growing things from the ground.

Starting from that point of view, no - AI, as a tool, won't replace programmers. But, given AI's theorized potential, we can't say for sure. Time will tell 😁

Instead of a takeaway

As much as AI is a tool, code is, too. As software professionals, our primary function is solving problems via automation. If a better tool came along, it feels fairly irrational to ignore it in the name of preserving the status quo. My point is—learn the new tool and get better at your craft. I, for one, can't wait to NEVER have to write another form validation.

"BuT, aUtH iS HaRd"

Darko Bozhinovski — Thu, 08 Aug 2024 14:03:03 +0000

No, it's not. It's boring, red-tapey, a solved problem... but don't call it hard as a blanket statement.

I'm "I've used MD5 to hash passwords in PHP" years old. Sure, it was a horrible idea, even back in 2012. But, back then, I don't remember considering auth "hard." It was a pretty straightforward ordeal by itself - get an email or a username, get a password, hash it (with MD5, as "god intended"), and if you were especially security conscious, salt the password. Store all of that somewhere, usually in a database. Ta-da, signup done.

Nowadays, the narrative has changed. "Auth is hard" feels like an ever-present narrative that lies a HackerNews or Reddit click away. But is it really? IMO, The truth is, auth isn’t hard to build - anyone can learn it (and everyone in this line of work should learn the basics). The real challenge lies in the extras: MFA, user management, password resets, each of the hundreds of OAuth providers, and account merges from different providers. It’s death by a thousand cuts. Since auth is a solved problem, reinventing the wheel isn’t the best use of your time. But that doesn't mean "auth is hard" as a blanket statement is correct or even close to correct. You should experiment, understand the basics, and build from there. The complexity only grows with the scale (or potential scale) of what you're creating.

So, how hard can auth really be? Let's dig in.

In the days of yore...

Picking up where I left the story about PHP and md5, building a login functionality followed a similar set of steps; Get an email and a password, check for the existence of the email in your storage, hash the password together with the salt stored for that email, compare the resulting hash with the one stored in the database, and if it all works out fine, set a cookie via setcookie (we're still in PHP land here - not that the overall logic was too different in other ecosystems).

Signing out was even simpler - just invalidate the cookie on the server, and you're done. If the server doesn't see a cookie with the next request, you're not logged in. So doing authenticated routes was also a simple ordeal overall. Things could get hairy when it came to permissions, but more often than not, with the apps I had to build, we had just admins and users. Which was something you could simply store together with the user record or in a permissions table if you ever needed to expand the amount of roles you had for your app.

Full disclosure—I work for SuperTokens. This piece, however, is borne out of personal frustration over an omnipresent narrative about how hard auth is as a blanket statement. In other words, I'm not trying to "sell you my thing." Use whatever you like.

Roll your own - a "modern" take

Email/password and Social auth

To get to where we are today, we'll start at the beginning... Surprising, I know. We can probably agree that these components are enough to make an email/password + social login PoC:

A server that handles routes - signup, sign-in, sign-out...
Some kind of storage to keep the user records (an in-memory array works, too)
Views - login, signup, and authenticated "dashboard" screens.
Handlers for social auth

Going with Express and Passport, since we're not going to reinventing wheels, we arrive at exactly 150 lines of very, very dull and repetitive code: https://github.com/supertokens/auth-express/blob/master/index.mjs. The next section will be surface-level explainer of what's going on in the code, so feel free to skip ahead if you're already familiar with the concepts. The express app is a PoC anyway.

Let's quickly dissect it:

Rendering stuff on screen

The way I see it, there are two ways to approach this - start with the rendering and move on to the auth route or the other way around. Mostly by chance, I ended up being an FE-heavy pleb (I can still do SQL, in case you were wondering), so I'll start with the "rendering stuff on-screen" approach.

Since this is a PoC, we're not gonna go all React-fancy. Plain ol' SSR with ejs will do just fine: https://github.com/supertokens/auth-express/tree/master/views

Adding routes

Based on some passport.js examples, but simplified further, we need the following:

Some deps: npm i passport passport-local express-session. Let's briefly go over each:
1. Passport.js - the OG auth middleware for express and node.
2. passport-local- an authentication strategy for Passport; An authentication strategy in a module that handles the auth process for a specific auth method - in this case, a local login using a username (email) and password.
3. express-session - a middleware that manages session data, allowing you to store and persist user sessions between HTTP requests. It works by assigning a unique session ID to each client, which is stored in a cookie on the client side and used to retrieve session data on the server.
A place to store our users (the example linked above uses an in-memory array): https://github.com/supertokens/auth-express/blob/master/index.mjs#L13
Configuration for our passport instance and our LocalStrategy instance to handle incoming requests for user lookup: https://github.com/supertokens/auth-express/blob/master/index.mjs#L18
Initialize passport (https://github.com/supertokens/auth-express/blob/master/index.mjs#L60) and express-session (https://github.com/supertokens/auth-express/blob/master/index.mjs#L69).

Verbose, sure. Hard? I don't think so, at least not in the implement-it-as-a-toy sense.
But we moved past using email/password combos a while ago. Let's inspect how hard it is to add a social provider on top of what we have.

For an example provider here, I decided to go with GitHub for a simple reason—if you decide to fully follow along, it's one of the easiest providers to get started with (looking at you, Google).

If you do decide to follow along fully, here's a link describing how to get those GitHub keys: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app
Oh, and BTW, the ones in the repo aren't valid, in case you were worried ;)

Integrating GitHub OAuth2 in our PoC

First off, we need one more dependency, npm i passport-github2. passport-github2 is an auth strategy for Passport, allowing us to integrate with GitHub's OAuth2 API.

Some handlers (https://github.com/supertokens/auth-express/blob/master/index.mjs#L122-L133) and configuration (https://github.com/supertokens/auth-express/blob/master/index.mjs#L29-L45) later, well, that's it. Complicated? Probably not. Red-tapey? You bet. Boring? Absolutely. Especially if you get to do it over and over again. It is a solved problem; reinventing wheels is often not the best use of one's time as we've established.

The big idea

By now, we can probably agree that Auth isn't hard to build. Ergo, it's not this magical thing that only white-bearded wizards who speak the mystical language of JWTs can understand and implement.

No, in fact, I'd argue that as a developer, one should understand the bare basics of how auth works. And I often see a narrative that claims otherwise - something to the tune of "trust me, bro, we can handle that for you". And sure, I agree that for the most part, rolling your own auth is a waste of time. But it's not that hard to build, and it's certainly not a mystical thing. Where it truly becomes hairy is with everything surrounding auth and the user experience.

Consider this - in the example above, we have a working auth thing. Sort-of. But here's what it can't do (also mentioned in the article opener):

2FA, MFA
Password resets
Each and every of the hundreds of OAuth providers with their specificity
User management
Account merges from different providers
Cover all the possible edge cases and potential security holes
...and I can go on

We can probably implement each of these. And on its own, each piece may be considered simple. But it adds up. So, it's not necessarily the implementation—it's maintaining it, being responsible for it, staying up to date with the standards, security breaches, and so on. Plus, a show of hands—how many of you like reading RfCs? I don't imagine I'd see many raised hands if we were on a meetup.

My point is that auth isn't easy, taken as a whole. Sure, we can easily cobble something together for a PoC, as we did above. But it's not magical, it's not impossible to understand, and please, please don't say that it is. That line of thinking (and marketing), IMO, is damaging to the industry as a whole.

So, the natural follow-up question would be - when should you roll your own?

Toy project, indie, and educational pursuits

...by all means. I'd even encourage it. You learn a lot by doing, so why not? If your indie/toy project or blog grows to have a considerable user base or following, switch it out to a service, a self-hosted solution, or something else. After all, you have a product at that point, and your time will undoubtedly be better spent building that product instead of maintaining auth.

Startups

Generally, if you're building products, don't roll your own auth. It's reinventing a very boring and red-tapey wheel. You have plenty of options to choose from. Plus, you are building something, right? Why are we even having this conversation if your product isn't auth?

Scaleups and above (however we choose to define them)

Don't. Same reason as startups - but it certainly applies more here.

You can probably see where I'm going with this. "Auth is hard" is, I'd say, a marketing pitch when used as a blanket statement. You can understand auth, you can build it, but it's boring, it's not fun to maintain, and it's a problem that's solved. Thus, it can be considered a commodity—one that you can pick off the shelf in whichever flavor you choose (some options below).

The self-hosted and FOSS landscape

For the ones that are into owning their stack (as yours truly is), you have plenty of options to choose from, too:

Auth libs

Passport.js, covered above in detail
Lucia - A simple and flexible authentication library for modern web applications, focusing on developer experience and ease of use.
Auth.js - A lightweight and customizable authentication library for Node.js, designed to be easily integrated into various frameworks and applications. Started off as a library for Next.

Auth servers

Keycloak - An open-source identity and access management server offering features like single sign-on (SSO), identity brokering, and user federation.
SuperTokens (see disclaimer above) - An open-source authentication solution providing pre-built features like session management, social login, and email/password authentication with a focus on security and simplicity.
FusionAuth - A flexible authentication platform catering to developers, offering features like user management, multifactor authentication (MFA), and single sign-on (SSO).
Authelia - An open-source authentication server providing multifactor authentication (MFA) and SSO, designed to secure applications using reverse proxies.

Storage + Auth

Supabase - An open-source backend-as-a-service (BaaS) platform providing database, authentication, and real-time capabilities, designed as a Firebase alternative.
Pocketbase - An open-source backend solution combining database, authentication, and file storage, aimed at simplifying the development of modern web and mobile applications.

So, even if you're not into using third-party software for Auth, you can just pick an open-source one off the shelf, depending on your needs and preferences and roll with that.

The takeaway: auth is the "red tape" of dev

My "big" takeaway is to avoid reinventing wheels, especially if it's a solved problem, as auth is. Get educated about said wheels, experiment with them, build a toy wheel, and understand it. But please, please, don't sell it as this impossibly hard thing to understand and build. Educate, don't gatekeep.