Forem: Reuben Tier

Hello from Bun!

Reuben Tier — Fri, 08 Sep 2023 15:11:46 +0000

Bun 1.0 less than an hour ago (at the time of publishing), and to celebrate this, I've migrated my blog's build process to Bun! This details how I now publish my static Astro blog to Cloudflare Pages using Bun.

First, a warning...

Before attempting this yourself, be warned that I used some hacky workarounds to bypass some existing issues with Cloudflare Pages, and Bun. I don't recommend this for important deployments yet.

Build an Astro site with Bun

Bun 1.0 supports Astro out the box. To start using it, make sure you have Bun installed and updated. Delete your existing package lockfile (package-lock.json, pnpm-lock.yml, yarn.lock) and use Bun to install dependencies.

bun install

Workaround for the `sharp` package

For those using sharp, it currently has an issue when installed with Bun, but there are two workarounds you can try.

Set sharp as a trusted dependency in your package.json.

"trustedDependencies": [
  "sharp"
],

If the first workaround failed, prefix your build command with the following to install sharp manually.

cd node_modules/sharp && bun install && cd ../../ && YOUR_BUILD_COMMAND

Run bun run build to test your site builds successfully.

Deploy to Cloudflare Pages

Cloudflare Pages has experimental support for Bun. I found a gist from a user in the Cloudflare Developers Discord which documents what you need to do to enable it.

In your Cloudflare dashboard, navigate to your project and add these two environment variables.

SKIP_DEPENDENCY_INSTALL=true
UNSTABLE_PRE_BUILD=asdf plugin add bun && asdf install bun latest && asdf global bun latest && bun i

Commit and deploy!

If everything works locally, and your Cloudflare environment variables are set, you're ready to deploy your site! My blog is still relatively small, and takes under a minute to build. However, now than Bun 1.0 is out, I'll be looking at other repos to use as benchmarks, and test how far I can push Bun. If you want to stay up to date with all my planned Bun & Astro content, and all my other shenanigans, be sure to subscribe to my email list (or the RSS feed) and follow me on Twitter.

Add Searching To Your Astro Static Site

Reuben Tier — Thu, 05 Jan 2023 15:38:16 +0000

This guide was initially published on my blog. Check it out here

Astro is great for static site generation, but it doesn't come with any built-in search tools out of the box. While some may use third-party tools such as Algolia, I wanted to avoid relying on third-party services.

Enter Pagefind, a static search library for indexing your content and presenting search results on your static site. Pagefind is framework agnostic, but setup can be a little tricky.

Installing Pagefind

Install Pagefind as a development dependency. The package contains a CLI tool that will generate the actual JavaScript to run on your site.

npm install --save-dev pagefind

Adding A `postbuild` Script

Pagefind needs to run after your site has been built, because it analyzes the HTML files to generate the search index. Add a postbuild script to your package.json to run Pagefind after your site has been built. The source directory will be the output of Astro's build (dist) and the bundle directory (which is always placed inside the source directory) will be pagefind.

{
  ...
  "scripts": {
    ...
    "postbuild": "pagefind --source dist --bundle-dir pagefind"
  },
  ...
}

Adding a Dev Endpoint

A big issue I came across when first solving this, is that there's no way to inject the pagefind bundle into your site at development time, because the site only exists as memory. I solved this by adding a dev endpoint to my site, which will serve a "fake" Pagefile script filled with 0 results. This way, the script will always be available, and the search results will always be empty. It's a little hacky, but it works. Create a new file at src/pages/pagefind/pagefind.js.ts with the following contents:

import type { APIContext } from "astro"

export async function get({}: APIContext) {
  return {
    body: 'export const search = () => {return {results: []}}'
  }
}

There's probably a better way to do this, but this will prevent your site from screaming at you when you try to access the pagefind script at development time. During build time, since Pagefind is run after the site is built, the actual Pagefind script will replace the dev endpoint.

Adding a Searchbar

To keep things simple, I'm going to simply use an <input> element as a searchbar, just to show how to integrate Pagefind's library. You can choose to put this anywhere on your site. If you're using the default Astro template, you can add it to src/pages/index.astro for example.

What we're doing here, is listening to the input event on the searchbar, and then loading the Pagefind script if it hasn't been loaded yet. Once the script is loaded, we can use the search function to search the index. The search function returns the results. Each result has a data function, which returns the data for that result. In this case, we're using the url and meta.title properties to create a link to the result, and the excerpt property to show a preview of the result. You can find a reference to the structure returned by data here.

<input id="search" type="text" placeholder="Search...">

<div id="results" />

<script is:inline>
  document.querySelector('#search')?.addEventListener('input', async (e) => {
    // only load the pagefind script once
    if (e.target.dataset.loaded !== 'true') {
      e.target.dataset.loaded = 'true'
      // load the pagefind script
      window.pagefind = await import("/pagefind/pagefind.js");
    }

    // search the index using the input value
    const search = await window.pagefind.search(e.target.value)

    // clear the old results
    document.querySelector('#results').innerHTML = ''

    // add the new results
    for (const result of search.results) {
      const data = await result.data()
      document.querySelector('#results').innerHTML += `
        <a href="${data.url}">
          <h3>${data.meta.title}</h3>
          <p>${data.excerpt}</p>
        </a>`
    }
  })
</script>

The benefit of asyncronously loading the Pagefind script is that it won't affect the performance of your site. The script is only loaded when the user starts typing in the searchbar. Allowing you to keep all 100s in your Lighthouse score 😎

Excluding Elements From The Index

Pagefind will index all of the text in the body element by default, excluding elements like nav, script, and form. If you want to exclude additional elements from the index, you can add the data-pagefind-ignore attribute to the element. I recommend doing this on any lists or archive pages to prevent the index from being bloated with duplicate content.

Wrapping Up

Now you can expose a good search experience to your users, without a third-party provider. It took me a few hours to get this working, so hopefully this will save you some debugging time. You won't be able to search your site in development, but you can always build your site to test it out.

Thanks for reading! If you have any questions, feel free to reach out to me on Twitter or Discord.

Generate OpenGraph Images Dynamically

Reuben Tier — Mon, 02 Jan 2023 22:54:07 +0000

This tutorial was originally posted on my new blog. Check it out here and watch out for new and exclusive articles soon.

Vercel's OG image generation library is an awesome tool for dynamically generating images for your website's content. It's a great way to make your content stand out on social media. In this post, we'll look at what makes up Vercel's OG image generation library and how we can recreate it without being limited to Vercel.
I'll be using Astro, but the general concepts can be applied to any framework.

What makes up Vercel's OG image generation library?

Satori

Satori is the library used in the @vercel/og package and is also maintained by Vercel. Satori takes a JSX component, and renders that into an SVG.

ReSVG

ReSVG is a library for SVGs and can be used to render SVGs to PNG images. ReSVG is used in the @vercel/og package to render the SVGs generated by Satori into PNG images.

Installing Some Dependencies

We'll use Satori & ReSVG to recreate the exact same functionality, but we will add one more thing. Satori-HTML is a library by Nate Moore to convert raw HTML into JSX suitable for Satori. This will allow us to use HTML to generate our images.

npm install satori satori-html @resvg/resvg-js

Loading Fonts

Satori requires that you load the fonts you want to use in your SVG. Download the font(s) you want to use, and import them into your project. I'll be using Open Sans for this example.

We need to add a Vite plugin to load the font files. I can't remember where exactly I first found the code, but the first instance of it I could find when coming back to writing this is from geoffrich/sveltekit-satori, so thanks to them for making my day much easier :D

Navigate to astro.config.mjs and add the following method. Also, we need to exclude the @resvg/resvg-js package from Vite's dependency optimization, otherwise we get some odd behaviour.

export default defineConfig({
  ...

  vite: {
    plugins: [rawFonts(['.ttf'])],
    optimizeDeps: { exclude: ['@resvg/resvg-js'] }
  },
});

function rawFonts(ext) {
  return {
    name: 'vite-plugin-raw-fonts',
    transform(_, id) {
      if (ext.some(e => id.endsWith(e))) {
        const buffer = fs.readFileSync(id);
        return {
          code: `export default ${JSON.stringify(buffer)}`,
          map: null
        };
      }
    }
  };
}

Creating an Endpoint

We'll create an endpoint to generate our images at /api/og.png.ts. Again, this can be done with any framework, but I'll be using Astro. Import satori, satori-html, and @resvg/resvg-js into the file. Also, import any fonts you want to use (at least one).

import satori from 'satori';
import { html } from 'satori-html';
import { Resvg } from '@resvg/resvg-js';
import OpenSans from '../../../lib/OpenSans-Regular.ttf'

Then define a function get to handle the request. Use a html tagged template to take some HTML and return a JSX component. You can either pass inline styles, or use Tailwind classes by including the tw prop.

export async function get() {
  const out = html`<div tw="flex flex-col w-full h-full bg-white">
    <h1 tw="text-6xl text-center">Hello World</h1>
  </div>`
}

Continue by rendering the JSX component to an SVG using Satori. You can pass in the fonts to Satori, as well as a height and width for the SVG.

  let svg = await satori(out, {
    fonts: [
      {
        name: 'Open Sans',
        data: Buffer.from(OpenSans),
        style: 'normal'
      }
    ],
    height: 630,
    width: 1200
  });

Use new Resvg to load the SVG into Resvg, passing any arguments. Call .render() to render the SVG to an image.

  const resvg = new Resvg(svg, {
    fitTo: {
      mode: 'width',
      value: width
    }
  });

  const image = resvg.render();

Finally, return the image as a PNG, and set the headers for content-type and cache the image if your usecase is static.

  return {
    headers: {
      'Content-Type': 'image/png',
      'Cache-Control': 'public, max-age=31536000, immutable'
    },
    body: image.asPng()
  }

That's it!

Navigate to http://localhost:3000/api/og.png to view the image. You can modify the HTML to see how it affects the image. You can use this to generate OG images at build time, or add SSR support to generate images at runtime time.

Thanks for reading. If you have any questions, feel free to reach out to me on Twitter or my brand new Discord server.

Create Your Own JavaScript Runtime

Reuben Tier — Thu, 01 Sep 2022 17:56:22 +0000

This post was originally posted in JavaScript in Plain English on Medium. You can find future tutorials over on my Medium series

Whether it be a browser runtime or a server-side runtime like Node.js, we all use some sort of runtime to run our JavaScript code. Today, we’ll create a basic JavaScript runtime of our own, using the V8 JavaScript engine.

What is a JavaScript runtime?

A JavaScript runtime is simply an environment that extends a JavaScript engine by providing useful APIs and allowing the program to interact with the world outside its container. This differs from an engine, which simply parses the code and executes it inside a contained environment.

As I mentioned earlier, V8 is a JavaScript engine, meaning it handles the parsing and execution of JavaScript source code. Node.js and Chrome (both powered by v8), provide objects and APIs that allow the code to interact with things like the file system (via node:fs), or the window object (in Chrome).

Setup

In this tutorial, we’ll be using Rust to create our runtime. We’ll use the V8 bindings maintained by the Deno team. Because creating a runtime is a complex process, today we’ll start simple, by implementing a REPL (read-evaluate-print loop). A prompt that runs JavaScript one input line at a time.

To get started, create a new project with cargo init. Then, add some dependencies to the Cargo.toml file. The v8 package contains the bindings to the V8 JavaScript engine, and clap is a popular library for handling command line arguments.

[dependencies]
v8 = "0.48.0"
clap = "3.2.16"

Managing command inputs

When using our runtime, we probably want to provide it with some command line arguments, such as what file to run, or any flags that modify behaviour. Open src/main.rs and in our main function, replace the println call with some code defining our sub-commands and input parameters. If no sub-command is provided, we’ll do the same thing Node.js does, and throw the user into a REPL. We’ll also create one sub-command run which we will implement in a later tutorial. run, once implemented, will allow the user to run a JavaScript file (with any other parameters we define).

use clap::{Command, arg};
fn main() {
  let cmd = clap::Command::new("myruntime")
  .bin_name("myruntime")
  .subcommand_required(false)
  .subcommand(
    Command::new("run")
      .about("Run a file")
      .arg(arg!(<FILE> "The file to run"))
      .arg_required_else_help(true),
  );
}

Now, we’ll match the arguments against this schema, and handle the responses accordingly.

  ...
  let matches = cmd.get_matches();
  match matches.subcommand() {
    Some(("run", _matches)) => unimplemented!(),
    _ => {
      unimplemented!("Implement this in the next step")
    },
  };

We only have two possibilities for now. The first is run which we will not be implementing today, and the second is no sub-command, which will open our REPL. Before we implement the REPL, we first need to create our JavaScript environment.

Initializing V8 & creating an engine instance

Before we can do anything with V8, we must first initialise it. Then, we need to create an isolate. An all-encompassing object that represents a single instance of the JavaScript engine.

Add a use statement at the top of the file to include the v8 crate. Next, let’s return to that slice of unimplemented code for our REPL and initialise V8, as well as create an isolate and wrap it in a HandleScope.

use v8;
...
    _ => {
      let platform = v8::new_default_platform(0, false).make_shared();
      v8::V8::initialize_platform(platform);
      v8::V8::initialize();
      let isolate = &mut v8::Isolate::new(v8::CreateParams::default());
      let handle_scope = &mut v8::HandleScope::new(isolate);
    },

Creating the REPL

To help manage our code, we’ll create our runtime inside a struct. When a new instance is created, we’ll create a Context. The Context allows a set of global and builtin objects to exist inside a “context”. Speaking of global objects, we’ll create an object template called global for use in a later tutorial. This object allows us to bind our own global functions, but for now, we’ll just use it to create the context.

struct Runtime<'s, 'i> {
  context_scope: v8::ContextScope<'i, v8::HandleScope<'s>>,
}
impl<'s, 'i> Runtime<'s, 'i>
where
  's: 'i,
{
  pub fn new(
    isolate_scope: &'i mut v8::HandleScope<'s, ()>,
  ) -> Self {
    let global = v8::ObjectTemplate::new(isolate_scope);
    let context = v8::Context::new_from_template(isolate_scope, global);
    let context_scope = v8::ContextScope::new(isolate_scope, context);
Runtime { context_scope }
  }
}

Next, let’s define a method inside Runtime responsible for handling the REPL, and only the REPL. Using a loop, we’ll grab the input on each iteration, then run that if successful. We’ll also need to import some things from std::io at the top of the file.

use std::io::{self, Write};
...
pub fn repl(&mut self) {
    println!("My Runtime REPL (V8 {})", v8::V8::get_version());
    loop {
      print!("> ");
      io::stdout().flush().unwrap();

      let mut buf = String::new();
      match io::stdin().read_line(&mut buf) {
        Ok(n) => {
          if n == 0 {
            println!();
            return;
          }

          // prints the input (you'll replace this in the next step)
          println!("input: {}", &buf);
        }
        Err(error) => println!("error: {}", error),
      }
    }
  }

Now let’s return our REPL command in main, create a runtime instance, and initialize the REPL.

      ...
      let mut runtime = Runtime::new(handle_scope);
      runtime.repl();

Running the code

Our run method will take the code, as well as a filename (which for the REPL we will simply use (shell)) for error handling. We create a new scope to handle the execution of the script and wrap this in a TryCatch scope for a better error handle (which we will implement in a future tutorial). Next, we initialise the script and create an origin object, which defines where this script originated from (in a file).

  fn run(
    &mut self,
    script: &str,
    filename: &str,
  ) -> Option<String> {
    let scope = &mut v8::HandleScope::new(&mut self.context_scope);
    let mut scope = v8::TryCatch::new(scope);
    let filename = v8::String::new(&mut scope, filename).unwrap();
    let undefined = v8::undefined(&mut scope);
    let script = v8::String::new(&mut scope, script).unwrap();
    let origin = v8::ScriptOrigin::new(
      &mut scope,
      filename.into(),
      0,
      0,
      false,
      0,
      undefined.into(),
      false,
      false,
      false,
    );
}

Now, continuing run, we compile the script, catch any errors, and print that an error occurred. We then run the script, again catching any errors and logging if an error did occur. We then return the result of the script (or None if an error occurred).

    ...
    let script = if let Some(script) = v8::Script::compile(&mut scope, script, Some(&origin)) {
      script
    } else {
      assert!(scope.has_caught());
      eprintln!("An error occurred when compiling the JavaScript!");
      return None;
    };
    if let Some(result) = script.run(&mut scope) {
      return Some(result.to_string(&mut scope).unwrap().to_rust_string_lossy(&mut scope));
    } else {
      assert!(scope.has_caught());
      eprintln!("An error occurred when running the JavaScript!");
      return None;
    }

Return to these two lines in our repl method.

          // prints the input (you'll replace this in the next step)
          println!("input: {}", &buf);

We can now implement our run method. Replace the println with an if statement to run the script, and print the result.

          if let Some(result) = self.run(&buf, "(shell)") {
            println!("{}", result);
          }

Conclusion

Congratulations! You’ve made the first step in creating your own JavaScript runtime using the V8 engine. The completed code from this tutorial can be found on GitHub, and I’ve listed some wonderful resources that made the tutorial possible below.

Next time, we’ll tackle error handling using some of the code we’ve already put in place (such as the TryCatch scope).