Forem: TakeShape

The Jamstack Identity Crisis: an Even-Handed Overview

Jaden Baptista — Thu, 19 Aug 2021 15:04:20 +0000

The community is abuzz.

The last few months, we've been debating — as a community — what the Jamstack even is. In the way of a quick summary, we largely split into two groups:

The Pragmatists

This group, pioneered by people like Hashicorp advocate Jeff Escalante, Forestry developer Franck Taillander, and Layer0 CTO Ishan Anand, is pushing to drop the name Jamstack because it's growing increasingly pointless as a descriptive term. They believe its trendiness has worn off and it's becoming restrictive and ultimately vexing as we fight about what's included in the definition.
The Resolutionists

On the other side of the aisle, you've got the folks who want to fix the definition of the Jamstack to include new practices rather than ditch it altogether. In this camp, you've got industry leaders like Bud Parr of the New Dynamic, Brian Rinaldi from StepZen, CloudCannon CEO Mike Neumegen (who wrote an excellent article on this just a few days ago by the way), and the king of performance and accessibility Henri Helvetica.

So far, we've been trying to place a clear border through a fuzzy gradient. We've been asking: "where do we draw the line between Jamstack and the other?"

We're starting to see a consensus, though. Attitudes are cooling and people are starting to come together on a solution. Here's the gist of what they're agreeing on:

The Jamstack as a set of best practices.

It's not a dichotomy anymore. The question is no longer, "is this site Jamstack?" The question is now, "how many Jamstack techniques does this site incorporate?"

That undercuts the whole premise of the earlier debate. If the Jamstack is no longer a restrictive and exclusive category, then you don't have to drop the name entirely to start using some non-Jamstack techniques like dynamic rendering on a monolithic server. You also don't need to redefine the Jamstack to start doing bigger and better things, because you can use the Jamstack label to talk about some of your site without sounding like a purist. Now, we don't need to draw a clear border through a fuzzy gradient, trying to separate Jamstack from the other. We don't even have to place our site on that spectrum at all.

Here are some of those principles:

Jamstack sites don't rely on dynamic page-building code on the server.
As much content as possible is baked into the markup at build time.
Extra functionality is primarily added with third-party APIs.
Any necessary custom server-side code is organized in manageable, atomic, decoupled microservices.
Most of the necessary assets for the site to load are held close to the client in a CDN.

Perhaps you are prerendering most of your site, but the backend API you've created for yourself is based around a monolithic architecture because your particular use case requires it. That doesn't have to be controversial! You've just used some Jamstack techniques in combination with some more traditional techniques to create an application that works best for you. We can all agree that a hybrid approach like this will — in many but not all situations — work better than either extreme, right?

Consensus is good...right?

Gif from the article linked below

From one point of view, absolutely! People who were, at one point, not seeing eye to eye are now cooperating, and that sure is lovely to see.

On the other hand, one of our favorite business articles over here at TakeShape, a 2016 post on the blog "Conferences that Work" entitled "When consensus is dangerous", makes a great point:

"The value of consensus is in the process of seeking it — not a “yes, we have consensus!” outcome."

It's the old adage "it's the journey, not the destination" playing itself out over again. If we focus on the outcome of what the community largely feels the Jamstack is, we might be missing the underlying lesson. This whole ordeal just goes to prove that the people who are participating in this discussion are doing so because they have a passion for whatever they feel the name "Jamstack" represents. That's what's really binding this otherwise heterogenous and diverse community together!

So let's find something new to argue about.

At the Jamstack Philly: Summer of Jamstack event that we organized on July 1 and August 4, 2021, the closing keynote argued that we'll see the next few years of Jamstack development marked by four major trends:

We'll take Astro's motto to heart and start seriously shipping less JavaScript. That means going back to the simplicity and bare-bones, lightweight structure of the first Jamstack tools (like Jekyll) while retaining all the functionality of the big platforms that came later (like Next.JS).
We'll help non-developers to work with us on equal footing, finding ways to get them interacting with us in the same tools and codebases with clever and intuitive GUIs.
We'll see tools that we've come to love like Netlify or Vercel start to separate from the pack with platform-specific features in order to stay relevant.
We'll adopt new terminology for the newest techniques we're using (for example, DPR) that are far less specific — in other words, get rid of that spectrum entirely. Some are suggesting calling it just "modern" development.

Let's talk about those! Let's ask new questions to keep the process of consensus going:

How far can we push HTML and CSS (and WASM?) to replace the need for the slow and burdensome JavaScript?
What tools can we create to remove the encumbrances of our non-developer colleagues and help them work with us on the same plane?
If platforms have to innovate independently to stay in business, how can they maintain the cross-platform values that the Jamstack is based upon?
If the term Jamstack grows insufficient as we consider more and more practices "best" outside of that immediate category, what terminology will we use to describe what we're doing?

Here at TakeShape, we're putting our money where our mouth is and investing in the future tooling of the Jamstack. We're building out a concept called an API mesh: a tool to stitch together the inconsistent APIs and external services we use all the time in the Jamstack. That's one of the most common tasks we use serverless functions for, and it sure has never been a simple task. All those inconsistencies make merging the data from those disparate services quite a bear, but by offloading that difficulty to a third-party API mesh like TakeShape, you can get only the data you need from a single GraphQL endpoint. It's the key to modern Jamstack development and part of the answer to the four questions above.

We'd love to hear your thoughts on those four questions too! Make sure to tag us on Twitter at @TakeShapeIO and @jadenguitarman with your thoughts and check out our site at TakeShape.io to learn more about our plans.

Making Accessibility Accessible

Jaden Baptista — Wed, 07 Jul 2021 15:41:23 +0000

I'll be honest: I've never been very accessibility-minded. I deal with mild colorblindness, so I get the need for strong color contrast, but besides that, I've always felt like accessibility was beyond me. I thought it was just something for accessibility experts, not a real problem that I needed to consider in my daily development.

That is, until I interviewed some of those experts. I'm very grateful that they took some time to sit down with me, and boy, did I learn a lot. Here's a recap of three main lessons that I learned from my interviews with Tessa Mero, developer advocate from Cloudinary and Henri Helvetica, king of web performance and accessibility.

1. Accessibility is a dichotomy, not a spectrum.

A site is either accessible or non-accessible. It's actually quite binary, since a partially-accessible site is still non-accessible. If you can't access all the features as a limited user (that includes human disabilities as well as those on devices with limited ability), then your site isn't accessible. As a way of testing our websites for potential hiccups, Henri proposed asking ourselves this question:

Can you achieve digitally, with some accessibility-related limitation, what you would have been reasonably able to do in person?

For example, imagine a banking website where you can do anything you would be able to do at a typical bank in person (within reason, of course). All of those features can be used by someone with accessibility challenges except for one: cashing a check. That's fairly simple to do at a bank (you can just hand the teller your check), but on the website, that might require the user to line up the check perfectly in their phone's camera view, which is nearly impossible if the user is blind. That's not accessible! The user could not achieve digitally, with their limitation, what they would have been able to do in person. Fixing this is quite a large task, as it would probably require rethinking the use of the camera in the first place, but asking the above question and identifying this as a potential problem area is the first step towards making their site usable by all.

2. It can be illegal to make a non-accessible site.

Do you remember the time a blind man sued Domino's Pizza because he couldn't order online? Or the time a blind woman from New York sued Beyonce because she couldn't keep up with the singer's latest news and products as easily as someone who could see?

The American Disabilities Act (and there are roughly equivalent laws in other countries, though details vary) requires that businesses that meet certain criteria for size and purpose must then keep their websites accessible to the blind, the deaf, those who must navigate by voice (for example, the paralyzed), and those with other limiting disabilities. While the law (at least in the United States) doesn't explicitly state any rules on deciding whether a website is accessible or not, it's commonly accepted that accessible websites follow the Web Content Accessibility Guidelines as established by the World Wide Web Consortium (who also set the HTML, CSS, DOM, and WASM standards). While the actual guidelines are pretty obtuse, the best practices they advocate for are found in simpler form by reputable sources all over the Internet.

3. Accessibility and user experience are one and the same.

You might've noticed earlier that when I defined "limited users", I included those on devices with limited ability. That's because, while we often think of accessibility as making your site friendly for the blind, it actually means making your website friendly for anyone with any limitation, including but not limited to:

Users on mobile devices
Users with bad internet
Users who simply prefer having a site read to them by a screen reader
Users with browser extensions that mess with the page
Users with a slow computer
Users on old browsers that don't support the newest features
Users that have set their browsers to minimize the amount of motion on the screen
Users with a broken peripheral device

Those are just the technological impairments that many of our users could potentially be dealing with. And that's in addition to the potential human disabilities they may face:

Users who have vision impairments, who might not see a button if it doesn't contrast enough with the background or if it can't be focused with a screen reader
Users who cannot hear well, who might not understand instructions if they only come in non-captioned video form
Users who must navigate the Internet by voice, who may not be able to click a link if a non-semantic tag is used instead of <a>
Users who don't intuit the things we might expect the user to know, who may not understand, for example, what a Share button looks like
Users with short-term memory impairments, who might not remember where they're supposed to click in your complex navigation
Users with perceptual disabilities like dyslexia, who may not be able to read our site if the font is too small or too thin
Users with tremors, dystrophy, arthritis, or some form of reduced dexterity, who may not be able to accurately move the mouse to keep hover-operated tooltips open

Truly, accessibility and user experience are one and the same, since the experience of such a wide swath of our users — over half are on mobile, for example — depends on us paying attention to their limitations, technological or human.

What I learned

I really enjoyed my chats with Tessa and Henri over on my Twitch channel. They taught me ways to expand my checklist for site-building to include considerations for the limited experiences I previously hadn't thought to test. The biggest lesson I got from these conversations was that accessibility and user experience require a lot of thought and care, even more than I had realized. Unfortunately, that makes it hard to also focus on your site's performance and underlying architecture, which is where TakeShape comes in. TakeShape's API Mesh enables front-end developers to harness the power of the Jamstack to reduce site complexity and ship faster, so your time is freed up to hone what matters the most: your user experience.

I actually learn a lot about a wide variety of subjects from these interviews, like the lessons Mark Lane discovered as he built several successful SaSS tools or that time I found that data and content modeling is actually a fascinating subject when Jeff Eaton is talking about it. If you're interested in catching the interviews live, keep an eye on my Twitter (@jadenguitarman) and Twitch (jadenbaptista).

Recordings of the interviews can be found on YouTube:

Henri Helvetica: https://www.youtube.com/watch?v=4Kpz6vHvuao&list=PLAF51ew9HblEE8dQepEEQKSw_03gBdU1L&index=6

Tessa Mero: https://www.youtube.com/watch?v=x3leuusTeSQ&list=PLAF51ew9HblEE8dQepEEQKSw_03gBdU1L&index=3

Our 8 favorite tools for monetizing your Jamstack website

Jaden Baptista — Sat, 12 Jun 2021 01:41:30 +0000

The Jamstack and ecommerce are a lot like chocolate and avocado. At first, they don't sound like they'll go together, but they actually work really well; once you try it and realize the potential, you'll find that there's a whole community of people ready to share their amazing recipes on how to make them taste great together. In the same way, the Jamstack can sometimes appear incompatible with ecommerce, but it doesn't have to be! Here are our top ten favorite tools to help you start selling on your Jamstack site:

TakeShape

TakeShape's API Mesh enables front-end developers to harness the power of the Jamstack by stitching together multiple external APIs with an intuitive internal CMS. I've actually been working on a series of livestreams about hydrating a product page with content from the TakeShape CMS and pricing data from Stripe, and while that might seem complex, TakeShape handles it smoothly. I just have to make one GraphQL request, and exactly the data I need arrives at the client, regardless of where that data originally came from. I wrote a summary article about those streams so you can see the process; you can check it out here.

I'm a little biased towards TakeShape, so I'll skip the ratings for this one, but I honestly love it; I'm including it in almost every project nowadays and think it's awesome.

Stripe

The whole point of ecommerce is to make money, so you need a tool to collect payment information and actually charge your customers. Stripe is the gold standard here. It's super simple to use, especially with the kits and libraries they provide, like Checkout and Elements. Their documentation is best-in-class, and their developer support team is the most helpful I've ever had to deal with.

Some more complicated setups can start getting difficult to manage, as Stripe locks you to using their system of products, subscriptions, prices, and customers, but that system is more than adequate for the vast majority of use cases. You do have to use something on the server-side for this, since Stripe requires that you keep one of your API keys secret for obvious reasons. On the Jamstack, that means running it on a host that supports serverless functions or funneling the requests to Stripe through an API Mesh like TakeShape.

All in all, I give Stripe a 9.5/10 based on its incredible developer experience.

Snipcart

Snipcart's tagline is Add a shopping cart to any website. It sure is bold, but they live up to that claim: devs from big names like Fiverr to small ecom sites are turning to Snipcart to make selling on the Internet easier. Using just HTML and JavaScript, you can inject a cart onto your site, define some attributes to describe whatever you're selling, and hook up your "Add To Cart" button. It's really that simple. DX is definitely important, but if the product manager still needs a little more convincing, you can tell them that it's portable (it's not stuck to any specific stack) and will speed up your development by working with your existing site. A lot of the tools in this market require you to build the site to work with the tool, but Snipcart has no such requirements.

Snipcart is flexible enough to handle almost any use case well, but there are some situations where you might be better off reaching for a more low-level tool. For example, I was looking into building a marketplace, and the guys from Snipcart told me that having money moving from a buyer to a seller would be difficult to implement without the money first going through a single account, which opens you up to higher transaction fees and getting taxed on those transactions differently depending on your jurisdiction.

Snipcart isn't the magic solution to every ecommerce need, but it absolutely nails its intended functionality, so I can confidently give this a 10/10.

Memberful

Ecommerce is more than just paying for a product online; one of the core concepts in ecom is the membership subscription. Memberful aims to simplify and abstract away the difficulty of this often tricky payment model, and man, does it succeed. Take a look at this guide for an example of its simplicity. It's definitely designed with non-developers in mind, so this will be a perfect fit for you if you're trying to paywall content on a larger site with dedicated content managers, if you're working on a site without a backend (like a Jamstack site), or with a Wordpress site (they've got an excellent and well-maintained plugin).

One thing I like about Memberful is that they're honest about their tool not being for everyone. In their own words, "we'd rather recommend a competitor that’s a better fit for your business than try to hard sell you on Memberful." They go on to list some situations where Memberful might be a little tougher to use and then they offer some better alternatives. For example, Memberful works best on digital content, so if you're selling physical products via an online experience (like Butcher Box or Dollar Shave Club), you might be better off with an all-in-one solution like Square.

It's less flexible than other solutions, but Memberful takes the master-of-one over the jack-of-all-trades approach, so they make up for it by perfecting their core feature set. They've definitely earned my approval: 9/10.

Auth0

Authentication is really hard to get right, and no matter how many times I try to roll it myself, I always fail. But then I heard about Auth0, and I believe I physically sighed in relief. They just give you a login system with best practices built right in, something I was really bad at building previously. Their security experts have already worked out solutions to fraud and other problems that modern ecommerce platforms are bound to face at some point or another.

That said, Auth0 can be difficult to get started with. It takes a bit of knowledge about those best practices to use Auth0's platform correctly without introducing more bugs and vulnerabilities. Thankfully, they've taken care of this by creating an excellent store of educational content on this topic to make integrating with them far easier. If you're interested in learning about how to work with Auth0, the best place to start is their blog.

With that said, it's the most powerful solution to one of the most common problems on the Internet: authentication. Auth0 earns a 8/10 from me.

Foxy.io (FoxyCart)

If Snipcart is the easy-to-use, build-into-your-existing-website shopping cart solution, Foxy.io is the super-powerful, only-for-devs, uber-customizable shopping cart solution. It's not better, just different from Snipcart, and so we use it in different scenarios. Perhaps when our small-town Mama's Pizza wants to start selling their pizzas online, Snipcart would be best, but Foxy.io might be the powerhouse needed to turn the gears behind BestBuy's website (large, but still with a single seller). Foxy.io doesn't manage inventory, while Snipcart does. Large sites like BestBuy likely are already handling that with a custom inventory solution, while something small like Mama's Pizza might make use of the inventory features of Snipcart to store their limited slate of pizza options. Foxy.io also can handle more payment gateways, which is unnecessary for smaller sites but could be critical for something as large as BestBuy.

I really like how they put it on this page: "FoxyCart is not a turnkey solution. This generally makes FoxyCart perfect for some and just plain wrong for others." I couldn't have said it better; Foxy.io (what they call it now) does the cart and checkout really well, but if that's not the largest part and central focus of your website, then you might be better off with a simple solution like Snipcart.

It's perfect for a small set of ecommerce sites, but go with Snipcart for everything else. I give it a solid 6/10 though.

SendGrid

Ah, SendGrid. Where were you all my life? Emailing is super difficult. The World Wide Web has evolved for the last 25 years, but the whole emailing system is stuck in 1996. SendGrid is kind of like a translator between that nonsense we had to deal with ages ago and the modern way we work with APIs. With customer outreach, support, and marketing being such a big part of the ecommerce world, tools that can make emailing easy like SendGrid have become absolutely indispensable. There's not that much to say about SendGrid other than the fact that they're trusted with handling crucial parts of the architecture of big websites like eBay, Nextdoor, Uber, AirBNB, and Yelp.

It does lean more towards being developer-friendly over content-creator-friendly, so you might find the interface a bit clunky if you're using SendGrid for blast emailing at a bigger company with dedicated marketers. It also looks like they funnel a lot of resources into development, which leaves customer support to focus on the biggest customers, so some smaller users have reported long stretches of time going by before hearing back from them.

Overall, I love SendGrid, and despite its minor flaws, it's always worked well for me. I give this one a 9.5/10.

Shopify

You were expecting this one, weren't you? I'll admit, I used to rail against Shopify, and I still have my qualms, but I've come to see just how powerful it can be. It's probably the least technical tool on this list, so that immediately opens up all sorts of possibilities to non-developers. That's quite important to a lot of web development agencies as their developers then don't have to be bogged down with minor updates and can focus on future development, depending on how much you've customized the templates they give you. There's a massive community (as one would expect the largest ecommerce solution to garner), and they've created all sorts of plugins and templates to make the developer's job even easier.

There is a caveat in that last pro, though. The plugin system can put the stability of your website in the hands of others, and we've seen that go well — and occasionally very, very badly — for Wordpress. Using plugins like this can open you up to vulnerabilities exposed by the plugin authors (who can be sometimes slow to fix them), so make sure to only use plugins created by companies you trust. Shopify also tends to be more of a platform than an add-on tool, so while you get the convenience of using prebuilt templates, it's much harder to customize and add non-ecommerce content. Many ecommerce companies run blogs or other informational pages, which aren't so easy to implement (it's definitely possible though!). Lastly, there's the fees. On top of the fee to use Shopify (which can be anywhere from $9 - $2000 depending on your needs), you'll likely be paying a fee on every transaction (plus your payment processor's fee).

I've grown to enjoy Shopify recently, but for many it's an acquired taste. Given just how powerful it can be, I'll give it a 7/10.

There you have it! That's my favorite 8 tools for turning a profit from your Jamstack site. It might've been historically difficult to combine ecommerce and the simplicity of the Jamstack, but thanks to tools like these 8, I'm hopeful that we'll be seeing more amazing ecommerce Jamstack experiences on the web in the future.

If you've got any questions about TakeShape or about the list in general, feel free to contact us on Twitter (@TakeShapeIO, @jadenguitarman) or at takeshape.io.

Using API Mesh to Streamline Ecommerce Development - A Stream Summary

Jaden Baptista — Mon, 24 May 2021 16:28:39 +0000

A recap of a two-part stream held over on twitch.tv/jadenbaptista

Launching an ecommerce experience involves many different stakeholders. Developers, designers, product manager, content producers, marketers and merchandisers, each bring their own niche tools and workflows to the challenge to help them do their jobs better. For example, a marketer will usually prefer to use SendGrid over a custom internal emailing tool because it's more developed and easier to use. It's the same reason why product managers like using Github Issues, content producers like using a CMS, and merchandisers like using Shopify. It's up to developers to make all the different pieces fit into a single cohesive customer experience. This can be a real obstacle! Usually it requires backend development work and managing your own infrastructure, or at least it forces you to cobble some plugins together in WordPress or Shopify.

However, in the age of the Jamstack, there is a new way for front-end developers to solve this challenge. It's called an API Mesh.

Term definition: an API Mesh is kind of like a switchboard for APIs. You can set it up so that all the data and functionality you'd normally ping an API for (for example, from a CMS, or from Stripe, or from another other REST or GraphQL API) and pipe it into TakeShape (the original API Mesh). Then with one GraphQL request to TakeShape, you can access whatever data or functionality you ask it for, regardless of its original source.

The Plan

In a recent two-part stream over on my Twitch, I demonstrated the process of collecting data from multiple sources and using it to fill out a product page right on the client-side with TakeShape's API Mesh. The first part of the stream was mostly about planning, so here's what I came up with:

I decided that the majority of the data about the product itself should be stored in TakeShape's CMS (it's helpfully bundled in the same suite of tools as the API Mesh and a static site generator), while any data about pricing should be stored in Stripe. That last part might seem a bit strange to anyone who's used to working with traditional databases like MySQL: you'd think it would be better to have all the information about the product available from a single source, right?

Actually, it turns out that keeping all that product data in one place isn't necessary. Stripe makes for a good example here, since your pricing data is going to have to be stored there anyways if you're going to charge people using Stripe. If you have the price stored in your database (or CMS) along with all the other product data, then there will be some period of time — like when you're changing how much something costs — when it doesn't match exactly with the price you've got in Stripe. Then suddenly you've found yourself in a situation where you're advertising one price but charging the customer another.

To avoid scary situations like this, we need to keep Stripe as the single source of truth for any piece of data it reasonably should control. All of our prices and money-related data ought to be kept there and only there, while any other product attributes (like title, description, image, etc) could stay in the CMS.

The Steps

Fill our data sources with data.

This was actually the easy part, since I just borrowed one of TakeShape's awesome starter kits on Github (I used this one). It came with everything I needed to get started, so I didn't have to do much setup. I actually ended up deleting 6 of the 9 products that came with the starter project, just for simplicity. After creating a new Stripe account, I created a product and a price in Stripe for each of the remaining sellable items, and called it done.
Tell the API Mesh about all of our sources.

The API Mesh needs to know where to collect data from if it's going to deliver it to us in one neat little packet, so we've got to give it our Stripe credentials and instructions on how to use their API. Now this might sound a bit complex, but it's really not; I went through this process live on the stream, and even with my impulsive rambling, it barely took 10 minutes.

All we really have to do is define these data sources as services in TakeShape. They're listed under the Schema tab. Just click the "Connect Service" button to add a new one.

To add a new service, click the Schema tab, and then the Connect Service button.

It'll walk you through a simple form just asking for the name of the service, the root endpoint (that's [api.stripe.com](http://api.stripe.com) in my case), and your auth details. Make sure to read the docs of the API you're using (here in my case) and the little note on the TakeShape form to make sure you're putting the right credentials in the right fields. In my initial stream, I made a tiny mistake here and used the wrong auth type. It wasn't a big deal; I just had to spend 5 minutes correcting it in the second stream.
Tell the API Mesh to stitch data from those sources into one request.

For this, we're going to jump into a little bit of JSON. Click the Export button on the Schema page to download the JSON that represents your entire project.

Click the Export button on the Schema page to download JSON that represents your entire project.

The JSON it downloads might seem a bit unwieldy, but luckily most of it isn't relevant at the moment, so I use my code editor to fold a lot of it up so I can focus on what's important right now:

My folded-up, simple view of the JSON schema that represents my whole project

See the Stripe service we added earlier? The TakeShape GUI just edited this JSON file for us. For the queries, shapes, and forms, we're going to do essentially the same thing, except we're just going to edit the JSON file ourselves.

The first step for me was to go into the Product form and remove any property that mentions price data, since we're going to keep that in Stripe. If you're following along, make sure to check the order list too. Do the same thing in the Product shape, making sure to check the required list as well (that was another thing I briefly forgot about in the livestream, which I had to spend a minute or two correcting).

Next, we've got to add a property to the Product shape called productId, which would look something like this:
```
"productId": {
    "type": "string",
    "title": "Product ID",
    "minLength": 1
}
```
That goes in the properties array under the Product shape.

The whole point of using this API Mesh in the first place was to help us developers stitch together all the tools our coworkers are using, so we've got to give whoever is in charge of maintaining the product entries the ability to enter the Stripe product ID into the CMS. TakeShape's CMS just displays forms to the user, which they can fill out to edit the product (or whatever other thing they're editing). So earlier, when we removed the price data from the Product form, we were removing the ability for our coworkers to add the price directly into TakeShape's CMS. Now that we want to let them add the Stripe product ID, we're going to add a new property to the Product form:
```
"productId": {
    "widget": "singleLineText"
}
```
Now here comes the toughest part, though it's still fairly straightforward. We want TakeShape to automatically pull in price data from Stripe whenever we ask it about a product. In other words, we're asking TakeShape to resolve the product to its appropriate price data from Stripe. In line with that, let's give TakeShape a resolver so it knows what data to give us.

Go back to that Product shape and add this property:
```
"priceData": {
    "type": "object",
    "properties": {
        "inCents": {
            "type": "number"
        }
    },
    "title": "Price Data",
    "@resolver": {
        "name": "rest:get",
        "service": "stripe",
        "options": {
            "fieldName": "priceData",
            "path": "v1/prices"
        },
        "argsMapping": {
            "searchParams.product": [
                [
                    "jsonPath",
                    {
                        "path": "$.source.productId"
                    }
                ]
            ]
        },
        "resultsMapping": {
            "inCents": [
                [
                    "jsonPath",
                    {
                        "path": "steps[0].data[0].unit_amount"
                    }
                ]
            ]
        }
    }
}
```
Here's a little breakdown for the curious:
1. First, we define that this is going to be an object, and that it'll have one property of its own called inCents, which will be a number.
2. Then, we tell it to get information from a GET request to the stripe service we defined earlier, at the /v1/prices endpoint.
3. Then, the API mesh is instructed to send the productID of this particular product into Stripe as a search parameter.
4. Lastly, we're asking that the unit_amount buried in Stripe's response be piped into that inCents property we defined earlier, so that our end result ends up nice and tidy.
We're done with this file, so just reimport that JSON file back into TakeShape and let the API Mesh do its thing.

Fill our product page with data from the API Mesh.

If we're going to hydrate our product page on the client, then we need to first request the data from our API Mesh. The GraphQL query we're sending to TakeShape would look something like this:

const query = `{
    getProductList {
        items {
            description
                image {
                    sourceUrl
                }
                name
                priceData {
                    inCents
                }
                category {
                    searchSummary
                }
                soldOut
            }
        }
    }`;

Here's the function I wrote to actually send that request:

const getMeMyData = async index => {
    let req = await fetch(
        `https://api.takeshape.io/project/${TS_PRODUCT_ID}/v3/graphql`, 
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${TS_API_KEY}`
            },
            body: JSON.stringify({ query })
        }
    );

    let result = await req.json();
    return result.data.getProductList.items[index];
};

And then here's the function that uses that data to hydrate my HTML:

const hydrateMePage = async productIndex => {
    const product_data = await getMeMyData(productIndex);

    document.getElementById("product-title").innerText = product_data.name;
    document.getElementById("product-description").innerText = product_data.description;

    let productImage = document.getElementById("product-image");
    productImage.src = product_data.image.sourceUrl;
    productImage.alt = product_data.name;

    document.querySelector(".product-price > span").innerText = "$" + (product_data.priceData.inCents / 100).toFixed(2);
    document.getElementById("product-category").innerText = product_data.category.searchSummary;
    if (product_data.soldOut) document.querySelector("main.container").classList.add("sold-out");
};

Those two small functions set us up to fill out our whole page with data from multiple sources without practically any technical debt. Just run a hydrateMePage(0) and it'll fill the page with data like magic; except that it's not magic, it's an API Mesh stitching together our CMS and Stripe data so we don't have to do the legwork of stitching it ourselves.

The Results

And with those four steps, we've suddenly created an entire data pipeline for our ecommerce website. To create a search results page, or a homepage, or anything else, we don't even have to replicate all the steps; depending on whether you need to add more sources or not, you'd just start from step 2 or 4.

If you're interested in seeing more builds like this, I stream over on my Twitch every Monday afternoon. We also talk with leaders in the web development community about their experiences with interactive interviews there on Thursday afternoons. Make sure to follow @takeshapeio and @jadenguitarman on Twitter to get the latest updates.

Demystifying GraphQL Queries

Jaden Baptista — Tue, 27 Apr 2021 22:44:40 +0000

It's hard to learn new things, isn't it? When I first started to learn Python, it looked like an indiscriminately shuffled string of stray symbols. But eventually I learned; I connected it with concepts I knew from other languages. Later on, I learned JavaScript and went through the same thing; I didn't understand the syntax, so it just looked like a bunch of meaningless characters to me. But once I saw the similarities with languages I already understood, it started to click. I originally had the same reaction to GraphQL queries. It seemed difficult at first, but I came around after I realized the key to learning it was just like the technologies I'd learned before, and now I use it almost every day.

I'm just like every other developer: I want to learn new things but sometimes struggle with remembering the details and grasping the why of it all, so I figured I'd write this post to explain where I started with GraphQL and how I got to where I am now.

Step 1: Conceptualize the thing

I can't get anything done until I can work out what's happening in my head.

Me figuring out something new

I'm grateful though that someone explained GraphQL to me as REST adopting the baby of JSON and SQL. GraphQL is declarative, meaning that you get back what you ask for. No more, no less. When writing a GraphQL query, we're using a syntax that is similar to JSON or a TypeScript interface to define what information we want to get back in our response. Just like how we'd use SQL to define what data to retrieve from a database. Except instead of directly accessing a database with SQL, with GraphQL we're telling an API what information we're looking for.

My lack of understanding was the result of seeing GraphQL in action before knowing why someone would use it in the first place. At the time, I had been working on my own attempt at standardizing API responses in JavaScript, so GraphQL was really right up my alley; I just didn't know it. Once I understood that GraphQL could tackle the problems I was having, I realized it that I had to start learning the syntax. That takes me to step 2...

Step 2: Learn the thing

Once I wrapped my mind around the why of GraphQL, I had to grasp the how of GraphQL. There's a fantastic quickstart tutorial on the official GraphQL website, but I'll just show the basics:

Types. Say you want to get some user account information, but you want it to conform to a certain spec. Let's imagine that you want get their first and last name (both strings), their age (an integer, in years), their username (a string), and whether they're subscribed to your newsletter (a boolean). In plain JavaScript, this would be tough (or at least lengthy) to check manually:
```
// assume we've got everything in an object called "data"
if (
    (typeof data.first_name != "string" && data.first_name != null)
    || (typeof data.last_name != "string" && data.last_name != null)
    || (typeof data.age != "number" && data.age != null)
    || (typeof data.username != "string" && data.username != null)
    || (typeof data.subbed != "boolean" && data.subbed != null
) return "invalid";
```
Let's be honest, that's a bit excessive, isn't it? It's technically best practice, and in theory, it allows each field to be either its assigned datatype or null. It just doesn't scale though. Having this after every API request gets old fast.

GraphQL forces the API to define those datatypes, so you're guaranteed to get back what you're expecting. If the API says that first_name will be a String, it will come to me as a string or null. I can count on that in my application. They can even rule out null too, by making the datatype String! with the exclamation point. On their side, they're defining a type like this:
```
type User {
    first_name: String
    last_name: String
    age: Int
    username: String
    subbed: Bool
}
```
Again, the API does all of this, so we don't have to. We can just count on what's coming in and out.

When you start working with more advanced GraphQL queries, you might end up implementing types on the client-side too! Check out the types docs here on the GraphQL website for more information.
Queries. We talked about guaranteeing what types of data we'll get with GraphQL, but now we actually have to get that data, and we do it with queries. This is the part I was talking about when I said it looks like JSON and SQL. You just kind of give it the keys of the JSON object you're looking for, and it'll fill in the values, similar to how SQL fills in the data once you give it the columns you're selecting.

Say you're trying to retrieve user data from an API mesh like TakeShape, and it's set up so you can trust that the data you get back conforms to the type up above. A query for that would look something like this:
```
{
    getUser (id: f8a5123b9705c8c618043dc206b09c6a) {
        first_name
        last_name
        age
        username
        subbed
    }
}
```
You just give the GraphQL API the keys to the JSON object, and the API will just fill in the values. You can nest this too; say we had the user's first and last name in a nested object. The query might look something like this:
```
{
    getUser (id: f8a5123b9705c8c618043dc206b09c6a) {
        name {
            first
            last
        }
        age
        username
        subbed
    }
}
```
GraphQL is powerful enough to reach down into these nested objects and make sure that everything conforms to the type defined by the API. This way we don't have to worry about getting the wrong information or trying to do all that manual validation in JavaScript anymore.

This isn't my any means all the things you can do with GraphQL, but it's enough to get by on, especially if you're just consuming a GraphQL API like the one TakeShape's API mesh provides. If you're fascinated by the possibilities here, I'll point you back to the detailed guide on the official GraphQL website here.

Step 3: Use the thing

This is the part I struggle with the most. Finding the time and the right opportunity to use a new technology can be a challenge.

After conceptualizing something new, and learning the syntax, I want to jump head first and start using my newly earned knowledge on a big new project! But, alas, I know that wouldn't be wise. It's best to start tinkering on a low stakes project. I decided to start simple with a starter blog using TakeShape's GraphQL API. Playing in this sandbox was like learning Python again. Just pressing buttons, trying new things, and experimenting with different ideas. It wasn't planned or scripted, and there wasn't any particular thing I wanted to make; I was satisfied just exploring what I didn't know before.

That's the crux of my advice to anyone who is still having trouble demystifying GraphQL queries: just tinker. Experiment. Build something. Anything. You don't have to work it into some polished portfolio-worthy project; you just have to go beyond understanding the why and the how and get to actually using GraphQL.

I hope this guide helped you to go through the same journey with GraphQL queries that I did: conceptualizing it, then learning the syntax, and then using it in a project. I wouldn't call myself an expert, but I think I'm a better developer for having gone through the process I outlined here, and I hope you'll feel the same. If you're looking for a place to dive into GraphQL more, I've littered this article with links and references to the official GraphQL guide and TakeShape, an easy-to-use example of a GraphQL API.

If you have any questions, feel free to reach out to me at jaden@baptista.dev.

How to use React Query with React and GraphQL

Ibrahima Ndaw — Wed, 24 Mar 2021 23:15:13 +0000

React Query is a library that provides a set of hooks for fetching, caching, and updating data in your React applications. In this tutorial, we will be looking at React Query and learning how to use it in a React and GraphQL app.

What is React Query?

React Query (RQ) is a performant and powerful data synchronization library for React apps. It provides a collection of hooks for fetching and managing data. It is backend agnostic, which means you can use REST, GraphQL, or whatever APIs you like, RQ doesn’t care. React Query handles caching, background updates, and stale data out of the box with zero-configuration. The caching layer of RQ is powerful and minimal effort to configure.

React Query makes state managing easy because it allows you to fetch, mutate and cache data with almost no hassle. And can also be customized for more advanced use cases. While React Query does a lot for you, it’s not a complete replacement for client-state management libraries because RQ can’t handle UI state (state for controlling the interactive parts of our app); it’s a library for fetching and synchronization data.

However, RQ is designed to replace the boilerplate code and related wiring used to manage cache data in your client-state and replaces it with just a few lines of code. RQ has to manage asynchronous operations between your server and client and use Redux, MobX, Zustand, or even React Context to handle the UI state. This way, you will get a simplified app logic and delivers a snappy experience to your users with less code.

What we’re building

In this guide, we will be building a Blog app using React, React Query, and GraphQL. We will retrieve the data from the TakeShape GraphQL API. Let’s get started!

Setting up

Before we craft up a new React app, we need to sign up for an account on TakeShape (it’s free) then create a new project to get a GraphQL API to play with. After you create an account and create a read-only API key, open your command-line interface and run the following:

npx create-react-app rq-graphql-app

This command will create a new React app for us. Next, we need to install a couple of libraries. Browse to the project root and do the following:

npm install react-query react-router-dom graphql graphql-request react-markdown

Here’s what each of the libraries you are installing does:

react-query allows interacting with the GraphQL API and retrieve the data.
react-router-dom enables routing in our app.
graphql is a dependency for graphql-request.
graphql-request allows fetching data from a GraphQL backend.
react-markdown helps render Markdown in a React app.

With the dependencies installed, we can get our hands dirty and see React Query in action.

Folder structure

Structure your project as follows:

├── src
|  ├── components
|  |  ├── Header.js
|  |  ├── Layout.js
|  |  ├── Post.js
|  |  └── PostTemplate.js
|  ├── App.js
|  ├── useRequest.js
|  ├── index.css
|  ├── index.js
├── .env
├── package.json
└── yarn.lock

Take special note of the useRequest.js file. It is a custom hook that uses RQ to retrieve the data from the TakeShape GraphQL API. This file is where the magic happens; it helps interact with the API to fetch the blog posts. You can alternatively use the RQ hooks in your components, but it’s nice to have a custom hook to avoid repeating ourselves.

Next, let’s configure our app to use React Query.

Setting up React Query

// index.js
import React from "react";
import ReactDOM from "react-dom";
import { QueryClient, QueryClientProvider } from "react-query";

import App from "./App";
import "./styles.css";

const queryClient = new QueryClient();

const rootElement = document.getElementById("root");
ReactDOM.render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </React.StrictMode>,
  rootElement
);

In order to use the hooks of RQ to interact with our GraphQl API, we need to wrap our top-level app component with the RQ library query provider.

Using React Query

// useRequest.js
import { useQuery } from "react-query";
import { GraphQLClient, gql } from "graphql-request";

const API_URL = `https://api.takeshape.io/project/${process.env.PROJECT_ID}/v3/graphql`;

const graphQLClient = new GraphQLClient(API_URL, {
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`
  }
});

export function useGetPosts() {
  return useQuery("get-posts", async () => {
    const { getPostList } = await graphQLClient.request(gql`
      query {
        getPostList {
          items {
            _id
            title
            description
            content
          }
        }
      }
    `);
    return getPostList;
  });
}

export function useGetPost(postId) {
  return useQuery(["get-post", postId], async () => {
    const { getPost } = await graphQLClient.request(
      gql`
        query getPost($postId: ID!) {
          getPost(_id: $postId) {
            _id
            content
            description
            title
          }
        }
      `,
      { postId }
    );
    return getPost;
  });
}

In useRequest.js, we start by importing the useQuery hook and graphl-request. Next, we declare the API_URL constant with the credentials provided by TakeShape. For each request, we need to include an authorization header with the API key from TakeShape in order to authenticate to the GraphQL API . Using GraphQLClient allows us to set the API key on each request.

To get all blog posts from the API, we use the useGetPosts function. The useQuery hook expects a key (get-posts) and a GraphQL query. The hook can receive more options, but for this example, we just need these two. Once the fetch is done, we return the data. React Query will append some data to the returned value, which allows handling loading and error states.

Next, useGetPost, receives the id of the post to fetch. To pass in the id to the GraphQL query, we need to add it as a second argument to the request() method. With this, the data is fetched and then returned.

The custom hook is ready to use. Let’s create the React components and rely on the hook to retrieve the data.

Creating the components

// components/Post.js
import React from "react";
import { Link } from "react-router-dom";
export default function Post({ article }) {
  const { _id, title, description } = article;
  return (
    <article className="Article">
      <h1>{title}</h1>
      <p>{description}</p>
      <Link to={`/single-post/${_id}`}>Read more &rarr;</Link>
    </article>
  );
}

This component is responsible for the display of a blog post preview. It receives the object as a parameter and then shows it accordingly.

// components/PostTemplate.js
import React from "react";
import ReactMarkdown from "react-markdown";
import { useParams } from "react-router-dom";
import { useGetPost } from "../useRequest";
export default function PostTemplate() {
  const { id } = useParams();
  const { data, error, isLoading, isSuccess } = useGetPost(id);

  if (error) return <h1>Something went wrong!</h1>;
  if (isLoading) return <h1>Loading...</h1>;

  return (
    isSuccess && (
      <article className="Post">
        <h1>{data.title}</h1>
        <ReactMarkdown source={data.content} />
      </article>
    )
  );
}

PostTemplate.js is a template to display a blog post. The id is pulled out from the router params and then passed in to the useGetPost hook. With this, we can now get the post using its id. It returns the data and some states provided by RQ to handle the case when something went wrong.

Showing the blog posts

// App.js
import React from "react";
import { BrowserRouter as Router, Route } from "react-router-dom";

import { useGetPosts } from "./useRequest";
import Post from "./components/Post";
import PostTemplate from "./components/PostTemplate";
import Layout from "./components/Layout";

export default function App() {
  const { data, error, isLoading, isSuccess } = useGetPosts();

  if (error) return <h1>Something went wrong!</h1>;
  if (isLoading) return <h1>Loading...</h1>;

  return (
    <Router>
      <Layout>
        <Route path="/" exact>
          {isSuccess &&
            data.items.map((post) => <Post key={post._id} article={post} />)}
        </Route>
        <Route path="/single-post/:id">
          <PostTemplate />
        </Route>
      </Layout>
    </Router>
  );
}

In App.js, we import the custom hook and use it to get all blog posts from the API. Then loop through the response data and display the posts using the Post component.

We are now ready to test our example app in the browser. Open the project directory in your CLI and run:

npm start

If everything works as it should, the app will be up and running here: [http://localhost:3000/](http://localhost:3000/).

app-preview

Awesome! Our Blog app is looking nice.

React Query comes with dedicated devtools. It helps visualize all of the inner workings of React Query and will likely save you hours of debugging. To enable it, we need to enable it in index.js.

// index.js
import React from "react";
import ReactDOM from "react-dom";
import { QueryClient, QueryClientProvider } from "react-query";
import { ReactQueryDevtools } from "react-query/devtools";

import App from "./App";
import "./styles.css";

const queryClient = new QueryClient();

const rootElement = document.getElementById("root");
ReactDOM.render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <App />
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  </React.StrictMode>,
  rootElement
);

Import ReactQueryDevtools from react-query and add it as a child component of the QueryClientProvider component. That’s it! The devtools are ready to use. Let’s try it in the browser.

devtools

Once you click on the React Query logo, the devtools will pop up with its neat features. Enjoy!

You can find the finished project in this CodeSandbox. Thanks for reading!

Conclusion

React Query is a useful library for managing asynchronous operations between your server and client. It continues to gain traction and is trusted in production by large companies such as Google, Facebook, Amazon, and Microsoft. Folks are using it to simplify their state management because it has great caching strategies, can synchronize and updates server state, and has less boilerplate. RQ is a go-to for your next project that requires remote data fetching.

How to Guide: Using Sapper with TakeShape

Ashutosh Kumar Singh — Wed, 27 Jan 2021 19:13:03 +0000

In this article, we will discuss how to use TakeShape with Sapper, an application framework powered by Svelte.

If you want to jump right into the code, check out the GitHub Repo here.

And here's a link to the deployed version: https://sapper-takeshape-example.vercel.app/

Prerequisites

Knowledge of HTML, CSS, JavaScript
Basics of Svelte and GraphQL
Node/NPM installed on your local dev machine
Any code editor of your choice

What is Svelte?

Svelte is a tool for building fast web applications, similar to JavaScript frameworks like React and Vue, svelte aims to make building slick interactive user interfaces easy. But there's a crucial difference.

According to official docs:

Svelte converts your app into ideal JavaScript at build time, rather than interpreting your application code at run time. This means you don't pay the framework's abstractions' performance cost, and you don't incur a penalty when your app first loads.

What is Sapper?

Sapper is a framework built on top of Svelte and has taken inspiration from Next.js. Sapper helps you create SEO optimized Progressive Web Apps (PWAs) with file system based routing, similar to Next.js.

How to Setup and Install a Sapper project

This tutorial uses sapper-template to quickly set up the initial Sapper project, which is also the preferred way to initialize a Sapper project.

In your project's root directory, run the following commands in the terminal.

npx degit "sveltejs/sapper-template#webpack" sapper-takeshape-example
cd sapper-takeshape-example
npm install
npm run dev

The last command npm run dev will start the development server on port 3000. Head over to http://localhost:3000/.

Here is how your app will look.

How to Generate TakeShape API Keys

If haven't already, create a free developer account on TakeShape.

Create a new project and configure it as shown below.

Give a name to your project; this tutorial uses a project named sapper-takeshape-example.

Now, click on Create Project.

On your TakeShape dashboard, head over to the Post tab. You will see the sample blog posts present in this project.

The next step is to generate API keys to authenticate your Sapper project with TakeShape. Click on the triple dots present next to your project's name on the dashboard.

In the drop-down menu, click on API Keys.

Click on New API Key.

Name this API key, and since you will only use this on the client-side to read the blog posts, you can set Permissions to Read. Click on Create API Key.

Copy the API key to a secure location; remember you will only see them once.

**Note:* These credentials belong to a deleted project; hence I have not hidden them throughout this tutorial to give you a better understanding of the process and steps. You should never disclose your private API keys to anyone.*

On the API Keys page, you will also see your TakeShape project id, i.e., the value between /project/ and /v3/graphql in your API endpoint; copy this project id.

In your project's root directory, run the following command to create a new file named .env to securely store this API key.

touch .env

In your .env file, add the environment variables.

# .env
TAKESHAPE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
TAKESHAPE_PROJECT="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

To access these environment variables, you need to install the dotenv package, which loads environment variables from the .env file.

Run the following command in the terminal to install the dotenv package in your project.

npm install dotenv

Now you also need to configure Sapper to use these environment variables. Modify your src/server.js file like this.

require("dotenv").config();

import sirv from "sirv";
import polka from "polka";
import compression from "compression";
import * as sapper from "@sapper/server";

const {PORT, NODE_ENV} = process.env;

const dev = NODE_ENV === "development";

polka() // You can also use Express
    .use(
        compression({threshold: 0}),
        sirv("static", {dev}),
        sapper.middleware()
    )
    .listen(PORT, (err) => {
        if (err) console.log("error", err);
    });

In the above code, you have imported the dotenv package at the top of the server.js file.

require("dotenv").config();

Restart your development server by closing it using Ctrl + C and starting it again using npm run dev.

How to Display Posts on the Blog Page

With your development server still running, head over to http://localhost:3000/blog. You will see a page similar to this, which lists all the posts with their links.

These are the sample blog posts that come with the sapper-template and are present in src/routes/blog/_posts.js. You need to update this /blog route to show posts fetched from TakeShape.

Every post in the posts array has a title and a slug, shown on the blog page. You need to create a similar GraphQL query that fetches the title and slug of each post.

On your TakeShape dashboard, click on API Explorer.

Here is how this API Explorer will look.

Copy and Paste the following GraphQL query in the left tab.

query AllPosts {
  allPosts: getPostList {
    items {
      _id
      title
      slug
    }
  }
}

Run this query; you will see an output similar to this.

In Sapper, Page is a Svelte component written in .svelte files. Server routes are modules written in .js files that export functions corresponding to HTTP methods like get, post, etc. Each function receives HTTP request and response objects as arguments, plus a next function.

The index.json.js file under routes/blog directory is a server route, which currently fetches data from the posts array in the _posts.js file. You need to update this server route to fetch posts from TakeShape.

You will need to install the node-fetch package to make the API requests. Run the following command in the terminal to install node-fetch.

npm install node-fetch

Update src/routes/blog/index.json.js file like this and restart your development server.

const fetch = require("node-fetch");

export async function get(req, res) {
    const {TAKESHAPE_API_KEY, TAKESHAPE_PROJECT} = process.env;

    const data = await fetch(
        `https://api.takeshape.io/project/${TAKESHAPE_PROJECT}/v3/graphql`,
        {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                Authorization: `Bearer ${TAKESHAPE_API_KEY}`,
            },
            body: JSON.stringify({
                query: `
                      query AllPosts {
                          allPosts: getPostList {
                              items {
                              _id
                              title
                              slug
                              }
                          }
                      }
    `,
            }),
        }
    );
    const response = await data.json();
    const posts = await JSON.stringify(response.data.allPosts.items);

    res.writeHead(200, {
        "Content-Type": "application/json",
    });

    res.end(posts)
}

In the above code, you first import the node-fetch package.

const fetch = require("node-fetch");

Then inside the get function, you extract the environment variables from process.env.

const { TAKESHAPE_API_KEY, TAKESHAPE_PROJECT } = process.env;

Now, you make the POST request to TakeShape using the fetch method.

const data = await fetch(
    `https://api.takeshape.io/project/${TAKESHAPE_PROJECT}/v3/graphql`,
    {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${TAKESHAPE_API_KEY}`,
        },
        body: JSON.stringify({
            query: `
                      query AllPosts {
                          allPosts: getPostList {
                              items {
                              _id
                              title
                              slug
                              }
                          }
                      }
    `,
        }),
    }
);

You pass the TakeShape API key under Authorization in headers. The GraphQL query inside the body is the same as discussed above in the API Explorer.

Finally, you return the posts in the response using res.end(posts).

const response = await data.json();
const posts = await JSON.stringify(response.data.allPosts.items);

res.writeHead(200, {
    "Content-Type": "application/json",
});

res.end(posts);

In Sapper, Page component have a optional preload function that runs before the component is created. As the name suggests this function, preloads the data that the page depends upon.

Preload is the Sapper equivalent to getInitialProps in Next.js or asyncData in Nuxt.js. You can read more about Preloading here.

Open src/routes/blog/index.svelte file in your code editor. Since index.json route is inside blog directory, it can also be referenced as blog.json.

You fetch data from blog.json route using this.fetch. This method is quite similar to fetch API with some additional features like requesting data based on user's session. You can read more about this.fetch here.

<script context="module">
export function preload() {
    return this.fetch(`blog.json`)
        .then((r) => r.json()).then((posts) => {
            return {posts};
        });
}
</script>

In Svelte, you can iterate over any array or array like value using an #each block as shown here. Here (post._id) is the key that uniquely identifies each post. You can read more about #each block here.

<ul>
 {#each posts as post (post._id)}
     <li><a rel="prefetch" href="blog/{post.slug}">{post.title}</a></li>
 {/each}
</ul>

You don't need to make any other change in index.svelte file except for adding a key in the #each block like shown above.

Navigate to http://localhost:3000/blog in your browser; you will notice that posts have been updated.

You can now delete the _posts.js file in the routes/blog directory.

Since the individual post routes don't exist yet so these links will result in a 404 error, you will create them in the next section.

How to Create Dynamic Routes for Posts

In Sapper, you can create dynamic routes by adding brackets to a page name, ([param]), where the param is the dynamic parameter that is the slug of the article.

You will notice that a file named [slug].svelte already exists in the src/routes/blog directory.

You need to update the server route used in this file so when a user clicks on a post, the data corresponding to that post is fetched and is displayed with the blog/[slug] route.

Update blog/[slug].json.js file like this.

const fetch = require("node-fetch");

export async function get(req, res, next) {
    const {slug} = req.params;

    const {TAKESHAPE_API_KEY, TAKESHAPE_PROJECT} = process.env;
    const data = await fetch(
        `https://api.takeshape.io/project/${TAKESHAPE_PROJECT}/v3/graphql`,
        {
            method: "post",
            headers: {
                "Content-Type": "application/json",
                Authorization: `Bearer ${TAKESHAPE_API_KEY}`,
            },
            body: JSON.stringify({
                query: `
          query PostBySlug($slug: String) {
            post: getPostList(where: {slug: {eq: $slug}}) {
            items {
              _id
              title
              deck
              bodyHtml
            }
            }
          }`,
                variables: {
                    slug: slug,
                },
            }),
        }
    );

    const response = await data.json();
    const post = JSON.stringify(response.data.post.items[0]);

    res.writeHead(200, {
        "Content-Type": "application/json",
    });

    res.end(post);
}

The above code is quite similar to the server route code discussed in the last section, with few key differences.

This route fetches individual post data based on the slug provided, which is accessed via req.params.

  const { slug } = req.params;

The GraphQL query in the above code fetches post matching the slug using where: { slug: { eq: $slug } }. In the query, bodyHtml corresponds to the HTML body of the post and deck is the short excerpt of the post.

query PostBySlug($slug: String) {
  post: getPostList(where: { slug: { eq: $slug } }) {
    items {
      _id
      title
      deck
      bodyHtml
    }
  }
}

The slug is made available to the GraphQL query via variables.

variables: {
  slug: slug,
},

Update blog/[slug].svelte file like this.

<script context="module">
export async function preload({params}) {
    const res = await this.fetch(`blog/${params.slug}.json`);
    const data = await res.json();

    if (res.status === 200) {
        return {post: data};
    } else {
        this.error(res.status, data.message);
    }
}
</script>

<script>
    export let post;
</script>

<style>
    .content :global(h2) {
        font-size: 1.4em;
        font-weight: 500;
    }

    .content :global(pre) {
        background-color: #f9f9f9;
        box-shadow: inset 1px 1px 5px rgba(0, 0, 0, 0.05);
        padding: 0.5em;
        border-radius: 2px;
        overflow-x: auto;
    }

    .content :global(pre) :global(code) {
        background-color: transparent;
        padding: 0;
    }

    .content :global(ul) {
        line-height: 1.5;
    }

    .content :global(li) {
        margin: 0 0 0.5em 0;
    }
</style>

<svelte:head>
    <title>{post.title}</title>
    <meta name="Description" content={post.deck}>
</svelte:head>

<h1>{post.title}</h1>

<div class="content">
    {@html post.bodyHtml}
</div>

The preload function takes two arguments, page and session. Here page is an object equivalent to { host, path, params, query } and session is used to pass data such as environment variables from the server.

In the above preload function, you access the page object's params property and pass the slug of the page to the server route.

If you console.log() the page object, you will see all the data available via the page object. Here is how this will look like.

{
  host: 'localhost:3000',
  path: '/blog/jump-aboard-new-treasure-island-edition',
  query: {},
  params: { slug: 'jump-aboard-new-treasure-island-edition' }
}

The post is returned based on the status code of the response. this.error is a method in Sapper for handling errors and invalid routes. You can read more about it here.

    if (res.status === 200) {
            return { post: data };
        } else {
            this.error(res.status, data.message);
        }

You only need to update post.body to post.bodyHtml in the div with class="content" in [slug].svelte file like.

<div class="content">
    {@html post.bodyHtml}
</div>

In Svelte, you can render HTML directly into a component using the @html tag like shown above. You can read more about this tag here.

And its done.

Try clicking on any of the posts on /blog route or head over to http://localhost:3000/blog/jump-aboard-new-treasure-island-edition. You will see a page similar to this.

You can view the finished website here and the code for the project here.

Conclusion

In this article, you learned how to use TakeShape with Sapper, an application framework powered by Svelte. We saw how simple it is to integrate TakeShape with Sapper.

We also discussed how to use API Explorer in TakeShape and how to use the preload function in Sapper.

With just a few simple modifications and updates in your Sapper project, you can easily achieve a perfect Lighthouse score. Amazing, Right!

Here are some additional resources that can be helpful.

Happy coding!

How to use GraphQL on the Client-side with React and TypeScript

Ibrahima Ndaw — Mon, 25 Jan 2021 23:29:55 +0000

In this tutorial, we will be looking at using GraphQL on the client-side with React, TypeScript, and Apollo Client. This article is a follow-up of How to use TypeScript with GraphQL (server-side) in which we built a GraphQL API using TypeScript and TypeGraphQL. We’ll be using the API we created in that article, so if you haven’t already, you may want to catch up before diving into the client-side because. Let’s get started!

Prerequisites

This guide assumes that you have basic experience with React and TypeScript. You will learn how to use GraphQL in a React App to interact with a GraphQL API and then retrieve the data using Apollo Client. We’ll be building a Todo App that relies on the API to add and fetch the Todos.

You can preview the GraphQL API in this CodeSandbox

Setting up

To start a new React App, execute this command on the command-line-interface (CLI):

npx create-react-app react-typescript-graphql

Next, we have to install the Apollo and GraphQL libraries. The Apollo Client will allow us to communicate with a GraphQL API. Open the React App directory in your CLI and run the following command:

yarn add apollo-boost @apollo/react-hooks graphql

Or for npm

npm install apollo-boost @apollo/react-hooks graphql

Now let’s structure the project as follows:

src
| ├── components
| |  ├── AddTodo.tsx
| |  └── Todo.tsx
| ├── type
| |  └── Todo.ts
| ├── App.tsx
| ├── useRequest.ts
| ├── graphql.ts
| ├── index.ts
| └── index.css

There are two files to take special notice of:

useRequest.ts is a custom hook that helps fetch data using Apollo Client.
graphql.ts holds the GraphQL logic to interact with the API.

With this folder structure in place, we can get our hands dirty and create our TypeScript Types!

Creating the TypeScript Types

types/Todo.ts

export interface ITodo {
  id?: string;
  title: string;
  description: string;
}

export interface ITodos {
  getTodos: ITodo[];
}

export type ITodoMutation = {
  addTodo: ITodo;
};

Let’s explore what each type describes. The ITodo type describes the shape of a Todo. We use the ITodo type to create ITodos which returns an array of Todos from the API. Finally, we rely on ITodo to define the type expected by the GraphQL mutation query ITodoMutation.

Next we’ll add Apollo Client into our React App.

Connecting React to Apollo Client

index.ts

import * as React from "react";
import { render } from "react-dom";
import ApolloClient from "apollo-boost";
import { ApolloProvider } from "@apollo/react-hooks";

import App from "./App";

const client = new ApolloClient({
  uri: "https://tyoku.sse.codesandbox.io/graphql"
});

const rootElement = document.getElementById("root");
render(
  <ApolloProvider client={client}>
    <App />
  </ApolloProvider>,
  rootElement
);

After importing ApolloClient, we create a new instance of it and pass in the URL of the GraphQL API. To connect it with React, we need to pass the client object to the ApolloProvider component. Apollo client can now be used to retrieve data from the API.

Next we’ll use gql and the hooks provided by Apollo Client to send the GraphQL queries to the API.

Writing the GraphQL queries

graphql.ts

import gql from "graphql-tag";

export const GET_TODOS = gql`
  {
    getTodos {
      id
      title
      description
      status
    }
  }
`;

export const ADD_TODO = gql`
  mutation AddTodo($title: String!, $description: String!) {
    addTodo(todoInput: { title: $title, description: $description }) {
      id
      title
      description
      status
    }
  }
`;

As you can see, GET_TODOS is a GraphQL Query for retrieving all Todos from the API and a GraphQL Mutation ADD_TODO for adding a new Todo. The mutation query expects a title, and a description in order to create a new Todo on the backend.

Fetching the Todos from the GraphQL API

useRequest.ts

import { DocumentNode, useQuery, useMutation } from "@apollo/react-hooks";
import { ITodos, ITodoMutation } from "./types/Todo";

export function useTodoQuery(gqlQuery: DocumentNode) {
  const { loading, error, data } = useQuery<ITodos>(gqlQuery);
  return { loading, error, data };
}

export function useTodoMutation(gqlQuery: DocumentNode) {
  const [addTodo] = useMutation<ITodoMutation>(gqlQuery);
  return [addTodo];
}

This custom hook is optional. You can skip it and use the Apollo hooks directly in your components.

In this file, we first have a function useTodoQuery that expects a GraphQL Query to fetch all Todos from the API and then returns the data. Next, we use the useTodoMutation method to create a new Todo based on the data received as a parameter.

So far, we have connected React and Apollo and created the GraphQL queries to access the API. Next, let’s build the React components to that will consume the returned data.

Creating the components

components/Todo.ts

import * as React from "react";
import { ITodo } from "../types/Todo";

type Props = {
  todo: ITodo;
};

const Todo: React.FC<Props> = ({ todo }) => {
  const { title, description } = todo;

  return (
    <div className="Card">
      <h1>{title}</h1>
      <span>{description}</span>
    </div>
  );
};

export default Todo;

The Todo component is responsible for the display of a Todo object. It receives the data of type Itodo and then uses destructuring (JavaScript expression for unpacking values from arrays or objects into distinct variables.) to pull out the title and the description of the Todo.

components/AddTodo.ts

import * as React from "react";
import { ApolloCache } from "@apollo/react-hooks";
import { FetchResult } from "apollo-boost";

import { useTodoMutation } from "../useRequest";
import { ADD_TODO, GET_TODOS } from "../graphql";
import { ITodo, ITodoMutation, ITodos } from "../types/Todo";

const AddTodo: React.FC = () => {
  const [formData, setFormData] = React.useState<ITodo | {}>();
  const [addTodo] = useTodoMutation(ADD_TODO);

  const handleForm = (e: React.FormEvent<HTMLInputElement>) => {
    setFormData({
      ...formData,
      [e.currentTarget.id]: e.currentTarget.value
    });
  };

  const handleSaveTodo = (
    e: React.FormEvent,
    { title, description }: ITodo | any
  ) => {
    e.preventDefault();
    addTodo({
      variables: { title, description },
      update: (
        cache: ApolloCache<ITodoMutation>,
        { data: { addTodo } }: FetchResult<ITodoMutation>
      ) => {
        const cacheData = cache.readQuery({ query: GET_TODOS }) as ITodos;
        cache.writeQuery({
          query: GET_TODOS,
          data: {
            getTodos: [...cacheData.getTodos, addTodo]
          }
        });
      }
    });
  };

  return (
    <form className="Form" onSubmit={(e) => handleSaveTodo(e, formData)}>
      <div>
        <div>
          <label htmlFor="name">Title</label>
          <input onChange={handleForm} type="text" id="title" />
        </div>
        <div>
          <label htmlFor="description">Description</label>
          <input onChange={handleForm} type="text" id="description" />
        </div>
      </div>
      <button>Add Todo</button>
    </form>
  );
};

export default AddTodo;

After importing the useTodoMutation hook into our component, we pass in the GraphQL mutation query ADD_TODO as an argument. Next, we handle the data entered by the user with the handleForm function and useState. Once the user submits the form, we call the addTodo method to create the Todo with the mutation query. To preview the Todo created, we need to update the Apollo cache by spreading the old Todos with the new one in an array of Todos.

We are now able to create and display a list of Todos. Finally, let’s put it all together and use the components in the App.ts file.

Showing the Todos

App.ts

import * as React from "react";
import "./styles.css";

import { GET_TODOS } from "./graphql";
import { useTodoQuery } from "./useRequest";
import AddTodo from "./components/AddTodo";
import Todo from "./components/Todo";
import { ITodo } from "./types/Todo";

const App: React.FC = () => {
  const { loading, error, data } = useTodoQuery(GET_TODOS);

  if (loading) return <h1>Loading...</h1>;
  if (error) return <h1>Something went wrong!</h1>;

  return (
    <div className="App">
      <h1>My Todos</h1>
      <AddTodo />
      {data.getTodos.map((todo: ITodo) => (
        <Todo key={todo.id} todo={todo} />
      ))}
    </div>
  );
};

export default App;

In this App component, we use the useTodoQuery hook to retrieve all Todos from the GraphQL API. Next, we loop through the response data and display it using the Todo component.

With this step, the app is ready to be tested on the browser. Open the project directory in the CLI and run this command:

yarn start

npm start

If everything works as expected, you should be able to see the React app here: http://localhost:3000/.

app-preview

And that’s it! Our React app is looking good!

We’ve built a Todo App with React, TypeScript, GraphQL, and Apollo Client. You can preview the finished project in this CodeSandbox.

Conclusion

In this tutorial, we learned how to use GraphQL on the client-side with React, TypeScript, and Apollo Client. We also used the GraphQL API built with TypeGraphQL as a backend to finish up with a full-stack strongly-typed app. A very exciting stack to try on your next project!

Resources

Check out these resources to dive deeper into the content of this tutorial:

How to use TypeScript with GraphQL

Ibrahima Ndaw — Mon, 25 Jan 2021 22:01:27 +0000

GraphQL is a powerful query language that allows you to build flexible APIs. It lets you define a type system for your data, so when you execute a query, it returns only the data you need.

GraphQL can offer a better developer experience when used with TypeScript because they are both typed language. TypeScript is a typed superset of JavaScript that extends it by adding types. So, using these technologies together will certainly help you to build predictable and strongly-types APIs.

In this tutorial, I will first explain why combining such technologies, and then show you how to use TypeScript with GraphQL by building an API from scratch using TypeGraphQL.

Prerequisites

This tutorial assumes that you have some experience using TypeScript, particularly TypeScript classes and decorators. Knowledge of GraphQL will come in handy but is not mandatory.

In this guide, we will be using TypeGraphQL, which is a modern framework for building GraphQL API using Node.js and TypeScript.

Why use TypeScript with GraphQL

TypeScript is a popular programming language developed and maintained by Microsoft. It is a superset of JavaScript that uses static type-checking to make your code predictable.

Over the years, TypeScript has proven to be a valuable language for large codebases. TypeScript enhances code quality with its types, which adds many benefits, such as robustness, understandability, and predictability.

GraphQL solves the problem of over-fetching or under-fetching APIs. It provides one single endpoint for all requests using a Post method to get exactly the data you need, nothing more and nothing less. In this way, GraphQL makes your queries flexible, and your API readable and easy to learn.

TypeScript and GraphQL both rely on types to make your code understandable. However, GraphQL types can only be defined in a GraphQL schema using the method buildSchema or a file with .gql extension. The GraphQL types are not supported on GraphQL resolvers because resolvers are just regular JavaScript functions, not GraphQL code. TypeScript solves this issue because, as we mentioned earlier, it’s a superset of JavaScript. So, It can set types on the GraphQL resolvers. This is the reason why using TypeScript along with GraphQL makes sense.

GraphQL handles the types for the GraphQL schemas, and TypeScript sets the types on the GraphQL resolvers. However, because you are handling multiple languages, building strongly-typed APIs using Node.js, GraphQL, and TypeScript can be a challenge to maintain.

Maintaining consistency between your schema and resolvers is what TypeGraphQL intends to solve. TypeGraphQL allows you to use TypeScript classes and decorators to create the schema, types, and resolvers of your API. It uses TypeScript to build the entire GraphQL API.

illustration

So far, we have learned why pairing TypeScript with GraphQL can be useful and why TypeGraphQL is handy for building and maintaining GraphQL APIs that use TypeScript.

Without further ado, let’s dive into the practice part and build up the GraphQL API using TypeGraphQL.

Setting up

To use TypeScript and GraphQL, we first need to create a new Node.js app.

Open your command-line interface (CLI) and run this command:

yarn init

Or for npm

npm init

You’ll need to respond to a few configuration questions which will emit a package.json file. Next, install the dependencies needed for this tutorial.

yarn add express apollo-server-express graphql reflect-metadata type-graphql class-validator

For npm

npm install express apollo-server-express graphql reflect-metadata type-graphql class-validator

We will break these packages down later and explain what they do. For now, let’s install their types so TypeScript can understand the libraries.

yarn add -D @types/express @types/node nodemon

npm install -D @types/express @types/node nodemon

Note that we installed nodemon as well to enable live-reloading whenever a change occurs.

Here’s what each of the installed libraries do:

express is a minimalist web framework for Node.js
apollo-server-express is a middleware that allows using express in an Apollo GraphQL server.
reflect-metadata enables TypeScript decorators to add the ability to augment a class and its members when the class is defined. It’s a dependency of TypeGraphQL.
class-validator allows TypeGraphQL to use decorator and non-decorator based validation.

Next, we need to structure the project as follows:

src
| ├── resolvers
| |  └── todoResolver.ts
| └── schemas
| |  └── Todo.ts
| └── index.ts
├── tsconfig.json
├── package.json
└── yarn.lock

Here, there are four files to underline:

The entry point of the server (index.ts).
The schemas folder that contains the GraphQL Schema of the project.
The resolvers folder that holds the resolvers of the API.
The tsconfig.json file tells to TypeScript how to compile the code.

With this in place, we can now add a script to start the server in the package.json file.

"scripts": {
  "start": "nodemon --exec ts-node src/index.ts"
}

This script will start the server using nodemon. And whenever our code is updated, it will restart.

Let’s now configure the tsconfig.json.

{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
  }
}

These two properties should be set to true to be able to use TypeScript decorators in the project.

We can now build a GraphQL Schema for the API.

Build the GraphQL Schema

TypeGraphQL allows you to build a schema using TypeScript classes and decorators. It’s just syntactic sugar because under the hood TypeGraphQL will still generate regular GraphQL code. We will see the code generated later - for now, let’s create the schema.

schemas/Todo.ts

import { Field, ObjectType, InputType } from ‘type-graphql’

@ObjectType() export class Todo {
  @Field() id: number
  @Field() title: string
  @Field() description: string
  @Field() status: boolean
}

@InputType() export class TodoInput implements Partial {
  @Field() title: string
  @Field() description: string
}

At the first the syntax might look weird, however, it’s relatively simple to understand. It’s just TypeScript decorators and classes.

Here, the @ObjectType() provided by TypeGraphQL enables creating a new object or schema. The Todo class reflects the shape of a Todo object, and the TodoInput defines the expected data for adding a new Todo.

Now, let’s write the same code using GraphQL.

type Todo {
  id: ID!
  title: String!
  description: String!
  status: Boolean!
}

input TodoInput {
  title: String!
  description: String!
}

As you can see, the logic is the same. The only difference is that here, we don’t use TypeScript.

Now we’re ready to create our GraphQL resolvers.

Create the GraphQL resolver

Unlike GraphQL, TypeGraphQL puts the GraphQL query or mutation in the resolvers. The name of the function will be used as an endpoint when querying or mutating data.

resolvers/todoResolver.ts

import { Query, Resolver, Mutation, Arg } from ‘type-graphql’;
import { Todo, TodoInput } from ‘../schemas/Todo’;

@Resolver((of) => Todo) export class TodoResolver { 
    private todos: Todo[] = []

    @Query((returns) => [Todo], { nullable: true })
    async getTodos(): Promise<Todo[]> {
        return await this.todos
    }

    @Mutation((returns) => Todo)
    async addTodo(
        @Arg('todoInput') { title, description }: TodoInput
    ): Promise<Todo> {
        const todo = {
            id: Math.random(), // not really unique
            title,
            description,
            status: false,
        }

        await this.todos.push(todo)
        return todo
    }
}

Here, we use the Resolver decorator to create a new GraphQL resolver that returns a Todo. Next, we build a GraphQL query to fetch all Todos.

After that, we define a mutation query that expects a title, and a description to add a new Todo on the array of data.

By the way, you don’t need to use async/await here, because this won’t take time to complete. But, I add it here for reference when you need to deal with a real server.

Let’s now convert the code to GraphQL.

type Mutation {
  addTodo(todoInput: TodoInput!): Todo!
}

type Query {
  getTodos: [Todo!]
}

With this in place, we can build the server that uses the schema and resolver we’ve just created.

Create the Server

src/index.ts

import ‘reflect-metadata’;
import { ApolloServer } from ‘apollo-server-express’;
import * as Express from ‘express’ import { buildSchema } from ‘type-graphql’;
import { TodoResolver } from ‘./resolvers/todoResolver’;

async function main() { const schema = await buildSchema({ resolvers: [TodoResolver], emitSchemaFile: true, })

    const app = Express()

    const server = new ApolloServer({
        schema,
    })

    server.applyMiddleware({ app })

    app.listen(4000, () =>
        console.log('Server is running on http://localhost:4000/graphql')
    )

}

main()

As you can see here, we import TodoResolver, which needs to be passed as a resolver to the buildSchema method. With that, TypeGraphQL can build a new GraphQL Schema based on the Todo resolver.

Next, we pass the schema object (it contains the GraphQL schemas and resolvers) to Apollo to create the server.

Setting the property emitSchemaFile: true allows TypeGraphQL to generate a schema.gql file at build-time.

Let’s check if the app works. Run the following command:

yarn start

npm start

Visit http://localhost:4000/graphql, and then add this code block below to GraphQL Playground to create a new Todo.

mutation {
  addTodo(todoInput: { title: "Todo 1", description: "This is my todo" }) {
    title
    description
    status
  }
}

The Todo object should be created successfully!

todo-created

Now query for the newly created Todo using the following GraphQL query.

{
  getTodos {
    title
    description
    status
  }
}

You should see that all Todos have been returned.

all-todos

Great! Our app looks good.

We have now finished building a GraphQL API using TypeScript.

You can find the finished project in this Github repo

Thanks for reading

GraphQL in TakeShape

TakeShape provides a flexible GraphQL API to manage your content easily. It gives you the ability to immediately see how changes to your content model will impact your API using the API Explorer. You don’t have to build any backend on your own, everything is set up for you. TakeShape automatically generates a secure GraphQL API to expose all of your content and services.

Next steps

Check out these resources to dive deeper into the content of this tutorial:

Scalable APIs with GraphQL and Netlify Functions

Ibrahima Ndaw — Fri, 22 Jan 2021 15:36:49 +0000

In this tutorial, we will be exploring serverless functions by learning how to use them with GraphQL to build scalable APIs.

What is serverless?

A serverless function is a way for adding a backend to your app without managing a server, virtual machine, or docker container. Behind every serverless function invocation is a server hosted and managed by a cloud provider such as AWS, Google Cloud, Netlify, Vercel, and so on. The providers are abstracting away a lot of the complexity so you can focus on just what your function needs to do. Serverless functions are basically functions-as-a-service.

What we’re building

In this tutorial, we will be using Netlify Functions, which are built on top of AWS Lambda Functions. We’ll be building a Project Tracker with GraphQL, serverless functions, and Airtable. We will be using The Airtable API to create and retrieve projects. Let’s get started!

Setting up

Before we get into creating a new lambda function, we need to sign up for an Airtable account to be able to use it as a DB. After you create an account, open your command-line interface and running the following:

npm install netlify-cli -g

This command will install Netlify CLI, which we will us to create a new serverless function. Next we need to set up our project, execute the following:

mkdir functions && touch netlify.toml

The command will first create a new folder named functions then will create a new file netlify.toml at the root. Netlify uses this file to configure the resources you’ll be using, in this case functions. With this in place, add the following code below to netlify.toml.

// netlify.toml

[build]
    functions = "functions"

These two lines tell Netlify that our serverless functions live in a folder named functions. Now, open your CLI and make sure to be in the folder that contains the functions folder.

netlify functions:create serverless-graphql

The Netlify CLI will prompt you with options to choose between several ready to use templates. Choose the one named >[apollo-graphql] GraphQL function using Apollo-Server-Lambda!. It’s the starter for the serverless function that uses Apollo GraphQL. Once the project is initialized, cd into the functions folder, then install the Airtable SDK.

npm install airtable

Next, create a .env file at the root of the project and replace the variables with your credentials.

// .env

AIRTABLE_API_KEY=<your-api-key>
AIRTABLE_BASE_ID=<your-table-base-id>
AIRTABLE_TABLE_NAME=<your-table-name>

AIRTABLE_API_KEY is your API key on your Airtable account.
AIRTABLE_BASE_ID is the id of your DB table (see here).
AIRTABLE_TABLE_NAME is the name given to your table.

With our setup and configuration complete, we can dive into coding our serverless function.

Building the serverless function with GraphQL

First, structure the project like so:

functions
├── graphql.js
├── utils
|  └── airtable.js
└── package.json

As you can see, the logic to interact with Airtable is holden by the file airtable.js. The entry point of the serverless function is graphql.js.

Connecting with Airtable

Let’s add the code below to the file airtable.js.

// utils/airtable.js

const Airtable = require('airtable')

const { AIRTABLE_API_KEY, AIRTABLE_BASE_ID, AIRTABLE_TABLE_NAME } = process.env

const base = new Airtable({ apiKey: AIRTABLE_API_KEY }).base(AIRTABLE_BASE_ID)

const table = base(AIRTABLE_TABLE_NAME)

const getAllProjects = async () => {
  const allProjects = await table.select({}).firstPage()
  return allProjects.map(({ id, fields }) => transformResponse(id, fields))
}

const addProject = async ({ project }) => {
  const { name, description, date } = project
  const createProject = await table.create([
    {
      fields: {
        name,
        description,
        date,
        status: 'In progress',
      },
    },
  ])
  const { id, fields } = createProject[0]
  return transformResponse(id, fields)
}

const transformResponse = (id, fields) => ({
  id,
  name: fields.name,
  description: fields.description,
  date: fields.date,
  status: fields.status,
})

exports.getAllProjects = getAllProjects
exports.addProject = addProject

Airtable allows us to connect our app to Airtable with the credentials passed in as arguments to it. After that, we initialize the DB table with the table constant.

Next, we retrieve all projects from Airtable using the function getAllProjects(). To add a new project, we rely on the method addProject(), which receives the object to add as a parameter. Finally, we use the method table.create() to persist the data on the DB.

Now, we have the functions needed to add and fetch the projects from Airtable. Let’s use them in the file graphql.js to perform the queries.

Creating the API with GraphQL

// graphql.js

const { ApolloServer, gql } = require('apollo-server-lambda')
const { getAllProjects, addProject } = require('./utils/airtable')

const typeDefs = gql`
  type Project {
    id: ID
    name: String
    description: String
    date: String
    status: String
  }
  input ProjectInput {
    name: String
    description: String
    date: String
  }
  type Query {
    getProjects: [Project]
    addProject(project: ProjectInput): Project
  }
`

const resolvers = {
  Query: {
    getProjects: () => {
      try {
        const allRecords = getAllProjects()
        return allRecords
      } catch (error) {
        throw new Error(error)
      }
    },
    addProject: (_, args) => {
      try {
        const createProject = addProject(args)
        return createProject
      } catch (error) {}
    },
  },
}

const server = new ApolloServer({
  typeDefs,
  resolvers,
})

const handler = server.createHandler()

module.exports = { handler }

If you have experience with Apollo Server, you should already notice that the library used here (apollo-server-lambda) is different from the one used for building servers. This package uses middleware to inject our lambda serverless function to Apollo Server.

Next , we import the functions getAllProjects and addProject from airtable.js. With this, we can define a new GraphQL Schema using gql. The query getProjects has to return an array of type Project. The method addProject expects an object of type ProjectInput as a parameter and should return a value that reflects the Project type.

Any GraphQL Schema has to have a GraphQl resolver that corresponds to it. That’s why, here, we have on the resolvers object, the functions getProjects() and addProject(). The first fetch all projects from Airtable and the second add a new object to the table.

Now, we have a schema and a resolver. We need to pass in the values to the constant server to let it handle the request when the endpoint /graphql is hit.

Testing the GraphQL API

With this step, the serverless app is ready to be tested in the browser. So, begin by browsing to the root of the project and running this command:

netlify dev

Our serverless function should be up and running and accessible here:

The app will land on the GraphQL Playground. It’s a neat tool built on top of GraphiQL. It’s a GraphQL IDE for sending queries or mutations, exploring the API docs, sending HTTP headers, and more.

http://localhost:8888/.netlify/functions/graphql

Now, add this code block below to create a new project.

mutation {
  addProject(project: { name: "My first project", description: "First project's description", date: "2020-12-11" }) {
    name
    description
    date
    status
  }
}

After sending the query, you should see this:

create-post

{
  getProjects {
    id
    name
    description
    date
    status
  }
}

Once all projects are fetched, the result should look like this:

get-all-posts

Next steps

Awesome! Our serverless function is looking nice. We’ve built a GraphQL API using serverless functions and Airtable. Let’s now deploy it to Netlify!

To do so, we first need to sign up here. Then, initialize our app with git. Make sure to be at the root of the project before executing the following.

git init

Add a .gitignore file at the root of the project.

touch .gitignore

Add this code block to ignore the files listed below when adding changes to git.

// .gitignore

/functions/node_modules
/functions/.env

Add and commit changes to git.

git add -A && git commit -m 'Ready to deploy on Netlify'

Create a new repository on Github and follow the steps to push your project. Next, go to Netlify and connect your Github repo. Move the package.json file to the root of the project, then create the environment variables on Netlify.

Deploy your serverless functions. We can now preview and interact with our app here: https://graphql-airtable.netlify.app/.netlify/functions/graphql

You can find the finished project in this Github repo. Thanks for reading!

Conclusion

Serverless is an exciting piece of technology. It allows us to build up a backend quickly without the hassle of managing a server, which brings us to the JAMStack. An architecture designed to make the web faster, more secure, and easier to scale with static sites and serverless functions.

Unit Testing Your Gatsby Site with Jest and React Testing library

Ibrahima Ndaw — Thu, 21 Jan 2021 21:15:40 +0000

Testing is a crucial piece when it comes to building websites or apps. It gives you more confidence in your product, makes your code better, and helps to avoid unexpected bugs in production.

In this tutorial, we will introduce you to unit testing by showing you how to test your Gatsby site with Jest and the React Testing Library. Let's get started.

Creating a new Gatsby app

To keep us focused on testing, we’ll use an out of the box Gatsby starter template. To use a Gatsby starter, begin by opening your command-line interface (CLI) and run this command:

npx gatsby new my-blog-starter https://github.com/gatsbyjs/gatsby-starter-blog

Note - If you have the Gatsby CLI installed on your machine, you can omit *npx*.

Next we will set up the testing environment. Unlike React, Gatsby does not ship with Jest or React Testing Library, so we’ll install those now.

Setting up our testing environment

Execute the command on the CLI to install the libraries needed for testing a Gatsby site.

NPM

npm install -D jest babel-jest @testing-library/jest-dom @testing-library/react babel-preset-gatsby identity-obj-proxy

Yarn

yarn add -D jest babel-jest @testing-library/jest-dom @testing-library/react babel-preset-gatsby identity-obj-proxy

With the dependencies installed, we can now create a new folder (tests) at the root of the project. The directory structure should look like this:

    tests
    ├── jest-preprocess.js
    ├── setup-test-env.js
    └── __mocks__
        ├── file-mock.js
        └── gatsby.js

With the folder structure in place, next we configure Jest. Let's begin with jest-preprocess.js

    // tests/jest-preprocess.js
    const babelOptions = {
      presets: ["babel-preset-gatsby"],
    }
    module.exports = require("babel-jest").createTransformer(babelOptions)

This config tells Gatsby how to compile our tests with Babel because both Gatsby and Jest use modern JavaScript and JSX.

    // tests/setup-test-env.js
    import "@testing-library/jest-dom/extend-expect"

As you can see, this file allows us to import jest-dom in one place and then use it on every test file.

    // tests/__mocks__/file-mock.js
    module.exports = "test-file-stub"

If you need to mock static assets, then this file is required to do so. We won't have that use-case, but be aware of what it does.

    // tests/__mocks__/gatsby.js
    const React = require("react")
    const gatsby = jest.requireActual("gatsby")
    module.exports = {
      ...gatsby,
      graphql: jest.fn(),
      Link: jest.fn().mockImplementation(
        // these props are invalid for an `a` tag
        ({
          activeClassName,
          activeStyle,
          getProps,
          innerRef,
          partiallyActive,
          ref,
          replace,
          to,
          ...rest
        }) =>
          React.createElement("a", {
            ...rest,
            href: to,
          })
      ),
      StaticQuery: jest.fn(),
      useStaticQuery: jest.fn(),
    }

This file allows us to mock some Gatsby features in order to query data with GraphQL or use the Link component. Make sure to name the folder __mocks__ and the file gatsby.js — otherwise, Gatsby will throw errors.

With this configuration in place, we can dive into Jest and customize it to follow our needs. Let's begin by creating a jest.config.js file in the root of the project and then add this code below.

    // jest.config.js
    module.exports = {
      transform: {
        "^.+\\.jsx?$": `<rootDir>/tests/jest-preprocess.js`,
      },
      moduleNameMapper: {
        ".+\\.(css|styl|less|sass|scss)$": `identity-obj-proxy`,
        ".+\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$": `<rootDir>/tests/__mocks__/file-mock.js`,
      },
      testPathIgnorePatterns: [`node_modules`, `\\.cache`, `<rootDir>.*/public`],
      transformIgnorePatterns: [`node_modules/(?!(gatsby)/)`],
      globals: {
        __PATH_PREFIX__: ``,
      },
      setupFilesAfterEnv: ["<rootDir>/tests/setup-test-env.js"],
    }

This file can look confusing at first, but it's relatively easy to grasp. Let's break it down:

transform use Babel to compile the JSX code.
moduleNameMapper mock the static assets.
testPathIgnorePatterns exclude the folders listed in the array when running the tests.
transformIgnorePatterns exclude the folders listed in the array when transforming the JSX code.
globals indicate to Jest the folders to test.
setupFilesAfterEnv import jest-dom before test runs.

The last step of the config consists of tweaking the package.json file to run Jest with the CLI.

    // package.json
      "scripts": {
        "test": "jest"
      }

Phew! The setting up is complete. Let's now start writing our tests in the next section.

Writing the unit tests

Unit testing is a method that ensures that a section of an application behaves as intended.
In this article, we will be testing the SEO component and the Home page (index.js). Let's structure the folder as follows:

    src
    ├── components
    | ├── seo.js
    | ├── bio.js
    | ├── layout.js
    | └── __tests__
    | |    |   └── seo.js
    ├── pages
    | ├── 404.js
    | ├── index.js
    | └── __tests__
    | |    |   └── index.js

You can use .spec or .test to create a testing file or put the files in the __tests__ folder. Jest will only execute the files under the __tests__ folder.

    // components/seo.js
    import React from "react"
    import PropTypes from "prop-types"
    import { Helmet } from "react-helmet"
    import { useStaticQuery, graphql } from "gatsby"

    const SEO = ({ description, lang, meta, title }) => {
      const { site } = useStaticQuery(
        graphql`
          query {
            site {
              siteMetadata {
                title
                description
                social {
                  twitter
                }
              }
            }
          }
        `
      )

      const metaDescription = description || site.siteMetadata.description
      const defaultTitle = site.siteMetadata?.title

      return (
        <Helmet
          htmlAttributes={{
            lang,
          }}
          title={title}
          titleTemplate={defaultTitle ? `%s | ${defaultTitle}` : null}
          meta={[
            {
              name: `description`,
              content: metaDescription,
            },
            {
              property: `og:title`,
              content: title,
            },
            {
              property: `og:description`,
              content: metaDescription,
            },
            {
              property: `og:type`,
              content: `website`,
            },
            {
              name: `twitter:card`,
              content: `summary`,
            },
            {
              name: `twitter:creator`,
              content: site.siteMetadata?.social?.twitter || ``,
            },
            {
              name: `twitter:title`,
              content: title,
            },
            {
              name: `twitter:description`,
              content: metaDescription,
            },
          ].concat(meta)}
        />
      )
    }

    SEO.defaultProps = {
      lang: `en`,
      meta: [],
      description: ``,
    }

    SEO.propTypes = {
      description: PropTypes.string,
      lang: PropTypes.string,
      meta: PropTypes.arrayOf(PropTypes.object),
      title: PropTypes.string.isRequired,
    }

    export default SEO

Now, let's write the unit tests for the SEO component.

    // components/__tests__/seo.js
    import React from "react"
    import { render } from "@testing-library/react"
    import { useStaticQuery } from "gatsby"

    import Helmet from "react-helmet"
    import SEO from "../seo"

    describe("SEO component", () => {
      beforeAll(() => {
        useStaticQuery.mockReturnValue({
          site: {
            siteMetadata: {
              title: `Gatsby Starter Blog`,
              description: `A starter blog demonstrating what Gatsby can do.`,
              social: {
                twitter: `kylemathews`,
              },
            },
          },
        })
      })

      it("renders the tests correctly", () => {
        const mockTitle = "All posts | Gatsby Starter Blog"
        const mockDescription = "A starter blog demonstrating what Gatsby can do."
        const mockTwitterHandler = "kylemathews"

        render(<SEO title="All posts" />)
        const { title, metaTags } = Helmet.peek()

        expect(title).toBe(mockTitle)
        expect(metaTags[0].content).toBe(mockDescription)
        expect(metaTags[5].content).toBe(mockTwitterHandler)
        expect(metaTags.length).toBe(8)
      })
    })

We start by importing React Testing Library, which allows rendering the component and giving access to DOM elements. After that, we mock the GraphQL query with useStaticQuery to provide the data to the SEO component.

Next, we rely on the render method to render the component and pass in the title as props. With this, we can use Helmet.peek() to pull the metadata from the mocked GraphQL query.

Finally, we have four test cases:

It tests if the title from the metadata is equal to All posts | Gatsby Starter Blog.
It checks if the description from the metadata is equal to A starter blog demonstrating what Gatsby can do..
It tests if the twitter from the metadata is equal to kylemathews.
It checks if the length of the metaTags array is equal to 8.

To run the tests, we have to execute this command on the CLI.

npm test

Or, for yarn

yarn test

All tests should pass as expected by showing some nice green sticks on the CLI.

    // pages/index.js

    import React from "react"
    import { Link, graphql } from "gatsby"

    import Bio from "../components/bio"
    import Layout from "../components/layout"
    import SEO from "../components/seo"

    const BlogIndex = ({ data, location }) => {
      const siteTitle = data.site.siteMetadata?.title || `Title`
      const posts = data.allMarkdownRemark.nodes
      if (posts.length === 0) {
        return (
          <Layout location={location} title={siteTitle}>
            <SEO title="All posts" />
            <Bio />
            <p>
              No blog posts found. Add markdown posts to "content/blog" (or the
              directory you specified for the "gatsby-source-filesystem" plugin in
              gatsby-config.js).
            </p>
          </Layout>
        )
      }

      return (
        <Layout location={location} title={siteTitle}>
          <SEO title="All posts" />
          <Bio />
          <ol style={{ listStyle: `none` }}>
            {posts.map(post => {
              const title = post.frontmatter.title || post.fields.slug
              return (
                <li key={post.fields.slug}>
                  <article
                    className="post-list-item"
                    itemScope
                    itemType="http://schema.org/Article"
                  >
                    <header>
                      <h2>
                        <Link
                          data-testid={post.fields.slug + "-link"}
                          to={post.fields.slug}
                          itemProp="url"
                        >
                          <span itemProp="headline">{title}</span>
                        </Link>
                      </h2>
                      <small>{post.frontmatter.date}</small>
                    </header>
                    <section>
                      <p
                        data-testid={post.fields.slug + "-desc"}
                        dangerouslySetInnerHTML={{
                          __html: post.frontmatter.description || post.excerpt,
                        }}
                        itemProp="description"
                      />
                    </section>
                  </article>
                </li>
              )
            })}
          </ol>
        </Layout>
      )
    }

    export default BlogIndex
    export const pageQuery = graphql`
      query {
        site {
          siteMetadata {
            title
          }
        }
        allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
          nodes {
            excerpt
            fields {
              slug
            }
            frontmatter {
              date(formatString: "MMMM DD, YYYY")
              title
              description
            }
          }
        }
      }
    `

Notice that here, we use data-testid on some elements to be able to select them from the testing file. Let's write the unit tests for the home page.

    //pages/__tests__/index.js
    import React from "react"
    import { render } from "@testing-library/react"
    import { useStaticQuery } from "gatsby"

    import BlogIndex from "../index"

    describe("BlogIndex component", () => {
      beforeEach(() => {
        useStaticQuery.mockReturnValue({
          site: {
            siteMetadata: {
              title: `Gatsby Starter Blog`,
              description: `A starter blog demonstrating what Gatsby can do.`,
              social: {
                twitter: `kylemathews`,
              },
            },
          },
        })
      })
      it("renders the tests correctly", async () => {
        const mockData = {
          site: {
            siteMetadata: {
              author: "John Doe",
            },
          },
          allMarkdownRemark: {
            nodes: [
              {
                excerpt: "This is my first excerpt",
                fields: {
                  slug: "first-slug",
                },
                frontmatter: {
                  date: "Nov 11, 2020",
                  title: "My awesome first blog post",
                  description: "My awesome first blog description",
                },
              },
              {
                excerpt: "This is my second excerpt",
                fields: {
                  slug: "second-slug",
                },
                frontmatter: {
                  date: "Nov 12, 2020",
                  title: "My awesome second blog post",
                  description: "My awesome second blog description",
                },
              },
            ],
          },
        }

        const { getByTestId } = render(
          <BlogIndex data={mockData} location={window.location} />
        )

        const { nodes } = mockData.allMarkdownRemark
        const post1 = "first-slug-link"
        const post2 = "second-slug-desc"

        expect(getByTestId(post1)).toHaveTextContent(nodes[0].frontmatter.title)
        expect(getByTestId(post2)).toHaveTextContent(
          nodes[1].frontmatter.description
        )
        expect(nodes.length).toEqual(2)
      })
    })

As you can see, we start by mocking the GraphQL query. Next, we create the dummy data and then pass in the object to the BlogIndex component.

After that, we pull out getTestId from the render method, which enables us to select elements from the DOM. With this in place, we can now explain what the tests do:

It tests if the title of the Link component of the first article is equal to My awesome first blog post
It test if the description of the second article is equal to My awesome second blog description.
It tests if the array of articles is equal to 2.

Now, execute this command on the CLI.

npm test

Or, for yarn

yarn test

All unit tests should pass.
With this final step, we are now able to test our Gatsby site with Jest and React Testing Library. You can find the finished project in this Github repo.

Conclusion

In this tutorial, we learned how to test a Gatsby site with Jest and React Testing Library. Testing is often seen as a tedious process, but the more you dig into it, the more value you get on your app.

Portfolio Challenge: Layout and Animate a Swiss Style Poster

Richard Haines — Thu, 21 Jan 2021 15:51:26 +0000

Often times when im looking for layout inspiration I find myself checking out old graphic design books I have laying around the house or old movie posters, which I used to collect. I find that with posters the creator has to be clever with their use of space and this leads to some wonderful shapes and arrangements.

There is a website by the artist Mike Joyce called swissted.com that has a plethora of amazing posters with intricate and exciting layouts. I highly recommend checking it out if you want to get inspiration or just have a layout you want to practice.

This tutorial will cover the re-creation of a poster with straight up HTML, CSS and JavaScript. We'll use [GSAP](https://greensock.com/) to animate elements of our poster and also learn how to load a custom font. The poster in question can be seen below, it is created by Mike Joyce and taken from their site.

The finished project can be view here: css-grid-and-gsap-poster-layout.netlify.app.

The source code can be viewed here: github.com/molebox/css-grid-and-gsap-poster-layout

We are not going to need to install anything, open vscode (or your choice of IDE) and create the following:

A font folder
A styles folder. Inside here create an index.scss file
An index.html file
An index.js file

We'll be making use of an extension called live server, I suggest installing that as a vscode extension. It will enable you to check on your progress with live updates on every file save.

Html

Let's begin by scaffolding out our html page.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bring a poster to life with CSS grid and GSAP</t
itle>
    <link rel="stylesheet" href="./styles/index.css">
</head>
<body>
    <!-- main container -->
    <div class="outer-container">

        <!-- grid layout -->
        <main class="main-grid">

            <!-- the top info text -->
            <section class="info-section">

                <!-- text on the left -->
                <section class="section-left">

                </section>

                <!-- text on the right -->
                <section class="section-right">

                </section>

            </section>

            <!-- the main title section -->
            <section class="title-section">

                <!-- the main title -->
                <h1 class="title">pixies</h1>

                <!-- the subtitle -->
                <section class="subtitle">

                </section>

            </section>

            <!-- circles grid layout -->
            <section class="circles-grid">

            <!-- our circles will be added dynamically -->

            </section>

        </main>
    </div>

    <script src="index.js"></script>
</body>
</html>

We begin by linking our index.cssfile in the header and doing the same with our index.js at the bottom of the body tag. We have given our htmla basic structure of how we want the poster to be laid out.

Styling

Before we start implementing our classes to define how our poster will look we can do a global reset of the margin, padding and box size. We'll also add our posters colours as css variables so that we can access them within our file in differtent places without having to repeat ourselves.

/* global reset */
* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

:root {
    --white-color: #dee2d5;
    --green-color: #5ebd44;
}

Thinking about our poster we will want it to have the shape of a poster, that means that it wont take up the whole width of our viewport. The outer-container class will take care of sizing our poster.

outer-container

/* set this to the dimensions of an A4 sheet of paper */
.outer-container {
    max-width: 21cm;
    height: 100vh;
    margin: 0 auto;

    background-color: var(--green-color);
    overflow: hidden;
}

After a little googling I found that the size of an A4 sheet of paper is roughly 21cm so we set that to the width of our poster. We want it to be the height of the viewport and the margin centers our content. We have set the overflow to hidden as we will be doing some positioning later on and this will hide some of the overflowing elements.

main-grid

Looking at the poster we could go for a flexbox layout and use a direction of column, stacking all the elements vertically. That would be a viable solution, but to have a little more control over the size of each column and its placement we can instead use the grid. We are setting an explicit height on the top section and the title section then saying the rest (which is made up of the circles) should take up the rest of the available space, or 1 fractional unit.

.main-grid {
    display: grid;
    grid-template-rows: 50px 200px 1fr;
}

info-section

The top section of the poster, with the two paragraphs of text will also utilize the grid. Flexbox would indeed be a good solution here, we could have used justify-content: space-between and then a padding on the horizontal of each text section to push them to the edges of the pages but with some padding from the actual edge. In keeping with using grid however, we can use a nifty feature of the autocloumn size to set a defined width on the elements on the edges but an auto size in between, pushing the outer elements apart. The left and right section of text use flexbox with a direction of column.

.info-section {
    grid-row: 1;
    display: grid;
    grid-template-columns: 300px auto 300px;
    padding: 1em;

    p {
        font-size: 0.8em;
    }

    .section-left {
        grid-column: 1;
        display: flex;
        flex-direction: column;
        padding: 1em;
    }
    .section-right {
        grid-column: 3;
        display: flex;
        flex-direction: column;
        padding: 1em;
    }
}

title-section

We are on a roll with grid! Let's use another one. Here we will be defining the width of each text section whilst also setting the rows height to that of the given second section in the main-grid class. The subtitle, that is, the text on the right which is split into three rows, was a little more fiddly to get right. Our final result is ok but it's not 100% acurate.

Due to the size of the title text on the left we use a cheeky margin-top to push the three rows down a tad, this gives our eyes the impression that these three rows are centered to the big text on the left. That's not actually true due to the dots on the i raising the height of the title text.

.title-section {
    grid-row: 2;
    display: grid;
    grid-template-columns: 400px auto 300px;
    grid-template-rows: 200px;
    align-items: center;
    padding: 1em;
    height: 100%;

    .title {
        grid-column: 1;
        font-size: 10em;
        font-weight: 500;
        letter-spacing: 3px;

    }
    .subtitle {
        grid-column: 3;
        color: var(--white-color);
        display: flex;
        flex-direction: column;
        padding: 1em;
        font-size: 1.3em;
        font-weight: 100;
        justify-content: space-evenly;
        height: 150px;
        margin-top: 1em;
    }
}

circles-grid

Our final class is the most "complicated". If we take a look at the original poster we can count how many circles we see, it's an 11x11 grid. The repeat() function allows us to set a repeating pattern of sizes in one short statement. For the columns we are saying that there should be 11 columns, each taking up the available space until they reach each end of the perant container. We do the same for the rows except that we explicitly state the height of the rows so that the child elements sizing more closely resemble that of the original poster.

Remember we set the overflow: hidden on the outer-cointainer? Here we can see why. When looking at the original poster we can see the circles on the horizontal edges are cut off, they are semi-circles. Now, rather than creating some special semi-circle shapes we set the width of this section (this grid) to be slightly larger than the parent container, and by hiding the overflow we give the illusion that the circles are semi-circles contained within our bounderies.

We use another little trick with the before pseudo element to give the illusion that the top of the grid is cut off and thus the circles look like semi-circles. The pseudo element here is creating a 20px high block which has the same colour as the poster. It's got an absolute position and lays on top of the circles-grid.

The nested circle class is the base circle that will be used to generate a circle dynamically using JavaScript. The white-circle will be used as an override to colour the white circles on the poster.

.circles-grid {
    grid-row: 3;
    display: grid;
    grid-template-columns: repeat(11, 1fr);
    grid-template-rows: repeat(11, 65px);
    place-items: center;
    background-color: black;
    min-width: 23.5cm;
    position: relative;
    left: -5.25%;

    // add a pseudo element to cut off the top of the grid
    &:before {
        content: '';
        width: 100%;
        height: 20px;
        background-color: var(--green-color);
        position: absolute;
        top: 0;
    }

    .circle {
        border-radius: 50%;
        width: 60px;
        height: 60px;
        background-color: var(--green-color);
    }
    /* when we add this to the circle class it will override the bg-color */
    .white-circle {
        background-color:  var(--white-color);
    }
}

Adding the text to the Html

We can now add the text we see on the poster to our sections on the html page.

                        <!-- the top info text -->
            <section class="info-section">
                <!-- text on the left -->
                <section class="section-left">
                    <p>saturday</p>
                    <p>december 13 1986</p>
                    <p>9 pm over 21</p>
                </section>
                <!-- text on the right -->
                <section class="section-right">
                    <p>at the rat</p>
                    <p>528 commonwealth</p>
                    <p>boston, mass.</p>
                </section>

            </section>
            <!-- the main title section -->
            <section class="title-section">
                <!-- the main title -->
                <h1 class="title">pixies</h1>
                <!-- the subtitle -->
                <section class="subtitle">
                    <p>with</p>
                    <p>throwing muses</p>
                    <p>big dipper</p>
                </section>
            </section>

Bringing it all together

If you havent already, start the live server by clicking the go live that sits on the bottom of vscode. You will see that we have our top two section but no circles are displayed yet. That is because we are going to create then dynamically and have them whizz onto the poster using some gsap magic.

But before we go ahead and do that, let's add out cusomt font. If we check the swissed site we can read that Mike Joyce uses the same font for all the posters, Berthold Akzidenz-Grotesk. The font can be downloaded from here: www.azfonts.net/load_font/berthold-akzidenz-grotesk-be-medium.html. This will give you the font in ttf format. We will want to convert that to woff (see here and here) We can do the conversion online via fontsquirrel.com/tools/webfont-generator.

Now that we have our font in woff format we can drag both the woff and woff2 fonts to our font folder. Then inside the index.scss folder we can load the font using @font-face. We can then add the font family to the outer-containerclass which will cascade down to the elements that use text.

/* load font */
@font-face {
    font-family: 'berthold_akzidenz_grotesk_bRg';
    src: url('../font/berthold-akzidenz-grotesk-be-medium-webfont.woff2') format('woff2'),
         url('../font/berthold-akzidenz-grotesk-be-medium-webfont.woff') format('woff');
    font-weight: normal;
    font-style: normal;
}

.outer-container {
        ...other stuff
    font-family: 'berthold_akzidenz_grotesk_bRg';
}

Next we need to import gsap into our project. We'll use the CDN. At the bottom of the body tag add these two script tags above the script that imports our own js file.

<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.5.1/gsap.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.5.1/EasePack.min.js"></script>

index.js

We have created space for our circles on our poster, in fact we have even given them a lovely grid to sit in. But they don't exist yet, let's change that.

First we can grab a reference to our circel-grid then we will be creating an array of circles that matches the grid dimentions we specified earlier (11x11). From each element we will create a div and attach our circleclass.

// get the circle grid from the DOM
let circleGrid = document.querySelector(".circles-grid");

// create 121 (11x11) circle elements and attach the circle class
const circles = Array.from(Array(121)).map((circle) => {
    // create the circle as a div
    circle = document.createElement("div");
    // attach the css class
    circle.className = 'circle';
    return circle;
});

The next step is for us to figure out which circles will be white and which wont so that we get that triangle effect. I took the liberty of counting these out so you can relax! Lets add a new whiteCirclesIndices array to our file. We will use this by looping over our newly created circles array and checking if the indexes match up, if they do we will override the circle class with the white-circle class. We then add all of our circles to the circle-grid.

// the indexes of the circles to be displayed as white
const whiteCirclesIndices = [12,23,24,34,35,36,45,46,47,48,56,57,58,59,60,67,68,69,70,71,72,78,,79,80,81,82,83,84,,89,,90,91,92,93,94,95,96,100,101,102,103,104,105,106,107,108];

// add the circles to our circle grid
circles.forEach((circle, index) => {
    // loop over the indexes that should be white
    for (const whiteIndex of whiteCirclesIndices) {
        // if the circles index matches the white index then add the new css class to it. 
        if (whiteIndex === index) {
            circle.classList.add('white-circle')
        }
    }
    // add the circle to the grid
    circleGrid.append(circle)
})

If you have the live server running you should now see the correct font being used and the circles filling up their grid, with a white triangle formed on the left-center of the grid.

Animate!

Posters are cool to look at, but they don't do much else. Us being web devs, we can makes stuff move for no other reason apart from we want too and it will look cool. So lets bring our poster to life!

At the top of our index.js file get the gsap object formt he window. We will then create a timline. Because we are going to be running a few animations one after the other it makes sense to use a timeline as this will fire off the animations sequentially. We'll start be animating in our info-section , title and subtitle sections.

const {gsap} = window;

let TL = gsap.timeline({delay: 0.5});

...creatingCircles...

// animate the intro text down from the top
TL.from(".info-section", {
    y: window.innerHeight * -1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
})

// animate the title in from the left
TL.from(".title", {
    x: window.innerWidth * -1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
}, "-=1");

// animate the subtitle in from the right
TL.from(".subtitle", {
    x: window.innerWidth * 1,
    duration: 1.5,
    ease: 'elastic.out(1, 1)'
}, "-=1")

We use the timeline variable TL to target the class names of each section we want to animate. We use the from method as that means that we animate from the given values to their originally set positions. Notice the -=1 ? Our timeline runs each of our animations sequentially, that is, one after the other. What we are doing here is saying to the timeline that we want that animation to overlap the previous one by 1 second. This gives our animations a smoother, more natural feel.

Next up we can animate in the grid itself. This won't be anything fancy, a simple opacity will do. The reaosn for this is that in a second we are going to make our circles fly in from an angle and they will be flying onto a black square. It will look alot nicer if the black square appears around the same time they start flying in.

// gentle opacity animation of the grid background
TL.from(".circles-grid", {
    opacity: 0,
    duration: 2,
}, "-=1") // "-=1" will overlap the end of the last tween by 1 second. It makes them appear smoother

Lastly we will bring in our circles. We'll make use of the stagger animation which can take a grid of elements and animate them from which ever way you like. You can explicitly tell it what the grid dimentions are (which we will do) or you can let it guess, seeing as we know our grids dimentions we'll use them. The from property tells the stagger from where the animation should begin. I like random, you can play about with it. You options are:

center
end
edges
random

// stagger and animate in the circles from the bottom left of the poster
TL.from(".circle", {
    y: window.innerHeight * 1,
    x: window.innerWidth * -1,
    duration: 1.2,
    ease: "bounce.out",
    stagger: {
        grid: [11, 11],
        from: 'random',
        amount: 1.5
    }
}, "-=1")

The finished poster

Fin

That as they say, is that. I think we have created a fairly acurate representation of the poster. We have use css grid in different ways, including dynamically populating it. We have looked at how to add a cusotm font to our css and finally we have added some cool animations. This is a great foundation from which to start creating your own animated layouts, everything you have learnt here can be iterated on and scaled up for use in any project.