DEV Community: Jonas Gierer

Astro + Storyblok: SSR Tips and Tricks

Jonas Gierer — Fri, 10 Feb 2023 16:01:07 +0000

This is a companion post to Astro + Storyblok: SSR preview for instant visual editing. Please read it first if you haven't already!

Below you'll find some extra tips and tricks I've discovered while developing my Astro + Storyblok site.

Remove drafts from the production site

To avoid loading draft content in production, I created a wrapper function for the Storyblok API:

// src/storyblok/utils.ts

import * as sb from '@storyblok/astro';

export const storyblokApi = (slug: string, params?: sb.ISbStoryParams) => {
  const api = sb.useStoryblokApi();

  return api.get(slug, {
    version:
      import.meta.env.PUBLIC_ENV === 'production' ? 'published' : 'draft',
    ...params,
  });
};

You can then use this wrapper wherever you would've used the Storyblok API, e.g.:

// src/pages/[slug].astro

import { storyblokApi } from '../storyblok/utils';

export async function getStaticPaths() {
  const { data } = await storyblokApi('cdn/links');
  let links = data.links;
  links = Object.values(links);

  return links
    .filter((link: any) => !['index', 'site-config'].includes(link.slug))
    .map((link: any) => {
      return {
        params: { slug: link.slug },
      };
    });
}

// ...

Prevent search engine indexing of the preview site

You probably don't want your preview site containing drafts and unfinished content to be indexed by search engines. To prevent that, use the astro-robots-txt integration:

npx astro add astro-robots-txt

// astro.config.{mjs,ts}

import robotsTxt from 'astro-robots-txt';
// ...

export default defineConfig({
  // ...
  integrations: [
    robotsTxt({
      policy: [
        {
          userAgent: '*',
          disallow: process.env.PUBLIC_ENV !== 'production' ? '/' : '',
        },
      ],
    }),
    // ...
  ],
  // ...
});

Disable `astro-imagetools` image processing in SSR

I found that my SSR pages loaded very slowly because I was using astro-imagetools to process images. Since optimized images aren't necessary during editing anyways, I created a wrapper component to bypass image processing in the preview environment:

---
import type { Picture } from 'astro-imagetools/components';

export type Props = Parameters<typeof Picture>[0];

let {
  breakpoints = [500, 900, 1800], // fallback breakpoints
  class: pictureClass = '',
  ...props
} = Astro.props;

let Component;
if (import.meta.env.PUBLIC_ENV === 'preview') {
  Component = 'img';
  props = {
    class: pictureClass,
    ...props,
  };
} else {
  Component = (await import('astro-imagetools/components')).Picture;
  props = {
    breakpoints,
    attributes: {
      picture: {
        class: pictureClass,
      },
    },
    ...props,
  };
}
---

<Component {...props} />

Astro + Storyblok: SSR preview for instant visual editing

Jonas Gierer — Fri, 10 Feb 2023 16:00:35 +0000

Storyblok is one of the most popular new content management systems. Its visual editing and component-based workflow are intuitive for editors, while also being easy for developers to work with.

While its @storyblok/astro integration with the Astro framework seems fairly straight-forward at first, getting the most out of both Storyblok's visual editor and Astro's static site generation is not as simple.

The Problem

Since Astro is (by default) a static site generator, which generates all pages at build time, editing content in Storyblok will not give your editors the instant feedback they might expect: Even if your Storyblok webhooks are set up correctly, it can take several minutes for the entire project to be rebuilt before the updated content appears. This makes for a very awkward and unintuitive editing experience.

One way to solve this problem is to use Astro in SSR mode. This uses a Nodejs server or serverless functions to render pages whenever they are requested, rather than at build time. This means pages will update as soon as editors change their content. Unfortunately this also means that you'll lose all benefits of a static site, such as the significantly faster page load times and lower operating costs.

The Solution

In order to get the best of both worlds, we'll want to set up two separate deployments: One that uses Astro's default SSG mode for your users to visit, and one SSR environment which is used as the preview site in Storyblok. This way, editors get instant feedback while editing content, but users will still get a fast, static site.

Assuming you followed the storyblok-astro Getting Started guide, here is a step-by-step guide to enable this dual environment:

1. Install Astro SSR adapter of your choice

Astro supports several platforms for server-side rendering. For this guide I will use Vercel's serverless functions. Please refer to the Astro docs for other platforms.

npx astro add vercel

2. Conditionally enable SSR mode

This is where the magic happens: Based on an environment variable, we switch between Astro's server or static mode. I chose to call the variable PUBLIC_ENV because Astro makes environment variables prefixed with PUBLIC_ available in client-side code, which might come in useful. We also conditionally load the SSR adapter since it's not needed in static mode.

// astro.config.{mjs,ts}

import vercel from '@astrojs/vercel/serverless';
// ...

export default defineConfig({
  // ...
  output: process.env.PUBLIC_ENV === 'preview' ? 'server' : 'static',
  adapter: process.env.PUBLIC_ENV === 'preview' ? vercel() : undefined,
  // ...
});

3. Conditionally enable the Storyblok bridge

The Storyblok bridge is responsible for reloading the page when there are changes to Storyblok content, as well as making individual components clickable in the Storyblok editor. Since we will never open the production static site in Storyblok, we can reduce the bundle size a little by disabling the bridge in production.

// astro.config.{mjs,ts}

export default defineConfig({
  // ...
  integrations: [
    storyblok({
      bridge: process.env.PUBLIC_ENV !== 'production',
      // ...
    }),
    // ...
  ],
  // ...
});

4. Create separate build scripts

In order to build the two different deployments, we'll create two build scripts which set the PUBLIC_ENV variable to the respective value. For the sake of completeness, we'll also set the variable to development when using the dev server.

// package.json

"scripts": {
  "dev": "PUBLIC_ENV=development astro dev",
  "build:production": "PUBLIC_ENV=production astro build",
  "build:preview": "PUBLIC_ENV=preview astro build",
  // ...
},
// ...

5. Deploy the two sites

Next, we'll create two separate deployments which use the different build scripts. In my case, I'll create two Vercel projects, connect both to the project's GitHub repo and set the Build Command under Settings > General > Build & Development Settings to npm run build:production for the static production site and to npm run build:preview for the SSR preview site. You should be able to do the same for Netlify, Cloudflare or similar providers.

6. Use webhooks to trigger production deploys

Now all that's left to do is to set up webhooks between Storyblok and your hosting provider so that the production site is rebuilt whenever content is published.

First, create a webhook in your production site's admin interface. For Vercel, I did this under Settings > Git > Deploy Hooks.

Then, copy the URL of the webhook you just created, and paste it in Storyblok under Settings > Webhooks > Story published & unpublished. Now your production site should be rebuilt whenever your editors publish or delete content!

Conclusion

This setup made Astro integrate with Storyblok much more nicely, and it is now one of my favorite framework-CMS pairings on the market. The awesome performance and developer experience of Astro static sites paired with the intuitive Storyblok visual editor is wonderful!

I hope this guide was helpful if you're building a site with these two technologies. Let me know if you have any questions or ideas for improvement!

Extras

There are a bunch of extra tips and tricks about Astro + Storyblok that I wanted to share, but since this guide is already getting long I decided to put them in a separate companion post, which you can find here: Astro + Storyblok: SSR Tips and Tricks. There I explain how to prevent drafts from showing up in your production site, disable search engine indexing of your preview site and more.

How to publish packages to the GitHub Package Registry

Jonas Gierer — Sat, 14 Sep 2019 02:00:36 +0000

If you were lucky enough to get into this week's batch of beta invitations for the GitHub Package Registry, you might be wondering how to get started publishing your npm package there.

The official docs do an OK job at explaining the basics, but aren't as straight forward as you might expect. And at some points, they are downright contradicting themselves. It is a beta, after all, and I'm sure GitHub will improve the docs as this new feature is moving closer to launch.

In this article, I'm going to explain step by step how you can publish your first package on the GitHub Package Registry (I'll call it GPR from now on.) Then, I'll give you a quick explanation how your users can install the package from the GPR, while still being able to install packages from the "normal" npmjs.org registry alongside it.

Keep in mind that the GPR is still in beta, so implementation details might change. Hopefully, I'll remember to keep this article updated, but if in doubt, better check against the official docs. And if you notice anything out-of-date, please let me know in the comments!

Terminology

The terms used for GitHub packages are mostly the same as for the npm registry. If you're already familiar with them, you can skip straight to the next section!

Registry: To resolve packages by name and version, npm (the CLI tool) talks to a registry website. The most popular registry is hosted by npm (the company) on registry.npmjs.org.
GitHub Package Registry (GPR): GitHub recently announced their own registry service, which is available on npm.pkg.github.com. This service will be tightly coupled to their other offerings, so you can expect your package to integrate well with your project's home on GitHub as well as GitHub Actions.
Scope: Scopes are a way of grouping related packages together. Both on the npm registry and the GPR, each user and organization has their own scope. While using a scope is optional on the npm registry, every package published to the GPR must be scoped.

Authorizing npm

These steps only have to be taken once per machine and GitHub user/org. You won't have to go through them again unless you want to publish from a new device or to a new scope.

Create a new personal access token for the account you want to publish the package to. It should have access to the read:packages and write:packages scopes.
If the repository you want to publish is private, the token additionally needs the repo permission.
Create or edit the .npmrc file in your home directory (~/.npmrc) and add the following line, replacing TOKEN with the personal access token created above:
```
//npm.pkg.github.com/:_authToken=TOKEN
```

Setting up your package

Each package has to be explicitly told to publish to the GPR. Otherwise, npm will fall back to the npm registry.

Create or edit the .npmrc file in the root of your project. Add the following line and replace OWNER with the username of the GitHub user or organization you want to publish to (i.e. the scope):
```
@OWNER:registry=https://npm.pkg.github.com
```
(The @ is part of the config syntax and should not be replaced.)
Make sure your package.json is properly configured:

The package name should be prefixed with the scope. PACKAGE here is the actual name of your package. (Again, keep the @):
```
{
  "name": "@OWNER/PACKAGE"
}
```
The repository field should point to the GitHub repository you're publishing:
```
{
  "repository": "https://github.com/OWNER/REPO"
}
```
It's also possible to publish multiple packages per repo, by changing only the package name but keep pointing the repository field to the same repo.

Publish!

All that's left to do is to create a GitHub repository for the package if it doesn't have one already, pushing the new changes, and running npm publish! (As far as I can tell, Yarn doesn't currently support publishing to registries other than npm.) If everything went right, you should see the first version of your package being published on https://github.com/OWNER/REPO/packages (check out one of my own packages for an example.)

Consuming a GPR package

Now that you published a package to the GPR, you or someone else might want to use it as a dependency in another project. To do so, you need to again add the relevant GPR URL to the project's .npmrc:

@OWNER:registry=https://npm.pkg.github.com

An important thing to note is that you need to repeat this process for every different GPR scope you want to use. So if you want to install the packages @facebook/react, @facebook/react-dom, @webpack/webpack, and @babel/core, the .npmrc should look like this:

@facebook:registry=https://npm.pkg.github.com
@webpack:registry=https://npm.pkg.github.com
@babel:registry=https://npm.pkg.github.com

These are just for demonstration purposes, at the time of writing none of these organizations have published any packages to the GPR yet.

What's nice though is that without any further config, you can install any package from the npm registry alongside those. So if you were to npm install lodash with the above config, it would still be able to resolve lodash from npm's registry. Just be careful if the package you want to install is scoped under the same user as a GPR package — you can't install @foo/bar from the npm registry and @foo/baz from the GPR.

Cross-publishing

If you'd like to start publishing to the GPR, but don't want to force users into switching registries, it's very easy to setup a 'hybrid' approach that publishes to both the GPR and the npm registry. Just setup a postpublish script in package.json like so:

{
  "scripts": {
    "postpublish": "npm publish --ignore-scripts --@OWNER:registry='https://registry.npmjs.org'"
  }
}

Note the --ignore-scripts flag which prevents the postpublish script to call itself again.

Closing thoughts

As you can see, it isn't exactly trivial to publish and consume packages from/to the GPR. Both GitHub and the npm/yarn developers need to put in some work to make this experience smoother, especially for the package consumers. That being said, it's great having a serious competitor to the npm registry, and the integrations into the GitHub interface and Actions are already looking really useful. I'll certainly cross-publish my future packages to GitHub, and install from there whenever possible.

Cover by chuttersnap on Unsplash