Estela Franco

The modern web can do more than you think

2025-04-17T00:00:00Z

This is the first post in a new series where I'll explore the native powers of the modern web and why they matter more than ever.

The web's not dead

No, the web's not dead. Far from it, it's just getting really good. Intrigued? Please continue reading.

Lately, I've found myself way more curious about what browsers can actually do. I've always loved the open nature of the web, and unless I absolutely have to, I don't want to install another app on my mobile. I'm tired (ok, tired is not the word I have in mind, but I'm trying to be polite) of being forced to download an app just to do a basic task. It's frustrating how many websites still assume you'll install their app to get the "real" experience, leaving the mobile web version slow, clumsy, or missing key features.

But here's the thing: it doesn't have to be that way.

Modern browsers have leveled up. The web now supports features that used to be exclusive to native apps such as offline storage, background sync, push notifications, or even installing apps to your home screen. And you can use all of it without the overhead of an app store, a native wrapper, or a multi-week dev cycle just to push a fix.

This series is all about those powerful browser features: what they are, why they matter, and how to use them to build fast, capable, user-friendly web apps.

Why this is important

The web has become a universal space, offering a significant advantage in accessibility. Unlike native apps that require users to find, download, and install specific software for their device, websites are by nature more open. A simple web address allows almost anyone with an internet connection to instantly access your content, making it easier to reach a wider audience and be more inclusive.

However, people expect more from the web now. They want fast loading, offline access, background updates, and smooth, native-feeling interactions.

And luckily, the browser is ready to deliver. We just need to start using it right.

What you'll learn in this series

I'll go hands-on with the tools that are evolving the web even beyond the typical "app feel". I'll show you how to leverage today's web capabilities to push the boundaries and unlock the full potential of the native web. Here's what's coming:

Native web APIs that rival native apps
App-like experience and offline capabilities (beyond PWAs)
Integration with hardware and OS
Progressive enhancement that actually works
Trustworthy UX using permissions & privacy controls
...and what's coming next in Chrome, Firefox, and friends

Conclusion

This isn't about replacing native apps. It's about knowing when you don't need one — and building smarter, leaner experiences on the platform that's already in every user's pocket.

And let's end this first chapter with a simple question: What actually makes a web app feel like a real app?

We'll explore that in Chapter 2.

Create a Blog with Eleventy and Storyblok

2024-05-13T00:00:00Z

This is the third post in a series of articles called "Eleventy and Storyblok" to learn how to use this combination to create a web project.

TL;DR: Too much text for you? Don't worry! You have all the code described in this tutorial in this template repository: https://github.com/guaca/11ty-storyblok-template/.

Keep in mind, however, that you will need to create your .env file with the proper variables described in this article for the template to work.

Now that you're familiar with why Eleventy + Storyblok is my ideal combination and how to seamlessly query data from Storyblok for use in an Eleventy project, it's time for the next exciting step: let's embark on creating a complete blog site using these two phenomenal technologies!

Creating the Blog Architecture in Storyblok

The desired blog content architecture has the following levels:

├── Homepage
├── articles
│   └── article-1
│   └── article-2
│   └── article-n
├── categories
│   └── category-1
│   └── category-2
│   └── category-n
└── authors
    └── author-1
    └── author-2
    └── author-n

So first you need to create a new site in Storyblok (you already learned how to do this in my previous article). Got it? Then let's create the data architecture and some initial content in it!

Removing the boilerplate content

Remove the default content that Storyblok adds when you create a new site. We will create the blocks and stories we need from scratch.

Creating the initial Blocks: Author and Category

Let's start by creating the Author type. To do this, go to the Block Library (which should be empty if you have deleted all the default blocks) tab and create a new block named Author. Select the option Content type block.

Let's edit it and define the required fields:

Name (text)
Bio (textarea)
Avatar (asset - images)

Remember to mark them as Required field if they are mandatory.

Let's repeat the process to create the Category type. Still in the Block Library, create a new Content type block type. In this case, the name is Category.

In this case, and to keep it simple for this tutorial, I have only defined one field called (surprise) Category.

Creating the first stories: Authors and Categories

Now that we have created two content types, let's create the first stories! To do that, go to the Content section (which should be empty) and create a new Folder.

Let's start with the Authors! During the definition of the folder, restrict the content type to Author. I also recommend you to check the Disable visual editor (Form only) as we won't use the visual editor in this tutorial.

You're now inside the (empty) Authors folder. Create a new Story. The pop-up will ask you for some basic data:

Name (required). Let's create the Author 1.
Slug (it's generated based on the name).
Parent folder. In this case, the Authors folder is the parent folder.
Content type (required). Select Author.

In the next screen, you will see the form with the fields that we defined when creating the Author type. Fill them and hit Save.

You can repeat the process and create some more authors. In my case, I have created another one, called (surprise) Author 2.

Let's now move on and create some Categories. You can repeat the process and create the Categories folder, which should be restricted to the Category content type. Remember to check the Disable visual editor (Form only) checkbox as we're not using this feature in this tutorial.

Now that you're inside the Categories folder, create a new story. In this case, it also asks you for some basic information:

Name (required). For this example, I'm super creative and I have created the Category One.
Slug (it's generated from the name).
Parent folder: Categories.
Content type: Select Category.
In the next screen, you will see the category form asking for the Category. In this basic example, this field is also Category One.

And what about the Articles?

Yes, I know. This is supposed to be a blog site, but I haven't covered the articles yet, right? That's because we're going step by step. And this is the step to start creating Articles.

Let's start by creating the Article content type. Remember how to do this? Correct! Go to the Block Library and create a new Block.

Technical name: Article.
Select block type: Content type block. And press Add Block.

Now edit it to add the fields.

Title: Text.
PublicationDate: Date/Time.
Author. And that's why we created the authors first! Choose the Single-Option type and choose the following source details:
- Source: stories
- Path to the folder of stories: authors/
- Restrict to content type: Author
Category. Similar to what we have done for Author. It is also a Single-Option type and these are the source details:
- Source: stories
- Path to the folder of stories: categories/
- Restrict to content type: Category
Body. Select Markdown, but check the Rich-text as default checkbox. This will allow you to have a WYSIWYG interface, but it will be saved (and served) as Markdown. As I mentioned in the first article of this series, Markdown is one of the template languages that you can use in your project. Therefore, choosing Markdown will be easier to manage than using the Richtext option.

And you already have the Article block created!

Let's now create the first article. Go to the Content section and create a new Folder called Articles:

Name: Articles.
Slug (it's generated from the Name).
Parent folder: Root.
Content type: Restrict content types to Articles

Once again, remember to disable the visual editor (Form only).

And now you will see the form to create your first article. You've seen that I am being very creative with the content I'm using in this new blog site, so you won't be surprised by my first article:

As you can see, the Author and Category were selected from the drop-down list.

You can repeat these steps to generate a few more articles. I have created a total of 3 articles for this tutorial.

Creating a Homepage

Last but not least, we need a homepage for our brand new blog site. You've seen how creative I've been with the rest of the content. So, the homepage can't be any different!

Let's create the Block first. As usual, go to the Block library and create a new one with the following information:

Technical name: Page (I used this, but feel free to use whatever works better for you).
Select block type: Content type block.

And now, let's define the fields:

Heading: Text.
Subtitle: Text.
Highlights: Multi-Options
- Source: Stories
- Path to folder of stories: articles/
- Restrict to content type: Article
- Minimum: 3
- Maximum: 5

So, our homepage will have a heading, a subtitle and a list of the top articles.

Let's now create the homepage content. Go to Content, create a new Story and the pop-up will ask you for some basic information:

Name (required)
Slug (it's generated from the name)
Parent folder: Root
Content type: Page

On the next screen, you will see the visual editor enabled. This is happening because Storyblok does offer to disable the visual editor when creating a Folder, but not when creating a Story. Let's disable it as we're not going to use it in this tutorial.

To do it, access the Entry configuration from the navbar above the visual editor. This will open a pop-up and you will see the Edit mode options. Check the Form-only one.

Ok, it looks easier this way, right? Let's fill the fields with my already-famous creative content:

Heading: This is the Homepage
Subtitle: Welcome to the homepage of this amazing web site!
Highlights: In my example, I created 3 articles and I will select them all. An important detail: it's a reordable drag-and-drop list, so feel free to sort them however you like.

And that's it! You have your headless CMS created and ready to generate new content.

Wait. And what about SEO?

If this question has crossed your mind, THANK YOU! Because we need more people who care about making our sites "SEO friendly" since the first stage of the project.

And if you haven't thought about it, don't worry. I'm here to add this topic just in time.

Create the SEO block

Let's go to the Block Library and create a new nestable block. Call it SEO. Define a minimum and maximum of 1 block.

Add the following fields:

title: text.
description: text.
canonical: text.
noindex: boolean. The default value will be disabled.
og_title: text.
og_description: text.
og_image: asset (image).

Add the SEO block to the other blocks

We want to be able to define the proper SEO and Social Media data for all the stories we have already created, so we need to add it to the related content types:

Article
Author
Category
Page

Once you've added the SEO block to them, you can access the content and add the SEO data:

Creating the Eleventy project

Alright, you've got the content, but now it's time to build the site that will put that content to use, right? The following steps will help you achieve the desired project structure:

├── src
│   └── _data
│   │    └── articles.js
│   │    └── authors.js
│   │    └── categories.js
│   │    └── home.js
│   │    └── metadata.json
│   └── includes
│   │    └── layouts
│   │    │    └── base.njk
│   │    └── footer.njk
│   │    └── head.njk
│   │    └── header.njk
│   └── public
│   │   └── css
│   │       └── styles.css
│   └── utils
│   │   └── storyblok.js
│   └── article-page.njk
│   └── articles-list.njk
│   └── author-page.njk
│   └── authors-list.njk
│   └── category-page.njk
│   └── categories-list.njk
│   └── index.njk
└── eleventy.js
└── .env
└── .gitignore
└── package.json

Setting up and configuring the Eleventy project

You already learned how to do this in my previous article, so I'll make it faster this time.

1. Create and access your project (and open it using VSCode)

mkdir myproject
cd myproject
code .

2. Create your package.json file in the root directory and paste the following lines:

{
 "scripts": {
   "build": "npx @11ty/eleventy",
   "start": "npx @11ty/eleventy --serve"
 },
 "devDependencies": {
   "@11ty/eleventy": "^2.0.1",
   "dotenv": "^16.4.1"
 }
}

3. Install dependencies

npm install

4. Create the `.env` file in the root directory

STORYBLOK_API_KEY="[your-storyblok-token-goes-here]"
DOMAIN="[your-website-domain-goes-here]"

5. Create the `eleventy.js` config file

require('dotenv').config()
module.exports = function (eleventyConfig) {
 // Add the .env domain as GlobalData to use in SEO meta data
 eleventyConfig.addGlobalData("domain", process.env.DOMAIN );
 // Add the current year ad GlobalData to use in the footer 
 eleventyConfig.addGlobalData("year", new Date().getFullYear())
 // Filter articles by Author slug
 eleventyConfig.addFilter("filterArticlesByAuthor", function(articles, authorFullSlug) {
   const filteredArticles = articles.filter(article => {
     return article.content.Author.fullSlug === authorFullSlug;
   });
   // Sort the filtered articles by PublicationDate in descending order
   filteredArticles.sort((a, b) => {
     return new Date(b.content.PublicationDate) - new Date(a.content.PublicationDate);
   });
   return filteredArticles;
 });
 
 // Filter articles by Category slug
 eleventyConfig.addFilter("filterArticlesByCategory", function(articles, categoryFullSlug) {
   const filteredArticles = articles.filter(article => {
     return article.content.Category.fullSlug === categoryFullSlug;
   });
   // Sort the filtered articles by PublicationDate in descending order
   filteredArticles.sort((a, b) => {
     return new Date(b.content.PublicationDate) - new Date(a.content.PublicationDate);
   });
   return filteredArticles;
 });

 // Sort the authors  by name: 
 eleventyConfig.addFilter("sortAuthorsByName", function(authors) {
   return authors.sort((a, b) => a.content.Name.localeCompare(b.content.Name));
 });

 // Pass Trhough Copy
 eleventyConfig.addPassthroughCopy({
   "./src/public/": "/",
 });

 return {
   dir: {
     input: 'src'
   },
 };
};

What have we done here? Let's go one by one:

Initializing dotenv This initial line populates env variables into process.env and makes it available in the config file.
Add Global Data We're adding the DOMAIN enviroment variable as Global Data, ensuring it's available throughout the project.
Filter articles by Author We've defined a new filter to retrieve articles authored by a specific author. This filter will be applied on the Author's page to list all articles authored by that individual. Additionally, the articles will be sorted by PublicationDate in descending order.
Filter articles by Category Similar to the previous filter, here we're filtering articles belonging to a specific Category. This filter will be utilized on the Category's page to list all articles within that particular Category. Once again, the articles are sorted by PublicationDate in descending order.
Sort authors by name This filter enables us to arrange the list of authors alphabetically by their names.

6. Create the `src > _data > metadata.json` file

{
   "title": "My site",
   "language": "en",
   "description": "Welcome to my blog site!",
   "image": "[fallback-image-for-social-media-goes-here]"
}

7. Create the `src > _includes > head.njk` file

<head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>{{ title or metadata.title }}</title>
 <link rel="stylesheet" href="/css/styles.css">
 <meta name="description" content="{{ description or metadata.description }}">
 <link rel="canonical" href="{{ canonical or domain+page.url }}">
 {% if noindex == "true" %}
   <meta name="robots" content="noindex">
 {% endif %}
 <meta property="og:title" content="{{ og_title or title or metadata.title }}">
 <meta property="og:description" content="{{ og_description or description or metadata.description }}">
 <meta property="og:image" content="{{ og_image or metadata.image }}">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="{{ og_title or title or metadata.title }}">
 <meta name="twitter:image" content="{{ og_image or metadata.image }}">
</head>

This might seem a bit overwhelming, right? It's because we're integrating Nunjucks variables and conditionals (using curly braces) with HTML tags. However, it's just as straightforward and incredible as you saw in the previous code.

For example <link rel="canonical" href="{{ canonical or domain+page.url }}"> generates a canonical link with the canonical URL sourced from the frontmatter data. If that's missing, it constructs a canonical URL by combining the domain (Global Data) with the URL of the current page. BOOM!

8. Create the `src > _includes > header.njk` file

<header>
 <nav class="header-nav">
   <a class="header-home" href="/">My site</a>
   <ul class="header-list">
       <li class="header-item"><a href="/articles/">Articles</a></li>
       <li class="header-item"><a href="/authors/">Authors</a></li>
       <li class="header-item"><a href="/categories/">Categories</a></li>
   </ul>
 </nav>
</header>

9. Create the `src > _includes > footer.njk` file

 <footer>
   © {{ year }} - All Rights Reserved
 </footer>

10. Create the `src > _includes > layouts > base.njk` file

<!DOCTYPE html>
<html lang="{{ metadata.language }}">
{% include "head.njk" %}
<body>
 {% include "header.njk" %}
 <main style="flex-grow:1;">
   {{ content | safe }}
 </main>
 {% include "footer.njk" %}
</body>
</html>

That seemed a bit weird, didn't it? Let's break it down step by step.

The lang attribute in the HTML comes from the metadata.json file, where we've set the language.
We utilize include to pull in the templates we've created (head, header and footer).

11. Create the `src > utils > storyblok.js` file

require('dotenv').config()
module.exports = async function fetchAPI(query, { variables, preview } = {}) {
   const res = await fetch("https://gapi.storyblok.com/v1/api", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Token: process.env.STORYBLOK_TOKEN,
       Version: "published",
     },
     body: JSON.stringify({
       query,
       variables,
     }),
   });
 
   const json = await res.json();
   if (json.errors) {
     console.error(json.errors);
     throw new Error("Failed to fetch API");
   }
   console.log(json.data)
   return json.data;
 }

This code may sound familiar because we've already covered it in the previous article. Remember, I'm using the published version, but you might opt for the draft version if this template isn't intended for a production site.

12. Create your `src > _data > articles.js` file.

It will generate the global articles data file, which you'll utilize to create your article pages. This is the code for this file:

const fetchAPI = require("../utils/storyblok.js");


module.exports = async function getArticles () {
 const data = await fetchAPI(`
 {
   ArticleItems {
     items {
       full_slug
       content {
         Body
         PublicationDate
         Title
         Author {
           name
           fullSlug
         }
         Category {
           name
           fullSlug
         }
         SEO
       }
     }
   }
 }  
 `);
 return data?.ArticleItems.items;
}

13. Create the `src > article-pages.njk` file

---
pagination:
   data: articles
   size: 1
   alias: article
permalink: "{{ article.full_slug }}/"
layout: layouts/base.njk
templateEngineOverride: njk,md
eleventyComputed: 
   title: "{{ article.content.SEO[0].title }}"
   description: "{{ article.content.SEO[0].description }}"
   canonical: "{{ article.content.SEO[0].canonical }}"
   noindex: "{{ article.content.SEO[0].noindex }}"
   og_title: "{{ article.content.SEO[0].og_title }}"
   og_description: "{{ article.content.SEO[0].og_description }}"
   og_image: "{{ article.content.SEO[0].og_image.filename }}"
---
<article>
   <h1>{{ article.content.Title }}</h1>
   <a href="/{{ article.content.Author.fullSlug }}">{{ article.content.Author.name }}</a>
   <span> - </span>
   <a href="/{{ article.content.Category.fullSlug }}">{{ article.content.Category.name }}</a>
   <p>{{ article.content.PublicationDate }}</p>
   <div>
       {{ article.content.Body | safe }}
   </div>
</article>

Yes, that's a lot of SEO and Social Media metadata, but it's necessary! You might be wondering why this data is under eleventyComputed instead of being set directly, like we did with permalink.

And that's a great question! We can only use variables and shortcodes in permalink and eleventyComputed. Therefore, we don't need to set the permalink under eleventyComputed, but the rest of the custom fields must be placed there to ensure they are dynamicly updated."

14. Create the `src > articles-list.njk` file

This template will list all the published articles.

---
permalink: "/articles/"
layout: layouts/base.njk
title: "Articles"
description: "This is the list of Articles"
---
<div>
   <h1>Articles</h1>
   <ul>
       {% for article in articles %}
       <li><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></li>
       {% endfor %}
   </ul>
</div>

15. Repeat steps 12 through 14, but this time creating the files related to `Authors`

Filename: src > _data > authors.js

const fetchAPI = require("../utils/storyblok.js");

module.exports = async function getAuthors () {
 const data = await fetchAPI(`
 {
   AuthorItems {
     items {
       full_slug
       content {
         Name
         Bio
         Avatar {
           filename
         }
         SEO
       }
     }
   }
 }
 `);
 return data?.AuthorItems.items;
}

Filename: src > author-page.njk

---
pagination:
   data: authors
   size: 1
   alias: author
permalink: "{{ author.full_slug }}/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ author.content.SEO[0].title }}"
   description: "{{ author.content.SEO[0].description }}"
   canonical: "{{ author.content.SEO[0].canonical }}"
   noindex: "{{ author.content.SEO[0].noindex }}"
   og_title: "{{ author.content.SEO[0].og_title }}"
   og_description: "{{ author.content.SEO[0].og_description }}"
   og_image: "{{ author.content.SEO[0].og_image.filename }}"
---

<div>
   <div class="author-info">
       <img class="author-avatar" src="{{ author.content.Avatar.filename }}">
       <h1 class="author-name">{{ author.content.Name }}</h1>
   </div>
       <p>{{ author.content.Bio }}</p>
   <h2>Articles by {{ author.content.Name }}</h2>
   
   {% set targetAuthorFullSlug = author.full_slug %}
   {% set filteredArticles = articles | filterArticlesByAuthor(targetAuthorFullSlug) %}
   <ul>
       {% for article in filteredArticles %}
           <li>
               <article>
                   <h3><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></h3>
                   <span>Publication Date: {{ article.content.PublicationDate }}</span>
               </article>
           </li>
       {% else %}
           <p>No articles found for this author.</p>
       {% endfor %}
   </ul>

</div>

Filename: src > authors-list.njk

---
permalink: "/authors/"
layout: layouts/base.njk
title: "Authors"
description: "This is the list of Authors"
---
<div>
   <h1>Authors</h1>
   <ul>
       {% for author in authors | sortAuthorsByName %}
       <li><a href="/{{ author.full_slug }}">{{ author.content.Name }}</a></li>
       {% endfor %}
   </ul>
</div>

16. Repeat steps 12 through 14, but this time creating files related to `Categories`

Filename: src > _data > categories.js

const fetchAPI = require("../utils/storyblok.js");

module.exports = async function getCategories () {
 const data = await fetchAPI(`
 {
   CategoryItems {
     items {
       full_slug
       content {
         Category
         SEO
       }
     }
   }
 }
 `);
 return data?.CategoryItems.items;
}

Filename: src > category-page.njk

---
pagination:
   data: categories
   size: 1
   alias: category
permalink: "{{ category.full_slug }}/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ category.content.SEO[0].title }}"
   description: "{{ category.content.SEO[0].description }}"
   canonical: "{{ category.content.SEO[0].canonical }}"
   noindex: "{{ category.content.SEO[0].noindex }}"
   og_title: "{{ category.content.SEO[0].og_title }}"
   og_description: "{{ category.content.SEO[0].og_description }}"
   og_image: "{{ category.content.SEO[0].og_image.filename }}"
---
<div>
   <h1>{{ category.content.Category }}</h1>

   {% set targetCategoryFullSlug = category.full_slug %}
   {% set filteredArticles = articles | filterArticlesByCategory(targetCategoryFullSlug) %}
   <ul>
       {% for article in filteredArticles %}
           <li>
               <article>
                   <h3><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></h3>
                   <span>Publication Date: {{ article.content.PublicationDate }}</span>
               </article>
           </li>
       {% else %}
           <p>No articles found for this category.</p>
       {% endfor %}
   </ul>
</div>

Filename: src > categories-list.njk

---
permalink: "/categories/"
layout: layouts/base.njk
title: "Categories"
description: "This is the list of Categories"
---
<div>
   <h1>Categories</h1>
   <ul>
       {% for category in categories %}
       <li><a href="/{{ category.full_slug }}">{{ category.content.Category }}</a></li>
       {% endfor %}
   </ul>
</div>

17. Create the `Home` related files

In this case, we need the Home id. You can find it using the GAPI browser, as I explained in my previous article.

Once you have the home id, add the variable in the .env file:

  STORYBLOK_API_KEY="[your-storyblok-token-goes-here]"
  DOMAIN="[your-website-domain-goes-here]"
+ HOME_ID="[your-home-id]"

Create the src > _data > home.js file and add the following code in it:

require('dotenv').config()
const fetchAPI = require("../utils/storyblok");

module.exports = async function getHome () {
 const data = await fetchAPI(`
 {
   PageItem(id: "${process.env.HOME_ID}") {
     content {
       Heading
       Subtitle
       Highlights {
         fullSlug
         name
         content
       }
       SEO
     }
   }
 }  
 `);
 return data?.PageItem;
}

Create the src > index.njk file:

---
pagination:
   data: home
   size: 1
permalink: "/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ home.content.SEO[0].title }}"
   description: "{{ home.content.SEO[0].description }}"
   canonical: "{{ home.content.SEO[0].canonical }}"
   noindex: "{{ home.content.SEO[0].noindex }}"
   og_title: "{{ home.content.SEO[0].og_title }}"
   og_description: "{{ home.content.SEO[0].og_description }}"
   og_image: "{{ home.content.SEO[0].og_image.filename }}"
---
<h1>{{ home.content.Heading }}</h1>
<p class="home-subtitle">{{ home.content.Subtitle }}</p>

<h2>Highlighted Articles</h2>
<ul>
   {% for article in home.content.Highlights %}
   <li><a href={{ article.fullSlug }}>{{ article.content.Title }}</a></li>
   {% endfor %}
</ul>

18. Create the `src > public > css > styles.css` file

/* Colors */
:root {
   --darkgray: #202124;
   --purple: #713973;
   --white: #FFF;
}
body {
 background-color: var(--white);
 color: var(--darkgray);
 display: flex;
 flex-direction: column;  
 font-family: system,-apple-system,system-ui,BlinkMacSystemFont,Roboto-Light,sans-serif;
 font-size: clamp(1.1em, calc(0.25vw + 0.8em), 1.25em);
 margin: 0;
 min-height: 100vh;
 padding: 0;
}
header {
 display: flex;
 justify-content: space-between;
 border-bottom: 1px solid var(--darkgray);
}
footer {
 border-top: 1px solid var(--darkgray);
 text-align: center;
 padding: 1em;
}
main {
 flex-grow: 1;
 margin: 4em auto 0 auto;
 width: min(60em, 90%);
}
.header-home {
 text-decoration: none;
 font-size: 1.5em;
 font-weight: 600;
 color: var(--darkgray);
 &:hover {
     color: var(--purple);
 }
}
.header-nav {
 display: flex;
 align-items: center;
 width: min(60em, 90%);
 margin: 0 auto;
}
.header-list {
 margin-right: 1em;
 padding: 0;
 list-style: none;
 float: left;
 margin-left: 1em;
 display: flex;
 justify-content: flex-end;
 flex-grow: 1;
 list-style: none;
}
.header-item {
 font-size: 1em;
 & a {
     margin: 0 1em;
     color: var(--darkgray);
     text-decoration: none;
     &:hover {
         color: var(--purple);
     }
 }
}
.author-avatar {
   width: 75px;
}
.author-name {
   margin-left: 1.5em;
}
.author-info {
   display: flex;
   flex-direction: row;
}
p:empty {
 display: none;
}

Run it locally

You're nearly finished! With your content in Storyblok and your code stored in a local repository, it's time to run it locally and ensure everything appears as intended.

npm start

Executing this command will run Eleventy locally, making your brand new (local) site accessible at port 8080. If port 8080 is already in use, the correct port will be displayed in the console.

Demo and Template Repository

You can see this blog site in action here: https://11ty-storyblok.netlify.app

In addition, you have all the code described in this tutorial in this template repository: https://github.com/guaca/11ty-storyblok-template/. So, you can create your own blog site by clicking the "Use this template" button.

What's next?

This tutorial has guided you through configuring and building a blog site, utilizing Storyblok for data storage and Eleventy for page generation. Once completed, you can deploy your Eleventy project to your preferred Jamstack hosting service. By setting up appropriate workflows and hooks, you can ensure that your site updates automatically whenever you publish a new story in Storyblok.

You have all these steps defined in this article.

Can I use the Storyblok Visual Editor with Eleventy?

Long answer short? Yes but it's not straightforward.

Long answer: Yes, you can leverage it by configuring an edge function to refresh the API/GAPI data from Storyblok upon updates. Eleventy generates data during build time. Consequently, even after saving new data, the data won't be updated in the Visual Editor preview unless the edge function rebuilds it.

Storyblok's visual editor seamlessly integrates with other frameworks like Next or Nuxt, allowing you to observe content updates instantly, even without saving changes. However, this functionality is not supported by static site generators.

In the next article in this series, I will use Netlify Edge functions to leverage the Storyblok Visual Editor to make working with the editor easier and more intuitive. Stay tuned!

How to connect Eleventy and Storyblok

2024-01-31T00:00:00Z

This is the second post in a series of articles called "Eleventy and Storyblok" to learn how to use this combination to create a web project.

Before getting into the matter, I really recommend you to read my first article of this series if you haven't yet. Take a moment to check it out and discover why Evleventy and Storyblok is my perfect combination and why you should start using it to take advantage of these two technologies. You can read it here.

So, in this second article I explain you how to connect Eleventy and Storyblok to start consuming content generated in this amazing Headless CMS.

Technical requirements

This article will show you step by step how to query data from Storyblok to use it in an Eleventy project. You'll need a computer with the following features:

Node.js. Eleventy requires Node.js 14. I've used v20.10.0 in the examples provided.
- You can check if you have Node installed by running node --version in a terminal window.
- If the command is not found or returns a number less than 14, you will need to download and install Node.js before proceeding to the next step.
A code editor. I use VSCode, but feel free to use your favorite.
A Storyblok account. You can create yours here.
Basic knowledge of HTML, CSS, JavaScript, Markdown, and the command line is helpful.

Once you have all the technical requirements in place, it's time to create the project.

Creating a project in Storyblok

First of all, let's create a basic Storyblok space for this project!

Select the New Space option, enter a name for the space, and select the server location (EU by default):

You can review the structure and sample content details. By default, you'll find the following components:

A Home page in the Content section:

When you access it, you will see the "Welcome to the Visual Editor" page by default, and the components of the page in the right sidebar:

As you can see, the Home page has a body component with two block elements:

Teaser: this is a text component. The current value of this field is "Hello world!".

Grid: this is a block component, with 3 text elements in it (with the text "Feature 1", "Feature 2", and "Feature 3" text on them).

We'll cover this later, but understanding the architecture of data is key to creating the right elements in your front-end development.

Creating a project in Eleventy

Eleventy does not require you to use any JavaScript framework or library. And you can have a basic project up and running in literally less than 1 minute:

Open a terminal
Create a folder for your new project

mkdir myproject

Access the project

cd myproject

Create an index.md file. The .md extension is for markdown.

echo '# Page header' > index.md

Run Eleventy. This command compiles the index.md file (but .md is only one of many valid file extensions) into the output folder(_site by default), ready to be upload to your favorite hosting service.

npx @11ty/eleventy

You should get something like this:

[11ty] Writing _site/index.html from ./index.md (liquid)
[11ty] Wrote 1 file in 0.03 seconds (v2.0.1)

However, you may want to run Eleventy from a local development server while working on it. Run Eleventy locally with this code:

npx @11ty/eleventy --serve

You will get something like this:

[11ty] Writing _site/index.html from ./index.md (liquid)
[11ty] Wrote 1 file in 0.04 seconds (v2.0.1)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

Open http://localhost:8080 in your browser and you will see your website.

Setting up and configuring the Eleventy project

So far, so simple, right? Your project should have the following architecture:

├── _site
│   └── index.html
└── index.md

But let's add a few more things to prepare our project for our Storyblok integration.

We've created our first page, index.html, using one of the valid file extensions (.md). But this is just one of many options you can use for your templates:

HTML: *.html
Markdown: *.md
WebC: *.webc
JavaScript: *.11ty.js
Liquid: *.liquid
Nunjucks: *.njk
Handlebars: *.hbs
Mustache: *.mustache
EJS: *.ejs
Haml: *.haml
Pug: *.pug
Custom: *.*

I will use .md and .njk in this article, but feel free to use the template languages you feel more comfortable with.

There's plenty of options to use, combine and override the template language. You can find all the details in the documentation.

In addition to pages, you can use layouts to wrap other content. So let's open the project in VSCode and let's create a base layout to define the common HTML elements for all pages:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ title }}</title>
  </head>
  <body>
    {{ content | safe }}
  </body>
</html>

Save this file as base.njk in a new _includes/layouts folder. Your project now has the following structure:

├── _includes
│   └── layouts
│       └── base.njk
├── _site
│   └── index.html
└── index.md

Now you can add the base.njk layout to your index.md page. To do this, add the following information to your existing file

+ ---
+ layout: layouts/base.njk
+ title: This is my homepage
+ ---

# Page header

What have been done here? The content between the two --- marks is the front matter. This is a YAML block at the top of the file and is a standard convention used by many Static Site Generators (SSG). So you're probably familiar with it if you've used other SSGs in the past. The content in the front matter is key-value pairs that provide information on how to generate data for this page.

In this case, two key-value pairs have been added:

layout: This is the route of the desired layout to apply to the page.
title: This is the title of the page. As mentioned earlier in the base.njk file, this information will be used in the <title> tag.

Get the API token from Storyblok

An API token is necessary to follow the next steps. By default, you can see your preview token on the "Welcome to the Visual Editor" page. But you can find it (or create a new one) in Settings > Access Tokens as well.

How to query the Storyblok data from Eleventy

Create the GraphQL query

In this article, I will be using the GraphQL Content Delivery API. This is a read-only endpoint and is optimized for fast content delivery.

Use the following endpoint to send GraphQL requests:

https://gapi.storyblok.com/v1/api

Note that you need to append the region code if you are using different regions. For example:

https://gapi-us.storyblok.com/v1/api

If you haven't used GraphQL schemas before, I have good news for you! Storyblok has a playground where you can explore the functionalities and create the right query. You can access it using this URL with your Access Token in it:

https://gapi-browser.storyblok.com/?token=insert-here-your-access-token

In this case, we want to get the Home page data:

Teaser (Hello world!)
Grid
- Feature 1
- Feature 2
- Feature 3

So, this will be our query:

{
  PageItem(id: "insert-your-home-id") {
    name
    content {
      body
    }
  }
}

You can find your Home id running the following query in the playground:

{
  PageItems {
    items {
      id
      name
    }
  }
}

And it will return the id and the name:

{
  "data": {
    "PageItems": {
      "items": [
        {
          "id": xxxxxxxxxx,
          "name": "Home"
        }
      ]
    }
  }
}

Ok, now we know what data we want to get from Storyblok. But how to do it?

Data in Eleventy

Eleventy can use data from several different sources. However, when merging data, there is a priority order for data sources. From highest to lowest priority:

Computed data
Front matter data in a template
Template data files
Directory data files
Front matter data in layouts
Configuration API global data
Global data files

The two ways that work best for applying a headless CMS are Global Data files and Configuration API global data. In this article, I'm going to use the first one.

As you can imagine, this means some code is necessary to execute the API call. Let's create a folder called utils. Inside it, create a storyblok.js file with the following code:

module.exports = async function fetchAPI(query, { variables, preview } = {}) {
    const res = await fetch("https://gapi.storyblok.com/v1/api", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Token: "xxxxxxxxxxxxxxxxxxxxxxxx",
        Version: preview ? "draft" : "published",
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });
  
    const json = await res.json();
    if (json.errors) {
      console.error(json.errors);
      throw new Error("Failed to fetch API");
    }
    console.log(json.data)
    return json.data;
  }

Hardcoding your API token into your code is not a good practice. So you can store it as an .env variable.

# .env file
STORYBLOK_TOKEN: xxxxxxxxxxxxxxxxxxxxxxxx

However, you will need to install the dotenv package to access it.

npm install dotenv --save-dev

You will see this step will generate some more files and folders. Don't worry, we'll manage this later. Now you can modify your storyblok.js file to use the .env variable:

+ require('dotenv').config()
module.exports = async function fetchAPI(query, { variables, preview } = {}) {
    const res = await fetch("https://gapi.storyblok.com/v1/api", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
-        Token: "xxxxxxxxxxxxxxxxxxxxxxxx",
+        Token: process.env.STORYBLOK_TOKEN,
        Version: preview ? "draft" : "published",
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });
  
    const json = await res.json();
    if (json.errors) {
      console.error(json.errors);
      throw new Error("Failed to fetch API");
    }
    console.log(json.data)
    return json.data;
  }

At this point, let's create a _data folder, and a homepage.js file in it with the following code:

const fetchAPI = require("../utils/storyblok");

module.exports = async function getHomepage () {
  const data = await fetchAPI(`
  {
    PageItem(id: "insert-your-home-id") {
      name
      content {
        body
      }
    }
  }
  `);
  return data?.PageItem;
}

The previous code will generate the homepage data from Storyblok's API, and it will be accessible from other pages and layouts.

So let's modify our index.md file to use it!

---
layout: layouts/base.njk
title: This is my homepage
---

- # Page header
+ # {{ homepage.content.body[0].headline }}
+ {{ homepage.content.body[1].columns[0].name }}
+ {{ homepage.content.body[1].columns[1].name }}
+ {{ homepage.content.body[1].columns[2].name }}

After following all these steps, you should see something similar to this on your local server:

Using the Visual Editor from Storyblok

As seen earlier, the Visual Editor uses a "Welcome to the Visual Editor" by default page. To see the page we've created using Storyblok's data we must set up the preview URL. Eleventy runs locally on http://localhost:8080. However, Storyblok requires an https connection to use the visual editor. There are several frameworks offering straightforward methods to use SSL in local development. Unfortunately, it's not that easy on Eleventy.

However, we can fis this issue with mkcert and local-ssl-proxy. Before following this process, ensure your local server is stopped. If it's still running, you can stop it by clicking Control + C.

Install mkcert (globally)

npm install -g mkcert

Add mkcert to your local root CAs

mkcert -install

Generate a certificate for your localhost on your project, signed by mkcert. This will generate two .pem files.

mkcert localhost

Install local-ssl-proxy (globally)

npm install -g local-ssl-proxy

Run Eleventy locally (and keep this terminal running it!). By default, it will run over the port 8080:

npx @11ty/eleventy --serve

Open a new terminal and run the proxy SSL server through the port 3000 (and keep it running in this new terminal):

local-ssl-proxy --source 3000 --target 8080 --cert localhost.pem --key localhost-key.pem

After these steps, open https://localhost:3000 on your browser and you should be able to see the same content as on http://localhost:8080.

With these two local servers running, you can go to Storyblok and change the preview URL. You can set it up directly from the default "Welcome to the Visual Editor" page, in the "Set up preview URL" field. Or you can change the preview URL from Settings > Configuration > Visual Editor:

But you will probably be a bit disappointed after doing this because you'll get a 404 error after saving it. That's because Storyblok adds the content page path to the URL. So, by default, the visual editor will try to load https://localhost:3000/home. To change this, go to the page configuration and set / as the Real path:

And now you have it! You can see the content using the Visual Editor.

Next steps

After following all these steps, you now know how to create content on Storyblok and consume it from Eleventy using the GraphQL API. However, you will notice that content management is not dynamic. If you change something in Storyblok, it will not be updated on the local server or in the visual editor.

That's the expected behavior because Eleventy executes the GraphQL query at build time. If we serve the page locally, this means that the query won't be updated unless we change a file in our project. Therefore, any changes we make won't be visible on Storyblok until we rebuild the project on our local server.

That's a bit annoying, isn't it? But don't worry. I will show you how to overcome all these inconveniences in an upcoming article of this series of Eleventy and Storyblok articles.

Eleventy and Storyblok - My perfect combination

2023-10-09T00:00:00Z

This is the first post in a series of articles called "Eleventy and Storyblok" to learn how to use this combination to create a web project.

If you know me, you already know that I'm a big Eleventy fan. So far, it's my favorite choice for creating a static project. But you can do so much more with it. You can even build an SPA with 11ty! The only downside to the escalation of my personal projects is the lack of a CMS to generate new content.

Don't get me wrong. I feel super comfortable writing in Markdown, but sometimes I miss the power of a CMS to easily check grammar mistakes or even preview the content instead of running my project on localhost.

That's why I started researching how to integrate a headless CMS into an Eleventy project. After investigating a few options, I fell in love with Storyblok.

In this article, I'll explain why I chose these options in the hope that you'll fall in love with them, too.

Eleventy, a simpler static site generator

11ty in a nutshell: Fast builds and even faster websites. That's what I'm looking for when starting a new project, so Eleventy seems to be made for my needs! But let the data speak for itself.

Eleventy ran a benchmark of x4000 Markdown files (you have all the information in this open source repository and the results in this article) and Eleventy performance is impressive:

Name	Building ×4000 MD Files
Eleventy	1.93s
Astro	22.90s
Gatsby	29.05s
Next.js	70.65s

Performance is important, but so is the developer experience. And I love the versatility of 11ty: you can create a project and choose between many template languages like HTML, Markdown, Nunjucks, Liquid, WebC, and others. You can even override the template language if you need to!

In addition, there are many official plugins that you can integrate into your project to take it to the next level easily. Or you can integrate plugins contributed by the community!

And that's important to me: Eleventy has an active community that helps make this SSG a great option.

For example, you can easily configure your templates using data keys like permalinks, layouts, pagination, tags, etc. And integrate plugins like Image (to resize and generate images), RSS, i18n (for internationalization), Navigation (also for breadcrumbs!), Shopify (import your Shopify products, pages and collections into Eleventy as global data), and more.

But don't take my word for it and see who trusts Eleventy to build their projects:

NASA
Cern
TC39
W3C
Google
Netlify
web.dev
MIT
Stanford
V8
Chrome Developers
Foursquare
CSS Tricks
WebPageTest
A11Y Project
NOAA
United Kingdom (gov)
France (gov)
Stack Overflow
Lit
Glitch
Stackblitz
Open Web Docs
jamstack.org
Greenpeace
CSIS
ESLint
Mocha
reveal.js
Panic
Filament Group
Set Studio
Ookla
Khan Academy
Basecamp
Snowpack
ffconf
UX London
Nordhealth
Orange
Univ. of Wisconsin-Madison
California (gov)
Red Hat
Just Eat Takeaway
…and more

Storyblok, the way to modern content

As you can see, Eleventy is a super powerful SSG that provides a great DX. However, if your project has content editors creating articles and pages, they won't be as excited as developers. Creating content directly on an SSG project can be difficult until they know how to write using Markdown or other project options.

So implementing a headless CMS is a great solution to solve this problem. As I told you before, after investigating several options, I fell in love with Storyblok, and you will agree with me after reading this article.

But let's take a step back.

What's a headless CMS?

A headless CMS is a pure backend web content management system that acts as a content repository. The content is then exposed through an API for display on any device, without a built-in front-end. This separates your data (body) from its presentation (head).

Separating the two gives you remarkable freedom and allows you to integrate Storyblok into any project such as websites, ecommerces, or apps. Moreover, developers can use whatever technology they want without worrying about how it affects the front end, and content editors can reuse their content on any number of devices of any type because it's not tied to a specific channel.

Why Storyblok?

Storyblok is a headless CMS designed to empower all content stakeholders while providing a cloud-native, headless architecture that allows developers to effortlessly work with and adapt to any technology.

Here are some of its most notable features:

Headless: You can integrate Storyblok into any front-end project because it's a headless solution. Moreover, you can change your front-end and easily migrate your content from one technology to another.
Cloud-native: You don't have to host it. Storyblok does that for you.
Internationalization: Excellent multilingual management. You can manage your translations at three different levels: field level, folder level, or space level. This allows you to choose the approach that best suits your project.
Visual Editor: You don't need to know Markdown or any other markup languages to create and manage your content. Storyblok has a visual editor where you can visually manage, organize and preview your content.

And trust me, the Visual Editor looks amazing and your content editors will love it.

Yes, Storyblok has a preview feature where you can see how the content will fit on the page on the fly!

If you want to learn more about Storyblok's features, check out this video (highly recommended!):

https://www.youtube.com/watch?v=902M1Pt6yW8

How to integrate Storyblok into Eleventy

As a headless CMS, you can integrate Storyblok into any front-end project. However, it is easier depending on the technology you use.

Storyblok works with many modern frameworks and maintains SDKs to install in Vue, Nuxt, React, Next, Astro, SvelteKit, Remix or Gatsby projects. However, there is no official Eleventy SDK (yet).

But there are other ways to integrate Storyblok into an Eleventy project. In a future article, I'll explain step-by-step how to integrate Storyblok into an Eleventy project using the GraphQL API. Want to see it in action? Stay tuned!

Building Lightning-Fast Websites with Astro and Storyblok

2023-07-10T00:00:00Z

In today's digital landscape, web performance has become a critical factor in delivering great user experiences. Slow-loading sites can frustrate visitors and lead to higher bounce rates and lower conversions. However, achieving blazing-fast performance without compromising functionality can be a challenging task.

Astro and Storyblok is a power couple that empowers developers to build lightning-fast websites with a limited amount of JavaScript. By combining Astro's static site generation capabilities with Storyblok's headless CMS, developers can leverage the power of pre-rendered content and reduce client-side JavaScript execution, resulting in optimal site speed. This article delves into the seamless integration of Astro and Storyblok, highlighting the performance benefits and efficiency this approach delivers for modern web development.

Astro

Astro is an open-source framework for building fast, content-focused websites with a modern developer experience.

Astro is:

Content-focused: this framework was designed for content-rich websites.
Server-first: rendering the HTML in the server results in faster websites.
Fast by default: in theory, building slow websites in Astro should be impossible.
Easy to use: Astro is for everybody. You don't need to be an expert to build something with Astro.
Fully-Featured: you can choose from over +100 Astro integrations.

Moreover, these are some of Astro's key features:

Bring Your Own Framework: You can use your favorite framework to build your project (React, Svelte, Vue...), or you can use just plain HTML and JavaScript.
100% static HTML: Astro renders your page to static HTML, removing all JavaScript from your final build by default.
On-Demand Components: If you need some JavaScript, Astro can automatically hydrate interactive components when they become visible on the page.
Fully-Featured: Astro supports TypeScript, Scoped CSS, CSS Modules, Sass, Tailwind, Markdown, MDX, and any of your favorite npm packages.
SEO features: Automatic sitemaps, RSS feeds, paginations, and collections.

As you can see, Astro is an excellent option for building lightning-fast websites. However, creating and managing the content directly from Astro may not be the best experience for content editors.

Storyblok

To overcome this limitation, you can use a headless CMS so your editors will have a visual tool to create and manage your website's content. And Storyblok is a great option to do that.

I'm planning to write a full article about Storyblok because it's worth going deeper into it and discovering all the capabilities and features you can leverage for your project.

But, for now, here you have some of Storyblok's key features and why I choose it as my favorite headless CMS:

Headless: you can integrate Storyblok in any front-end project because it's a headless solution. Moreover, you can change your front-end and easily migrate your content from one technology to another.
Cloud-native: you don't need to host it. Storyblok does that for you.
Visual editor: you don't need to know markdown or any other markup languages to create and manage your content. Storyblok has a visual editor where you can visually manage and preview your content.

Show, don't tell

The theory sounds great, but let's see a step-by-step practical example of creating a basic project using Astro and Storyblok.

1. Create a Storyblok project

Choose the New Space option, define a name for the space and choose the server location (by default, EU):

Storyblok will create a space with sample content for you.

2. Create an Astro project

From your Storyblok space, go to Get Started and copy the npx command:

Now you can locally execute the copied command, and Storyblok's wizard will guide you through the process. To properly follow this tutorial, I need you to choose the following options:

Select framework: Astro
Select package manager: npm
Space region: EU
Local folder name for the project: up to you!
Serve Storyblok locally: No

This will create the local Astro project. Now, access and install all the dependencies by running the following command:

cd ./your-project-folder && npm install

Once everything is installed, you will have your Astro + Storyblok project locally. But let's modify a couple of things.

Open your astro.config.mjs file. You will see your Access token is hardcoded there.

...
export default defineConfig({
  integrations: [
    storyblok({
      // accessToken: env.STORYBLOK_TOKEN,
      accessToken: 'xxxxxxxxxxxxxxxxxxxxxxxx',
      apiOptions: {
        region: '',
      },
...

But you can create a .env file in your root and set there your access token:

# .env file
STORYBLOK_TOKEN: xxxxxxxxxxxxxxxxxxxxxxxx

And modify your astro.config.mjs file accordingly:

...
export default defineConfig({
  integrations: [
    storyblok({
-     // accessToken: env.STORYBLOK_TOKEN,
-     accessToken: 'xxxxxxxxxxxxxxxxxxxxxxxx',
+     accessToken: env.STORYBLOK_TOKEN,
      apiOptions: {
        region: '',
      },
...

If your region is in the US instead of EU, you will need to update that field in the same file:

...
export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_TOKEN,
      apiOptions: {
-        region: '',
+        region: 'US',
      },
...

Optional step: Storyblok requires HTTPS to access the visual editor. By default, the Astro project comes with Vite's basicSsl plugin. However, I prefer to use mkcert. To install it, run the following command:

# install mkcert with npm
 npm install vite-plugin-mkcert -D

And update your astro.config.mjs file accordingly:

// astro.config.mjs file 
  import { defineConfig } from 'astro/config';
  import storyblok from '@storyblok/astro';
  import { loadEnv } from 'vite';
- import basicSsl from '@vitejs/plugin-basic-ssl'
+ import mkcert from 'vite-plugin-mkcert';

 const env = loadEnv("", process.cwd(), 'STORYBLOK')
 
 export default defineConfig({
  integrations: [
    storyblok({
      accessToken: env.STORYBLOK_TOKEN,
    })
  ],
  vite: {
-   plugins: [basicSsl()],
+   plugins: [mkcert()],
    server: {
      https: true,
    },
  },
 })

3. Enable the Visual Editor

You're almost done! Now, you can return to Storyblok's visual editor and change the preview URL. Go to Settings > Configuration > Visual Editor and set your localhost URL using HTTPS:

Next step! Storyblok adds the path of the content page to the URL. So, by default, the visual editor will try to load https://localhost:3000/home. To change it, you need to go to the page configuration and set / as the Real path:

And now, if you refresh the visual editor, you will see your local version of your by-default Astro project's Home directly on Storyblok 🥳

4. Deploy the project on Netlify

Having a visual editor is a great tool, especially for content editors. And this is something that other headless CMSs don't offer. However, using localhost as the preview URL doesn't sound like something that content editors will be happy to hear.

The good news is Storyblok allows you to configure multiple Preview URLs. Therefore, you can keep your localhost Preview URL for local development, and add other development/deployment environments as an option for the Preview source.

To simplify, let's deploy our Astro project on Netlify and configure it as a new Preview URL.

I assume you're familiar with GitHub and Netlify. If not, check this and this before continuing.

Once you've created a new site on Netlify, connected it to your Astro project on GitHub, and deployed it, you can add your new Netlify URL as a Preview URL. Go to Settings > Configuration > Visual Editor on your Storyblok space and set your Netlify URL. You can decide if you want it as your default environment or if you want it as an option:

And now, you finally have your visual editor enabled and available for both your developers and content editors... but with some limitations.

Astro is (by default) an SSG (static site generator) and generates all pages at build time. Hence, editing content in Storyblok won't give your content editors the instant update in Netlify they might expect.

To overcome this, you can use Astro in SSR mode in a specific environment for your content editors. You have more info about how to do this here.

Last but not least, once you publish any content/change in Storyblok, you will need to deploy the project to update your pages. Doing this manually is very annoying, but you can configure a webhook to manage it.

In Netlify, go to Deploys > Deploy settings > Build hooks > Add new hook. Define a name (for example, storyblok_publish), and save it. Copy the URL that this process generates.

Now, go to your Storyblok space and create a new webhook in Settings > Webhooks > New Webhook. Paste the copied URL from Netlify in the Endpoint URL field and check the following triggers: Story > Story published and Story > Story unpublished.

Every time you publish or unpublish any story, a new deployment will be triggered in Netlify——hence, your website will be updated.

Is Astro + Storyblok really fast?

I've explained a ton of things to create an Astro + Storyblok project because this combo is a great option to generate lightning-fast websites. And now that we have a boilerplate project, we can compare it to other options, right?

To properly evaluate the web performance results of this project, I also created a Nuxt.js and a Next.js project with the same boilerplate content — and I deployed all the projects on Netlify. So, I have 3 publicly accessible URLs that can be measured in the lab using PageSpeed Insights:

Astro: https://astro-storyblok.netlify.app/
Nuxt: https://nuxt-3-storyblok.netlify.app/
Next: https://next-storyblok.netlify.app/

After running 5 separate tests for each project, this is the average data:

DESKTOP	Astro	Next	Nuxt
FCP (s)	0.413	0.438	1.071
LCP (s)	0.499	0.535	1.071
SI (s)	0.629	0.696	1.328
TBT (ms)	0	1.2	0
CLS	0	0	0.001

MOBILE	Astro	Next	Nuxt
FCP (s)	0.991	0.945	2.539
LCP (s)	0.991	1.197	2.539
SI (s)	1.243	1.377	2.972
TBT(ms)	0	92.4	0
CLS	0	0	0.001

As you can see, Astro has better results when compared to Nuxt or Next. And yes, I'm only testing a very basic template. However, it shows the baseline differences——and demonstrates Astro + Storyblok is a winning combo.

Moreover, Astro is lighter and loads less JS resources:

DESKTOP	Astro	Next	Nuxt
Total resources	4	10	11
Size (Bytes)	10977	91912	81407
Total Scripts	2	8	6
Size (Bytes)	7915	88276	62955

MOBILE	Astro	Next	Nuxt
Total resources	4	10	11
Size (Bytes)	10981	92003	81415
Total Scripts	2	8	6
Size (Bytes)	7915	88332	62935

So, have you tried it yet? :)

How to measure CWVs on SPAs

2023-03-08T00:00:00Z

One of the most challenging questions to answer when talking about Core Web Vitals is how to measure them in a Single-Page Application (SPA). In this article, I'll clarify the bottlenecks and the current state of this topic.

But before going into specifics, let’s talk about soft navigations. A soft navigation refers to the seamless transition between web pages, where a new page is not entirely loaded but changed by JavaScript. While this technique has recently become quite popular through several frameworks, there are limitations to how it affects the Core Web Vitals.

Core Web Vitals are a set of metrics that Google uses to measure website performance, including load speed, interactivity, and visual stability. These metrics are vital because they impact the website's user experience and, potentially, search engine results. Google introduced Core Web Vitals in May 2020, and since then, it has become a significant factor in website development.

Challenges

As I mentioned before, while SPAs can offer a more seamless experience, they create challenges when measuring Core Web Vitals. For instance, a typical SPA page may have several navigation options, which the user can click to access different parts of the application. With soft navigations, these options are not considered unique pages, and each click merely loads new content onto the current page. The URL can be modified through JavaScript, emulating the multi-page applications' (MPAs) navigation, but to the browser they are seen as updates to the current page, rather than new pages.

The Chrome User Experience Report (CrUX) is based on “hard” page navigations. This means metrics such as FCP, LCP, or FID will only be reported for the first viewed page. Other metrics such as CLS or INP are measured for the entire lifecycle of a page. Hence, new CLS and INP values may be collected, but assigned to the first viewed page - even if they occur after one or some soft navigations. Additionally you only get one overall value for CLS and INP, rather than one value per each application page.

To overcome these limitations, developers can adopt several strategies to ensure more useful Core Web Vitals measurements. One approach is to create custom performance metrics that accurately measure user experience in SPAs.

Developers can also consider using other rendering options, such as server-side rendering (SSR) or static site generators (SSG) to overcome some of the limitations of SPAs. Under these architectures, developers can ensure users have hard page navigations and avoid all the SPA inconveniences when measuring CWV.

However, these options are not always possible.

Enabling soft navigations in Chrome (experimental)

Since Chrome 110, you can enable soft navigations and have the opportunity to start measuring Core Web Vitals. According to Chrome’s documentation, you can enable it in two different ways:

By turning on the Experimental Web Platform features flag at chrome://flags/#enable-experimental-web-platform-features
Or using the --enable-experimental-web-platform-features command line argument when launching Chrome.

Note: For websites that wish to enable this for all their visitors to see the impact, there is an origin trial running from Chrome 110 to Chrome 112 which can be enabled by signing up for the trial and including a meta element with the origin trial token in the HTML or HTTP header.

After enabling the Experimental Web Platform features flag, you will see the following information in the Console after each soft navigation.

  A soft navigation has been detected: https://example.com/page

And now you’re almost ready to start measuring CWVs for each soft navigation.

Using a PerformanceObserver

If you’re using a PerformanceObserver, you need to include includeSoftNavigationObservations: true in your observe call. For instance, a basic example to display the LCP in the console:

  new PerformanceObserver((entryList) => {
    for (const entry of entryList.getEntries()) {
      console.log('LCP candidate:', entry.startTime, entry);
    }
  }).observe({type: 'largest-contentful-paint', buffered: true, includeSoftNavigationObservations: true});

Once you implement this, you will be able to see the different LCP candidates for each soft navigation in the console. Something like this:

  A soft navigation has been detected: https://www.example.com/page2
  LCP candidate: 6054.2999
  ▶ LargestContentfulPaint {renderTime: 6054.299, loadTime: 0, size: 3591, id: '', url: '', ...}
  LCP candidate: 6177.7999
  ▶ LargestContentfulPaint {renderTime: 6177.799, loadTime: 6155, size: 166500, id: '', url: 'https://www.example.com/image.jpg', ...}

For every LCP candidate, you'll get an object with all the related details such as the HTML element, URL (if the LCP candidate is an external file), loadTime, and size, among others.

As well as LCP, you can use a PerformanceObserver to display the details for the other web vitals as desired. For example, the following code will display the details for CLS:

  let clsValue = 0;
  let clsEntries = [];

  let sessionValue = 0;
  let sessionEntries = [];

  new PerformanceObserver((entryList) => {
    for (const entry of entryList.getEntries()) {
      // Only count layout shifts without recent user input.
      if (!entry.hadRecentInput) {
        const firstSessionEntry = sessionEntries[0];
        const lastSessionEntry = sessionEntries[sessionEntries.length - 1];

        // If the entry occurred less than 1 second after the previous entry and
        // less than 5 seconds after the first entry in the session, include the
        // entry in the current session. Otherwise, start a new session.
        if (sessionValue &&
            entry.startTime - lastSessionEntry.startTime < 1000 &&
            entry.startTime - firstSessionEntry.startTime < 5000) {
          sessionValue += entry.value;
          sessionEntries.push(entry);
        } else {
          sessionValue = entry.value;
          sessionEntries = [entry];
        }

        // If the current session value is larger than the current CLS value,
        // update CLS and the entries contributing to it.
        if (sessionValue > clsValue) {
          clsValue = sessionValue;
          clsEntries = sessionEntries;

          // Log the updated value (and its entries) to the console.
          console.log('CLS:', clsValue, clsEntries)
        }
      }
    }
  }).observe({type: 'layout-shift', buffered: true, includeSoftNavigationObservations: true});

Using web-vitals.js

An easier way is to use the web-vitals.js library to measure them, which takes care of many of the calculations you may need to do from the Performance Observer entries, as shown in the above CLS example. To do this use the soft-navs branch and include {reportSoftNavs: true} in the functions' calls. For example, using this basic code to display FCP, LCP and CLS:

  import {
    onFCP,
    onLCP,
    onCLS
  } from 'web-vitals'

  onFCP(({value}) => console.log('FCP: ', value), {reportSoftNavs: true});
  onLCP(({value}) => console.log('LCP: ', value), {reportSoftNavs: true});
  onCLS(({value}) => console.log('CLS: ', value), {reportSoftNavs: true});

And then you will get this kind of information in the console:

  A soft navigation has been detected: https://www.example.com/page2
  CLS: 0.00192837465
  FCP: 32.6739203094
  LCP: 803.83929999

The web-vitals library currently reports the following metrics for soft navigations:

TTFB: Reported as 0. In the future, Google may support more precise ways of knowing which request is the soft navigation’s “navigation request” and will be able to have more precise TTFB measurements.
FCP: The time of the next contentful paint, relative to the soft navigation start time. Existing paints present from the previous navigation are not considered - only new contentful paints. Therefore, the FCP will be >= 0.
LCP: The time of the next largest contentful paint, relative to the soft navigation start time. Like FCP, existing paints present from the previous navigation are not considered. Therefore, the LCP will be >= 0. As usual, this will be reported upon an interaction (for example by clicking on the page), or when the page is backgrounded or navigated away from, as only then can the LCP be finalized.
CLS: The largest window of shifts between the navigation times. Similar to LCP, this is only finalized when the page is backgrounded or navigated away from. A 0 value is reported if there were no shifts on that page.
FID: Currently only the first FID for the page is reported by Chrome, so this is not yet reported for soft navigations.
INP: The INP between the navigation times. As usual this will be reported upon an interaction, or when the page is backgrounded as only then can the INP be finalized. A 0 value is not reported if there are no interactions.

Conclusions

This is an exciting experiment to start measuring a common architecture on the modern web that is currently missing from CrUX. Still, it is a first step, and again, it is an experiment. However, Google is really looking forward to gathering feedback from it. So, if you're testing this approach, feel free to share your feedback with them:

Open an issue on GitHub.
Report an issue on Chrome.
Drop a message at web-vitals-feedback@googlegrouops.com.

Hello, World!

2022-07-18T00:00:00Z

Hi there! This is my first post on my brand new blog.

As a Jamstack fangirl, I built it with Eleventy and deployed it with Netlify. Don't you know what I'm talking about? Don't worry. I'll write about this Jamstack stuff in future articles on my blog.

Who am I?

My name is Estela Franco. I'm a web performance and technical SEO lover from sunny Barcelona (Spain). If you're interested, you can find a little bit more information about me in the About me section.

What will you find here?

As I mentioned, here you will find articles about Jamstack. But that's not the only (or even the most important) topic. Currently, I'm focused on web performance and technical SEO. So, expect content covering these areas, among other content related to web development or Google technologies.

What's next? Stay tuned!

This is only a "Hello, World!" article before shipping my new website to production. So, it's short and concise.

I haven't planned a specific periodicity to write stuff here, but if you need more content before my next article, you can also follow me on Twitter or Mastodon.

Last but not least, I also know I still need to keep working on CSS to improve the overall look & feel. Will do! But you know, done is better than perfect.

See you soon!

Estela Franco

The modern web can do more than you think

The web's not dead #

Why this is important #

What you'll learn in this series #

Conclusion #

Create a Blog with Eleventy and Storyblok

Creating the Blog Architecture in Storyblok #

Removing the boilerplate content #

Creating the initial Blocks: Author and Category #

Creating the first stories: Authors and Categories #

And what about the Articles? #

Creating a Homepage #

Wait. And what about SEO? #

Create the SEO block #

Add the SEO block to the other blocks #

Creating the Eleventy project #

Setting up and configuring the Eleventy project #

1. Create and access your project (and open it using VSCode) #

2. Create your package.json file in the root directory and paste the following lines: #

3. Install dependencies #

4. Create the .env file in the root directory #

5. Create the eleventy.js config file #

6. Create the src > _data > metadata.json file #

7. Create the src > _includes > head.njk file #

8. Create the src > _includes > header.njk file #

9. Create the src > _includes > footer.njk file #

10. Create the src > _includes > layouts > base.njk file #

11. Create the src > utils > storyblok.js file #

12. Create your src > _data > articles.js file. #

13. Create the src > article-pages.njk file #

14. Create the src > articles-list.njk file #

15. Repeat steps 12 through 14, but this time creating the files related to Authors #

16. Repeat steps 12 through 14, but this time creating files related to Categories #

17. Create the Home related files #

18. Create the src > public > css > styles.css file #

Run it locally #

Demo and Template Repository #

What's next? #

Can I use the Storyblok Visual Editor with Eleventy? #

How to connect Eleventy and Storyblok

Technical requirements #

Creating a project in Storyblok #

Creating a project in Eleventy #

Setting up and configuring the Eleventy project #

Get the API token from Storyblok #

How to query the Storyblok data from Eleventy #

Create the GraphQL query #

Data in Eleventy #

Using the Visual Editor from Storyblok #

Next steps #

Eleventy and Storyblok - My perfect combination

Eleventy, a simpler static site generator #

Storyblok, the way to modern content #

What's a headless CMS? #

Why Storyblok? #

How to integrate Storyblok into Eleventy #

Building Lightning-Fast Websites with Astro and Storyblok

Astro #

Storyblok #

Show, don't tell #

1. Create a Storyblok project #

2. Create an Astro project #

3. Enable the Visual Editor #

4. Deploy the project on Netlify #

Is Astro + Storyblok really fast? #

How to measure CWVs on SPAs

Challenges #

Enabling soft navigations in Chrome (experimental) #

Measuring Core Web Vitals per soft navigation #

Using a PerformanceObserver #

Using web-vitals.js #

Conclusions #

Hello, World!

Who am I? #

What will you find here? #

What's next? Stay tuned! #

The web's not dead

Why this is important

What you'll learn in this series

Conclusion

Creating the Blog Architecture in Storyblok

Removing the boilerplate content

Creating the initial Blocks: Author and Category

Creating the first stories: Authors and Categories

And what about the Articles?

Creating a Homepage

Wait. And what about SEO?

Create the SEO block

Add the SEO block to the other blocks

Creating the Eleventy project

Setting up and configuring the Eleventy project

1. Create and access your project (and open it using VSCode)

2. Create your `package.json` file in the root directory and paste the following lines:

3. Install dependencies

4. Create the `.env` file in the root directory

5. Create the `eleventy.js` config file

6. Create the `src > _data > metadata.json` file

7. Create the `src > _includes > head.njk` file

8. Create the `src > _includes > header.njk` file

9. Create the `src > _includes > footer.njk` file

10. Create the `src > _includes > layouts > base.njk` file

11. Create the `src > utils > storyblok.js` file

12. Create your `src > _data > articles.js` file.

13. Create the `src > article-pages.njk` file

14. Create the `src > articles-list.njk` file

15. Repeat steps 12 through 14, but this time creating the files related to `Authors`

16. Repeat steps 12 through 14, but this time creating files related to `Categories`

17. Create the `Home` related files

18. Create the `src > public > css > styles.css` file

Run it locally

Demo and Template Repository

What's next?

Can I use the Storyblok Visual Editor with Eleventy?

Technical requirements

Creating a project in Storyblok

Creating a project in Eleventy

Setting up and configuring the Eleventy project

Get the API token from Storyblok

How to query the Storyblok data from Eleventy

Create the GraphQL query

Data in Eleventy

Using the Visual Editor from Storyblok

Next steps

Eleventy, a simpler static site generator

Storyblok, the way to modern content

What's a headless CMS?

Why Storyblok?

How to integrate Storyblok into Eleventy

Astro

Storyblok

Show, don't tell

1. Create a Storyblok project

2. Create an Astro project

3. Enable the Visual Editor

4. Deploy the project on Netlify

Is Astro + Storyblok really fast?

Challenges

Enabling soft navigations in Chrome (experimental)

Measuring Core Web Vitals per soft navigation

Using a PerformanceObserver

Using web-vitals.js

Conclusions

Who am I?

What will you find here?

What's next? Stay tuned!