Basically you can summarize the law suit down to 2 points,

• Apple is using their platform to limit competition in unfair ways; if iOS and others were not open to 3rd parties this really wouldn't be a problem

• Apple may not be the largest player per-se but their Market Power and Abuse of said power is an indication of Monopolistic behaviour

  • A good example here would be Amazon and Google. Amazon is not the only shopping website in the world (neither is Google for search) but they have a lot of Market Power. On their Platforms they need to ensure that they don't unfairly promote their products at the expense of other competition basically competition must be fair when you have a platform (same thing with Microsoft actually)

Note: Gov't don't necessarily care if you're a Monopoly, what they care about is if you're actively abusing your enhanced Market Position to limit competition or promote your own products.

Another Note: The US gov't doesn't necessarily use anti-trust laws for the sake of consumers they use it to guarantee competition and a fair playground/market place with the idea being that with more competition, customers get better deals and better products

Another Another Note: The US gov't is not suing Apple for the Phones (they can't touch that since people are voting with their wallets there) they're suing Apple for their OS, and the rules being unfair on said OS

TL;DR; Apple is abusing Market Power in a way that makes it difficult to compete on their platforms. Apple may have built the best sandbox but so long as they're allowing others to play in that sandbox they need to make sure the game is played fairly, this same rule applied to Microsoft during their anti-trust lawsuit case. Windows is Microsoft's baby but if Microsoft unfairly promotes their products at the detriment to other competitors then anti-trust lawsuit (as simple as that)

It's been a minute, hasn't it? I've been...busy, but I'm back with something that I think you'll find both useful and intriguing. While I was away, I stumbled upon a nifty trick that involves swapping Docker for Podman in DevContainers on VS Code. This isn't a step-by-step guide; it's more like sharing a cool discovery I made. So, let's get to it!

A Quick Refresher on DevContainers 🏝

If you're new to the concept, DevContainers in VS Code are a way to containerize your development environment. This ensures that your setup is both portable and consistent, effectively eliminating the "it works on my machine" syndrome.

Think of DevContainers as your very own Codespace or Gitpod, but without needing the cloud. It's like having a sandbox, but your computer is the playground. You get to build your castles in an isolated space, keeping the rest of your system pristine.

The Podman Appeal 🎸

Switching gears to Podman, why would you want to replace Docker? Imagine Docker as the old, reliable minivan. It gets the job done, but it's not the sleekest. Podman is like the electric car that just rolled off the assembly line—efficient, user-friendly, and secure.

Docker has been the go-to containerization tool for years, but Podman is emerging as a strong alternative. Podman offers a few advantages:

1. Rootless Containers: Run containers without needing root privileges, enhancing security. Learn more about rootless containers.

2. Systemd Integration: Better integration with Linux's init system, systemd. For Linux users, this is a significant benefit. Podman's compatibility with systemd offers better process management and orchestration. Learn more about systemd.

3. Follows Open Standards: Fully compatible with Open Container Initiative (OCI) standards. Podman is OCI-compliant, which means it adheres to industry standards for container images, making it easier to switch between different container technologies. Learn more about OCI.

So, if you're looking to break free from Docker's grasp, Podman is worth considering.

The Challenge: VS Code Loves Docker

Here's the hiccup: VS Code's DevContainers extension is tightly coupled with Docker. When you try to use Podman, VS Code throws a fit and keeps asking you to install Docker. That's the issue we're going to solve today.

The Solution: Trick VS Code with a Shell Script

macOS

Step 1: Install Podman

First things first, you'll need to install Podman. On a Mac, you can use Homebrew:

brew install podman

Step 2: Initialize and Start Podman Machine

Before using Podman, you need to initialize and start a Podman machine:

podman machine init
podman machine start

Step 3: Create a Shell Script

VS Code is looking for a command named docker. We'll give it what it wants, but we'll secretly redirect it to podman.

Create a new shell script and name it docker:

sudo nano /usr/local/bin/docker

In the script, add the following lines:

#!/bin/bash
exec podman "$@"

Save the file and exit the text editor.

Step 4: Make the Script Executable

Now, make the script executable:

sudo chmod +x /usr/local/bin/docker

Step 5: Restart VS Code

Close and reopen VS Code to apply the changes. It should now be none the wiser, happily using Podman instead of Docker.

Linux

Step 1: Install Podman

Open your terminal and run the following command to install Podman:

sudo apt install -y podman

Steps 2-5: Follow the same steps as for macOS

Windows

Step 1: Install Podman for Windows

Download and install Podman from the official site.

Step 2: Create a Batch File

Create a batch file named docker.bat to act as an alias for Podman:

@echo off
podman %*

Place this batch file in a directory that's in your system's PATH.

Option 1: Use an Existing Directory in PATH

1. Open a Command Prompt and type echo %PATH% to see the directories currently in your PATH.

2. Choose an existing directory that you have write access to, such as C:\Users\YourUsername\bin.

3. Save or move your docker.bat file into that directory.

Option 2: Create a New Directory and Add It to PATH

1. Create a new directory where you want to store your batch files, for example, C:\batch_files.

2. Move your docker.bat file into this new directory.

3. To add this directory to your PATH, right-click on 'This PC' or 'Computer' on your desktop or File Explorer, and choose Properties.

4. On the left-hand side, click on Advanced system settings.

5. Click on the Environment Variables button near the bottom right.

6. Under the 'System variables' section, find and select the Path variable, then click on Edit.

7. Click on New and add the path to your new directory, C:\batch_files.

8. Click OK on all the dialog boxes to save your changes.

Verify the Setup

To verify that the batch file is accessible:

1. Open a new Command Prompt window (important, as existing windows won't pick up the change).

2. Type docker and hit Enter. If everything is set up correctly, this should now execute Podman due to the aliasing in your docker.bat file.

By following these steps, you ensure that the batch file is in a directory listed in your PATH, making it accessible from any command prompt window.

Step 3: Restart VS Code

Close and reopen VS Code to apply the changes.

Wrapping Up

There you have it—a Podman-powered DevContainer in VS Code, right on your local machine. It's like having a VIP pass to a more secure and efficient coding environment. Whether you're a newcomer or a seasoned developer, I hope you find this as useful as I did.

So go ahead, give Podman a spin, and bring a little more freedom to your containerized development environments.

Bye!

I was closing out some long lived issues over on bundlejs, when issue #50 reminded me of the ongoing debate about how bundlejs should handle the ESM and CJS packages.

Lightbulbs flickered, coffee was consumed (I don't drink coffee, but you get the point), and I'm pretty sure I've cracked a solution. But there are a few slight behavior changes you need to be aware of. So buckle up. If anything looks off or confusing, please let me know in either the comments below, on GitHub Discussions or issue #50 directly.

The Issue at Hand 🧐

The root of the problem lies in how bundlejs was handling CommonJS files.

"CommonJS files only export their default, which created a conundrum. How can we tell if a module is CommonJS if we don't fetch it? And if we fetch it first, it's too late for esbuild to deal with it properly."

But never fear! I've worked out a solution that is impartial to whether the module is ESM or CommonJS.

The Solution 🧩

Let's walk through this step by step, using our handy deno.bundlejs.com API for demonstration.

1. Single CJS File: Only export the default (no renaming involved). Check out this example using postcss-easings: https://deno.bundlejs.com/?file&q=postcss-easings&minify=false

    // ...
    // virtual-filesystem:/index.ts
    var index_exports = {};
    __export(index_exports, {
      default: () => import_postcss_easings.default
    });
    __reExport(index_exports, __toESM(require_postcss_easings_4_0()));
    var import_postcss_easings = __toESM(require_postcss_easings_4_0());
    var export_default = import_postcss_easings.default;
    export {
      export_default as default
    };
   

2. Multiple CJS Files: Export the default but use the file URL as the import name. Also, append ...Default to the end of it like so: reactDefault & reactDomDefault. Take a peek here: https://deno.bundlejs.com/?file&q=react,react-dom&minify=false

    // ...
    // virtual-filesystem:/index.ts
    var index_exports = {};
    __export(index_exports, {
      reactDefault: () => import_react.default,
      reactDomDefault: () => import_react_dom.default
    });
    __reExport(index_exports, __toESM(require_react_18_2()));
    var import_react = __toESM(require_react_18_2());
    __reExport(index_exports, __toESM(require_react_dom_18_2()));
    var import_react_dom = __toESM(require_react_dom_18_2());
    var export_reactDefault = import_react.default;
    var export_reactDomDefault = import_react_dom.default;
    export {
      export_reactDefault as reactDefault,
      export_reactDomDefault as reactDomDefault
    };
   

3. Single ESM File: Export everything, including the default. No renaming here, folks! https://deno.bundlejs.com/?file&q=spring-easing&minify=false

    // ...
    export {
      BatchSpringEasing,
      CSSSpringEasing,
      EaseInOut,
      EaseOut,
      EaseOutIn,
      EasingDurationCache,
      EasingFunctionKeys,
      EasingFunctions,
      EasingOptions,
      FramePtsCache,
      GenerateSpringFrames,
      INFINITE_LOOP_LIMIT,
      SpringEasing,
      SpringFrame,
      SpringInFrame,
      SpringInOutFrame,
      SpringOutFrame,
      SpringOutInFrame,
      batchInterpolateComplex,
      batchInterpolateNumber,
      batchInterpolateSequence,
      batchInterpolateString,
      batchInterpolateUsingIndex,
      SpringEasing as default, // <- The default export
      getLinearSyntax,
      getOptimizedPoints,
      getSpringDuration,
      getUnit,
      interpolateComplex,
      interpolateNumber,
      interpolateSequence,
      interpolateString,
      interpolateUsingIndex,
      isNumberLike,
      limit,
      parseEasingParameters,
      ramerDouglasPeucker,
      registerEasingFunction,
      registerEasingFunctions,
      scale,
      squaredSegmentDistance,
      toAnimationFrames,
      toFixed
    };
   

4. Multiple ESM Files: Export all methods and variables from all exports, but remember to use the naming rules for all default exports. For instance, after exporting the other module exports, rename the default export to springEasingDefault and codepointIteratorDefault: https://deno.bundlejs.com/?file&q=spring-easing,codepoint-iterator&minify=false

    // ...
    var mod_default = asCodePointsIterator;
    export {
      BITS_FOR_2B,
      BITS_FOR_3B,
      BITS_FOR_4B,
      BatchSpringEasing,
      CSSSpringEasing,
      EaseInOut,
      EaseOut,
      EaseOutIn,
      EasingDurationCache,
      EasingFunctionKeys,
      EasingFunctions,
      EasingOptions,
      FramePtsCache,
      GenerateSpringFrames,
      INFINITE_LOOP_LIMIT,
      LEAD_FOR_1B,
      LEAD_FOR_2B,
      LEAD_FOR_3B,
      LEAD_FOR_4B,
      LEAD_FOR_5B,
      MASK_FOR_1B,
      MASK_FOR_2B,
      MASK_FOR_3B,
      MASK_FOR_4B,
      SpringEasing,
      SpringFrame,
      SpringInFrame,
      SpringInOutFrame,
      SpringOutFrame,
      SpringOutInFrame,
      UTF8_MAX_BYTE_LENGTH,
      asCodePointsArray,
      asCodePointsCallback,
      asCodePointsIterator,
      batchInterpolateComplex,
      batchInterpolateNumber,
      batchInterpolateSequence,
      batchInterpolateString,
      batchInterpolateUsingIndex,
      bytesToCodePoint,
      bytesToCodePointFromBuffer,
      codePointAt,
      mod_default as codepointIteratorDefault, // <- codepoint-iterator's default export
      getByteLength,
      getIterableStream,
      getLinearSyntax,
      getOptimizedPoints,
      getSpringDuration,
      getUnit,
      interpolateComplex,
      interpolateNumber,
      interpolateSequence,
      interpolateString,
      interpolateUsingIndex,
      isNumberLike,
      limit,
      parseEasingParameters,
      ramerDouglasPeucker,
      registerEasingFunction,
      registerEasingFunctions,
      scale,
      SpringEasing as springEasingDefault, // <- spring-easing's default export
      squaredSegmentDistance,
      toAnimationFrames,
      toFixed
    };
   

5. Treeshaking: Here, we assume you want the driver's seat if you add the treeshake query param to the URL. So, all of the above rules are null and void, and you now have complete control over what is exported, including the default exports not being automatic. https://deno.bundlejs.com/?file&q=spring-easing,react&treeshake=[*],[*]&minify=false

    // ...
    export {
      BatchSpringEasing,
      CSSSpringEasing,
      EaseInOut,
      EaseOut,
      EaseOutIn,
      EasingDurationCache,
      EasingFunctionKeys,
      EasingFunctions,
      EasingOptions,
      FramePtsCache,
      GenerateSpringFrames,
      INFINITE_LOOP_LIMIT,
      SpringEasing,
      SpringFrame,
      SpringInFrame,
      SpringInOutFrame,
      SpringOutFrame,
      SpringOutInFrame,
      batchInterpolateComplex,
      batchInterpolateNumber,
      batchInterpolateSequence,
      batchInterpolateString,
      batchInterpolateUsingIndex,
      getLinearSyntax,
      getOptimizedPoints,
      getSpringDuration,
      getUnit,
      interpolateComplex,
      interpolateNumber,
      interpolateSequence,
      interpolateString,
      interpolateUsingIndex,
      isNumberLike,
      limit,
      parseEasingParameters,
      ramerDouglasPeucker,
      registerEasingFunction,
      registerEasingFunctions,
      scale,
      squaredSegmentDistance,
      toAnimationFrames,
      toFixed
    };
    // ^ React isn't exported at all
   

🚨 Note: You might run into issues with CJS modules if you don't export default properly. Part of this is because tree-shaking is somewhat of a no-show for CJS packages, so tread lightly here!

There you have it! A quick and dirty rundown of the latest updates to the way bundlejs.com handles CJS and ESM packages.

So, go ahead and take the new system for a spin. Let me know what you think. Take it for a ride 🚗

Photo by Marcin Jozwiak: https://www.pexels.com/photo/abstract-red-and-white-waves-background-subtle-gradients-flow-liquid-lines-design-element-13835514/

Check it out vercel.com/changelog/support-center

BTW, I joined Vercel 🎉 ~6 months ago...

Well anyway...

Support Center is a modern tool for viewing and communicating with Customer Support at Vercel. Built for enterprises to improve the customer support experience while retaining the practices and tools that the Customer Support Team at Vercel had built up over the years. From what customers and the Customer Support Team have told us we've achieved that goal.

For some background. Before Support Center, customers had to email support before they could get any help 😬, it was clunky and prone to "**email got sent to spam errors", and "**I didn't check my email problems", realizing that the experience wouldn't do, the dev team drafted up the idea to connect the current Salesforce based ticketing system with a UI/UX customers would enjoy.

The main hiccup we ran into during development was the excessively complex (and archaic) work of integrating with Salesforce and the performance of the support center, of which the solution is caching (the bane of all Software Engineers everywhere).

📚 Fun fact: Salesforces uses a SQL-like syntax for querying data that's similar to SQL but yet very far away from SQL, it's called SOQL, and working with it can be very frustrating

The problems boiled down to:

1. How do you keep the cache always up to date?

2. How to keep the support center fast, responsive, and reliable with the most up-to-date info?

3. How to make working with Salesforce easier?

The solution to the first 2 problems... 🥁 are webhooks of course.

In essence, whenever a change is made on Salesforce we call a webhook and have that webhook sync with a cache that we use for the support cases 🤯.

We can then expand how long the cache should securely hold case data, and add a cache warm-up for when on the main page.

The last issue was dealing with the complexity of working with Salesforce, we just powered through and though frustrating, I think the results are pretty fantastic.

Working on this project was awesome, and I'm grateful for being able to work with such a capable team of designers & developers on this project.

✌️

Someone recently asked me how to use FormData with Astro, to which I responded I'll create a small document for this (I'll create a pr to add this to the Astro docs a little later).

Getting started

I won't go into detail on what FormData is, but here is a short summary

FormData [is an] interface [which] provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the fetch() or XMLHttpRequest.send() method. It uses the same format a form would use if the encoding type were set to "multipart/form-data".

Source: MDN - FormData

Basically instead of using JSON to send data to and from your server, you'd use FormData, except unlike JSON it supports files natively.

For example,

// 1. Create or Get a File 
/** Creating a File */
const fileContent = `Text content...Lorem Ipsium`;
const buffer = new TextEncoder().encode(fileContent);
const blob = new Blob([buffer]);
const file = new File([blob], "text-file.txt", { type: "text/plain" });
/** OR */
/** Getting a File */
const fileInput = document.querySelector("#files"); // <input id="files" type="file" multiple /> 
const file = fileInput.files.item(0);

// 2. Create FormData
const formData = new FormData();

// 3. Add File to FormData through the `file` field
formData.append("file", file); // FormData keys are called fields

const file = fileInput.files.item(0);

^ fileInput.files is a FileList, which is similar but not an array, to work around this you can convert the FileList to an array of File's using Array.from

For our use case, since we're only trying to upload one file, it'd be easier to select the first File in the FileList

Learn more on MDN - HTMLInputElement and MDN - File

Note: you can also just directly use FileReader instead of using an <input /> element

Usage

There are 2 ways to support FormData in Astro; the easy and the hard way, I'll show you both.

Note: both the easy and hard way require Astro to be configured in server (SSR) mode

import { defineConfig } from 'astro/config';

// https://astro.build/config
export default defineConfig({
 output: 'server',
});

Easy Way

The easy way requires you to create a new .ts file that will act as your endpoint, for example, if you wanted a /upload endpoint, you would create a .ts file in src/pages.

Read Astro's official docs on File Routes to learn more

Your basic file tree should look like this after creating your endpoint

src/
├─ pages/
│  ├─ upload.ts
│  ├─ index.astro

Inside your index.astro file follow the example I gave above in #getting-started, on getting FormData up and running.

Once you've created an instance of FormData and populated it with the files you'd like to upload, you then just setup a POST request to that endpoint.

// ...
const res = await fetch('/upload', {
  method: 'POST',
  body: formData,
});
const result = await res.json();
console.log(JSON.stringify(result));

From the endpoint side you'd then need to export a post method to handle the POST request being sent,

Here is where things get complex. I recommend going through Astro's File Routes Docs

import type { APIContext } from 'astro';

// File routes export a get() function, which gets called to generate the file.
// Return an object with `body` to save the file contents in your final build.
// If you export a post() function, you can catch post requests, and respond accordingly
export async function post({ request }: APIContext) {
  const formData = await request.formData();
  return {
    body: JSON.stringify({
      fileNames: await Promise.all(
        formData.getAll('files').map(async (file: File) => {
          return {
            webkitRelativePath: file.webkitRelativePath,
            lastModified: file.lastModified,
            name: file.name,
            size: file.size,
            type: file.type,
            buffer: {
              type: 'Buffer',
              value: Array.from(
                new Int8Array(await file.arrayBuffer()).values()
              ),
            },
          };
        })
      ),
    }),
  };
}

The basics of what's happening here are fairly simple, but the code all put together seems rather complex, so let's break it down.

First, the exported post function handles POST requests as its name suggests, meaning if you send a get request and don't export a get function an error will occur.

export async function post() { ... } what?! Yeah, I too recently learned that Astro supports this out of the box, which is awesome.

W3Schools cover POST and GET fairly well, take a look at their article if you're not familiar with POST and GET requests

Let's first talk about the request parameter. As it's name suggests request is an instance of the Request class which includes all the methods that Request supports, including a method for transforming said request into FormData you can work with.

// ...
export async function post({ request }: APIContext) {
  const formData = await request.formData();
  // ...
}

Using formData you can get all the instances of a specific field (FormData keys are called fields), for example, get all File's in the file field.

// ...
export async function post({ request }: APIContext) {
  const formData = await request.formData();
  return {
    body: JSON.stringify({
      // getAll('file') will return an array of File classes
      fileNames: formData.getAll('file'),
    }),
  };
}

The problem with this solution is that it will return {"fileNames":[{}]} due to JSON.stringify being unable to convert File classes to a string

To deal with this formatting issue we need to format the File's array properly,

// ...
export async function post({ request }: APIContext) {
  const formData = await request.formData();
  return {
    body: JSON.stringify({
      // getAll('files') will return an array of File classes
      fileNames: formData.getAll('files').map(async (file: File) => {
          return {
            webkitRelativePath: file.webkitRelativePath,
            lastModified: file.lastModified,
            name: file.name,
            size: file.size,
            type: file.type,
            buffer: { /* ... */ }
          };
        }),
    }),
  };
}

The last part is converting ArrayBuffers into data that is easy to work with, for this case using arrays to represent buffers works rather well, so we just do some conversion,

// ...
export async function post({ request }: APIContext) {
  const formData = await request.formData();
  return {
    body: JSON.stringify({
      // getAll('file') will return an array of File classes
      fileNames: formData.getAll('file').map(async (file: File) => {
          return {
            // ...
            buffer: {
              type: 'Buffer',
              value: Array.from(
                new Int8Array(
                  await file.arrayBuffer()
                ).values()
              ),
            },
          };
        }),
    }),
  };
}

That's the easy way. Using Astro's baked in file routes to act as an endpoint for your FormData.

To actually run Astro with the /upload endpoint all you need is npm run dev

You can view a demo of the easy way on Stackblitz, CodeSandbox and GitHub

Hard Way

The hard way requires you to use the multer middleware together with expressjs, in order to make the @astrojs/node integration support FormData requests.

The hard way mostly builds on the #easy-way, except instead of a src/pages/upload.ts file, you would instead use a server.mjs file in the root directory to define your endpoints, so, your file structure would look more like this,

src/
├─ pages/
│  ├─ index.astro
server.mjs

The core of the hard way occurs inside server.mjs. server.mjs should look like this by the end of this blog post

import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';
import multer from 'multer';

const app = express();
app.use(express.static('dist/client/'));
app.use(ssrHandler);

const upload = multer();
app.post('/upload', upload.array('file'), function (req, res, next) {
  // req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
  //
  // e.g.
  //  req.files['avatar'][0] -> File
  //  req.files['gallery'] -> Array
  //
  // req.body will contain the text fields, if there were any
  console.log(req.files);
  res.json({ fileNames: req.files });
});

app.listen(8080);

When you build an Astro project in server (SSR) mode (e.g. npm run build), Astro will automatically generate a dist/server/entry.mjs file, it's this file that allows us to build our own custom nodejs server and then run Astro off this server.

For this specific use case we are using express for the server, and to enable FormData support in express we need the multer middleware, so if you're familiar with express at all this should look familiar,

import express from 'express';
import { handler as ssrHandler } from './dist/server/entry.mjs';

const app = express();
app.use(express.static('dist/client/'));
app.use(ssrHandler);

// ...
app.listen(8080);

The ssrHandler enables Astro to run on the express server, for the most part it can be treated like any other express middleware and ignored.

Note: If you're not familiar with the code snippet above, please go through express' documentation, it'll make the rest of the explanation easier to understand

The real interesting part is where multer and express meet.

By using a POST request handler we are able to recieve POST requests made to the /upload endpoint and respond back with the parsed FormData results, but unlike in the #easy-way, express is able to handle all the formatting allowing File responses to be as expected.

// ...
import multer from 'multer';

const app = express();
// ...

const upload = multer();
app.post('/upload', upload.array('files'), function (req, res, next) {
  // req.files is an object (String -> Array) where fieldname is the key, and the value is array of files
  //
  // e.g.
  //  req.files['avatar'][0] -> File
  //  req.files['gallery'] -> Array
  //
  // req.body will contain the text fields, if there were any
  console.log(req.files);
  res.json({ fileNames: req.files });
});

app.listen(8080);

Response to express POST request

That's the hard way. Using Astro's SSR mode together with express and multer to create the /upload endpoint which supports formData.

To actually run Astro you need to do a bit more than you'd need for the #easy-way

1. Install express and multer ->npm install express multer

2. Build Astro SSR handler ->npm run build

3. Run server.mjs -> node server.mjs

The hard way may seem easier, but that is due to having done alot of the prep work in the #easy-way, it is actually more overall work than the easy way.

You can view a demo of the hard way on Stackblitz, CodeSandbox and GitHub

Note: If you'd like to save uploaded files just to disk, add this to multer

const server = multer({ dest: './public/data/uploads/' })

That tells multer to automatically save the file to disk, read more on the multer docs

For Easy Mode here is a link to Stackblitz on how to save files.

Conclusion

There are 2 ways of using FormData with Astro, either the easy way or the hard way.

The easy way is to use Astro's baked-in File Routes to act as an endpoint for your FormData POST requests.

The hard way is to use Astro's SSR mode together with express and multer to create a /upload endpoint which supports FormData.

There is no right way, but I will recommend the easy way as it is easier and less confusing to work with overall.

Photo by Caleb Jack (@hitthetrailjack) on Unsplash.

Also, published on dev.to, and Hackernoon

bundlejs (pronounced bundle js) is a quick and easy way to treeshake, bundle, minify, and compress (in either gzip or brotli) your typescript, javascript, jsx and npm projects, while receiving the total bundles' file size.

bundlejs aims to generate more accurate bundle size estimates by following the same approach that bundlers use:

• Doing all bundling locally

• Outputing the treeshaken bundled code

• Getting the resulting bundle size

The benefits of using bundlejs are:

1. It's easier to debug errors

2. You can verify the resulting bundled code

3. The ability to configure your bundles

4. The ability to treeshake bundles

5. The ability view a visual analysis of bundles

6. You can bundle offline (so long as the module has been used before)

7. Supports different types of modules from varying Content Delivery Networks (CDNs), e.g. CDNs ranging from deno modules, to npm modules, to random github scripts, etc...

This blog post is meant to highlight some of the most important changes as well as to give some insight into how bundlejs works in the background, and to act as the docs for bundlejs.

📒Note: There will be a follow up article to this one, going into the technical nitty gritty on how bundlejs works and how you can use what I've learned from this project to either create your own online bundler or an es build-wasm backed js repl.

😅 TL;DR: this blog post is rather long, so take a look at the bundlejs.com website first, then skim through this blog post making sure to check out the images and the code examples, those can help cut down on confusion and reduce the required reading time.

Quick feature run down

This video runs through all the major features of bundlejs (there is audio but I don't have a good mic 😅)

Bundling, Treeshaking, and Minification

• Bundling is the process of efficiently concatenating modules together into one file which we call a bundle.

• Treeshaking is the process of a bundler traversing the modules to be bundled and removing unused code.

• Minification is the process of shrinking the amount of code necessary to have a functional program, e.g. removing blank space or reducing variable names, etc...

bundlejs uses esbuild and it's incredible ability to bundle, transform, transpile, minify, treeshake and traverse files. Specifically, bundlejs uses esbuild-wasm which is able to access a subset of those features, with the key limitations being,

1. npm only runs on node, so no package.json or npm install (a-la, a joke about using StackBlitzWebContainers to run node on the browser)

2. browsers don't work the way nodejs does. They don't have a easy way to access file system, so storing and accessing files isn't practical. The way esbuild would normally work when installed on node just causes issues on the web

3. due to the limitation of esbuild-wasm when running on a browser (no npm, and node nodejs), the only option is for modules to come from the web but esbuild doesn't natively support importing http(s)://... modules, so a different solution is required

To solve each of these problems esbuild's plugin system comes in clutch. I created a total of 4 plugins to solve these limitations, they are,

1. HTTP plugin - Fetches and caches modules

2. CDN plugin - Redirects npm package imports (sometimes referred to as bare imports) to Content Delivery Network (CDN) urls for fetching

3. EXTERNALS plugin - Marks certain imports/exports as modules to exclude from bundling

4. ALIAS plugin - Aliases certain imports/exports to modules of a different name

Content Delivery Networks (CDNs) are a great way to distribute code all over the world at fast speeds. In the context of bundlejs, CDNs represent online repositories of code that bundlejs can fetch from.

For example, unpkg.com is a fast global content delivery network for everything on npm. It's used to quickly and easily load any file from any package on npm using a URL like: https://unpkg.com/package-name@version/file.js, a similar thing would apply for skypack.dev, esm.sh, etc...

In a later blog post I will delve deeper into the technical details of how these plugins work, but for now just keep in mind that these plugins assist esbuild-wasm to create javascript bundles.

Console

In previous versions of bundlejs.com I encouraged devs to use the devtools console for viewing console logs, and for a while I thought it was an ok experience, but I started realizing that it was inconvenient and not very mobile friendly. Initially, I thought creating a virtual console would be a large undertaking, so I delayed adding a custom console for quite some time. Well in the March of this year inspired by @hyrious's esbuild-repl I finally did it 👏.

When I realized that a polyfill/ponyfill doesn't exist for SharedWorkers I realized I needed to make one, and to ensure reliable that the polyfill was thoroughly vetted and tested for cross browser compatibility, so, I made @okikio/sharedworker.

Usage

@okikio/sharedworker is a small mostly spec. compliant polyfill/ponyfill for SharedWorkers, it acts as a drop in replacement for normal Workers, and supports a similar API surface that matches normal Workers.

You use it like this,

shared-worker.js

/* 
 * All variables and values outside the `start(...)` function are shared between all pages, this behavior can cause unexpected bugs if you're not careful
 */
const start = (port) => {
    // All your normal Worker and SharedWorker stuff should just work
    // With no more setup 

    /** 
     * All variables and values inside the `start(...)` function are isolated to each page, and will be allocated seperately per page. 
     */
    port.onmessage = ({ data }) => {
        if (data == "Hey")
            port.postMessage("Hello, from the SharedWorker."); 
    };
};

self.onconnect = e => {
    let [port] = e.ports;
    start(port);
};

// This is the fallback, just in case the browser doesn't support SharedWorkers
if ("SharedWorkerGlobalScope" in self) 
    start(self);

main.js

import SharedWorker from "@okikio/sharedworker";

const sharedworker = new SharedWorker(new URL("shared-worker.js", import.meta.url));
sharedworker.onmessage = ({ data }) => {
    console.log(data); //= Hello, from SharedWorker
};

sharedworker.postMessage("Hey");

In the cases of bundlejs.com and astro.build/play, @okikio/sharedworker was used for esbuild as well as the monaco-editors editor and typescript workers. @okikio/sharedworker was used as a separate utility file for easy access.

Limitation

The major limitation with @okikio/sharedworker is that on browsers that don't natively support SharedWorker, you can't use @okikio/sharedworker as an across tab communication tool. But for everything else it's feature parity and spec. compliance should be great.

Conclusion

So, will you use it? Tell me below, or say Hi on twitter.

Image from Tengyart on Unsplash.

I released major updates for https://bundlejs.com, they include

• add copy, wrap, format & reset btns
• add PWA screenshots & sharing to PWA
• detect offline/online mode
• faster preloading & prefetching
• prefetch workers
• preload monaco.min.js for faster perf
• and more....

You can read more about bundlejs.com on the Github repo,

Note: Github Codespaces is only free for personal use during its beta period, which might change in the future, for Github Teams and Organizations there is a pay-as-you-go pricing setup. To get access to personal Github Codespaces you will need to sign up for the beta.

If you have trouble signing up for Codespaces as a team or organisation the process is to email codespaces@github.com

This article details my personal experiences with Gitpod and Github Codespaces, these are my opinions and not definitive facts, your experiences may differ from mine.

Why online IDEs?

I have more experience with Gitpod, as it's been around for quite a bit longer than Github Codespaces, however, my experience with online code editors and IDEs is longer than that.

My first experience with an online code editor was Cloud9 in 2016 (this was before Cloud9 was bought by Amazon and became AWS Cloud9). At the time Cloud9 was a free service and was readily available for personal use, I loved the convenience of the service, so much so, that I fully switched from programming locally to programming online for a short period. All good things come to an end, by December 2019, Cloud9 announced that they were shutting down their standalone service, and instead, Cloud9 would be offered as part of AWS, so, just before I lost access to Cloud9, I started searching for alternatives, ranging from Eclipse Che, Red Hat CodeReady Workspaces, Codeanywhere to StackBlitz, out of all the alternatives the most competent of them was Gitpod.

The online vscode revolution

The main reason I searched for alternatives was that at that point in time I was attempting to use a Chromebook for all my work. When I found Gitpod I liked the general user experience it was similar to vscode but had some extra additions that made more sense in an online environment, such as the ability to open small previews of websites while developing, etc... Plus, online editors were the only way to code on a Chromebook (this has now changed. Chrome OS now supports Linux as a subsystem), so, 🤷‍♂️.

Gitpod vs. Codespaces

Gitpod themselves already made an article about their benefits over Github Codespaces, you can find it here gitpod.io/gitpod-vs-github-codespaces. I will give a brief overview of the differences between the two, note where they overstate their differences and benefits, explain how to make the most of the each service, and then give my personal take on both services.

The first point Gitpod makes is that it's "Ready in a flash"

Gitpod removes long init and build times by continuously pre-building workspaces for your project. Thereby it allows you to start coding or debugging immediately, from any context, at any time.

This is technically correct, at least to a certain point. Gitpod's actual building process takes slightly longer than that of Github Codespaces or at the very least it feels that way, I haven't, nor do I plan to give any exact empirical performance data, as both services are constantly changing things, in fact, the week before I wrote this article, Github introduced github.dev.

For your information: github.dev is an online vscode based web editor, the difference between this and Github Codespaces, is that Codespaces comes with a terminal, and this doesn't

In the defense of Gitpod, it can prebuild a workspace unlike Github Codespaces, so you can start coding immediately, without having to wait for the long build process to finish.

Another point that Gitpod makes is that it has "3x more power",

By leveraging cloud technologies like containers and Kubernetes, Gitpod achieves best-in-class resource efficiency with scalable workspaces running on shared high-powered cloud servers.

This is probably the iffiest points they make, since I can't verify their server configs, nor can I verify that the plans they used for testing, end up being cheaper in actual use, especially, since Github has only released the pricing scheme for Github Teams and Enterprise, and not personal use.

Note: After a discussion with @GeoffreyHuntley from @gitpod I have confirmed that “[they] currently provision machines with 64gb of memory and 16vCPUs and workspaces timeshare the resources in a burstable manner. There are upper limitations to resource consumption on a per workspace basis”. Gitpod is working on sharing more information on their server side config in the coming months.

As of August 30, 2021, Gitpod has 8 plans*, 2 of which are self-hosted options. They are,

For Github Codespaces, the pricing* is,

*Both services have more details included in their pricing scheme, I recommend going through those for detailed and up-to-date information.

Note: You have to pay for your Codespaces storage for the time while said workspace exists, this includes while you are not actively using the workspace. Gitpod to my knowledge doesn't require paying for storage.

Sources: Gitpod, GitHub Codespaces.

In the final point Gitpod makes, they list some of the benefits they offer in a table-like format, I will be blatantly honest, they are leaving out quite a lot of details, so, I will answer in kind but in a more detailed manner.

Workspace Setup

Both Gitpod and Github Codespaces have config files based on Docker that configures your whole env. On Gitpod their config system uses a .gitpod.yml file which stores your workspace config info and a .gitpod.Dockerfile file which sets up a docker image that you can use to run your workspace. By default, Gitpod uses a standard docker image as the foundation for workspaces, the standard image has most of the default tools and programs devs require, plus you can also build on top of it to add small additions to it.

The .gitpod.yml files store basic configuration information, ranging from open ports to post-install scripts. Your basic .gitpod.yml files look like this:

# Commands to start on workspace startup
tasks:
  - init: yarn install
    command: yarn build
# Ports to expose on workspace startup
ports:
  - port: 8000
    onOpen: open-preview

For most of the projects I use Gitpod for, I set up a .gitpod.yml file like this

# .gitpod.yml
image:
  file: .gitpod.Dockerfile

# List the ports you want to expose and what to do when they are served. See https://www.gitpod.io/docs/43_config_ports/
ports:
  - port: 3000
    onOpen: open-preview
  - port: 3001
    onOpen: ignore

github:
  prebuilds:
    # enable for the master/default branch (defaults to true)
    master: true
    # enable for all branches in this repo (defaults to false)
    branches: true
    # enable for pull requests coming from this repo (defaults to true)
    pullRequests: true
    # enable for pull requests coming from forks (defaults to false)
    pullRequestsFromForks: true
    # add a "Review in Gitpod" button as a comment to pull requests (defaults to true)
    addComment: true
    # add a "Review in Gitpod" button to pull requests (defaults to false)
    addBadge: false
    # add a label once the prebuild is ready to pull requests (defaults to false)
    addLabel: prebuilt-in-gitpod

# List the start up tasks. You can start them in parallel in multiple terminals. See https://www.gitpod.io/docs/44_config_start_tasks/
tasks:
  - init: >
      npm install -g pnpm &&
      pnpm install -g ultra-runner &&
      pnpm install
    command: >
      npm install -g pnpm &&
      pnpm install -g ultra-runner &&
      pnpm build

The Gitpod prebuilds section sets up a prebuild for each branch, and pull request, and leaves a comment with a link to the prebuild, check out the docs for Gitpod prebuilds to learn more.

However, where things get interesting is in the tasks section. The init task is run once on workspace startup, and the command task is run on workspace startup, and then on every workspace restart.

The real problem is that the init task even though it runs on startup, doesn't store the environmental variable of nor does it link globally installed packages, and from what I can tell this comes from the fact that every terminal environment is based on the Gitpod docker image that is supplied. If no docker image is specified in the gitpod.yml file then the standard "workspace-full" image is used instead. I recommend reading through Gitpod's docs on the matter.

Note: From what I have been told by @GeoffreyHuntley from @gitpod “[It’s] recommend [that] you build your own docker image and install any software you need as part of building your docker image once your project complexity merits it. In addition to this [they] are also making changes to implement full-workspace backups which will snapshot the entire environment removing this friction”.

The .gitpod.Dockerfile, is the file that directly gives you admin access, and enables you to install/do anything you want to your workspace. From my experience, you most likely won't need to change anything here, except for, maybe VNC purposes, and even then, the docs are very clear.

# .gitpod.Dockerfile
FROM gitpod/workspace-full:latest

# Install custom tools, runtime, etc. using apt-get
# For example, the command below would install "bastet" - a command-line tetris clone:
#
# RUN sudo apt-get -q update && 
#     sudo apt-get install -yq bastet && 
#     sudo rm -rf /var/lib/apt/lists/*
#
# More information: https://www.gitpod.io/docs/config-docker/

On the other hand, setting up a workspace for Github Codespaces is hands-on. Picking a default container is easy enough*, you just follow the docs on VS Code, the real problem is that the setup for Github Codespaces is very overwhelming.

For Codespaces you need to create a .devcontainer.json file and store it in the .devcontainer/ folder. The .devcontainer.json file is a json file that contains the information needed to set up your workspace. The .devcontainer.json file looks like this:

// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.162.0/containers/typescript-node
{
  "name": "Node.js & TypeScript",
  "build": {
    "dockerfile": "Dockerfile",
    // Update 'VARIANT' to pick a Node version: 10, 12, 14
    "args": {
      "VARIANT": "16"
    }
  },

  // Set *default* container specific settings.json values on container create.
  "settings": {
    "npm.packageManager": "pnpm"
  },

  // Add the IDs of extensions you want to be installed when the container is created.
  "extensions": [
    "bierner.jsdoc-markdown-highlighting",
    "yzhang.markdown-all-in-one",
    "shd101wyy.markdown-preview-enhanced",
    "visualstudioexptteam.vscodeintellicode"
  ],

  // Use 'forwardPorts' to make a list of ports inside the container available locally.
  "forwardPorts": [3000],

  // Use 'postCreateCommand' to run commands after the container is created.
  "postCreateCommand": "pnpm install",

  // Comment out connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
  "remoteUser": "node"
}

You also need to create a Dockerfile stored inside the .devcontainer/ folder. The Dockerfile contains docker info, so any configs, you require for your workspace can be set here, like this:

# See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.187.0/containers/typescript-node/.devcontainer/base.Dockerfile

# [Choice] Node.js version: 16, 14, 12
ARG VARIANT="16-buster"
FROM mcr.microsoft.com/vscode/devcontainers/typescript-node:0-${VARIANT}

# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
#     && apt-get -y install --no-install-recommends <your-package-list-here>

# [Optional] Uncomment if you want to install an additional version of node using nvm
# ARG EXTRA_NODE_VERSION=10
# RUN su node -c "source /usr/local/share/nvm/nvm.sh && nvm install ${EXTRA_NODE_VERSION}"

# [Optional] Uncomment if you want to install more global node packages
# RUN su node -c "npm install -g <your-package-list -here>"

RUN su node -c "npm install -g pnpm"

This example is based on one of my Github projects okikio/native, it's a good starting point for setting up a workspace for your own project.

_Note: The major thing that can throw you off with the Github Codespaces config is that you can't install local packages (I'm talking about node_modules) inside the docker config. Of course, this could be my lack of experience with Docker, but thus far I've been unable to get it to work properly._

For your information: The Gitpod team is planning to add support for the Github Codespaces devcontainer.json format, so, in the future, you might be able to easily switch between both Github Codespaces and Gitpod without breaking a sweat.

Collaboration

I personally haven't collaborated with anyone on Gitpod or Github Codespaces, but each service does offer a way to collaborate with others. For one, Gitpod allows you to share both running workspaces and snapshots (copies of workspaces) with others, and for the other, Github Codespaces allows you to use Live Share to collaborate on the same project.

I feel Live Share is a better collaboration tool, sure with Gitpod you can share workspaces with others, but with Codespaces you can both be working on the same project, without skipping a beat, and technically it would be very similar to sharing workspaces with other devs, so...I'll leave the final judgment of this to you.

Documentation

Github Codespaces has highly detailed documentation, but it's very content dense and a tad bit overwhelming. Gitpod's documentation on the other hand is simpler and more focused on the basics and includes docs and short screencasts. It's a great way to get started with a cloud based dev environment. Github Codespaces basically assumes you're already very experienced, while Gitpod assumes you're new to the world of online dev environments and slowly builds on top.

VNC

Gitpod and Github Codespaces both have VNC support. From my experiences, both are about equal in terms of how VNC works, however, Gitpod is easier to set up with VNC.

Virtual Network Computing (VNC) is a graphical desktop-sharing system that uses the Remote Frame Buffer protocol (RFB) to remotely control another computer. It transmits the keyboard and mouse input from one computer to another, relaying the graphical-screen updates, over a network. Read more on Wikipedia

A little while back I tried experimenting to see if I could set up Webkit (Safari's browser engine) on my Windows laptop...I failed, I couldn't figure out how to build the Webkit source code on Windows (it was painfully difficult), so, I tried the next best thing, the "cloud", it too failed, but interestingly enough, for a vastly different reason.

For this experiment, I used Github Codespaces (for a previous experiment I had already tried using Gitpod with VNC, so, I thought I would try Github Codespaces this time). I was able to get VNC functional but couldn't set up Webkit, since, Docker has problems with some of the libraries that Webkit uses. I tried for a good ~16 hours before I gave up. I eventually found another alternative, Playwright.

Playwright is an end-to-end framework for testing web apps on multiple browsers, it's a great tool for testing web apps.

While trying out Playwright, I found it would only work on Windows (this was because of Webkit & Docker's library issue).

Let's get back to the original topic, VNC. In my experiments, I found setting up VNC on Github Codespaces difficult and the build process for said workspace long, I actually timed it, the build process for Github Codespaces with VNC was ~6 minutes, while, on Gitpod it was much faster (I can't remember exactly how long it took, but what I do remember is that it was less than 5 minutes), also, Gitpod's documentation is much easier to digest and just get started with.

For VNC on Gitpod check out gitpod.io/blog/native-ui-with-vnc.

For VNC on Github Codespaces check out github.com/microsoft/vscode-dev-containers/blob/main/script-library/docs/desktop-lite.md.

Annoyances

In Gitpod workspaces every terminal is built from the Gitpod docker image given or if non can be found the Gitpod standard image "workspace-full", in theory, this sounds awesome, however, from my experience, it ends up being a huge pain to work around. For example, I have found that if you, use nvm (node version manager) to install a new version of node, let's say v16 to replace the Gitpod standard images node, v14, every new terminal you create will use the version of node set up in the standard image, this seems like a very minor issue, but it can cause a bunch of issues and just make you very annoyed over time, plus it just slows down your development velocity. As stated in workspace-setup section, this issue can be mitigated by building your own docker image or by typing into your .gitpod.yml file,

tasks:
  # Replace version with version you want installed
  - init: >
      nvm install v16 &&
      'nvm alias default v16' >> /home/gitpod/.bashrc
      nvm list

See more on Stackoverflow

The Internet Problem

By using Gitpod and Github Codespaces, you become reliant on the internet, and if you don't have access to the internet, you can't use either service. For most devs, this isn't really a problem, since, in most cases, they need access to the internet to commit changes to Github, Bitbucket, etc...

For cases where you don't have access to the internet, let's say your ISP messed up somewhere and you lose access for a couple days (I am speaking from personal experience here), then you become unable to do any programming at all.

For those who are worried about internet connections the best thing you can do is, to make sure you always have a local copy with all the tools and dependencies already installed, so, you can at least make some progress when you lose access.

For small instances where you lose connection for maybe a minute or two, Github Codespaces and Gitpod keep local copies of all open files, and merge them into the online copy when the connection is re-established, so, no worries there.

Warning: One thing you should pay attention to is, if you lose internet access for a long time while using Gitpod, you have to pin your workspace in their dashboard, otherwise you may lose your workspace after 14 days, and have to start over. This doesn't really apply to Github Codespaces, since you must actively delete a workspace, Codespaces will shut down a workspace, but it won't delete it for you. If you can't find a workspace, and the last time said workspace was used was less than 14 days, you will have click the View All Workspaces button

Miscellaneous

A minor difference between Gitpod and Github Codespaces is that Github Codespaces supports using your locally installed version of VS Code to continue development using the VS Code you know and love, as well as forwarding remote ports to localhost ports and much more, all together Github Codespaces allows devs to develop in an environment very similar to local developments except with less resource use (as most of the processing is happening on the remote server), and slightly greater dependence on the internet, read through Github's docs to learn more.

Gitpod supports something similar, if you install the Gitpod app as a PWA (from what I know, only Edge allows you to forcefully install websites as apps), you can then forward the remote ports on the server to your computer's localhost ports, read more about this on Gitpod's docs.

For your information: Gitpod is working on support for local VS Code, so, by the time you are reading this article it might already be live.

I don't know how important this is to devs, but Github Codespaces automatically syncs settings between VS Code and itself. To use this feature with Gitpod, you need to do some setup with your VS Code installation, read through the issue opened by Gitpod to learn more.

When to use Github Codespaces?

Github Codespaces is an easy to use and reliable VS Code service, its integration with Github is quite convenient and is hard to properly quantify, its extension support is top tier, its a coding experience that is hard to pass on, especially for devs who already use Github's other services. Github Codespaces is great for devs who need high-resource workspaces and are ok without self-hosting on other platforms.

Github Codespaces is good, but it's not the perfect solution for everyone. Github's billing model is a bit strenuous, as workspace storage is not free, so, if you want to use Github Codespaces professionally, you might end up paying quite a bit unintentionally, plus, depending on how many hours you use each Github Codespace, your monthly bill can be a rather painful pill to swallow.

When to use Gitpod?

Gitpod is an easy-to-use and very reliable VS Code service, and its open-source design allows you to get involved, maybe even fix issues as they arise. Gitpod is great for open-source projects, for those that want a reliable and consistent monthly pricing scheme, for devs looking for non-proprietary VS Code workspaces, or devs that want to use Bitbucket, Gitlab, etc.. and/or to use a self-hosted option on AWS, GCP, etc... Really Gitpod is great for the same reasons as Github Codespaces, it’s just that Gitpod has a little less Github integration which makes Github Codespaces a nicer experience to use with Github.

Conclusion

Both services are amazing, as they bring a consistent and reliable VS Code experience to devs via the web. However, they are not the perfect solution for everyone, as they each have their ups and downs.

I have stated my personal experience with both services, and I would recommend using the one that you feel is best for you. Personally, I switch between both services rather often, however, I prefer Github Codespaces. I find it to be the best option for me as it syncs my settings, supports local VS Code, and has great integration with Github and VS Code extensions (I am even able to use Github Copilot in Github Codespaces).

Note: I actually used Github Codespaces together with Github Copilot to write this article. Trust me when I say it's an excellent writing companion, it's almost like the Gmail autocomplete, but better, since it also recognizes code syntax, and can apply them rather effectively.

An alternative to Github Copilot is Tabnine. I haven’t actually used it, but I feel it’s worth mentioning as an alternative, since it works on Gitpod.

For a more neutral and objective comparison between both services, I suggest reading through Nader Dabit's article on FreeCodeCamp comparing the two.

Update Sept. 09, 2021: Add missing selfhost and opensource Gitpod plans; get quotes from @GeoffreyHuntley from @gitpod concerning server config; add Tabnine as an alternative to Github Copilot; add possible Docker or .gitpod.yml fix to Gitpod’s terminal node version issue; fix spelling and grammar issues

The idea for this article came from a tweet by Nik Molnar @nikmd23 and Stephan Meijer @meijer_s.

Photo by Okiki Ojo, you can find the image on Dropbox.

Also, published on Hackernoon and dev.to

<!--
  The page supports both dark and light color schemes,
  and the page author prefers dark.
-->
<meta name="color-scheme" content="dark light">

or you can even add it using css

/*
  The page supports both dark and light color schemes,
  and the page author prefers dark.
*/
:root {
  color-scheme: dark light;
}

I absolutely detest sites that "have a dark mode, BUT DON'T MAKE THE SCROLLBAR DARK!", a great example of this is docusaurus.

Docusarus Why???

I actually tweeted at them asking why the scrollbar isn't dark as well, 🤣

The light mode scrollbar hurts the eyes, and ruins the look of the site, so, for the sake of everyone who has eyes and likes dark mode, please use color-scheme, you can even use it together with your dark mode toggle by using css, for example, one of the sites I made for a client josephojo.com

When using the color-scheme property you can turn form elements, webpage background, text color, and scrollbars dark, a more famous example would be, Github,

Notice, how the scrollbar is dark, and doesn't burn the eyes, they're able to do it, by using the meta tag.

For josephojo.com I used the color-scheme css property together with @media (prefers-color-scheme: dark) {} and the .dark class, the final result is

html {
    color-scheme: light;
}

html.dark {
    color-scheme: dark;
}

@media (prefers-color-scheme: dark) {
    html:not([data-theme]) {
        color-scheme: dark;
    }
}

When creating the site I used tailwindcss, with the dark mode set to "class", my tailwind config looked like this,

module.exports = {
    darkMode: 'class',
    // ...
}

For those who haven't used tailwindcss before, it's basically the same as defining a class that when added to the html element will signal that the site is in dark mode.

Or in simpler terms it's,

<html class="dark"> 
    <!-- ... -->
</html>

You: Wait, but, how did you handle the theme toggle button?

Me: I'm glad you asked.

Now that we have some boilerplate code, all you really need to do, is setup a toggle that will remember our current theme state.

While developing josephojo.com, I found that you have to set your theming system to support the native media theme before anything else, it's generally less painful to the user, that's why I set html:not([data-theme]) in the prefers-color-scheme: dark media query,

/* ... */
@media (prefers-color-scheme: dark) {
    html:not([data-theme]) {
        color-scheme: dark;
    }
}
/* ... */

html.dark represents the dark theme applied by tailwind and [data-theme] represents the currently applied theme, if data-theme is different from the local storage, then the theme was manually toggled and the page should use the new theme in data-theme as well as update the local storage theme, otherwise, it should use the local storage theme as data-theme, but because data-theme is only applied to the html element after javascript is loaded we can tell our css to use the default dark theme if prefers-color-scheme: dark and the html element doesn't have the data-theme attribute.

The result you get is this,

As you saw at the end there, changing the actual browser theme won't permanently change the theme set in local storage, with the idea being, if a user a manually changes the theme they must want to use that theme permanently, otherwise use the system theme.

Here is the code for the theme toggle,

// Based on [joshwcomeau.com/gatsby/dark-mode/]
let getSavedTheme = () => {
  const theme = window.localStorage.getItem("theme");
  // If the user has explicitly chosen light or dark,
  // let's use it. Otherwise, this value will be null.
  if (typeof theme === "string") return theme;

  // If they are using a browser/OS that doesn't support
  // color themes, let's not do anything.
  return null;
};

let saveTheme = (theme) => {
  // If the user has explicitly chosen light or dark, store the default theme
  if (typeof theme === "string")
    window.localStorage.setItem("theme", theme);
};

let mediaTheme = () => {
  // If they haven't been explicitly set, let's check the media query
  const mql = matchMedia("(prefers-color-scheme: dark)");
  const hasMediaQueryPreference = typeof mql.matches === "boolean";
  if (hasMediaQueryPreference) return mql.matches ? "dark" : "light";
};

const html = document.querySelector("html");

// Get theme from html tag, if it has a theme or get it from localStorage
let checkCurrentTheme = () => {
  let themeAttr = html.getAttribute("data-theme");
  if (themeAttr) return themeAttr;

  return getSavedTheme();
};

// Set theme in localStorage, as well as in the html tag
let applyTheme = (theme) => {
  html.className = theme;
  html.setAttribute("data-theme", theme);
};

try {
  // if there is a saved theme in local storage use that,
  // otherwise use `prefer-color-scheme` to set the theme 
  let theme = getSavedTheme();
  if (theme == null) theme = mediaTheme();

  // set the initial theme
  html.setAttribute("data-theme", theme);
  html.classList.add(theme);

  // If a user changes the system/browser/OS theme, update the site theme as well,
  // but don't save the change in local storage
  window
    .matchMedia("(prefers-color-scheme: dark)")
    .addEventListener("change", (e) => {
      applyTheme(e.matches ? "dark" : "light");
    });

  // On theme toggle button click, toggle the page theme between dark and light mode,
  // then save the theme in local storage
  document
    .querySelector("#theme-toggle")
    .addEventListener("click", () => {
      let theme = checkCurrentTheme() === "dark" ? "light" : "dark";
      applyTheme(theme);
      saveTheme(theme);
    });
} catch (e) {
  console.warn("Theming isn't available on this browser.", e);
}

You can view the demo below, but you may need to open the demo in a new tab for it to work properly.

Also, notice, how I never set the text color, background color, scrollbar color or button styles, that's part of the magic of setting color-scheme.

You can read more about color-scheme on web.dev,

Please tell me what you think about color-scheme in the comments below.

Update: Another cool part feature of the color-scheme meta tag is that Samsung Internet won't force dark mode on your site if it uses the color-scheme meta tag, from what I can tell Chrome might implement a similar feature in the future. I tweeted about it

You can learn more about this on the Samsung Developers site,

Photo by Alexander Andrews on Unsplash

Well a major limitation of the Web Animation API and consequently @okikio/animate, was that it didn't support custom easing, this limitation is on the verge of being removed.

Based on a comment by jakearchibald on Github and an article by kirillvasiltsov

https://github.com/w3c/csswg-drafts/issues/229#issuecomment-860778689

Using the fact that WAAPI allows for linear easing, I created a small function that generates a set of arrays that create custom easing effects like bounce, elastic, and spring. As of right now it builds on top of @okikio/animate but that isn't absolutely necessary, it just may not be as comfortable as using it with @okikio/animate.

You can view a demo below,

As of right now if I add this to the @okikio/animate library it will more than double the size of the library (Note: treeshaking the actual package @okikio/animate while custom easing isn't in use will cause it to excluded from the final build reducing the size down to ~5.79 KB).

I'm not sure if I should make Custom Easing a separate package or build it directly into @okikio/animate, please tell me what you think in the comments below.

You can also tweet at me

This article also appeared on dev.to.

Photo by Ellen Qin on Unsplash.

The Web Animations API lets us construct animations and control their playback with JavaScript. The API opens the browser’s animation engine to developers and was designed to underlie implementations of both CSS animations and transitions, leaving the door open to future animation effects. It is one of the most performant ways to animate on the Web, letting the browser make its own internal optimizations without hacks, coercion, or window.requestAnimationFrame().

With the Web Animations API, we can move interactive animations from stylesheets to JavaScript, separating presentation from behavior. We no longer need to rely on DOM-heavy techniques such as writing CSS properties and scoping classes onto elements to control playback direction. And unlike pure, declarative CSS, JavaScript also lets us dynamically set values from properties to durations. For building custom animation libraries and creating interactive animations, the Web Animations API might be the perfect tool for the job. Let’s see what it can do!

For the rest of this article, I will sometimes refer to the Web Animation API as WAAPI. When searching for resources on the Web Animation API, you might be led astray by searching “Web Animation API” so, to make it easy to find resources, I feel we should adopt the term WAAPI; tell me what you think in the comments below.

This is the library I made with the WAAPI

@okikio/animate is an animation library for the modern web. It was inspired by animateplus, and animejs; it is focused on performance and developer experience, and utilizes the Web Animation API to deliver butter-smooth animations at a small size, weighing in at ~5.79 KB (minified and gzipped).

The story behind @okikio/animate

In 2020, I decided to make a more efficient PJAX library, similar to Rezo Zero’s - Starting Blocks project, but with the ease of use of barbajs. I felt starting blocks was easier to extend with custom functionality, and could be made smoother, faster, and easier to use.

Note: if you don’t know what a PJAX library is I suggest checking out MoOx/pjax; in short, PJAX allows for smooth transitions between pages using fetch requests and switching out DOM Elements.

Over time my intent shifted, and I started noticing how often sites from awwwards.com used PJAX, but often butchered the natural experience of the site and browser . Many of the sites looked cool at first glance, but the actual usage often told a different story — scrollbars were often overridden, prefetching was often too eager, and a lack of preparation for people without powerful internet connections, CPUs and/or GPUs. So, I decided to progressively enhance the library I was going to build. I started what I call the “native initiative” stored in the GitHub repo okikio/native; a means of introducing all the cool and modern features in a highly performant, compliant, and lightweight way.

For the native initiative I designed the PJAX library @okikio/native; while testing on an actual project, I ran into the Web Animation API, and realized there were no libraries that took advantage of it, so, I developed @okikio/animate, to create a browser compliant animation library. (Note: this was in 2020, around the same time use-web-animations by wellyshen was being developed. If you are using react and need some quick animate.css like effects, use-web-animations is a good fit.) At first, it was supposed to be simple wrapper but, little by little, I built on it and it’s now at 80% feature parity with more mature animation libraries.

Note: you can read more on the native initiative as well as the @okikio/native library on the Github repo okikio/native. Also, okikio/native, is a monorepo with @okikio/native and @okikio/animate being sub-packages within it.

Where @okikio/animate fits into this article

The Web Animation API is very open in design. It is functional on its own but it’s not the most developer-friendly or intuitive API, so I developed @okikio/animate to act as a wrapper around the WAAPI and introduce the features you know and love from other more mature animation libraries (with some new features included) to the high-performance nature of the Web Animation API. Give the project’s README a read for much more context.

Now, let’s get started

@okikio/animate creates animations by creating new instances of Animate (a class that acts as a wrapper around the Web Animation API).

import { Animate } from"@okikio/animate";

new Animate({
    target: [/* ... */],
    duration: 2000,
    // ... 
});

The Animate class receives a set of targets to animate, it then creates a list of WAAPI Animation instances, alongside a main animation (the main animation is a small Animation instance that is set to animate over a non-visible element, it exists as a way of tracking the progress of the animations of the various target elements), the Animate class then plays each target elements Animation instance, including the main animation, to create smooth animations.

The main animation is there to ensure accuracy in different browser vendor implementations of WAAPI. The main animation is stored in Animate.prototype.mainAnimation, while the target element’s Animation instances are stored in a WeakMap, with the key being its KeyframeEffect. You can access the animation for a specific target using the Animate.prototype.getAnimation(el).

You don‘t need to fully understand the prior sentences, but they will aid your understanding of what @okikio/animate does. If you want to learn more about how WAAPI works, check out MDN, or if you would like to learn more about the @okikio/animate library, I’d suggest checking out the okikio/native project on GitHub.

Usage, examples and demos

By default, creating a new instance of Animate is very annoying, so, I created the animate function, which creates new Animate instances every time it’s called.

import animate from "@okikio/animate";
// or
import { animate } from "@okikio/animate";

animate({ 
    target: [/* ... */],
    duration: 2000,
    // ... 
});

When using the @okikio/animate library to create animations you can do this:

import animate from "@okikio/animate";

// Do this if you installed it via the script tag: const { animate } = window.animate;

(async () => {
    let [options] = await animate({
    target: ".div",

    // Units are added automatically for transform CSS properties
    translateX: [0, 300],
    duration: 2000, // In milliseconds
    speed: 2,
    });

    console.log("The Animation is done...");
})();

You can also play with a demo with playback controls:

Try out Motion Path:

Try different types of Motion by changing the Animation Options:

I also created a complex demo page with polyfills:

View demo

You can find the source code for this demo in the animate.ts and animate.pug files in the GitHub repo. And, yes, the demo uses Pug, and is a fairly complex setup. I highly suggest looking at the README as a primer for getting started.

The native initiative uses Gitpod, so if you want to play with the demo, I recommend clicking the “Open in Gitpod” link since the entire environment is already set up for you — there’s nothing to configure.

You can also check out some more examples in this CodePen collection I put together. For the most part, you can port your code from animejs to @okikio/animate with few-to-no issues.

I should probably mention that @okikio/animate supports both the target and targets keywords for settings animation targets. @okikio/animate will merge both list of targets into one list and use Sets to remove any repeated targets. @okikio/animate supports functions as animation options, so you can use staggering similar to animejs. (Note: the order of arguments are different, read more in the “Animation Options & CSS Properties as Methods” section of the README file.)

Restrictions and limitations

@okikio/animate isn’t perfect; nothing really is, and seeing as the Web Animation API is a living standard constantly being improved, @okikio/animate itself still has lots of space to grow. That said, I am constantly trying to improve it and would love your input so please open a new issue, create a pull request or we can have a discussion over at the GitHub project.

The first limitation is that it doesn’t really have a built-in timeline. There are a few reasons for this:

1. I ran out of time. I am still only a student and don’t have lots of time to develop all the projects I want to.
2. I didn’t think a formal timeline was needed, as async/await programming was supported. Also, I added timelineOffset as an animation option, should anyone ever need to create something similar to the timeline in animejs.
3. I wanted to make @okikio/animate as small as possible.
4. With group effects and sequence effects coming soon, I thought it would be best to leave the package small until an actual need comes up. On that note, I highly suggest reading Daniel C. Wilson’s series on the WAAPI, particularly the fourth installment that covers group effects and sequence effects.

Another limitation of @okikio/animate is that it lacks support for custom easings, like spring, elastic, etc. But check out Jake Archibald’s proposal for an easing worklet. He discusses multiple standards that are currently in discussion. I prefer his proposal, as it’s the easiest to implement, not to mention the most elegant of the bunch. In the meanwhile, I'm taking inspiration from Kirill Vasiltsov article on Spring animations with WAAPI and I am planning to build something similar into the library.

The last limitation is that @okikio/animate only supports automatic units on transform functions e.g. translateX, translate, scale, skew, etc. This is no longer the case as of @okikio/animate@2.2.0, but there are still some limitations on CSS properties that support color. Check the GitHub release for more detail.

For example:

animate({
    targets: [".div", document.querySelectorAll(".el")],

    // By default "px", will be applied
    translateX: 300,
    left: 500,
    margin: "56 70 8em 70%",

    // "deg" will be applied to rotate instead of px
    rotate: 120, 

    // No units will be auto applied
    color: "rgb(25, 25, 25)",
    "text-shadow": "25px 5px 15px rgb(25, 25, 25)"
});

Looking to the future

Some future features, like ScrollTimeline, are right around the corner. I don’t think anyone actually knows when it will release but since the ScrollTimeline in Chrome Canary 92, I think it’s safe to say the chances of a release in the near future look pretty good.

I built the timeline animation option into @okikio/animate to future-proof it. Here’s an example:

Thanks to Bramus for the demo inspiration! Also, you may need the Canary version of Chrome or need to turn on Experimental Web Platform features in Chrome Flags to view this demo. It seems to work just fine on Firefox, though, so… 🤣.

If you want to read more on the ScrollTimeline, Bramus wrote an excellent article on it. I would also suggest reading the Google Developers article on Animation Worklets.

My hope is to make the library smaller. It's currently ~5.79 KB which seems high, at least to me. Normally, I would use a bundlephobia embed but that has trouble bundling the project, so if you want to verify the size, I suggest using bundlejs.com because it actually bundles the code locally on your browser. I specifically built it for checking the bundle size of @okikio/animate, but note it's not as accurate as bundlephobia.

Polyfills

One of the earlier demos shows polyfills in action. You are going to need web-animations-next.min.js from web-animations-js to support timelines. Other modern features the KeyframeEffect constructor is required.

The polyfill uses JavaScript to test if the KeyframeEffect is supported and, if it isn’t, the polyfill loads and does its thing. Just avoid adding async/defer to the polyfill, or it will not work the way you expect. You’ll also want to polyfill Map, Set, and Promise.

<html>
    <head>
        <!-- Async -->
        <script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=default,es2015,es2018,Array.prototype.includes,Map,Set,Promise" async></script>

        <!-- NO Async/Defer -->
        <script src="./js/webanimation-polyfill.min.js"></script>
    </head>
    <body>
        <!-- Content -->
    </body>
</html>

And if you’re building for ES6+, I highly recommend using esbuild for transpiling, bundling, and minifying. For ES5, I suggest using esbuild (with minify off), Typescript (with target of ES5), and terser; as of now, this is the fastest setup to transpile to ES5, it's faster and more reliable than babel. See the Gulpfile from the demo for more details.

Conclusion

@okikio/animate is a wrapper around the Web Animation API (WAAPI) that allows you to use all the features you love from animejs and other animation libraries, in a small and concise package. So, what are your thoughts after reading about it? Is it something you think you’ll reach for when you need to craft complex animations? Or, even more important, is there something that would hold you back from using it? Leave a comment below or join the discussion on Github Discussions.

TLDR @okikio/animate is basically animejs but built on the Web Animation API.

This article was originally published on dev.to but also appeared on hackernoon and on CSS-Tricks.
Photo by Pankaj Patel on Unsplash.