DEV Community: Obinna Ekwuno

TIL: How to make a Synced Sandbox from a GitHub repository

Obinna Ekwuno — Thu, 23 Feb 2023 15:06:28 +0000

"Some features work like magic. Some features are just Magic!" - Some human.

Today I learned about a really helpful feature on CodeSandbox that automatically allows you to create Sandboxes that stay synced with changes you make to your GitHub repositories.

TIL means Today I learned. 😉

Synced sandboxes

From my understanding, Synced sandboxes are sandboxes that stay up to date with the latest changes you have pushed to a GitHub project using your .git file.

Their main advantage is that they allow you to create sandboxes from specific sub-folders within your GitHub projects without importing the whole repo.

Make a Synced Sandbox in CodeSandbox

First, open your project on GitHub and then edit the URL to start with codesandbox.io/p/sandbox/ prefix before the github.com the remove .com from github.com.

For example, let's use the demo project from my last blog post on Content collection in Astro.

The GitHub URL: https://github.com/Ekwuno/content-collecttion-api-example will become
https://codesandbox.io/p/sandbox/github/Ekwuno/content-collecttion-api-example

Why does this need to exist?

When changes are made to your GitHub projects or your example subfolders, you have to do the stressful task of updating all other replicas across platforms, but with synced sandboxes, they all stay up to date because they are "synced" to the source.

Once you push a change to GitHub, your sandbox also has those changes.

Use case for Open source projects.

Another use case I see is for Open-source projects that have example folders. Most frameworks have a repo with example folders which are usually sub-folders that get harder to maintain. By making these example folders synced sandboxes, each update is added automatically, allowing maintainers or contributors to share specific folders as sandboxes so they can be viewed as individual projects.

Use case for Embedding Cloud sandbox to docs.

The final use case I see for this feature is embedding your GitHub repository in the documentation and ensuring it is always up to date. So when people come to docs, they can create sandboxes from the embeds.

I recently made one of these for a project Joe Previte made and now whenever Joe makes an update, this sandbox I made gets the changes.

// Detect dark theme var iframe = document.getElementById('tweet-1627819277267894272-435'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1627819277267894272&theme=dark" }

That's all, folks!

How to use content collection in Astro.

Obinna Ekwuno — Mon, 06 Feb 2023 16:38:50 +0000

In case you missed it, Astro launched 2.0 with a couple of exciting announcements, one of which is the new Content collection API with Type-safety powered by Zod.

In a previous post, I wrote a summary of What's new in Astro 2.0; you can check it out for more information.

This post will look at creating Content collections and how you can start building and sourcing content in your Astro application.

We will be doing so by building a simple newsletter application, exploring creating a collection, querying the collection in components and creating routes for each markdown file in the collection.

Project setup

To follow the project in the blogpost, you can fork my content collection example project on Codesandbox. Create a fork, and you are good to go.

Pull the repo from GitHub and set up if you prefer to do this locally.

The parts that are covered is the Content/, Pages/newsletter folders. The file structure looks like and t

/
├── public/
│   └── favicon.svg
├── src/
│   ├── components/
│   │   └── Card.astro
│   ├── content/
│   │   └── newsletter
│   │       ├── post-1.md
│   │       └── post-2.md
|   ├── config.ts
│   ├── layouts/
│   │   └── Layout.astro
│   └── pages/
│       ├── newsletter
│       │   ├── [slug].astro
│       └── index.astro
└── package.json

Setting up Content Collections in Astro

A content collection is a group of .mdx or .md files that are created under the src/content folder in Astro. The content files are type-safe and allow you to group your content in a schema and type-safe way. Once you have a collection, you can start querying your content using Astro’s built-in Content APIs.

Define collection schema

First, create a config.ts file in the src/content folder, which is the config file where you define the "collections" for your project. We describe the frontmatter schema in this file and use Zod to define types.

From the code block below, you can notice that we define the schema with some types. Doing so ensures that when we create new .md or .mdx files, the frontmatter is type-safe, and we get the benefits of Typescript in markdown.

import { z, defineCollection } from "astro:content";

// Define a collection of newsletter posts
const newsletterCollection = defineCollection({
// Define the schema 
    schema: z.object({
        title: z.string().max(100),
        date: z.date(),
        categories: z.array(z.string()),
        summary: z.string(),
        image: z.string().optional(), //Image can be optional
    })
});

// Export
export const collections = {
    //  collectionName: collection
    newsletter: newsletterCollection,
};

Creating Markdown content in Astro

Since we are creating content collections, the markdown files must follow a "collection" type format. So in the src/content folder, create a newsletter folder this is where we add markdown files and inside those files add the frontmatter, following the schema format that is was defined.

Under the newsletter folder create a post-1.md and then define the frontmatter with respect to the schema

---
title: "Newsletter Post 1"
date: 2019-01-01T00:00:00.000Z
categories: [Newsletter, News]
summary: "This is the first newsletter post."
---
# Newsletter Post 1

// Content

The frontmatter is type-safe, so if you add any field that isn't defined in the schema, you will get a prompt to fix the error. Thankfully Astro has very helpful error messages to prompt. Also, notice how no image is defined because, in the schema, it is marked as optional.

Importing Content collections to components

Now that you have defined the schema and have your first post up. You can pull your content data using the getCollection from astro:content.

Then pass your collection name into the getCollection function. Doing so will give you an array that you can map through and display in a component.

You might need to restart your dev server after importing so that astro:content can be accessed.

import { getCollection } from 'astro:content';
const newsletters = await getCollection('newsletter');

// ...

{ newsletters.map((newsletter) => {
    return (
        <Card
         href={`/newsletter/${newsletter.slug}`}
         title={newsletter.data.title}
         body={newsletter.data.summary}/>
        )
    })
}

Notice that the href for the newsletter cards opens up a path /newsletter/${newsletter.slug}. This is because, in Astro, all pages are created under the pages folder so, we create a newsletter folder under pages to make routes for each post.

You can make multiple routes for each collection that you have.

Generate Pages for Content collections

If you are familiar with creating dynamic routes, they are often depicted with [] and have an identifier to create the routes based on the identifier.
For example, it can be making each route based on the id:[name.id] or on the folder's name [Professions.name].

To create a new page for each of the newsletter entries under the Pages folder, create newsletters/[slug].astro; this will create a new page for each post.

Of course, you can also define custom slugs for your files, but we will stick with the generated ones.

First, get the collection; you will use the getCollection function again.

import { getCollection } from "astro:content";

Then, because we want to create paths from these collections at build time, we make a function getStaticPaths. In this function, we will pass the newsletter collection into getCollection and await the response.

This response is then mapped out to create a slug for each post at build time, the params Object shows what file is rendered, as seen below:


// This function gets called at build time and generates the paths from the content folder
export async function getStaticPaths() {
    // Define the colection you are creating pages for
    const allNewsletters = await getCollection("newsletter");

    return allNewsletters.map((newsletter) => {
        return {
            params: {slug: newsletter.slug},
    // 
            props:{newsletter},
        };
    });
}

Access props and rendering markdown for Content collections.

Now that we have defined the newsletter, we would need to access the props in this particular component, and we can do that with Astro.props to typecast this even further add a
{CollectionEntry<>} type and pass in newsletter as seen below:

---
import {CollectionEntry, getCollection } from "astro:content";
//.. 

// Access the props in this component 
const {newsletter} = Astro.props as {newsletter: CollectionEntry<"newsletter">};
const {Content} = await newsletter.render();
---

To get the actual content from the post-1.md file, call the render function pass in the Content.

We can now render the content like so:

<main>
    <h1>{newsletter.data.title}</h1>
    <p>Category: {newsletter.data.categories.join(',')}</p>
    <Content />
    <p>
    <a href="/">Back to previous newsletters</a>
</p>
</main>

Learn more

Astro's content collection API allows for so flexibility and type-safety when it comes to handling data. There is also a guide for migrating from File-based routing if you want to update your projects.

To get started with this example project, you can create a fork of my Content-collection API project on CodeSandbox. Happy coding 👋🏾

What's new in Astro 2.0?

Obinna Ekwuno — Wed, 25 Jan 2023 16:08:31 +0000

Astro 1.0 introduced developers to a way of building applications optimised to reduce excess Javascript in an application by introducing us to Astro Islands, representing a paradigm shift for frontend web architecture.

This shift allows people to build static Pages and implement "Islands" of dynamic behaviour using frameworks you were already familiar with, like React, Vue, and Preact ...

This shift brought ASTROnomical (Pun intended) improvements to the performance of your application as the Unused JavaScript got replaced with lightweight HTML, which meant faster loads and time-to-interactive (TTI).

The use case of Astro spans E-commerce and blogs. As you can imagine, the list keeps growing.

So... Astro 2.0?

Collection API

Since a lot of the content coming into websites these days are static coming from a content management system (CMS) or Markdown or MDX, Astro has added a Collection API which allows you to manage collections of extended markdown files in a Type-safe way!

If you are familiar with Typescript's data inference, you can now get that in Astro powered by zod, which is a Typescript validation library.The src/content directory allows you to group together markdown files and access them from within your application.

Learn more about the Content API in the documentation

Hybrid rendering..

When building applications you often have to make the decision between static (SSG) and server (SSR) build output.

What if... ? What if you could enable server side rendering and static site generation on a per route bases??

Well now you can with Astro 2.0!! This means Improve render performance of popular pages and performance improvements with builds.

You can now pre-render certain pages without giving up your
deployed server. Pre-rendering builds pages ahead-of-time so
that all of those requests load instantly.

Improved Error messaging

Astro 2.0 provides better error messaging, you know.. the type that is helpful and doesn't make you want to do this:

It's so much better, because it points out exactly what's wrong.

// Detect dark theme var iframe = document.getElementById('tweet-1617959618285633536-55'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1617959618285633536&theme=dark" }

Other Improvements

There have been improvements to the Hot module reload(HMR) of Astro, and it also now supports some Vite 4.0 improvements.

Astro also officially launch the new Public Roadmap for Astro. So now you can see all the things the team is up to!

You can start testing these new features today by running npm i astro@latest to upgrade an existing project. If you don't have an existing project, you can start a new project locally or on an Online development environment like Codesandbox.

Codesandbox has automatic Language syntax support for Astro and is a really seemless way to build applications without setting things up locally as it is powered by micro VMs

Check out the Astro starter running 2.0 already: https://codesandbox.io/p/sandbox/astro-j1qiqf

In a follow up blog post I'll be sharing a project using Astro 2.0!

Happy coding! 🎉

Auditing for accessibility with Evinced

Obinna Ekwuno — Wed, 03 Feb 2021 18:45:39 +0000

Again, the topic for today is accessibility. I know sometimes when you hear about this your eyes roll to the back of your head. Maybe. because the process of testing for this can be a bit too long or stressful.

Another reason might be you don't even know exactly what you are looking for. Now you have 50 tabs open looking for the answer to a "few" (37 heading to 60) accessibility warnings.

I am going, to be frank with you, auditing for accessibility defects is hard. Even harder when you don't know if the bug you are fixing exists in one place or does it span your app. -- This is another horror story.

Where does it all end?

I spent a couple of weeks testing out a new site scanner feature on a web service called Evinced. Evinced provides a way to pinpoint accessibility defects in a site by allowing the algorithm to crawl all the pages (or selected pages) on your website and scan for pages that have accessibility debts

Evinced has multiple tools for auditing accessibility, you can check them out on the products page.

The thing I love about this tool's site scanner feature is how it points out the specific problem and also redirects you to a glossary where you can learn more about the error it picked up and even examples.

Too much talk show me a demo!

I used this tool to test out some websites that I had been curious to know how they'd perform. The first site I tested was my personal site of course!

Now my personal site has an accessibility lighthouse score of 84, I set some color-contrast errors to see if Evinced would pick it up.

Most of these accessibility errors are in a subdomain of my website so Let's see how this plays out.

Step 1: Go to https://app.evinced.com/, you will be directed to apply for the free Community Service or Enterprise Free Trial for the Site Scanner, and then log in.

When that is done you'll see the modal below, then proceed to put your site URL in the property input box

Step 2: Allow the site scanner to crawl and scan your site and wait for the magic.

When the scan is over, you can see that it has gone through every part of your site (or the pages specified) and picked up all the accessibility errors, and even provides you with a break down of these errors

How does this help me fix it?

My 48 counts of violations for my website can be broken down by Evinced into components, that's really helpful because I can actually tell what's going on and where it is going on.

What this shows me is the exact problem and If I go into developer tools and checked the component I can fix it in chrome and that automatically reflects in my codebase

Conclusion and feedback.

I only tested this on my site because I created the accessibility errors and I wanted to see if the tool would pick it up.

However, a progress bar for the crawling and scanning process would be great I wasn’t sure when these processes finished because I just left the site and did something else.

At the end of the day, I am happy that more tools that aid and automate the process of accessibility exist.

Gatsby Cloud and Gatsby open source aren't mutually exclusive. Here's why I think so.

Obinna Ekwuno — Mon, 02 Nov 2020 21:54:13 +0000

Now I know, I work at Gatsby. I am supposed to say "good" things about Gatsby -- but here's the thing. Before anything, I am a developer and I care about my community.

I have spent a couple of days asking a lot of questions about how our community views the Cloud offering of Gatsby. Most of the comments seem to view it as Gatsby's "money maker",

Being open-source while also making a profit as a business seems to be a conflict in some minds. When open source starts to get involved with money, if not put in the proper context it can be seen as !Open-source (Not open-source, pardon me I couldn't help it. )

Here's what it actually is.

Gatsby Cloud, simply put, is an optimization tool for sites Gatsby built with the open-source framework. It will improve how fast your Gatsby sites are built and also offers you more optimizations as your sites grow.

It's like playing God of War on a PS4, for example. In the beginning, you have only a simple axe. But as you go further into the game you unlock pretty awesome abilities -- and you pay for them with the coins you have collected along the way. (Yes! I am currently playing God of War 😅).

Gatsby was designed for front end devs to be able to assemble websites from modular services, each one having its own best-fit data source, using plugins to make it quick to build this way. This architecture means that a site built with Gatsby is fast anywhere it runs. But for a Gatsby site to be as fast as it is architected to be there needed to be customized cloud infrastructure.

My point is Gatsby Cloud wasn't built to just "make money for Gatsby" -- although users paying for the advanced features added to it will help pay the Engineers working full time on open source Gatsby (i.e me and my team). It was built as the arena for Gatsby sites to reach their true superpowers.

Gatsby Cloud is of course a cloud platform. This infrastructure costs money! But we support open source even in our Cloud platform: we will always have a free tier for personal projects. Because we want anybody using the open-source Gatsby framework to be able to experience the ideal place to build and deploy their projects. If you're a company using a lot of Cloud builds on a product you make money from well, then, of course, we would like for you to pay for your usage.

Now, with that in mind here's what you get from using Gatsby Cloud to build your Gatsby Sites for free:

100 Real-Time Edits/month
Standard Builds
Deploy Previews
Real-time CMS Previews
Lighthouse Reports
1 editor

In my opinion, this is pretty helpful for a free plan and if you're not running a really giant site or doing constant updating this is perfect.

Now the more advanced stuff like Incremental build, Site Access Control, extended real-time edits/month for larger themes, comes with the paid plans (which start at $19/Month 🤭). This is cool! But tbh these are things that big teams working on big projects would benefit from more.

In conclusion

Gatsby Cloud at its core is built to improve the workflow of the web developer using Gatsby open source, by providing a tool to build at blazing speed and also cut build times by 90% to <10sec. Check out willit.build which is a benchmark site that helps predict the build time of your site.

I hope this helps and also I am happy to hear your opinions about Gatsby Cloud. Would you use it? Anything I can help explain?

What do you think about GraphQL? Who's using it? Love it, hate it? Tell me why?

Obinna Ekwuno — Wed, 28 Oct 2020 20:39:32 +0000

My story with learning and using GraphQL is a bittersweet one, I went from "What does this button do?" to "WOOT WOOT"

Why did you start using GraphQL? If you don't why not?

This Filesystem API made my life easier.

Obinna Ekwuno — Sat, 10 Oct 2020 20:48:54 +0000

Building with static site generators is aimed at cutting off all the "difficult" parts and getting you started with serving content while using the same best practices and methods available.

We have a lot of them (Gatsby, Hugo, Jykll), some more straightforward than others, each solving a particular use case, and to be frank, I would rather not compare them based on usage but on the Use case. At the end of the day, it all boils down to what you are trying to do.

You see, the thing about abstraction is we have to know where to stop, as sometimes the solution might create a new problem. A problem that you have to solve.

Here's my experience with a particular problem.

Programmatically creating pages in Gatsby.

Now I love Gatsby, it makes a lot of things easier and in the process, it did open the door to a lot of other exciting things for me like GraphQL, and an API file called Gatsby-node, where a lot of my early pains came from.

The way Gatsby handles programmatically creating pages(which is a fancy way of saying, creating pages on demand by sourcing from a Content Management System) is in the following steps:

Source page via Slug in Gatsby-node.
Use the createPages API to create a page for each slug.
Resolve that in a template component path.
Create that Path and then source for all the other information using the slug as a unique identifier.

Looks something like this,

Sourcing using `createPages API`

Resolving in the Template directory

Sounds like a lot yes? Hence, the cover image of this blog post.

There are a lot of reasons why Gatsby uses GraphQL, the most common is to facilitate sourcing data from different places and getting the exact thing you need.

While this is a logical reason, this process isn’t as intuitive and sometimes might not be as straightforward as my steps make it seem.

What if there was a way to make this more interesting, with fewer lines of code?

Gatsby file system routes API

There is always a soul of good in things "evil" if people distill it out - Shakespeare

This was an answer to my WTF questions, an API built on top of the createPages API to replaces the above steps with a more intuitive approach. This is how it works:

use curly braces ({ }) in naming the file to signify dynamic URL segments that relate to a field within the node.
write your query as you would for a particular page.

You can leverage this feature by running

GATSBY_EXPERIMENTAL_ROUTING_APIS=1 gatsby develop

That's the END of this blog post.... (Joking)

Ok seriously, Here's an example, If you would query a file like so :

allProduct {
  nodes {
    id # Gatsby always queries for id
    name
  }
}

Then the file name in your pages directory would be src/pages/products/{Product.name}.js

Notice the pattern? Gatsby turns anything put into the pages folder to a route, so doing this automatically makes /products/{Product.name}.js to a route.

Here's what it turns the code block into:

Notice how the file name is in curly braces, that's about it.

Note: This File system Routes API is built on top of the createPages API so you will not have to refactor your existing applications 😉

In addition to the simplification, Gatsby automatically includes a gatsbyPath field on every model used by collection pages.

The gatsbyPath field must take an argument of the filePath it is trying to resolve. This is necessary because it’s possible that one model is used in multiple collection pages.

This is an example of what the gatsbyPath looks like in a query:

This feature is still experimental and as it gets built out I am sure it will create a more interesting way to query pages in Gatsby.

Wait there is more...

This file system API also helps with creating client-only route. Previously, to access dynamic content that isn’t known to Gatsby at build time,(Which is referred to as client-only routes) you would have to create a route with one or more dynamic segments to query data from a server in order to render your page.

For example, to show a user a personalized settings page, in order to edit a user, you might want a route like /user/:id to fetch the data for whatever id is passed into the URL. You can now use square brackets ([ ]) in the file path to mark any dynamic segments of the URL.

This means src/pages/users/[id].js would look like this /users/:id. Gatsby also supports splat routes, learn more about this in the documentation

Conclusion

There you have it, folks. I believe that with a few improvements to other pain points of Gatsby, some of the processes will be less stressful.