<?xml version="1.0" encoding="UTF-8"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>Nick Ball</title><description>Web development</description><link>https://npbee.me/</link><language>en-us</language><atom:link href="https://npbee.me/rss.xml" rel="self" type="application/rss+xml"/><item><title>Fresh with a Type-safe Hono API</title><link>https://npbee.me/posts/fresh-hono-rpc/</link><guid isPermaLink="true">https://npbee.me/posts/fresh-hono-rpc/</guid><description>Create a type-safe API with Fresh and Hono’s rpc</description><pubDate>Sat, 10 Feb 2024 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;a href=&quot;https://fresh.deno.dev/&quot;&gt;Fresh&lt;/a&gt; is a full-stack framework from &lt;a href=&quot;https://deno.com/&quot;&gt;Deno&lt;/a&gt;. Because it’s full-stack, you can build API endpoints directly into the framework using &lt;a href=&quot;https://fresh.deno.dev/docs/getting-started/custom-handlers&quot;&gt;custom handlers&lt;/a&gt;.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// routes/api/random-uuid.ts
import { Handlers } from &amp;quot;$fresh/server.ts&amp;quot;;

export const handler: Handlers = {
  GET(_req) {
    const uuid = crypto.randomUUID();
    return new Response(JSON.stringify(uuid), {
      headers: { &amp;quot;Content-Type&amp;quot;: &amp;quot;application/json&amp;quot; },
    });
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The &lt;code&gt;/api/random-uuid&lt;/code&gt; route is now a JSON endpoint exposed with your app. No need to set up a separate service for your API application.&lt;/p&gt;
&lt;p&gt;There have been times, though, that I’ve wanted a bit more separation between my web and API surfaces. Recently I found &lt;a href=&quot;https://github.com/Rykuno/fullstack-example&quot;&gt;this&lt;/a&gt; repository that shows using Hono within a SvelteKit app and it seemed like exactly what I was looking for. Since Fresh, like SvelteKit, operates on &lt;code&gt;Request&lt;/code&gt; and &lt;code&gt;Response&lt;/code&gt; primitives, we should be able to achieve something similar. Let’s try!&lt;/p&gt;
&lt;p&gt;Example repo set up &lt;a href=&quot;https://github.com/npbee/fresh-hono-rpc&quot;&gt;here&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;Setup&lt;/h2&gt;
&lt;p&gt;Start with a bare Fresh app:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;deno run -A -r https://fresh.deno.dev
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In an &lt;code&gt;api&lt;/code&gt; directory, we can stub out a basic Hono app following their &lt;a href=&quot;https://hono.dev/guides/rpc#using-with-larger-applications&quot;&gt;documentation&lt;/a&gt;:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// api/mod.ts
import { Hono } from &amp;quot;npm:hono&amp;quot;;

const booksApp = new Hono()
  .get(&amp;quot;/&amp;quot;, (c) =&amp;gt; c.json(&amp;quot;list books&amp;quot;))
  .post(&amp;quot;/&amp;quot;, (c) =&amp;gt; c.json(&amp;quot;create a book&amp;quot;, 201))
  .get(&amp;quot;/:id&amp;quot;, (c) =&amp;gt; c.json(`get ${c.req.param(&amp;quot;id&amp;quot;)}`));

export const app = new Hono();

const routes = app.route(&amp;quot;/books&amp;quot;, booksApp);
export type AppType = typeof routes;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;On its own, this won’t do anything yet because Fresh doesn’t know about it. In order to make use of this Hono app, we have to set up a route in the &lt;code&gt;routes&lt;/code&gt; directory. In our case, we want &lt;em&gt;all&lt;/em&gt; routes on the &lt;code&gt;/api&lt;/code&gt; path to be routed to our Hono app. We can do that with a wildcard route:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// routes/api/[...all].ts
import { app } from &amp;quot;@/api/mod.ts&amp;quot;;

export const handler = (req: Request) =&amp;gt; app.fetch(req);
&lt;/code&gt;&lt;/pre&gt;
&lt;blockquote&gt;
&lt;p&gt;P.S. You can get the fancy &lt;code&gt;@/api/mod.ts&lt;/code&gt; import paths with an import alias in your &lt;code&gt;deno.json&lt;/code&gt; like &lt;code&gt;”@/“: “./“&lt;/code&gt;&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Now, every &lt;code&gt;/api&lt;/code&gt; route will route back to our Hono app. Except it’s not quite working yet. If you start your Fresh app and try to hit &lt;code&gt;/api/books&lt;/code&gt; you’ll get a 404. That’s because Hono doesn’t know about the &lt;code&gt;/api&lt;/code&gt; segment in the path. We can adjust our Hono app with a base path to fix this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// api/mod.ts
// ...

export const app = new Hono().basePath(&amp;quot;/api&amp;quot;);

// ...
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now when you go to &lt;code&gt;/api/books&lt;/code&gt; you should get back a response from your Hono app!&lt;/p&gt;
&lt;p&gt;This by itself is neat. You could stop right here and have a Hono-powered API app within Fresh.&lt;/p&gt;
&lt;h2&gt;Using Your Own API&lt;/h2&gt;
&lt;p&gt;If we were building an API-first application, we might want to bake in most of our business logic into the API itself and have our web app use the API for CRUD actions. In this sense, our Fresh web routes will be a client of our Hono API app. We can use Hono’s &lt;a href=&quot;https://hono.dev/guides/rpc&quot;&gt;RPC&lt;/a&gt; guide to make this type safe.&lt;/p&gt;
&lt;p&gt;We can start by making a client:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// api/mod.ts
import { hc } from &amp;quot;npm:hono/client&amp;quot;;

// ...

// We need to pass a full URL here.
export const client = hc&amp;lt;AppType&amp;gt;(&amp;quot;http://localhost:8000&amp;quot;);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;One snag you’ll notice is that we need to pass the full URL of our application. We’ll come back to that in a minute.&lt;/p&gt;
&lt;p&gt;In our root route, we can now use our client:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;// routes/index.tsx
import { client } from &amp;quot;@/api/mod.ts&amp;quot;;

export default async function Home() {
  const bookResponse = await client.api.books.$get();
  const json = await bookResponse.json();
  return &amp;lt;pre&amp;gt;{json}&amp;lt;/pre&amp;gt;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Notice that you get type hints with the client:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/fresh-hono-client-types.png&quot; alt=&quot;TypeScript LSP type hints with a Hono client&quot;&gt;&lt;/p&gt;
&lt;p&gt;This is nice, but we can improve it. One thing to realize with this setup is that we’re actually making &lt;em&gt;two&lt;/em&gt; HTTP calls: one to &lt;code&gt;/&lt;/code&gt; and another to &lt;code&gt;/api/books&lt;/code&gt;. We can prove that with a quick logging middleware:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// routes/_middleware.ts
import { Handler } from &amp;quot;$fresh/server.ts&amp;quot;;

export const handler: Array&amp;lt;Handler&amp;gt; = [loggingMiddleware()];

function loggingMiddleware(): Handler {
  return (req, ctx) =&amp;gt; {
    if (ctx.destination !== &amp;quot;route&amp;quot;) {
      return ctx.next();
    }
    console.log(`${req.method}  ${req.url}`);
    return ctx.next();
  };
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;When loading the root route in the browser, you will see two HTTP calls:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt; 🍋 Fresh ready
    Local: http://localhost:8000/

GET  http://localhost:8000/
GET  http://localhost:8000/api/books
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is not a huge deal, but since we’re on the same server it feels a little unnecessary because we can just call our route handler directly. If you’re using SvelteKit, you get a &lt;code&gt;fetch&lt;/code&gt; &lt;a href=&quot;https://kit.svelte.dev/docs/load#making-fetch-requests&quot;&gt;helper&lt;/a&gt; that does this for you. And if you’ve ever tried to call your own API route on Deno Deploy, you may be met with with a &lt;code&gt;Loop Detected&lt;/code&gt; &lt;a href=&quot;https://github.com/denoland/deploy_feedback/issues/187&quot;&gt;error&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;As a workaround for the above Deno Deploy issue and a general performance improvement, we can wire up our Hono client to have a custom &lt;code&gt;fetch&lt;/code&gt; handler. To do that, we’ll turn our &lt;code&gt;client&lt;/code&gt; into a &lt;code&gt;createClient&lt;/code&gt; function.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// api/mod.ts
import { ClientRequestOptions, Hono } from &amp;quot;npm:hono&amp;quot;;
//...

export function createClient(url: string, options?: ClientRequestOptions) {
  return hc&amp;lt;AppType&amp;gt;(url, options);
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;We’ll pass in the &lt;code&gt;url&lt;/code&gt; here to avoid hard-coding. Back in our root route, we can set up the client like so:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;import { createClient } from &amp;quot;@/api/mod.ts&amp;quot;;
import { handler } from &amp;quot;@/routes/api/[...all].ts&amp;quot;;

export default async function Home() {
  const client = createClient(&amp;quot;http://localhost:8000&amp;quot;, {
    fetch: (...params: Parameters&amp;lt;typeof fetch&amp;gt;) =&amp;gt; {
      const req = new Request(...params);
      return handler(req);
    },
  });
  const bookResponse = await client.api.books.$get();
  const json = await bookResponse.json();
  return &amp;lt;pre&amp;gt;{json}&amp;lt;/pre&amp;gt;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now you should just see a single HTTP request when loading the root route because we are calling the API handler directly instead of fetching:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt; 🍋 Fresh ready
    Local: http://localhost:8000/

GET  http://localhost:8000/
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;To avoid setting up the client each time, you probably want to move that into a function:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// lib/api.ts
import { createClient } from &amp;quot;@/api/mod.ts&amp;quot;;
import { handler } from &amp;quot;@/routes/api/[...all].ts&amp;quot;;

const client = createClient(&amp;quot;http://localhost:8000&amp;quot;, {
  fetch: (...params: Parameters&amp;lt;typeof fetch&amp;gt;) =&amp;gt; {
    const req = new Request(...params);
    return handler(req);
  },
});

export const api = client.api;
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;// routes/index.tsx
import { api } from &amp;quot;@/lib/api.ts&amp;quot;;

export default async function Home() {
  const bookResponse = await api.books.$get();
  const json = await bookResponse.json();
  return &amp;lt;pre&amp;gt;{json}&amp;lt;/pre&amp;gt;;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Closing Thoughts&lt;/h2&gt;
&lt;p&gt;I think this is a pretty neat pattern. One caveat here is that calling the route handler directly &lt;strong&gt;will not&lt;/strong&gt; execute any Fresh middleware you have set up for the &lt;code&gt;api&lt;/code&gt; directory. All middleware logic for the API would have to be moved to Hono. And generally, I’d want to keep an eye on any hidden couplings between Fresh and Hono since they are only superficially separated here. I wouldn’t want to go to split out my Hono app later and realize I was relying on a specific header or request parameter coming from Fresh.&lt;/p&gt;
&lt;p&gt;Thanks for reading!&lt;/p&gt;
</content:encoded></item><item><title>Supabase Auth with Deno Fresh</title><link>https://npbee.me/posts/fresh-supabase-auth/</link><guid isPermaLink="true">https://npbee.me/posts/fresh-supabase-auth/</guid><description>Using Supabase&apos;s new SSR auth with Deno&apos;s Fresh framework</description><pubDate>Fri, 05 Jan 2024 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Supabase recently released an updated package for handling authentication outside of client-only environments. Most of the docs are geared around popular full-stack frameworks like NextJS or Remix, so I thought I’d try out setting up in &lt;a href=&quot;https://fresh.deno.dev/&quot;&gt;Fresh&lt;/a&gt;. Turns out, it works pretty well!&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Disclaimer - I’m fairly new to both Supabase and Fresh.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;I&apos;ve set up an example repo &lt;a href=&quot;https://github.com/npbee/fresh-supabase-auth&quot;&gt;here&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;Setup Supabase&lt;/h2&gt;
&lt;p&gt;You’ll need to set up a &lt;a href=&quot;https://supabase.com/&quot;&gt;Supabase&lt;/a&gt; project to get started. Alternatively, you can set up the &lt;a href=&quot;https://supabase.com/docs/guides/cli&quot;&gt;CLI&lt;/a&gt; for local development which will spin up a local Supabase project in a Docker container.&lt;/p&gt;
&lt;p&gt;If you are using local development, you’ll need to update the &lt;code&gt;supabase/config.toml&lt;/code&gt; file to contain the correct URLs. Here’s an example with Fresh’s defaults:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-toml&quot;&gt;[auth]
enabled = true
# ...

# HERE -&amp;gt; Update to match Fresh&apos;s localhost URL
site_url = &amp;quot;http://127.0.0.1:8000&amp;quot;

# ...

[auth.email]
# ...

# Here -&amp;gt; Set this to `true` to use the PKCE flow locally
enable_confirmations = true

&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You’ll also need to make sure your &lt;code&gt;.env&lt;/code&gt; file has the correct key values:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;# .env
SUPABASE_URL=xxx
SUPABASE_ANON_KEY=xxx
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Grab the NPM packages&lt;/h2&gt;
&lt;p&gt;Since Deno can run npm packages now, we can put those in our &lt;code&gt;deno.json&lt;/code&gt; file like so:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsonc&quot;&gt;{
  // ...
  &amp;quot;imports&amp;quot;: {
    &amp;quot;$fresh/&amp;quot;: &amp;quot;https://deno.land/x/fresh@1.6.1/&amp;quot;,
    // ...
    &amp;quot;@supabase/ssr&amp;quot;: &amp;quot;npm:@supabase/ssr&amp;quot;,
    &amp;quot;@supabase/supabase-js&amp;quot;: &amp;quot;npm:@supabase/supabase-js&amp;quot;
  }
  // ...
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Fresh Plugin&lt;/h2&gt;
&lt;p&gt;I found it cleanest to set up a Fresh &lt;a href=&quot;https://fresh.deno.dev/docs/concepts/plugins&quot;&gt;plugin&lt;/a&gt; called &lt;code&gt;auth.ts&lt;/code&gt; to contain every related to auth. It’s primarily middleware involved, so there is flexibility in how this is setup.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// plugins/auth.ts
import type { Plugin } from &amp;quot;$fresh/server.ts&amp;quot;;

export const authPlugin: Plugin = {
  name: &amp;quot;auth&amp;quot;,
  middlewares: [
    // Coming up...
  ],
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Add the plugin to your Fresh config:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;import { defineConfig } from &amp;quot;$fresh/server.ts&amp;quot;;
import tailwind from &amp;quot;$fresh/plugins/tailwind.ts&amp;quot;;
import { authPlugin } from &amp;quot;./plugins/auth.ts&amp;quot;;

// Set up some types we&apos;ll reference later
export type SignedInState = {
  session: Session;
};

export type SignedOutState = {
  session?: null;
};

export type AuthState = SignedInState | SignedOutState;

export default defineConfig({
  plugins: [authPlugin, tailwind()],
});
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Set up the client&lt;/h2&gt;
&lt;p&gt;The Supabase client will be a “server” client specifically for handling cookie-based authentication. It works with standard &lt;code&gt;Request&lt;/code&gt; and &lt;code&gt;Response&lt;/code&gt; objects. It took me a minute to wrap my head around how it works, but the gist is that you pass it &lt;code&gt;Request&lt;/code&gt; and &lt;code&gt;Response&lt;/code&gt; objects and the client will update the &lt;code&gt;Response&lt;/code&gt; you passed with the necessary cookies for authentication. You can then use that response to render the page.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// plugins/auth.ts
import type { FreshContext, Plugin } from &amp;quot;$fresh/server.ts&amp;quot;;
import { createServerClient, parse, serialize } from &amp;quot;@supabase/ssr&amp;quot;;
import { assert } from &amp;quot;$std/assert/assert.ts&amp;quot;;

export function createSupabaseClient(req: Request, resp: Response) {
  const cookies = parse(req.headers.get(&amp;quot;Cookie&amp;quot;) || &amp;quot;&amp;quot;);

  const SUPABASE_URL = Deno.env.get(&amp;quot;SUPABASE_URL&amp;quot;);
  const ANON_KEY = Deno.env.get(&amp;quot;SUPABASE_ANON_KEY&amp;quot;);

  assert(SUPABASE_URL, &amp;quot;SUPABASE_URL is not set&amp;quot;);
  assert(ANON_KEY, &amp;quot;SUPABASE_ANON_KEY is not set&amp;quot;);

  return createServerClient(SUPABASE_URL, ANON_KEY, {
    cookies: {
      get(key) {
        return cookies[key];
      },
      set(key, value, options) {
        const cookie = serialize(key, value, options);
        // If the cookie is updated, update the cookies for the response
        resp.headers.append(&amp;quot;Set-Cookie&amp;quot;, cookie);
      },
      remove(key, options) {
        const cookie = serialize(key, &amp;quot;&amp;quot;, options);
        // If the cookie is removed, update the cookies for the response
        resp.headers.append(&amp;quot;Set-Cookie&amp;quot;, cookie);
      },
    },
  });
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Set up session refresh&lt;/h2&gt;
&lt;p&gt;There needs to be a middleware that runs on every request to ensure the session is in the correct state.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// plugins/auth.ts
import type { Plugin } from &amp;quot;$fresh/server.ts&amp;quot;;

export const authPlugin: Plugin = {
  name: &amp;quot;auth&amp;quot;,
  middlewares: [
    // For every route, we ensure the session state is updated
    {
      path: &amp;quot;/&amp;quot;,
      middleware: {
        handler: setSessionState,
      },
    },
  ],
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The middleware handler is a little goofy because we have to set up an empty &lt;code&gt;Response&lt;/code&gt; object that the Supabase client will attach cookies to and then copy over those cookies to the real &lt;code&gt;Response&lt;/code&gt;. We do this because we don’t want to call &lt;code&gt;await ctx.next()&lt;/code&gt; before we’ve updated the session state.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// ...

async function setSessionState(req: Request, ctx: FreshContext) {
  if (ctx.destination !== &amp;quot;route&amp;quot;) return await ctx.next();

  // Sanity check - start without a session
  ctx.state.session = null;

  // Create an empty response object here. We want to make sure we do this
  // session refresh before going further down the middleware chain
  const resp = new Response();
  const supabase = createSupabaseClient(req, resp);

  // Refresh session if expired
  const { data } = await supabase.auth.getSession();

  // Stash this on context for later...
  ctx.state.session = data.session;

  /**
   * Unlike `supabase.auth.getSession()`, which returns the session _without_
   * validating the JWT, this function also calls `getUser()` to validate the
   * JWT before setting the session.
   */
  const { error, data: { user } } = await supabase.auth.getUser();
  if (error) {
    // JWT validation has failed
    ctx.state.session = null;
    ctx.state.user = null;
  }

  ctx.state.user = user;

  // Continue down the middleware chain
  const nextResp = await ctx.next();

  // Copy over any headers that were added by Supabase
  // Note how we&apos;re spreading the headers before iterating. This ensures we&apos;re
  // capturing potentially duplicated headers that Supabase might add, like
  // chunked cookies.
  for (const [key, value] of [...resp.headers]) {
    nextResp.headers.set(key, value);
  }

  return nextResp;
}
&lt;/code&gt;&lt;/pre&gt;
&lt;blockquote&gt;
&lt;p&gt;Edit!
Fixed an issue where duplicate Supabase headers weren&apos;t handled properly.
Thanks, &lt;a href=&quot;https://github.com/npbee/fresh-supabase-auth/issues/1&quot;&gt;@nikololay&lt;/a&gt;&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;Guard Protected Routes&lt;/h2&gt;
&lt;p&gt;Now that we have an accurate session state, we can start guarding any routes we want to be logged in. We can set up another middleware for a &lt;code&gt;/dashboard&lt;/code&gt; route:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-ts&quot;&gt;// plugins/auth.ts

// A little helper for redirects. We will write this a lot...
import { redirect } from &amp;quot;../utils.ts&amp;quot;;

// ...

export const authPlugin: Plugin = {
  name: &amp;quot;auth&amp;quot;,
  middlewares: [
    // ...

    // For the dashboard route, we ensure the user is signed in
    {
      path: &amp;quot;/dashboard&amp;quot;,
      middleware: {
        handler: ensureSignedIn,
      },
    },
  ],
};

function ensureSignedIn(_req: Request, ctx: FreshContext) {
  if (!ctx.state.session) {
    return redirect(
      &amp;quot;/auth/signin?message=You must be signed in to access this page&amp;quot;,
    );
  }

  return ctx.next();
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Dashboard Route&lt;/h2&gt;
&lt;p&gt;Let’s set up the &lt;code&gt;/dashboard&lt;/code&gt; route so we have a place to land authenticated users.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;// routes/dashboard/index.tsx
import { FreshContext } from &amp;quot;$fresh/server.ts&amp;quot;;
import { Container } from &amp;quot;../../components/Container.tsx&amp;quot;;
import { SignedInState } from &amp;quot;../../plugins/auth.ts&amp;quot;;

// Make this an `async` function so we can get the full context
export default async function DashboardPage(
  _req: Request,
  ctx: FreshContext&amp;lt;SignedInState&amp;gt;,
) {
  const { user } = ctx.state;
  return (
    &amp;lt;Container&amp;gt;
      &amp;lt;h1 class=&amp;quot;text-xl&amp;quot;&amp;gt;Dashboard&amp;lt;/h1&amp;gt;
      &amp;lt;p&amp;gt;Hello, {user.email}&amp;lt;/p&amp;gt;
    &amp;lt;/Container&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Sign up&lt;/h2&gt;
&lt;p&gt;For signing up users we will use the PKCE flow described &lt;a href=&quot;https://supabase.com/blog/supabase-auth-sso-pkce&quot;&gt;here&lt;/a&gt;. This will send a link to a user’s email that will send them back to our app and exchange a one-time code for a session.&lt;/p&gt;
&lt;p&gt;Let’s first set up the callback route users will land on from their email:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;import { Handlers } from &amp;quot;$fresh/server.ts&amp;quot;;
import { redirect } from &amp;quot;../../utils.ts&amp;quot;;
import { createSupabaseClient } from &amp;quot;../../plugins/auth.ts&amp;quot;;

export const handler: Handlers = {
  async GET(req) {
    const requestUrl = new URL(req.url);
    // Set up a successful response
    const resp = redirect(&amp;quot;/dashboard&amp;quot;);
    const code = requestUrl.searchParams.get(&amp;quot;code&amp;quot;);
    const supabase = createSupabaseClient(req, resp);

    if (code) {
      await supabase.auth.exchangeCodeForSession(code);
    }

    return resp;
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now we can set up a sign up page:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;// routes/auth/signup.tsx
import { Handlers } from &amp;quot;$fresh/server.ts&amp;quot;;
import { assert } from &amp;quot;$std/assert/assert.ts&amp;quot;;
import { createSupabaseClient } from &amp;quot;../../plugins/auth.ts&amp;quot;;

export const handler: Handlers = {
  async POST(req) {
    // Set up the response we want to return if successful
    const resp = new Response(null, {
      headers: {
        location: &amp;quot;/auth/signup?message=Check your email for the sign in link&amp;quot;,
      },
      status: 303,
    });

    // Do whatever we need to grab the login details
    const form = await req.formData();
    const email = form.get(&amp;quot;email&amp;quot;)?.toString();
    const password = form.get(&amp;quot;password&amp;quot;)?.toString();

    assert(email, &amp;quot;email is required&amp;quot;);
    assert(password, &amp;quot;password is required&amp;quot;);

    // Setup the supabase client
    const supabase = createSupabaseClient(req, resp);
    const { error } = await supabase.auth.signUp({
      email,
      password,
      options: {
        emailRedirectTo: new URL(&amp;quot;/auth/callback&amp;quot;, req.url).toString(),
      },
    });

    if (error) {
      return new Response(null, {
        headers: { location: &amp;quot;/auth/signup?message=Could not sign up&amp;quot; },
      });
    }

    // Return the response. Supabase client will have added cookies
    return resp;
  },
};

export default function Page(req: Request) {
  const message = new URL(req.url).searchParams.get(&amp;quot;message&amp;quot;);
  return (
    &amp;lt;div&amp;gt;
      &amp;lt;form method=&amp;quot;post&amp;quot;&amp;gt;
        &amp;lt;label for=&amp;quot;email&amp;quot;&amp;gt;Email&amp;lt;/label&amp;gt;
        &amp;lt;input id=&amp;quot;email&amp;quot; type=&amp;quot;email&amp;quot; name=&amp;quot;email&amp;quot; /&amp;gt;

        &amp;lt;label for=&amp;quot;password&amp;quot;&amp;gt;Password&amp;lt;/label&amp;gt;
        &amp;lt;input id=&amp;quot;password&amp;quot; type=&amp;quot;password&amp;quot; name=&amp;quot;password&amp;quot; /&amp;gt;

        &amp;lt;button type=&amp;quot;submit&amp;quot;&amp;gt;Sign up&amp;lt;/button&amp;gt;
      &amp;lt;/form&amp;gt;
      {message &amp;amp;&amp;amp; &amp;lt;p&amp;gt;{message}&amp;lt;/p&amp;gt;}
    &amp;lt;/div&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If you’re using local Supabase development, you should see an email in your “Inbucket” that looks like this:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/inbucket.png&quot; alt=&quot;Image of the local development inbox &quot;&gt;&lt;/p&gt;
&lt;h2&gt;Sign In&lt;/h2&gt;
&lt;p&gt;The sign in page will look similar:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;// routes/auth/signin.tsx
import { Handlers } from &amp;quot;$fresh/server.ts&amp;quot;;
import { assert } from &amp;quot;$std/assert/assert.ts&amp;quot;;
import { createSupabaseClient } from &amp;quot;../../plugins/auth.ts&amp;quot;;
import { redirect } from &amp;quot;../../utils.ts&amp;quot;;

export const handler: Handlers = {
  async POST(req) {
    const resp = redirect(&amp;quot;/dashboard&amp;quot;);
    const supabase = createSupabaseClient(req, resp);
    const form = await req.formData();
    const email = form.get(&amp;quot;email&amp;quot;)?.toString();
    const password = form.get(&amp;quot;password&amp;quot;)?.toString();

    assert(email, &amp;quot;email is required&amp;quot;);
    assert(password, &amp;quot;password is required&amp;quot;);

    const { error } = await supabase.auth.signInWithPassword({
      email,
      password,
    });

    if (error) {
      return redirect(&amp;quot;/auth/signin?message=Error signing up&amp;quot;);
    }

    return resp;
  },
};

export default function Page(req: Request) {
  const message = new URL(req.url).searchParams.get(&amp;quot;message&amp;quot;);

  return (
    &amp;lt;div&amp;gt;
      &amp;lt;h1&amp;gt;Sign in&amp;lt;/h1&amp;gt;
      &amp;lt;form method=&amp;quot;post&amp;quot;&amp;gt;
        &amp;lt;label for=&amp;quot;email&amp;quot;&amp;gt;Email&amp;lt;/label&amp;gt;
        &amp;lt;input id=&amp;quot;email&amp;quot; type=&amp;quot;email&amp;quot; name=&amp;quot;email&amp;quot; /&amp;gt;

        &amp;lt;label for=&amp;quot;password&amp;quot;&amp;gt;Password&amp;lt;/label&amp;gt;
        &amp;lt;input id=&amp;quot;password&amp;quot; type=&amp;quot;password&amp;quot; name=&amp;quot;password&amp;quot; /&amp;gt;

        &amp;lt;button type=&amp;quot;submit&amp;quot;&amp;gt;Sign in&amp;lt;/button&amp;gt;
      &amp;lt;/form&amp;gt;
      {message &amp;amp;&amp;amp; &amp;lt;p&amp;gt;{message}&amp;lt;/p&amp;gt;}
    &amp;lt;/div&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Sign out&lt;/h2&gt;
&lt;p&gt;Sign out is even simpler:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;import { Handlers } from &amp;quot;$fresh/server.ts&amp;quot;;
import { createSupabaseClient } from &amp;quot;../../plugins/auth.ts&amp;quot;;
import { redirect } from &amp;quot;../../utils.ts&amp;quot;;

export const handler: Handlers = {
  async GET(req) {
    const resp = redirect(&amp;quot;/auth/signin&amp;quot;);
    const supabase = createSupabaseClient(req, resp);

    await supabase.auth.signOut();

    return resp;
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Summing Up&lt;/h2&gt;
&lt;p&gt;If everything worked out, you should be able sign up/out/in users and get to a dashboard page that looks like this:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dashboard.png&quot; alt=&quot;Image of a logged-in dashboard page&quot;&gt;&lt;/p&gt;
&lt;p&gt;Did I miss something? Do something wrong? Let me know!&lt;/p&gt;
</content:encoded></item><item><title>Showing audio progress with waveform images</title><link>https://npbee.me/posts/audio-waveform-scrubber/</link><guid isPermaLink="true">https://npbee.me/posts/audio-waveform-scrubber/</guid><description>Use CSS clip-path to overlay two waveform images and show audio progress.</description><pubDate>Fri, 29 Dec 2023 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;import Code from &apos;../../components/system/Code.astro&apos;;
import Example from &apos;../../components/system/Example.astro&apos;;
import CodeDetails from &apos;../../components/system/CodeDetails.astro&apos;;
import Attempt1 from &apos;../../components/posts/audio-waveform-scrubber-1.astro&apos;;
import Attempt1Raw from &apos;../../components/posts/audio-waveform-scrubber-1.astro?raw&apos;;
import Attempt1Color from &apos;../../components/posts/audio-waveform-scrubber-2.astro&apos;;
import Attempt2 from &apos;../../components/posts/audio-waveform-scrubber-3.astro&apos;;
import Attempt2Raw from &apos;../../components/posts/audio-waveform-scrubber-3.astro?raw&apos;;
import Final from &apos;../../components/posts/audio-waveform-scrubber-4.astro&apos;;
import { AudioPlayer } from &amp;quot;../../components/audio-player/player.tsx&amp;quot;;&lt;/p&gt;
&lt;p&gt;A passion project of mine I&apos;ve been working on recently is https://waveformr.com/. It’s a service that accepts a URL of an audio file and gives you back an SVG of the waveform. You can use it to display audio waveforms like you would an image. Like this:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://waveformr.com/render?url=https://res.cloudinary.com/dhhjogfy6//video/upload/q_auto/v1575831765/audio/ghost.mp3&amp;amp;stroke=005f73&quot; alt=&quot;Audio waveform image&quot;&gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;CodeDetails code=&amp;quot;https://waveformr.com/edit?url=https://res.cloudinary.com/dhhjogfy6//video/upload/q_auto/v1575831765/audio/ghost.mp3&amp;amp;stroke=005f73&amp;quot; lang=&amp;quot;html&amp;quot; /&amp;gt;&lt;/p&gt;
&lt;p&gt;I’ll write more about this service in the future, but for now I wanted to cover a technique for showing progress on an audio waveform, similar to Soundcloud:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/soundcloud-waveform.png&quot; alt=&quot;Soundcloud waveform progress&quot;&gt;&lt;/p&gt;
&lt;p&gt;Since we’re rendering the audio waveforms as an image, we have to get more creative to achieve the progress visualization.&lt;/p&gt;
&lt;h2&gt;Enter Clip-path&lt;/h2&gt;
&lt;p&gt;The secret here is to use CSS &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path&quot;&gt;clip-path&lt;/a&gt;.
If we have two waveform images, we can overlay them on top of each other and use &lt;code&gt;clip-path&lt;/code&gt; to get the visual progress that we&apos;re looking for.
Here&apos;s the first attempt:&lt;/p&gt;
&lt;p&gt;&amp;lt;Example&amp;gt;
&amp;lt;Attempt1 /&amp;gt;
&amp;lt;/Example&amp;gt;
&amp;lt;Code code={Attempt1Raw} lang=&amp;quot;astro&amp;quot; /&amp;gt;&lt;/p&gt;
&lt;p&gt;The &lt;code&gt;polygon&lt;/code&gt; shape tells CSS to &amp;quot;clip&amp;quot; the image to the coordinates we&apos;re drawing.
In this case, we want to clip the image so that it stops at the point where the current time of the audio is.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/clip-path-1.svg#diagram&quot; alt=&quot;Two rectangles are displayed. The bottom one is clipped to represent the clipped waveform&quot;&gt;&lt;/p&gt;
&lt;p&gt;Assuming we have the current percentage of audio that&apos;s played, we can set that as a CSS custom property and use that as a dynamic way to apply our &lt;code&gt;clip-path&lt;/code&gt;.&lt;/p&gt;
&lt;h2&gt;Going further&lt;/h2&gt;
&lt;p&gt;What we have is pretty solid, but there was one thing that bugged me. It&apos;s easier to see with different colors.&lt;/p&gt;
&lt;p&gt;&amp;lt;Example&amp;gt;
&amp;lt;Attempt1Color /&amp;gt;
&amp;lt;/Example&amp;gt;&lt;/p&gt;
&lt;p&gt;Here&apos;s a zoomed-in version:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/clip-path-2.png#diagram&quot; alt=&quot;A zoomed in image of two waveforms. One is bleeding through behind the other&quot;&gt;&lt;/p&gt;
&lt;p&gt;It&apos;s subtle, but the &amp;quot;base&amp;quot; waveform is bleeding through behind the progress waveform.
This makes sense because we&apos;re layering the progress waveform right over the top of the base waveform.
We can adjust this so that there is no overlap by using another &lt;code&gt;clip-path&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;&amp;lt;Example&amp;gt;
&amp;lt;Attempt2 /&amp;gt;
&amp;lt;/Example&amp;gt;
&amp;lt;Code code={Attempt2Raw} lang=&amp;quot;astro&amp;quot; /&amp;gt;&lt;/p&gt;
&lt;p&gt;We&apos;re applying the inverse shape to the base waveform so that the two are clipped in a way that avoids overlapping.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/clip-path-3.svg#diagram&quot; alt=&quot;Diagram showing two rectangles that are clipped to avoid overlapping&quot;&gt;&lt;/p&gt;
&lt;p&gt;Here are the two side-by-side for comparison:&lt;/p&gt;
&lt;p&gt;&amp;lt;Example&amp;gt;
&amp;lt;Attempt1Color /&amp;gt;
&amp;lt;Attempt2 /&amp;gt;
&amp;lt;/Example&amp;gt;&lt;/p&gt;
&lt;h2&gt;The end result&lt;/h2&gt;
&lt;p&gt;Here&apos;s the end result using some prettier colors:&lt;/p&gt;
&lt;p&gt;&amp;lt;Example&amp;gt;
&amp;lt;Final /&amp;gt;
&amp;lt;/Example&amp;gt;&lt;/p&gt;
&lt;p&gt;Note that this technique is purely for &lt;em&gt;visual&lt;/em&gt; progress.
For using in a real audio player, make sure to think about accessibility.&lt;/p&gt;
&lt;p&gt;Here&apos;s a real-life demo using this technique:&lt;/p&gt;
&lt;p&gt;&amp;lt;Example label=&amp;quot;demo&amp;quot;&amp;gt;
&amp;lt;AudioPlayer client:load /&amp;gt;
&amp;lt;/Example&amp;gt;&lt;/p&gt;
&lt;p&gt;Code for this is &lt;a href=&quot;/demos/audio-player&quot;&gt;here&lt;/a&gt;.&lt;/p&gt;
</content:encoded></item><item><title>Neovim, Deno, and TypeScript in a monorepo</title><link>https://npbee.me/posts/deno-and-typescript-in-a-monorepo-neovim-lsp/</link><guid isPermaLink="true">https://npbee.me/posts/deno-and-typescript-in-a-monorepo-neovim-lsp/</guid><description>How to avoid LSP conflicts</description><pubDate>Thu, 09 Nov 2023 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;If you’ve ever tried to get both &lt;a href=&quot;https://deno.com/&quot;&gt;Deno&lt;/a&gt; and TypeScript LSP’s set up in Neovim you’ve likely run into configuration issues. Both Deno and TypeScript operate on &lt;code&gt;.ts&lt;/code&gt; files, so by default both LSP’s will try to attach when you open a TypeScript file.&lt;/p&gt;
&lt;p&gt;The Deno &lt;a href=&quot;https://docs.deno.com/runtime/manual/getting_started/setup_your_environment#neovim-06-using-the-built-in-language-server&quot;&gt;docs&lt;/a&gt; recommend using the root file pattern to avoid conflicts.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-lua&quot;&gt;local nvim_lsp = require(&apos;lspconfig&apos;)

nvim_lsp.denols.setup {
  on_attach = on_attach,
  root_dir = nvim_lsp.util.root_pattern(&amp;quot;deno.json&amp;quot;, &amp;quot;deno.jsonc&amp;quot;),
}

nvim_lsp.tsserver.setup {
  on_attach = on_attach,
  root_dir = nvim_lsp.util.root_pattern(&amp;quot;package.json&amp;quot;),
  single_file_support = false
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This tells the Deno language server to only start if it finds a &lt;code&gt;deno.json&lt;/code&gt; or &lt;code&gt;deno.jsonc&lt;/code&gt; file at the root of your project. Similarly, the TypeScript language server will start if it finds a &lt;code&gt;package.json&lt;/code&gt; file. The &lt;code&gt;single_file_support = false&lt;/code&gt; part is needed to avoid the TypeScript LSP starting up in “single file mode” for any &lt;code&gt;.ts&lt;/code&gt; file.&lt;/p&gt;
&lt;p&gt;This mostly works, but if you’re in a monorepo set up with something like &lt;a href=&quot;https://pnpm.io/&quot;&gt;pnpm&lt;/a&gt;, this won’t quite work because there is likely a &lt;code&gt;package.json&lt;/code&gt; file setup at your workspace root:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;my-monorepo/
  apps/
    deno-api/
      main.ts
      deno.jsonc
    typescript-frontend/
	  package.json
package.json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Opening &lt;code&gt;main.ts&lt;/code&gt; will still attach the TypeScript language server because it finds the &lt;code&gt;package.json&lt;/code&gt; at the workspace root. You&apos;ll end up with both the TypeScript and Deno LSP&apos;s attached.&lt;/p&gt;
&lt;p&gt;The &lt;code&gt;root_dir&lt;/code&gt; field is a function takes the filename as a parameter and is expected to return either a string or &lt;code&gt;nil&lt;/code&gt;. If it returns &lt;code&gt;nil&lt;/code&gt;, then the LSP won’t attach to the current buffer. We can use this idea to make a specialized &lt;code&gt;root_pattern_exclude&lt;/code&gt; function that takes an exclusion value so that we only attach the TypeScript LSP if we &lt;em&gt;don’t&lt;/em&gt; find a Deno root file. Here’s what that might look like:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-lua&quot;&gt;---Specialized root pattern that allows for an exclusion
---@param opt { root: string[], exclude: string[] }
---@return fun(file_name: string): string | nil
local function root_pattern_exclude(opt)
  local lsputil = require(&apos;lspconfig.util&apos;)

  return function(fname)
    local excluded_root = lsputil.root_pattern(opt.exclude)(fname)
    local included_root = lsputil.root_pattern(opt.root)(fname)

    if excluded_root then
      return nil
    else
      return included_root
    end
  end
end

lspconfig.tsserver.setup({
  on_attach = on_attach,
  root_dir = root_pattern_exclude({
    root = { &amp;quot;package.json&amp;quot; },
    exclude = { &amp;quot;deno.json&amp;quot;, &amp;quot;deno.jsonc&amp;quot; }
  }),
  single_file_support = false
})

lspconfig.denols.setup({
  on_attach = on_attach,
  root_dir = lspconfig.util.root_pattern(&amp;quot;deno.json&amp;quot;, &amp;quot;deno.jsonc&amp;quot;, &amp;quot;deno.lock&amp;quot;),
  init_options = {
    lint = true,
    suggest = {
      imports = {
        hosts = {
          [&amp;quot;https://deno.land&amp;quot;] = true,
        },
      },
    },
  },
})
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Now, we can pull up a TypeScript file and, depending on which application we’re in within the monorepo, either the Deno LSP or the TypeScript LSP will start.&lt;/p&gt;
</content:encoded></item><item><title>Command-based undo for JS apps</title><link>https://npbee.me/posts/command-based-undo/</link><guid isPermaLink="true">https://npbee.me/posts/command-based-undo/</guid><description>A brain dump of research into non-trivial undo implementations</description><pubDate>Mon, 23 Oct 2023 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;I’ve always been fascinated by undo/redo in web applications. It’s a useful addition to nearly any app and arguably expected in complex ones. If it’s there, it becomes integral to how the product is used, like search or a command palette. And it’s invisible! Users can’t “see” it, but they generally have a good idea of what should happen when they use it. And as an implementor, it can be mind-melting.&lt;/p&gt;
&lt;p&gt;If you’re dealing with a single component or a smaller-scoped project, there are libraries available for implementing undo that you can and should be using. If you’re building an &lt;em&gt;app&lt;/em&gt; on the scale of something like Figma or TLDraw, then undo stops being a “feature” and starts becoming part of your architecture. Implementing undo is less about installing the right library and more about following the right patterns.&lt;/p&gt;
&lt;p&gt;The command pattern is one that I’ve found to be the most flexible for robust undo implementation, but it’s been challenging to find practical examples to learn from. I always seem to first land on the simple examples and then jump straight to CRDTs without anything in between. I wanted to dig into this pattern more and see how it could be applied using everyday, “boring” frontend tooling. This is admittedly a bit of a brain dump for my later self, but hopefully others will find it useful.&lt;/p&gt;
&lt;p&gt;If you&apos;re interested in going straight into some code, check out the &lt;a href=&quot;https://github.com/npbee/undo-redo-playground&quot;&gt;repository&lt;/a&gt; and &lt;a href=&quot;https://undo-redo-playground.pages.dev/&quot;&gt;demo&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;The memento pattern&lt;/h2&gt;
&lt;p&gt;First, a quick primer on the memento pattern. It’s a &lt;em&gt;state-based&lt;/em&gt; approach that deals with undo/redo from the perspective of state changes. The idea is save a snapshot of the undoable state for every change made. Undoing means restoring a previous state. If you’ve built a lot of Redux apps, this approach will feel familiar. It’s a straightforward and generalizable approach and it’s the &lt;a href=&quot;https://redux.js.org/usage/implementing-undo-history&quot;&gt;official recommendation&lt;/a&gt; from the Redux docs. I’ve used this approach with good success. If it works for you I’d recommend it.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;{
  counter: {
    past: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
    present: 10,
    future: []
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There’s a couple of downsides with this pattern though:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;You need to store your undoable state for every change, which could get excessively large. In practice, I’ve never had an issue with this. If you’re following Redux/React typical best practices, you are likely performing immutable updates and achieving some structural sharing.&lt;/li&gt;
&lt;li&gt;You’re forced to store all of your undoable state in a single object. If your application state is spread around to multiple stores like Jotai atoms or Tanstack query cache, this may not work for you.&lt;/li&gt;
&lt;li&gt;After an undo, you might need to persist a save to the backend in a format that’s &lt;em&gt;different&lt;/em&gt; from your undoable state shape. Knowing the state snapshot is not enough information to persist the change.&lt;/li&gt;
&lt;li&gt;You might need to attach other metadata to the change to perform side effects. For example, re-focusing an input element after undoing an edit. Another example might be providing a human-readable description of a change.&lt;/li&gt;
&lt;li&gt;It’s all-or-nothing. Every action has to be undoable. If you perform an action on the state that is &lt;em&gt;not&lt;/em&gt; undoable, you have to clear the undo stack.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;The command pattern&lt;/h2&gt;
&lt;p&gt;Contrasted with the state-based approach above, the command pattern is more &lt;em&gt;action-based&lt;/em&gt;. Undo/redo is handled by defining commands that can execute and undo a change.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;const myCommand = {
  exec() {
    // ...
  },
  undo() {
    // ...
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;To make a change on the system, a command is dispatched to a central handler to call the &lt;code&gt;exec&lt;/code&gt; or &lt;code&gt;undo&lt;/code&gt; functions and move the command between an undo stack and a redo stack.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;function dispatch(command) {
  command.exec();
  undoStack.push(command);
}

function undo() {
  const command = undoStack.pop();
  if (command) {
    command.undo();
    redoStack.push(command);
  }
}

function redo() {
  const command = redoStack.pop();
  if (command) {
    command.exec();
    undoStack.push(command);
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This approach is more flexible, but less generalizable. Ultimately, the command pattern is not a pattern specific to undo implementations, it’s more of a general architectural pattern. This is where we veer off into “how do I build undo” to “how do I build an event-driven, command-based architecture (that also has undo)?” It’s hard to describe a command-based undo system that’s &lt;em&gt;just&lt;/em&gt; focused on undo because it has an effect on your whole system.&lt;/p&gt;
&lt;h2&gt;Keeping a history log&lt;/h2&gt;
&lt;p&gt;The state-based approach and the action-based approach are different in how they approach undo, but they share a common pattern: keeping a log. This seems obvious to point out, but to undo a change you have to know that a change occurred and you have to know a few details about how it happened. The entries in the log are what we use to derive the current state from past user actions. How the entries in the log are structured can vary, but typically you have an &lt;code&gt;undoStack&lt;/code&gt; and a &lt;code&gt;redoStack&lt;/code&gt;. You might also see these named as &lt;code&gt;past&lt;/code&gt; and &lt;code&gt;future&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;In the memento pattern, it’s a log of state snapshots. The log isn&apos;t concerned with &lt;em&gt;how&lt;/em&gt; the snapshots were created, only the end result. This is nice because the &lt;em&gt;how&lt;/em&gt; doesn’t inject its way into the rest of the architecture. It can be contained to a single component or service and you can fairly easy &amp;quot;upgrade&amp;quot; a piece of state to be undoable.&lt;/p&gt;
&lt;p&gt;In the command pattern, the log holds instances of commands, but I prefer to think of them as just &amp;quot;events&amp;quot; or &amp;quot;entries&amp;quot;. The events contain any information you might need to execute or undo an action. This could be functions to make state like &lt;code&gt;.exec()&lt;/code&gt; or &lt;code&gt;.undo()&lt;/code&gt; or any other plain data you want to attach to the event.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;const undoStack = [
  {
    params: {
      id: &amp;quot;xxx&amp;quot;,
      previous: &amp;quot;foo&amp;quot;,
      next: &amp;quot;bar&amp;quot;,
    },
    exec() {
      state[params.id].value === params.next;
    },
    undo() {
      state[params.id].value === params.previous;
    },
  },
];
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In contrast to the memento pattern, commands do care about how the state changes are applied. The &lt;code&gt;exec&lt;/code&gt; and &lt;code&gt;undo&lt;/code&gt; functions on a command typically need to work together for the implementation to work as expected.&lt;/p&gt;
&lt;h2&gt;Using Patches&lt;/h2&gt;
&lt;p&gt;One way to retain some of the advantages of the memento pattern could be to use patches in your event log. Patches can be a more compact way to describe state changes without needing to store the entire state. Using a library like Immer, you could build something like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;import { produceWithPatches, applyPatches } from &amp;quot;immer&amp;quot;;

const myCommand = {
  params: {
    id: &amp;quot;xxx&amp;quot;,
    previous: &amp;quot;foo&amp;quot;,
    next: &amp;quot;bar&amp;quot;,
  },
  exec(params) {
    const [nextState, patches, inversePatches] = produceWithPatches((state) =&amp;gt; {
      state[params.id].value === params.next;
    });

    setState(nextState);

    // Return this for the `undo` call
    return { patches, inversePatches };
  },
  undo(logEntry) {
    // Apply the inverse patches to revert the `exec` function
    const nextState = applyPatches(state, logEntry.inversePatches);
    setState(nextState);
  },
};

function dispatch(command) {
  const payload = command.exec(command.params);
  const entry = {
    commmand,
    payload,
  };
  undoStack.push(entry);
}

function undo() {
  const entry = undoStack.pop();
  if (entry) {
    entry.command.undo(entry);
    // TODO: What&apos;s the redoStack here?
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In this example, there’s a new thing called an “entry” that represents a command that’s been executed. Another name might be a “transaction”. The command &lt;code&gt;exec&lt;/code&gt; function returns the &lt;code&gt;patches&lt;/code&gt; and &lt;code&gt;inversePatches&lt;/code&gt; that can be used later to undo it. If you can constrain all of your commands to adhere to this pattern, you can abstract this even more to make commands very succinct.&lt;/p&gt;
&lt;p&gt;Beware, though, that there’s an implicit parameter with patches though and that’s the “base” that we’re applying the patches against. You don’t want to apply patches to the wrong base object, otherwise you’ll end up at the wrong result.&lt;/p&gt;
&lt;h2&gt;Data Mutation Strategy&lt;/h2&gt;
&lt;p&gt;When building frontend apps, there’s always the challenge of how the UI state will be synced to the source of truth. In a typical app, you may have a few different flavors:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;A &lt;em&gt;local-first&lt;/em&gt; approach where updates are applied to the UI state immediately then synced to the source of truth later&lt;/li&gt;
&lt;li&gt;A &lt;em&gt;server-first&lt;/em&gt; approach where the app waits for a response from the backend before updating the UI.&lt;/li&gt;
&lt;li&gt;An &lt;em&gt;optimistic&lt;/em&gt; approach where the backend call and UI updates happen simultaneously, assuming the backend call will succeed.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;In a typical app, you can co-locate the data mutation strategy with the action in the place that it originated and you can mix and match strategies throughout the app to taste. Here&apos;s an example from the &lt;a href=&quot;https://remix.run/docs/en/main/discussion/pending-ui&quot;&gt;Remix&lt;/a&gt; docs on pending UI:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;import type { ActionFunctionArgs } from &amp;quot;@remix-run/node&amp;quot;; // or cloudflare/deno
import { redirect } from &amp;quot;@remix-run/node&amp;quot;; // or cloudflare/deno
import { useNavigation } from &amp;quot;@remix-run/react&amp;quot;;

export async function action({ request }: ActionFunctionArgs) {
  const formData = await request.formData();
  const project = await createRecord({
    name: formData.get(&amp;quot;name&amp;quot;),
    owner: formData.get(&amp;quot;owner&amp;quot;),
  });
  return redirect(`/projects/${project.id}`);
}

export default function CreateProject() {
  const navigation = useNavigation();

  // important to check you&apos;re submitting to the action
  // for the pending UI, not just any action
  const isSubmitting = navigation.formAction === &amp;quot;/create-project&amp;quot;;

  return (
    &amp;lt;Form method=&amp;quot;post&amp;quot; action=&amp;quot;/create-project&amp;quot;&amp;gt;
      &amp;lt;fieldset disabled={isSubmitting}&amp;gt;
        &amp;lt;label&amp;gt;
          Name: &amp;lt;input type=&amp;quot;text&amp;quot; name=&amp;quot;projectName&amp;quot; /&amp;gt;
        &amp;lt;/label&amp;gt;
        &amp;lt;label&amp;gt;
          Owner: &amp;lt;UserSelect /&amp;gt;
        &amp;lt;/label&amp;gt;
        &amp;lt;button type=&amp;quot;submit&amp;quot;&amp;gt;Create&amp;lt;/button&amp;gt;
      &amp;lt;/fieldset&amp;gt;
      {isSubmitting ? &amp;lt;BusyIndicator /&amp;gt; : null}
    &amp;lt;/Form&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In contrast, a command-based system has in a single handler that works against a generalized command structure so the data mutation strategy has to be encoded into the command. Saying that this command is &amp;quot;server-first&amp;quot; and this other command is &amp;quot;local-first&amp;quot; means that your command handler implementation needs to know how to handle that. It’s much easier to implement a command-based system that has a single agreed-upon approach to how data mutations should occur. This applies to how you structure your application state as well. The more unified your application state is, the simpler the undo implementation can be. If your application state is a single global store that can be updated with patches which can be sent to the server for persistence, you can make a streamlined undo system. If your state is in multiple stores and you have unique endpoints for every mutation, then you’ll have more tedious command definitions.&lt;/p&gt;
&lt;p&gt;Additionally, undo and redo operations are almost always best suited for immediate updates. Since undo operations typically have no UI associated with them, there’s not a good spot to put any pending UI to indicate that something is happening. Users are probably looking at the thing that they want to undo, so if nothing happens when that mash &lt;code&gt;⌘+z&lt;/code&gt;, it won&apos;t be a good experience.&lt;/p&gt;
&lt;p&gt;All this is to say that a general rule could be that &lt;strong&gt;anything that goes into your undo or redo stacks should be able to be applied immediately&lt;/strong&gt;. This implies that your system needs to know how to apply local state updates immediately and then “sync” them to the source of truth optimistically. This comes with all of the challenges of optimistic UI but it&apos;s harder because it&apos;s generalized and not co-located with the original user action.&lt;/p&gt;
&lt;p&gt;This strategy will come with trade offs. Anything that cannot be applied immediately can happen “out of band” in an isolated modal experience. For example, take the creation of a new entity where the &lt;code&gt;id&lt;/code&gt; must be supplied by the backend. The “undo” of a create is a delete, but true deleting would also require going to the backend. To make the undo optimistic, we need to define a property that represents a “soft delete” state so we can filter those out from the UI.&lt;/p&gt;
&lt;p&gt;In practice, this might look like this in a command structure:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;function CreateForm() {
  &amp;lt;form
    onSubmit={(evt) =&amp;gt; {
      const formData = new FormData(evt.target);

      // Go to the server first to create the entity
      const serverResult = await fetch(&amp;quot;/api/create&amp;quot;, {
        title: formData.get(&amp;quot;title&amp;quot;),
      }).then((res) =&amp;gt; res.json());

      // Now create a new command entry
      dispatch(
        createEntity({
          entity: serverResult.data,
        }),
      );
    }}
  &amp;gt;
    &amp;lt;input name=&amp;quot;title&amp;quot; /&amp;gt;
    &amp;lt;button&amp;gt;Submit&amp;lt;/button&amp;gt;
  &amp;lt;/form&amp;gt;;
}

const createEntity = (entity) =&amp;gt; ({
  // The `exec` command could be async to allow for setups.
  exec(params) {
    updateUI((state) =&amp;gt; {
      state[entity.id] = entity;
    });

    // Maybe we return a payload we will want later in the `undo`
    // operation
    return {
      type: &amp;quot;exec&amp;quot;,
      id: entity.id,
    };
  },
  undo(entry) {
    updateUI((state) =&amp;gt; {
      state[entry.payload.id].isArchived = true;
    });

    return {
      id: entry.payload.id,
      type: &amp;quot;undo&amp;quot;,
    };
  },
  redo(entry) {
    updateUI((state) =&amp;gt; {
      state[entry.payload.id].isArchived = false;
    });
    return {
      id: entry.payload.id,
      type: &amp;quot;undo&amp;quot;,
    };
  },

  syncToBackend(entry) {
    if (entry.type === &amp;quot;exec&amp;quot;) {
      // Nothing to do here because we already created the entity
    }

    if (entry.type === &amp;quot;undo&amp;quot;) {
      fetch(&amp;quot;/api/markArchived&amp;quot;, {
        method: &amp;quot;POST&amp;quot;,
        body: JSON.stringify({
          id: entry.payload.id,
        }),
      });
    }
  },
});

function dispatch(command, params) {
  const payload = command.exec(params);
  const transaction = createTransaction(command, payload);
  syncQueue.push(transaction);
  undoStack.push(transaction);
}

function undo() {
  const txn = undoStack.pop();
  if (txn) {
    txn.command.undo(txn);
    // Create a new transaction after the undo
    const nextTxn = createTransaction(txn.command, txn.payload);
    syncQueue.push(nextTxn);
    redoStack.push(nextTxn);
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Dynamic Redos, a.k.a Undoing an undo&lt;/h2&gt;
&lt;p&gt;The command-based approach nudges you to define your &lt;code&gt;exec&lt;/code&gt; and &lt;code&gt;undo&lt;/code&gt; functions upfront. This intuitively makes sense and can work, but it’s predicated on the fact that the undoable state has not changed since the time that the undo was performed, which may not be the case for multi-player apps. Trying to define both an &lt;code&gt;undo&lt;/code&gt; and a &lt;code&gt;redo&lt;/code&gt; upfront may mean that by the time you perform a &lt;code&gt;redo&lt;/code&gt;, you’re using outdated information.&lt;/p&gt;
&lt;p&gt;Illustrated using the patches idea, the inverse of an undo is a redo so we could define a redo as:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;const myCommand = {
  exec(state) {
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) =&amp;gt; {
        state.value = &amp;quot;foo&amp;quot;;
      },
    );

    return { patches, inversePatches };
  },
  undo(executeTxn) {
    // We apply the inverse patches from the `exec` transaction and return
    // _new_ patches to be used later for redo
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) =&amp;gt; {
        applyPatches(state, executeTxn.inversePatches);
      },
    );

    return { patches, inversePatches };
  },
  redo(undoTxn) {
    // Now we are undoing and undo with the inverse patches produced by the
    // `undo` operation
    const [state, patches, inversePatches] = produceWithPatches(
      currentState,
      (state) =&amp;gt; {
        applyPatches(state, executeTxn.inversePatches);
      },
    );

    return { patches, inversePatches };
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Things start to get a little mind bending here. If you’re not dealing with multi-player, then this is probably not worth the extra mental gymnastics. If you are dealing with multi-player, you should probably be using an existing framework.&lt;/p&gt;
&lt;h2&gt;Side effects&lt;/h2&gt;
&lt;p&gt;Another thing that may come up is the need to perform ad-hoc side effects on the UI when an undo or redo occurs. For example, you may want to refocus an &lt;code&gt;input&lt;/code&gt; element after an undo occurs.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;const myCommand = {
  params: {
    id: &amp;quot;xxx&amp;quot;,
    previous: &amp;quot;foo&amp;quot;,
    next: &amp;quot;bar&amp;quot;,
    focusId: &amp;quot;yyy&amp;quot;,
  },
  exec() {
    state[params.id].value === params.next;
  },
  undo() {
    state[params.id].value === params.previous;
    document.getElementById(params.focusId)?.focus();
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Performing imperative UI logic may or may not feel icky to you, but this may be enough. The issue you may run into is dealing with library-specific paradigms, like React’s &lt;code&gt;useEffect&lt;/code&gt;. UI side effects like these belong in a &lt;code&gt;useEffect&lt;/code&gt;, so you could take a queue from &lt;a href=&quot;https://github.com/davidkpiano/useEffectReducer&quot;&gt;useEffectReducer&lt;/a&gt; and package up effects into the state:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;const myCommand = {
  params: {
    id: &amp;quot;xxx&amp;quot;,
    previous: &amp;quot;foo&amp;quot;,
    next: &amp;quot;bar&amp;quot;,
    focusId: &amp;quot;yyy&amp;quot;,
  },
  exec() {
    state[params.id].value === params.next;
  },
  undo(createEffect) {
    state[params.id].value === params.previous;

    createEffect(() =&amp;gt; {
      document.getElementById(params.focusId)?.focus();
    });
  },
};

function undo() {
  const txn = undoStack.pop();
  if (txn) {
    const effects = [];
    const createEffect = (effect) =&amp;gt; effects.push(effect);
    const entry = txn.command.undo(createEffect);

    // push the effects needed to run
    state.effects = effects;
  }
}

function App() {
  const effects = useEffects();

  // Now run all of the effects created in the last transaction;
  useEffect(() =&amp;gt; {
    // TODO: Cancellation!
    effects.forEach((effect) =&amp;gt; {
      effect();
    });
  }, [effects]);
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Another challenging aspect of side effects is that it starts to tie your undo implementation to your UI. In the above example, focusing an input element after an undo assumes that the input element is visible at the time that the undo occurs. This can easily get hard to track or out-of-sync.&lt;/p&gt;
&lt;h2&gt;Altering the past, a.k.a. Mind the GURQ&lt;/h2&gt;
&lt;p&gt;One way to think about performing an undo is that you’re going backwards in time. If you then make an edit at that point in time, you’re &lt;em&gt;changing&lt;/em&gt; the past. Trying to perform a redo at that point in time would be redoing an event against a different timeline and no longer makes sense.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/command-based-undo/branching-undo.png#diagram&quot; alt=&quot;A visualization of a &amp;quot;branching&amp;quot; undo pattern. A blue square points backwards to a pink square and says &amp;quot;undo&amp;quot;. The pink square points to a green square and then an orange square. The green square is annotated as a &amp;quot;history change&amp;quot;. The squares are arranged to resemble tree branches. The pink and green squares are annotated as being contained in the &amp;quot;undo stack&amp;quot;.&quot;&gt;&lt;/p&gt;
&lt;p&gt;When thinking about it this way, the only sensible thing to do with the redo stack is to clear it. You’d be redoing operations done on a past version of the state.&lt;/p&gt;
&lt;p&gt;There is another way to think about undo, which is to think about it always going &lt;em&gt;forward&lt;/em&gt;. An undo operation is a forward action that happens to be the inverse of a previous action. If you think about the history as linear and always moving backwards and forwards, then it makes sense that you should always be able to go back to a previous version of what you were looking at, even if you got there via an undo or redo.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/command-based-undo/non-branching-undo.png#diagram&quot; alt=&quot;A visualization of &amp;quot;non-branching&amp;quot; undo. A pink square points to a blue square, then a pink square, then a green square, and then an orange square. The squares are arranged in a single row. Below that, the same squares are arranged with red dots indicating the path that was followed to reach the orange square.&quot;&gt;&lt;/p&gt;
&lt;p&gt;The &amp;quot;trick&amp;quot; as prescribed by the &lt;a href=&quot;https://github.com/zaboople/klonk/blob/master/TheGURQ.md&quot;&gt;GURQ&lt;/a&gt; here is to replay the redo stack at the time of the history change back on to the undo stack &lt;em&gt;twice&lt;/em&gt;: once forwards and once inverted. How this inversion happens depends on the undo implementation. For a real-life example of this, check out emacs.&lt;/p&gt;
&lt;h2&gt;Takeaways&lt;/h2&gt;
&lt;p&gt;I consider undo/redo to be one of the harder things to implement, or more specifically, one of the harder things to implement &lt;em&gt;well&lt;/em&gt;. I put together an example utilizing some of these techniques in this repository: https://github.com/npbee/undo-redo-playground with a working demo located &lt;a href=&quot;https://undo-redo-playground.pages.dev/&quot;&gt;here&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;References&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;https://www.placemark.io/post/how-placemark-implements-undo-redo-to-make-map-making-safe-and-chill&lt;/li&gt;
&lt;li&gt;https://medium.com/@mweststrate/distributing-state-changes-using-snapshots-patches-and-actions-part-1-2811a2fcd65f&lt;/li&gt;
&lt;li&gt;https://github.com/zaboople/klonk/blob/master/TheGURQ.md&lt;/li&gt;
&lt;li&gt;https://www.figma.com/blog/how-figmas-multiplayer-technology-works/&lt;/li&gt;
&lt;li&gt;https://liveblocks.io/blog/how-to-build-undo-redo-in-a-multiplayer-environment&lt;/li&gt;
&lt;li&gt;https://www.youtube.com/watch?v=WxK11RsLqp4&lt;/li&gt;
&lt;li&gt;https://www.youtube.com/watch?v=Wo2m3jaJixU&lt;/li&gt;
&lt;li&gt;https://twitter.com/steveruizok/status/1566142910546038784&lt;/li&gt;
&lt;li&gt;https://maxliani.wordpress.com/2021/09/01/undo-the-art-of-part-1/&lt;/li&gt;
&lt;/ul&gt;
</content:encoded></item><item><title>Testing an API endpoint with Deno</title><link>https://npbee.me/posts/testing-an-api-endpoint-with-deno/</link><guid isPermaLink="true">https://npbee.me/posts/testing-an-api-endpoint-with-deno/</guid><description>A method for testing an HTTP endpoint using Deno without testing implementation details.</description><pubDate>Sun, 08 Oct 2023 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;a href=&quot;https://deno.com/&quot;&gt;Deno&lt;/a&gt; has become one of my favorite tools for web development. It’s refreshing to have all of the essential features readily available without needing to reach for third-party libraries. Recently, I’ve been working on an API-first version of &lt;a href=&quot;https://waveformr.com/&quot;&gt;Waveformr&lt;/a&gt; and landed on a way to test the endpoints that I’d like to share.&lt;/p&gt;
&lt;h2&gt;The endpoint&lt;/h2&gt;
&lt;p&gt;For the purposes of this article, I’m going to set up a basic HTTP &lt;code&gt;GET&lt;/code&gt; endpoint using Deno and &lt;a href=&quot;https://hono.dev/&quot;&gt;Hono&lt;/a&gt;. But note, Deno and Hono here are implementation details. I’m only using them because they are easy to set up, but the tests won’t care what we’re using to implement the endpoint.&lt;/p&gt;
&lt;p&gt;The endpoint implementation will look like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;import { Hono } from &amp;quot;https://deno.land/x/hono/mod.ts&amp;quot;;

const app = new Hono();

// The &amp;quot;database&amp;quot;
const books = new Map();

// Post a book with a name to create it
app.post(&amp;quot;/book&amp;quot;, async (c) =&amp;gt; {
  const body = await c.req.json&amp;lt;{ name: string }&amp;gt;();
  const { name } = body;
  const book = {
    id: crypto.randomUUID(),
    name,
  };

  books.set(book.id, book);
  return c.json({ status: &amp;quot;ok&amp;quot;, id: book.id });
});

// Look up a book by id
app.get(&amp;quot;/book/:id&amp;quot;, (c) =&amp;gt; {
  const book = books.get(c.req.param(&amp;quot;id&amp;quot;));
  if (book) {
    return c.json({ status: &amp;quot;ok&amp;quot;, book });
  } else {
    return c.json({ status: &amp;quot;error&amp;quot;, message: &amp;quot;not found&amp;quot; }, 404);
  }
});

export function run() {
  return Deno.serve(app.fetch);
}

// Run this immediately if this is the entrypoint to the program
// Useful for testing because we can import this file and run it
// with a function call when we&apos;re ready
if (import.meta.main) {
  run();
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;The test&lt;/h2&gt;
&lt;p&gt;The test code looks like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-typescript&quot;&gt;import { assert } from &amp;quot;https://deno.land/std@0.202.0/assert/assert.ts&amp;quot;;
import { run } from &amp;quot;./main.ts&amp;quot;;
import { assertEquals } from &amp;quot;https://deno.land/std@0.202.0/assert/mod.ts&amp;quot;;

const PORT = 8000;
const url = (path: string) =&amp;gt; new URL(`http://localhost:${PORT}/${path}`);

Deno.test(&amp;quot;POST a new book&amp;quot;, async (t) =&amp;gt; {
  // Pass an `AbortController` so that we can abort the server when we&apos;re done
  const controller = new AbortController();
  run({
    port: PORT,
    signal: controller.signal,
  });

  const resp = await fetch(url(&amp;quot;book&amp;quot;), {
    method: &amp;quot;POST&amp;quot;,
    body: JSON.stringify({
      name: &amp;quot;The Great Gatsby&amp;quot;,
    }),
  });

  assertEquals(resp.status, 200);

  const { id, status } = await resp.json();
  assertEquals(status, &amp;quot;ok&amp;quot;);
  assert(typeof id === &amp;quot;string&amp;quot;);

  const newBookResp = await fetch(url(`book/${id}`));
  assertEquals(newBookResp.status, 200);
  const newBookJson = await newBookResp.json();
  assertEquals(newBookJson.book.name, &amp;quot;The Great Gatsby&amp;quot;);

  controller.abort();
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Running the tests will give an output that looks a bit like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-sh&quot;&gt;Check file:///Users/nickball/code/deno-endpoint-testing/main_test.ts
running 1 test from ./main_test.ts
POST a new book ...
------- output -------
Listening on http://localhost:8000/
----- output end -----
POST a new book ... ok (8ms)

ok | 1 passed | 0 failed (26ms)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;What I like about this method is that we’re hitting the endpoint like a real user would and using standard Web APIs. Deno has this all built in, so it feels very natural. One note here is that we’re passing an &lt;code&gt;AbortController&lt;/code&gt; into the server so that we can manually kill the server after we’re done testing it.&lt;/p&gt;
&lt;p&gt;That’s it!&lt;/p&gt;
</content:encoded></item><item><title>Double overflow with CSS grid</title><link>https://npbee.me/posts/css-grid-double-overflow/</link><guid isPermaLink="true">https://npbee.me/posts/css-grid-double-overflow/</guid><description>A deceptively tricky layout</description><pubDate>Sun, 02 Oct 2022 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Here&apos;s a deceptively tricky layout I encountered at work recently:&lt;/p&gt;
&lt;p&gt;&amp;lt;img alt=&amp;quot;Sketch of layout&amp;quot; src=&amp;quot;/posts/css-grid-double-overflow-sketch.svg#diagram&amp;quot; /&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;h3&amp;gt;It has:&amp;lt;/h3&amp;gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Flex and grid layouts combined&lt;/li&gt;
&lt;li&gt;Multiple overflow containers&lt;/li&gt;
&lt;li&gt;Set and variable width columns&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Here&apos;s how I solved it!&lt;/p&gt;
&lt;p&gt;&amp;lt;div&amp;gt;
&amp;lt;p class=&amp;quot;codepen&amp;quot; data-height=&amp;quot;700&amp;quot; data-default-tab=&amp;quot;css,result&amp;quot; data-slug-hash=&amp;quot;ExLLRaQ&amp;quot; data-user=&amp;quot;npbee&amp;quot; style=&amp;quot;height: 600px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;&amp;quot;&amp;gt;
&amp;lt;span&amp;gt;See the Pen &amp;lt;a href=&amp;quot;https://codepen.io/npbee/pen/ExLLRaQ&amp;quot;&amp;gt;
Double Overflowing Columns with CSS Grid&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&amp;quot;https://codepen.io/npbee&amp;quot;&amp;gt;@npbee&amp;lt;/a&amp;gt;)
on &amp;lt;a href=&amp;quot;https://codepen.io&amp;quot;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/span&amp;gt;
&amp;lt;/p&amp;gt;
&amp;lt;script async src=&amp;quot;https://cpwebassets.codepen.io/assets/embed/ei.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
</content:encoded></item><item><title>Challenges of a Local-first App</title><link>https://npbee.me/posts/local-first-challenges/</link><guid isPermaLink="true">https://npbee.me/posts/local-first-challenges/</guid><description>Blurring the lines of client and server</description><pubDate>Sat, 16 Jul 2022 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;Recently I&apos;ve been getting excited about &lt;a href=&quot;https://www.inkandswitch.com/local-first/&quot;&gt;local-first&lt;/a&gt; applications so I thought I would try my hand at building one.
The app will be a personal songwriting tool for organizing, versioning, and making notes on in-progress songs. Sort of a personal Soundcloud app of sorts.
I think I&apos;ve finally settled on a decent architecture, but the process has forced me to rethink some of my go-to patterns that I use to build on cloud-based software.&lt;/p&gt;
&lt;h2&gt;Am I the Client or the Server?&lt;/h2&gt;
&lt;p&gt;In my normal day-to-day work I&apos;m almost always writing code for the &lt;em&gt;client&lt;/em&gt;.
You want data? Make an HTTP request from the &lt;em&gt;server&lt;/em&gt; to get it.
You need a file? Make an HTTP request from the &lt;em&gt;server&lt;/em&gt;.
In a local-first app those boundaries aren&apos;t as clear.
I can write a SQL query right next to my React component!&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-tsx&quot;&gt;function SomeComponent({ db, id }) {

  async function updateName(name) {
    await db.execute(`
      UPDATE songs
      SET name = ?
      WHERE id = ?
    `,
    [name, id]
  }

  return (
    &amp;lt;input
      onChange={evt =&amp;gt; updateName(evt.target.value)}
    /&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;h2&gt;Storage? Also Syncing. And undo/redo. Oh also searching?&lt;/h2&gt;
&lt;p&gt;So far I&apos;ve found it challenging to get all of these features out of the box.
Like anything in software, the architecture needs to be based on the needs of the application.
One of the best parts about local-first apps is that your data is truly local.
But that also means that if you &lt;em&gt;want&lt;/em&gt; that data to be available elsewhere (like on a phone perhaps), then you have to figure out how to sync the data.
Additionally, if you want multiple people to interact with that data you need to think about merging and conflict resolution.
Tying in undo/redo into syncing and conflict resolution makes all of that a &lt;em&gt;hard&lt;/em&gt; application to build.&lt;/p&gt;
&lt;p&gt;The rage right now for local-first apps is &lt;a href=&quot;https://crdt.tech/&quot;&gt;CRDTs&lt;/a&gt;.
I&apos;m still wrapping my head around it, but I understand enough to know that I don&apos;t want to build this myself.
There are a couple of libraries out there that do this like &lt;a href=&quot;https://automerge.org/&quot;&gt;Automerge&lt;/a&gt; and &lt;a href=&quot;https://yjs.dev/&quot;&gt;Y.js&lt;/a&gt;.
Y.js in particular seems pretty darn good as it has syncing and undo/redo out of the box.&lt;/p&gt;
&lt;p&gt;The last challenge that relates here is searching.
For a local-first app, it feels strange to &lt;em&gt;not&lt;/em&gt; choose SQLite since it can easily and efficiently search and query.
Using a CRDT library feels like it forces data into a document-based storage format which conflicts a little with how one might typically structure a SQLite database.&lt;/p&gt;
&lt;p&gt;Can you have a CRDT data structure that supports undo/redo and store that in SQLite?
Probably, but I haven&apos;t figured it out yet.&lt;/p&gt;
</content:encoded></item><item><title>In Search of Mocks</title><link>https://npbee.me/posts/in-search-of-mocks/</link><guid isPermaLink="true">https://npbee.me/posts/in-search-of-mocks/</guid><description>A journey through various data mocking techniques for testing React apps (and GraphQL)</description><pubDate>Mon, 15 Jun 2020 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;An obsession of mine lately has been figuring out a good way for my teammates and I test React components that rely on server requests.
Specifically, I&apos;m looking for ways to:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Setup a test with the &lt;em&gt;least&lt;/em&gt; amount of ceremony possible. Less ceremony means less friction for choosing to write a test or not.&lt;/li&gt;
&lt;li&gt;When doing that setup, be able to only specify specifically which pieces of data I need for that test and nothing more so it&apos;s clear what&apos;s important for the test.&lt;/li&gt;
&lt;li&gt;Assert what was sent to the server during my test. In some cases, this is the only way to really verify that something worked as expected.&lt;/li&gt;
&lt;li&gt;Easily mock one-off errors in tests.&lt;/li&gt;
&lt;li&gt;Have a good base of mocks with realistic data that can be overridden per test as needed&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;We&apos;re full in on the testing philosophies of [React Testing Library](We&apos;ve already gone full ahead with the
) and &lt;a href=&quot;https://kentcdodds.com&quot;&gt;Kent C. Dodds&lt;/a&gt;, but how far do you take it?&lt;/p&gt;
&lt;p&gt;This will be a brain dump of some of my learnings along the way for my specific scenarios, so I don&apos;t expect it to apply to everyone but I wanted to write it down anyways.
Some things I&apos;ll be talking about:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Mocking abstraction layers&lt;/strong&gt; - At which layer do you apply the mock?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mocked &lt;em&gt;data&lt;/em&gt; vs. mocked _responses__&lt;/strong&gt; - What&apos;s the difference?&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mocking your entire backend in tests &lt;em&gt;and&lt;/em&gt; the browser&lt;/strong&gt; - E.g. &lt;a href=&quot;https://mswjs.io/&quot;&gt;MSW&lt;/a&gt; or &lt;a href=&quot;https://miragejs.com/&quot;&gt;MirageJS&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;At the end of the day, I&apos;ve concluded that a tool like &lt;a href=&quot;https://miragejs.com/&quot;&gt;MirageJS&lt;/a&gt; or &lt;a href=&quot;https://mswjs.io/&quot;&gt;Mock Service Worker&lt;/a&gt;, plus some sort of in-memory database really capture everything I need.&lt;/p&gt;
&lt;h2&gt;Mocking Layers&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;See: &lt;a href=&quot;https://kentcdodds.com/blog/stop-mocking-fetch&quot;&gt;Stop Mocking Fetch&lt;/a&gt; by Kent C. Dodds.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;As I mentioned above, I very much subscribe to the &lt;a href=&quot;https://kentcdodds.com/&quot;&gt;Kent C. Dodds&lt;/a&gt; method of testing React components.
Specifically, I like to test as few implementation details as possible and minimize mocking so that I can have high confidence that things are working and easily swap out implementation details.
In my position at work, we&apos;re constantly rebuilding and trying new experiments, so it&apos;s important to me to be able to write tests that will survive those changes.
I&apos;m generally less concerned with what &amp;quot;kind&amp;quot; of test I&apos;m writing (unit, integration, etc.).&lt;/p&gt;
&lt;p&gt;So knowing that, my first point of research was around figuring out which point to start mocking out server responses.
And at this point I&apos;ve (again) agreed with Kent that mocking at the &lt;em&gt;network&lt;/em&gt; layer is the way to go.
Kent&apos;s article above lays out a lot of this really well, but here&apos;s my own take.&lt;/p&gt;
&lt;p&gt;Let&apos;s use this code for all of the examples:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;function CreateLabel(props) {
  let { api } = props;
  let [value, setValue] = React.useState(&amp;quot;&amp;quot;);
  let [msg, setMsg] = React.useState(&amp;quot;&amp;quot;);

  function handleSubmit(evt) {
    evt.preventDefault();

    // Simplified for the sake of the example
    api
      .post(&amp;quot;/label&amp;quot;, {
        data: value,
      })
      .then(id =&amp;gt; {
        setMsg(`Success! Created label with id ${id}`);
      }, err =&amp;gt; {
        setMsg(&amp;quot;Error!&amp;quot;)
      }));
  }

  return (
    &amp;lt;div&amp;gt;
      {msg}
      &amp;lt;form onSubmit={handleSubmit}&amp;gt;
        &amp;lt;label htmlForm=&amp;quot;label&amp;quot;&amp;gt;Label&amp;lt;/label&amp;gt;
        &amp;lt;input
          id=&amp;quot;label&amp;quot;
          value={value}
          onChange={evt =&amp;gt; setValue(evt.target.value)}
        /&amp;gt;
        &amp;lt;button type=&amp;quot;submit&amp;quot;&amp;gt;Submit&amp;lt;/button&amp;gt;
      &amp;lt;/form&amp;gt;
    &amp;lt;/div&amp;gt;
  );
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A pseudo-component that shows an input and a submit button, posts to a theoretical API on submit, and then prints a message to the screen.
And we&apos;ll that the theoretical API looks like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;export let api = {
  post(url, config) {
    // Does some manipulation and then calls out to `fetch`
    return fetch(url, config);
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There are different points at which we could mock out the network call for this component.
I see them roughly like this:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Dependency Injection&lt;/strong&gt; - Test injects a mock &lt;code&gt;api&lt;/code&gt; value. Network client is never hit&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mocked Client&lt;/strong&gt; - Test mocks the network client. Environment call is never hit (&lt;code&gt;fetch&lt;/code&gt; or &lt;code&gt;xhr&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Mocked Environment&lt;/strong&gt; - Test mocks at the environment level. Client is hit but the real &lt;code&gt;fetch&lt;/code&gt; is never called&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Network Intercept&lt;/strong&gt; - Test intercepts actual network requests and allows for custom response. Real &lt;code&gt;fetch&lt;/code&gt; is called and the test asserts on custom responses. (Example: Nock, MSW, Mirage)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Network Intercept + Mocked data layer&lt;/strong&gt; - Test intercepts network requests, but requests are handled with actual logic mimicking production code and write to an in-memory database. Tests assert on the database. (Example: Mirage JS)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/mock-layer.png#diagram&quot; alt=&quot;Mocking layer&quot;&gt;&lt;/p&gt;
&lt;h3&gt;Dependency Injection / Mocking &lt;code&gt;fetch&lt;/code&gt;&lt;/h3&gt;
&lt;p&gt;For a long time I really only considered two ways of mocking this component: Dependency injection or mocking the client.
Dependency injection would look like this:&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;I&apos;m using &lt;a href=&quot;https://testing-library.com/docs/react-testing-library&quot;&gt;React Testing Library&lt;/a&gt; here.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {
  // In a test
  let mockApi = {
    post: jest.fn(() =&amp;gt; Promise.resolve(123)),
  };
  render(&amp;lt;CreateLabel api={mockApi} /&amp;gt;);

  // Type a value into the input, then submit
  type(screen.getByLabelText(&amp;quot;Label&amp;quot;), &amp;quot;Home&amp;quot;));
  click(screen.getByRole(&apos;button&apos;, { name: &amp;quot;Submit&amp;quot; });

  // Assert we called our mocked API
  await waitFor(() =&amp;gt; expect(mockApi.post).toHaveBeenCalledTimes(1));

  // Assert we called our mocked API _with_ the value we typed
  expect(mockApi.post).toHaveBeenCalledWith(&amp;quot;/label&amp;quot;, { data: &amp;quot;Home&amp;quot; });

  // Assert that we used the value returned from our API and printed it to the screen
  expect(screen.queryByText(&amp;quot;Success! Created label with id 123&amp;quot;)).toBeInTheDocument()
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;We&apos;re passing in a mocked API so that we can make a direct assertion on what was called.
This is kind of nice because everything is in one spot and there aren&apos;t many abstraction layers, so things are easy to follow.&lt;/p&gt;
&lt;p&gt;However, as stated in Kent&apos;s article above, this strategy has some downsides as well:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It doesn&apos;t exercise the logic in the &lt;code&gt;api&lt;/code&gt; at all. A separate test is needed for that.&lt;/li&gt;
&lt;li&gt;It ties your API implementation details to your component. In your test, you have to know that your component calls &lt;code&gt;api.post&lt;/code&gt;. If you later change this logic, you&apos;ll have to update your test.&lt;/li&gt;
&lt;li&gt;Further on the last point, your response from your mock API is hard-coded. If you later change your API response to return an object like &lt;code&gt;{ id: 1}&lt;/code&gt;, you&apos;ll have to update your test.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A closely related strategy to this is mocking one level up at the &lt;code&gt;fetch&lt;/code&gt; level.
That might look like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {
  fetch.mockImplementationOnce(() =&amp;gt; Promise.resolve(123))

  render(&amp;lt;CreateLabel /&amp;gt;);

  // Type a value into the input, then submit
  type(screen.getByLabelText(&amp;quot;Label&amp;quot;), &amp;quot;Home&amp;quot;));
  click(screen.getByRole(&apos;button&apos;, { name: &amp;quot;Submit&amp;quot; });

  // Assert we called our mocked API
  await waitFor(() =&amp;gt; expect(fetch).toHaveBeenCalledTimes(1));

  // Assert we called our mocked API _with_ the value we typed
  expect(fetch).toHaveBeenCalledWith(&amp;quot;/label&amp;quot;, { data: &amp;quot;Home&amp;quot; });

  // Assert that we used the value returned from our API and printed it to the screen
  expect(screen.queryByText(&amp;quot;Success! Created label with id 123&amp;quot;)).toBeInTheDocument()
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is better than dependency injection because we&apos;re now excercising our &lt;code&gt;api&lt;/code&gt; logic and removing some implementation details in our test.
But, we still have the issue of hard-coding the response from the API &lt;em&gt;and&lt;/em&gt; we can also see another implementation detail: &lt;code&gt;fetch&lt;/code&gt;!
The fact that we&apos;re mocking &lt;code&gt;fetch&lt;/code&gt; means that we&apos;re not actually testing that we&apos;re calling &lt;code&gt;fetch&lt;/code&gt; with the correct arguments.&lt;/p&gt;
&lt;p&gt;To move further up the mocking layer, let&apos;s talk about some other things first.&lt;/p&gt;
&lt;h2&gt;Mocked Responses vs. Mocked Data&lt;/h2&gt;
&lt;p&gt;So let&apos;s say you&apos;re convinced that mocking at the &lt;code&gt;environment&lt;/code&gt; isn&apos;t the best solution.
The next layer for mocking would be to call the APIs in the environment that make network calls, but intercept those calls so they don&apos;t actually hit the network.
This is where something like &lt;a href=&quot;https://mswjs.io/&quot;&gt;&lt;code&gt;msw&lt;/code&gt;&lt;/a&gt; comes in:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;import { rest } from &apos;msw&apos;;
import { server } from &apos;./test/server&apos;;

test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {

  // Tell our &amp;quot;server&amp;quot; to intercept POST requests to `/label` and respond
  // with this specific response
  server.use(
    rest.post(&apos;/label&apos;, (req, res, ctx) =&amp;gt; res(ctx.text(123)))
  )

  render(&amp;lt;CreateLabel /&amp;gt;);

  // Type a value into the input, then submit
  type(screen.getByLabelText(&amp;quot;Label&amp;quot;), &amp;quot;Home&amp;quot;));
  click(screen.getByRole(&apos;button&apos;, { name: &amp;quot;Submit&amp;quot; });

  // Assert that we used the value returned from our API and printed it to the screen
  expect(screen.queryByText(&amp;quot;Success! Created label with id 123&amp;quot;)).toBeInTheDocument()
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is interesting because there&apos;s no mocking of &lt;code&gt;fetch&lt;/code&gt; anywhere.
We could theoretically switch our entire client layer to use &lt;code&gt;xhr&lt;/code&gt; if we wanted and this test would still pass.&lt;/p&gt;
&lt;p&gt;You may have noticed that we&apos;re no longer asserting what we called our API with.
We could still do that here by making the response a mocked function.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;import { rest } from &apos;msw&apos;;
import { server } from &apos;./test/server&apos;;

test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {

  // Tell our &amp;quot;server&amp;quot; to intercept POST requests to `/label` and respond
  // with this specific response

  // Use a mock function that we can assert on later
  let handler = jest.fn((req, res, ctx) =&amp;gt; res(ctx.text(123)))

  server.use(rest.post(&apos;/label&apos;, handler))

  render(&amp;lt;CreateLabel /&amp;gt;);

  // Type a value into the input, then submit
  type(screen.getByLabelText(&amp;quot;Label&amp;quot;), &amp;quot;Home&amp;quot;));
  click(screen.getByRole(&apos;button&apos;, { name: &amp;quot;Submit&amp;quot; });

  // Assert we called our mocked API
  await waitFor(() =&amp;gt; expect(handler).toHaveBeenCalledTimes(1));

  // Assert things about the last call. This will be a bit cumbersome because
  // it&apos;s the full request. Likely could create a helper like:
  expect(getLastRequestBody(handler)).toHaveBeenCalledWith({
    data: &amp;quot;Home&amp;quot;
  })

  // Assert that we used the value returned from our API and printed it to the screen
  expect(screen.queryByText(&amp;quot;Success! Created label with id 123&amp;quot;)).toBeInTheDocument()
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This is pretty good!
But, there are still a few short-comings with this:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The test is still coupled to the network API details through the URL of the request. If we want to change the endpoint this component hits, we&apos;ll have to update our test. This could be a perfectly fine trade-off depending on your needs.&lt;/li&gt;
&lt;li&gt;We&apos;re still hard-coding the response payload in the test. If we have other tests that hit this endpoint, we&apos;d be hard-coding that data there as well. If the payload changes, we&apos;d need to update all places that use it.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Another interesting short-coming is that as things get more complicated in your app, you essentially have to implicitly implement your backend logic through your mocks.
Here&apos;s an example of what I mean:&lt;/p&gt;
&lt;p&gt;Say that our example above actually makes &lt;em&gt;two&lt;/em&gt; network calls: One that posts to create the label, and then another that refetches all labels to get the latest data:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;function CreateLabel(props) {
  /* ... */

  function handleSubmit(evt) {
    evt.preventDefault();

    // This is simplified for the sake of the example
    api
      .post(&amp;quot;/label&amp;quot;, {
        data: value,
      })
      .then(id =&amp;gt; {
        setMsg(`Success! Created label with id ${id}`);

        // Refetch all labels so we have the latest data
        return refetchAllLabels()
      }, err =&amp;gt; {
        setMsg(&amp;quot;Error!&amp;quot;)
      }));
  }

  /* ... */
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Assuming we want to assert something about that refetching in our tests, we have to set that up in our mocks;&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;import { rest } from &amp;quot;msw&amp;quot;;
import { server } from &amp;quot;./test/server&amp;quot;;

test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {
  // Tell our &amp;quot;server&amp;quot; to intercept POST requests to `/label` and respond
  // with this specific response

  // Use a mock function that we can assert on later
  let handler = jest.fn((req, res, ctx) =&amp;gt; res(ctx.text(123)));

  server.use(
    rest.post(&amp;quot;/label&amp;quot;, handler),

    // Intercept this request too and ensure we&apos;re returning the same data
    // that our mocked post handler did
    rest.get(&amp;quot;/labels&amp;quot;, (req, res, ctx) =&amp;gt; res(ctx.data([123])))
  );

  render(&amp;lt;CreateLabel /&amp;gt;);

  // ...
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;We have to intercept two requests now and line up each response so that they return related data, so in a sense we&apos;re doing what our backend would be doing with these requests.
You could say that this is unnecessary to do because the tests don&apos;t &lt;em&gt;really&lt;/em&gt; care that the same data exists in both responses, they just care that your response is what you said it would be.
This is fair, but in my opinion I think it also dilutes the readability of the test.
I think it&apos;s helpful to see in my test that, yes, this the endpoint returns the data that was created in this other endpoint because they are related and that&apos;s how the real thing works.
By encoding this information into mocks, you have this info spread through all of your tests.&lt;/p&gt;
&lt;p&gt;So let&apos;s go one step further...&lt;/p&gt;
&lt;h2&gt;Mocking Your Entire Backend&lt;/h2&gt;
&lt;p&gt;Instead of mocking individual requests, we can actual mock the &lt;em&gt;handlers&lt;/em&gt; of those requests and write to a mocked in-memory database.
The difference here is subtle, but interesting.
It&apos;s mostly easily demonstrated in the udpated test:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-jsx&quot;&gt;import { rest } from &apos;msw&apos;;
import { server, db } from &apos;./test/server&apos;;

test(&amp;quot;CreateLabel can create a label&amp;quot;, async () =&amp;gt; {
  render(&amp;lt;CreateLabel /&amp;gt;);

  // Type a value into the input, then submit
  type(screen.getByLabelText(&amp;quot;Label&amp;quot;), &amp;quot;Home&amp;quot;));
  click(screen.getByRole(&apos;button&apos;, { name: &amp;quot;Submit&amp;quot; });

  // Assert we called our mocked API
  await waitFor(() =&amp;gt; expect(db.getLabels()).toHaveLength(1))

  let label = db.getLabels()[0]

  expect(label.title).toBe(&apos;Home&apos;)

  // Assert that we used the value returned from our API and printed it to the screen
  expect(screen.queryByText(`Success! Created label with id ${label.id}`)).toBeInTheDocument()
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;A couple of interesting things to point out:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;We don&apos;t mock each individual response, so the test is a lot shorter.&lt;/li&gt;
&lt;li&gt;We don&apos;t assert the arguments of the request, we &lt;em&gt;assert&lt;/em&gt; the result of the database.&lt;/li&gt;
&lt;li&gt;We&apos;re asserting &lt;em&gt;less&lt;/em&gt; about our implementation details. This may feel uncomfortable.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;If you&apos;ve ever written or peered into a backend test, it probably looks a lot like this.
You set up some things for the tests, perform an action, and then assert on the database.
The fact that our frontend test does this same thing is nice because I think it helps solidify the mental model of what&apos;s actually happening.&lt;/p&gt;
&lt;p&gt;Setting this up with &lt;code&gt;msw&lt;/code&gt; would depend on how you&apos;re making requests.
In my case, I&apos;m typically using GraphQL so I&apos;ll show that as an example.
GraphQL is especially interesting because there&apos;s really only one endpoint and all of the logic is in the resolvers.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// test/server.js
import { rest } from &apos;msw&apos;;
import { setupServer } from &apos;msw/node&apos;;
import schema from &apos;./my-schema.graphql&apos;;

let db = /* ... */

let root = {
  createPost(args, { db }) {
    let { title } = args;

    // Make a new &apos;post&apos; in our database
    let newPost = db.create(&apos;post&apos;, { title })
    return newPost;
  },
  posts(_args, { db }) {
    // Return all of the posts in our db
    return db.get(&apos;post&apos;);
  }
}

export let server = setupServer(
  rest.post(&apos;/api/graphql&apos;, async (req, res, ctx) =&amp;gt; {
    // Get the query and variables from the body
    let { query, variables } = req.body;
    let context = { db };

    // Make a real query against our schema!
    let response = await graphql(schema, query, root, context, variables);

    return res(ctx.delay(500), ctx.status(200), ctx.json(response));
  })
)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As for the &amp;quot;database&amp;quot;, it can be just about as simple or complicated as you want.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;let data = {
  post: {},
};

export let db = {
  create(model, attrs) {
    let id = makeId();

    let thing = {
      id,
      ...attrs,
    };

    data[model][id] = thing;

    return thing;
  },
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Positives of this type of test are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;All of your &apos;backend&apos; mocking logic lives in one spot. It can be updated here and all tests will get the udpates.&lt;/li&gt;
&lt;li&gt;It removes &lt;em&gt;all&lt;/em&gt; implementation details from your test. Not even which endpoints you are calling are part of the test.&lt;/li&gt;
&lt;li&gt;It&apos;s (in theory) very close to how the real system works&lt;/li&gt;
&lt;li&gt;In the case of GraphQL, it&apos;s making a real query against your real schema. It can catch if you are returning responses that don&apos;t match the schema, which ensures your test data always resembles production.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Downsides are:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;There&apos;s a lot more abstraction. It&apos;s now harder to see in your test everything that&apos;s in your component under test&lt;/li&gt;
&lt;li&gt;More test logic in the request handlers. The test is actually asserting on the test database logic, which can have its own bugs.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;All together, this pattern essentially does what &lt;a href=&quot;https://miragejs.com/&quot;&gt;MirageJS&lt;/a&gt; does but I wanted to show that it can be done with msw as well.
The interesting thing about both of these tools, is that you can use both of them in the browser as well!
So you now have a way to develop new features against real data using the same production-like data you use in your tests.&lt;/p&gt;
&lt;h2&gt;Slippery Slope&lt;/h2&gt;
&lt;p&gt;One argument I&apos;m primed to take on with my co-workers is that this is essentially rebuilding our backend on the frontend.
In this simple example, the resolvers are easy, but in a real app things are complicated.
There are relationships between models and service calls to be made, etc.
That&apos;s all true and I think a trade off to be made for each team.
But at the end of the day, I think if you think of it as a development tool first, it will always be helpful.
The point is not to faithfully recreate exactly what your backend is doing, but to give an approximation of it and to have all of the logic in one place.
Remember, it&apos;s only a slight extension of doing this at the request level.
And ultimately, being able to hop down to mock out the request level should be the escape hatch.
If you have a test that&apos;s asserting on a complicated backend response, write a one-off request mock.
Use your shared database for mocks that are easy and can be reused across tests.
Writing my tests like a backend test with a database feels very strange at first, but I&apos;ve found that it actually solidifies my understading of features &lt;em&gt;more&lt;/em&gt;.&lt;/p&gt;
&lt;h2&gt;Wrap Up&lt;/h2&gt;
&lt;p&gt;I&apos;m still exploring all of this, but so far I&apos;m pretty happy with this setup.
It ticks all of my boxes and feels like the right trade offs have been made...for now.
To sum up my current ideal setup, I&apos;ve created a repo: &lt;a href=&quot;https://github.com/npbee/msw-jest-graphql&quot;&gt;https://github.com/npbee/msw-jest-graphql&lt;/a&gt;.&lt;/p&gt;
</content:encoded></item><item><title>Sentry for Single-Page Apps</title><link>https://npbee.me/posts/sentry-for-single-page-apps/</link><guid isPermaLink="true">https://npbee.me/posts/sentry-for-single-page-apps/</guid><description>Effectively using Sentry for single-page, JavaScript apps</description><pubDate>Sun, 16 Feb 2020 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;&lt;a href=&quot;https://sentry.io&quot;&gt;Sentry&lt;/a&gt; is an error-monitoring service that helps log, track, and resolve runtime issues in your applications.
I&apos;ve used it for quite a while to manage errors in front-end apps that I&apos;ve built and I thought I&apos;d run through some tips and tricks that I&apos;ve found to help make Sentry most useful.
We&apos;ll start with some basics and then increase the level of integration, ending with a fully automated Sentry setup with GitHub actions, source maps, and Sentry releases.&lt;/p&gt;
&lt;p&gt;You can check an &lt;a href=&quot;https://github.com/npbee/sentry-releases-example&quot;&gt;example repo&lt;/a&gt; with working examples.&lt;/p&gt;
&lt;h2&gt;What You&apos;ll Need&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A Sentry account and project&lt;/li&gt;
&lt;li&gt;A Sentry &lt;a href=&quot;https://docs.sentry.io/workflow/integrations/integration-platform/#internal-integrations&quot;&gt;Internal Integration&lt;/a&gt; set up with &lt;code&gt;project:read&lt;/code&gt; and &lt;code&gt;releases&lt;/code&gt; permissions.&lt;/li&gt;
&lt;li&gt;A continuous integration tool like Netlify or GitHub Actions&lt;/li&gt;
&lt;li&gt;The &lt;a href=&quot;https://github.com/getsentry/sentry-cli&quot;&gt;&lt;code&gt;sentry-cli&lt;/code&gt;&lt;/a&gt; package&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;EXAMPLE REPO:&lt;/p&gt;
&lt;h2&gt;The Basics&lt;/h2&gt;
&lt;p&gt;Assuming you have an account with Sentry and a project setup, the basics to get up and running with Sentry is to use the browser SDK to initialize it as soon as possible in your app:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;import * as Sentry from &amp;quot;@sentry/browser&amp;quot;;

Sentry.init({
  dsn: /* your DSN */
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You can think of the &apos;DSN&apos; as the client key for your particular project.
This value is how Sentry ties errors in your runtime to a particular project in the Sentry dashboard.
Even with this basic setup you can get some good information about runtime errors.
Sentry does a good just wrangling stack traces across browsers to give you as much information as possible without much setup.
But, if you&apos;re using any sort of build process where your final asset output is not the same as your original source, you&apos;ll have a hard time diagnosing the rrors reports in Sentry.&lt;/p&gt;
&lt;p&gt;&amp;lt;p class=&amp;quot;full-bleed&amp;quot;&amp;gt;
&amp;lt;img alt=&amp;quot;Sentry error without source maps&amp;quot; src=&amp;quot;/posts/sentry-no-sourcemaps.png&amp;quot; /&amp;gt;
&amp;lt;/p&amp;gt;&lt;/p&gt;
&lt;p&gt;To be able to show the original location of the error from your &lt;em&gt;source&lt;/em&gt; files, Sentry needs to access to the source maps of the application.
Before we get to sourcemaps, though, we need to talk about Sentry releases.&lt;/p&gt;
&lt;h2&gt;Releases&lt;/h2&gt;
&lt;p&gt;A &lt;em&gt;release&lt;/em&gt; in Sentry is a particular build of your app.
It&apos;s how Sentry associates errors to distinct releases of your app.
Typically, any time you build your single-page app you&apos;ll create a new release.
Every release must have a distinct &lt;em&gt;version&lt;/em&gt; or identifier so that it can be differentiated from other releases.
This identifier is up to you to create, but typically it will likely be the Git hash of the commit your building, or perhaps the &lt;code&gt;version&lt;/code&gt; from the &lt;code&gt;package.json&lt;/code&gt;.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;import * as Sentry from &amp;quot;@sentry/browser&amp;quot;;

Sentry.init({
  dsn: /* your DSN */,
  release: /* your release */
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Since you won&apos;t want to manually type out your &lt;code&gt;dsn&lt;/code&gt; or &lt;code&gt;release&lt;/code&gt; value each time, you&apos;ll want to set those up as environment variables that can be read at build time when you&apos;re application is being assembled for release.
The way you include these variables will change depending your toolchain, but most popular bundlers include ways to do this.
For Webpack, you can use the &lt;code&gt;DefinePlugin&lt;/code&gt; plugin to make these values available at build time:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;new webpack.DefinePlugin({
  SENTRY_DSN: /* However you&apos;re including your DSN */,
  SENTRY_RELEASE: /* read from git hash or package.json */,
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;For my example, I&apos;m going to use &lt;a href=&quot;https://parceljs.org/&quot;&gt;Parcel&lt;/a&gt; because it&apos;s a bit simpler for smaller apps, but the concept is the same.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;import * as Sentry from &amp;quot;@sentry/browser&amp;quot;;

Sentry.init({
  release: `releases-example@${process.env.npm_package_version}`,
  dsn: /* the dsn */
});
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Here I&apos;m using the special &lt;code&gt;process.env.npm_package_version&lt;/code&gt; value that Parcel makes available by default.
It will replace the value with the &lt;code&gt;version&lt;/code&gt; value from my &lt;code&gt;package.json&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;By including the release version in the SDK setup, Sentry will now show this as a &apos;release&apos; and start to associate errors to it:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/sentry-release.png&quot; alt=&quot;Sentry releases panel&quot;&gt;&lt;/p&gt;
&lt;p&gt;Ok, back to source maps.&lt;/p&gt;
&lt;h2&gt;Source Maps&lt;/h2&gt;
&lt;p&gt;In order to show the original source location for errors, Sentry needs to be able find the source maps for your app.
There are two ways to do that: public source maps or direct upload.
Public source maps means that Sentry will try to infer the public URL of your source map for the file related to the error, and the fetch that file and use it for the source mapping.
Using public source maps is the simplest because it requires the least amount of work on your end and in fact I&apos;ve run apps perfectly fine this way without many issues.
However, public source maps can be brittle and have multiple opportunities for something to go wrong, leaving you without source maps for your error logs.
Sentry recommends uploading source maps directly and I think it&apos;s a good idea as well.
Making the source map upload an explicit part of your build step ensures that you&apos;ll always have source maps for your error logs &lt;em&gt;before&lt;/em&gt; you deploy your app.&lt;/p&gt;
&lt;h3&gt;Building &amp;amp; Uploading Source Maps&lt;/h3&gt;
&lt;p&gt;Building source maps is another common setting for popular bundlers, and is enabled by default for Parcel.
Running &lt;code&gt;parcel build&lt;/code&gt; will automatically create source maps.&lt;/p&gt;
&lt;p&gt;The recommended way to upload source maps is to use the &lt;code&gt;@sentry/cli&lt;/code&gt; package.
In order to properly associate the source maps with the correct release, we have to use the &lt;code&gt;version&lt;/code&gt; identifier we created earlier.&lt;/p&gt;
&lt;h2&gt;Continuous Integration&lt;/h2&gt;
&lt;p&gt;Now let&apos;s take what we know and start setting up the commands needed to automate the Sentry workflow we have so far.
Assuming you have some way of running commands for a particular commit or build, we can set up a &lt;code&gt;build&lt;/code&gt; command that does what we need so far.
In general, the workflow will be:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Create a &apos;release&apos; in Sentry&lt;/li&gt;
&lt;li&gt;Build our assets, using the release version from step 1&lt;/li&gt;
&lt;li&gt;Upload the source maps created from step 2, again using the release version&lt;/li&gt;
&lt;li&gt;Finalize the release in Sentry&lt;/li&gt;
&lt;li&gt;Deploy the app&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;To make all of this happen, we also need at least the following environment variables available:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;SENTRY_ORG=xxx
SENTRY_PROJECT=xxx
SENTRY_AUTH_TOKEN=xxx
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;The way you provide these variables depends on your continuous integration tooling.
For the &lt;code&gt;SENTRY_AUTH_TOKEN&lt;/code&gt;, you&apos;ll need to create an &lt;a href=&quot;https://docs.sentry.io/workflow/integrations/integration-platform/#internal-integrations&quot;&gt;Internal Integration&lt;/a&gt; within Sentry which will provide you with an authorization token for use with the Sentry CLI.&lt;/p&gt;
&lt;p&gt;Here&apos;s an example of how to create the CI command:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// In package.json
{
  &amp;quot;scripts&amp;quot;: {
    &amp;quot;build&amp;quot;: &amp;quot;./scripts/sentry&amp;quot;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;#!/bin/bash

VERSION=$(node scripts/get-version.js)

echo &amp;quot;Building version: $VERSION&amp;quot;

npx sentry-cli releases new $VERSION
npx parcel build src/index.html
npx sentry-cli releases files $VERSION upload-sourcemaps dist --rewrite
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You&apos;ll notice I&apos;ve created a little helper file for getting the correct version:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;console.log(require(&amp;quot;../package.json&amp;quot;).version);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Also notice that I&apos;m using &lt;a href=&quot;https://www.npmjs.com/package/npx&quot;&gt;&lt;code&gt;npx&lt;/code&gt;&lt;/a&gt; to run the Sentry CLI commands.
This makes it easy to install and use the &lt;code&gt;@sentry/cli&lt;/code&gt; package that&apos;s installed locally to your project rather than relying on it being installed globally.&lt;/p&gt;
&lt;p&gt;After build and uploading source maps, we can then &apos;finalize&apos; the release and, if deploying immediately, mark it as deployed:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;# Finalize the release and mark it deployed
npx sentry-cli releases finalize $VERSION
npx sentry-cli releases deploys $VERSION new -e prod
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;You should now be able to run this on your continuous integration tool and automatically create new Sentry releases with source maps.&lt;/p&gt;
&lt;h2&gt;Git Integration&lt;/h2&gt;
&lt;p&gt;There&apos;s more we can do!
Sentry can now tell us which location our errors are coming from in our original source, but with a bit more work Sentry can also tell us which &lt;em&gt;commits&lt;/em&gt; an error came from.
To gain this power, you need to tell Sentry about the commit information associated with each release.
Sentry has integrations built for common providers like GitHub that ease the pain of this, but also provides a finer-grained approach which I&apos;ll go through as well.
For the GitHub example, after authorizing your GitHub account with Sentry, GitHub will begin sending commit data to Sentry.
The step you need to do is tell Sentry which of those commits are associated with the release you&apos;re building.
The Sentry CLI has a command to figure this out for you:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;npx sentry-cli releases set-commits --auto $VERSION
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Best I can tell, this essentially grabs all of the commits between now and the time you last released.
With this in, you&apos;ll start seeing commits associated with your release, as well as &amp;quot;suspect&amp;quot; commits in issues:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/sentry-suspect-commit.png&quot; alt=&quot;Image of a &apos;Suspect commit&apos; in Sentry&quot;&gt;&lt;/p&gt;
&lt;h2&gt;Alt Git Integration&lt;/h2&gt;
&lt;p&gt;The Sentry GitHub integration works well and I&apos;d recommend using it if possible.
However, you may in a situation where you cannot use Sentry&apos;s integration.
For example, if you&apos;re not keen on authorizing Sentry to your GitHub repo.
If that&apos;s the case, you can still tell Sentry about commit information, but you&apos;re responsible for finding the right commits, formatting them, and sending them to Sentry&apos;s API.
I&apos;ve outlined a quick-and-dirty example of how to do that in the &lt;a href=&quot;https://github.com/npbee/sentry-releases-example&quot;&gt;example repo&lt;/a&gt; for this post, but essentially it involes what I listed above:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Fetch the latest release for your project&lt;/li&gt;
&lt;li&gt;From the latest release, find the last commit hash&lt;/li&gt;
&lt;li&gt;Find all of the commits since that commit hash and &lt;code&gt;HEAD&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Format each commit into a &amp;quot;patch set&amp;quot;&lt;/li&gt;
&lt;li&gt;Send all of this info to Sentry&apos;s API when creating the release&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Unfortunately this is not straightforward and involves some parsing of the Git log to get the commits in the exact format Sentry&apos;s expects.&lt;/p&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;Getting fully up and running with Sentry is no easy task, but I think it highly increases the value you can get out of the service.&lt;/p&gt;
</content:encoded></item><item><title>Eleventy + DatoCMS + Netlify</title><link>https://npbee.me/posts/eleventy-datocms-netlify/</link><guid isPermaLink="true">https://npbee.me/posts/eleventy-datocms-netlify/</guid><description>Building a static site with a headless CMS</description><pubDate>Sat, 21 Dec 2019 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;As a web developer I get the occasional ask from friends to help them build a
website. I generally don&apos;t mind and am happy to help out my buddies, but lately
as I&apos;ve been limited on spare time, I&apos;ve been more and more upfront with some requirements:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;I will only build &lt;em&gt;static&lt;/em&gt; sites. I don&apos;t want to be building anyone&apos;s custom
CMS or billing system.&lt;/li&gt;
&lt;li&gt;I will only work with my preferred development workflow: Git / GitHub + Netlify
and continuous deployment. I&apos;d rather not hand off code in a zip file or
configure anyone&apos;s &lt;em&gt;phpMyAdmin&lt;/em&gt; console.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;As long as my friends are OK with my snobby requirements, I&apos;m happy to oblige.
One missing piece from this workflow is the ability for people to update the
content after the site has been deployed. Historically the solution to that
has either been use a CMS like Wordpress or just update the content manually
everytime a change is needed. But recently there&apos;s been a surge of tools that
provide a new option: use a headless CMS. A headless CMS allows for content
owners to update the content in a third-party admin console and for me to
pull in that data at build time so I can continue to use my favorite static-site
tools. One of the new headless CMS options is &lt;a href=&quot;https://datocms.com&quot;&gt;DatoCMS&lt;/a&gt;,
and I recently had a great experience working with it alongside &lt;a href=&quot;https://11ty.io&quot;&gt;Eleventy&lt;/a&gt;,
my current static-site generator of choice. In this post I&apos;ll go through the
setup and experience.&lt;/p&gt;
&lt;p&gt;I&apos;ve set up an example respository here if you&apos;d like to skip to the code:
&lt;a href=&quot;https://github.com/npbee/Eleventy-DatoCMS-Netlify&quot;&gt;Eleventy-DatoCMS-Netlify&lt;/a&gt;.&lt;/p&gt;
&lt;h2&gt;What is a Headless CMS Anyway?&lt;/h2&gt;
&lt;p&gt;First, a quick primer on headless CMS systems. A typical Content Management
System (CMS) loads content from a database and renders that content to a
template of some sort. Updating the content involves logging into an adminstration
console and changing the content. So in this world,
the content, administration, and display logic are all together in one codebase.
A headless CMS on the other hand, separates the content and adminstration of the
content from the view layer. Data is maintained and updated in one system and
the view layer pulls in that data at build time to create the static site. If
you&apos;ve ever built a static site that had local data files of some sort, it&apos;s
just like that except your data files live on a third-party server somewhere.&lt;/p&gt;
&lt;p&gt;There are lots of headless CMS options out there, but for my project I chose
&lt;a href=&quot;https://datocms.com&quot;&gt;DatoCMS&lt;/a&gt;. The interface was simple, pricing was reasonable,
and they have a GraphQL API interface, of which I&apos;m a big fan.&lt;/p&gt;
&lt;h2&gt;The Data Flow&lt;/h2&gt;
&lt;p&gt;Since Netlify is the point at which the updated data is fetched from DatoCMS, a
new site build can happen either when new site code is pushed to GitHub &lt;em&gt;or&lt;/em&gt; when
the content is udpated through the Dato admin interface. In the case of data
updates, Dato tells Netlify that a new build needs to happen. Netlify then
starts the build and asks Dato for the new data.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-1.png&quot; alt=&quot;Image describing data flow between Github, DatoCMS, and Netlify&quot;&gt;&lt;/p&gt;
&lt;h2&gt;Fetching Data from DatoCMS&lt;/h2&gt;
&lt;p&gt;To actually start building a site, we need to be able to get data from DatoCMS.
The example we&apos;ll work with is a restaurant building a menu (which was the
actual original use case).&lt;/p&gt;
&lt;p&gt;Each headless CMS service will have different details, but fundamentally in each
one you describe how your content is structured by telling the service what
kind of data you&apos;re working with and what each of the properties are. In DatoCMS,
these are &amp;quot;models&amp;quot; and &amp;quot;fields&amp;quot; so you may have a model called &amp;quot;Menu Item&amp;quot;
that is made of up of a &amp;quot;name&amp;quot; field that is a string and a &amp;quot;price&amp;quot; field that
is a number.&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-model.png&quot; alt=&quot;DatoCMS Model structure&quot;&gt;&lt;/p&gt;
&lt;p&gt;This configuration ties directly to the GraphQL query that you make to DatoCMS:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-graphql&quot;&gt;query Site {
  allMenuItems {
    name
    price
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;DatoCMS offers an &amp;quot;API Explorer&amp;quot; on the site which allows you to query your
data:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-api-explorer.png&quot; alt=&quot;DatoCMS API Explorer&quot;&gt;&lt;/p&gt;
&lt;p&gt;The API Explorer is great because you can tinker with your query until you get
it just right and then copy the query and paste it into a file in your
codebase. This makes for a really nice workflow where updating the data on the
site is a matter of pasting in a new query to a file.&lt;/p&gt;
&lt;p&gt;Finally, to actually fetch the data we can use a rather plain &lt;code&gt;fetch&lt;/code&gt; call;&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const fetch = require(&amp;quot;node-fetch&amp;quot;);
const path = require(&amp;quot;path&amp;quot;);

// The DatoCMS token available fro the DatoCMS dashboard
// More on this later...
const token = process.env.DATO_API_TOKEN;

async function fetchData(token) {
  // Read the query from the file. A bit nicer to work with once the query
  // gets bigger. You can also copy and paste directly from the Dato API
  // explorer into the file.
  const query = await readFile(path.join(__dirname, &amp;quot;query.graphql&amp;quot;));
  const response = await fetch(&amp;quot;https://graphql.datocms.com/&amp;quot;, {
    method: &amp;quot;POST&amp;quot;,
    headers: {
      &amp;quot;Content-Type&amp;quot;: &amp;quot;application/json&amp;quot;,
      Accept: &amp;quot;application/json&amp;quot;,
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      query: query.toString(),
    }),
  }).then((res) =&amp;gt; {
    if (res.ok) {
      return res.json();
    } else {
      throw new Error(&amp;quot;Aborting: DatoCMS request failed with &amp;quot; + res.status);
    }
  });

  if (response.errors) {
    for (let error of response.errors) {
      console.error(error.message);
    }
    throw new Error(&amp;quot;Aborting: DatoCMS errors&amp;quot;);
  } else {
    return response.data;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;As you can see above, we need a token from DatoCMS in order have the authorization
necessary to query our site. This is secret, so it lives in an environment
variable. For development, that means doing something like setting the
variable with in a &lt;code&gt;.env&lt;/code&gt; file and using something like &lt;a href=&quot;https://github.com/motdotla/dotenv&quot;&gt;&lt;code&gt;dotenv&lt;/code&gt;&lt;/a&gt; to pull in the variables. In production, we&apos;ll have to set the
variable within the Netlify dashboard. More on that soon.&lt;/p&gt;
&lt;h2&gt;Fetching Data with Eleventy&lt;/h2&gt;
&lt;p&gt;Above we showed how to fetch data from DatoCMS using a &lt;code&gt;fetch&lt;/code&gt; call, but how
does that work with Eleventy? The answer is Eleventy&apos;s &lt;a href=&quot;https://www.11ty.dev/docs/data-js/&quot;&gt;JS data files&lt;/a&gt;. With JS data files, you can use JS to do anything you need
to do to get your data, including making a network call. By placing a
file within the special &lt;code&gt;_data&lt;/code&gt; directory, Eleventy will expose whatever you
return to your template files:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// _data/cms.js
module.exports = async function Cms() {
  const token = process.env.DATO_API_TOKEN;
  const cachePath = path.join(__dirname, &amp;quot;cms.cache.json&amp;quot;);
  return await fetchData(token);
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Then in your templates:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;!-- `cms` because that&apos;s what we named the file in the `_data` directory --&amp;gt;
{% for item in cms.allMenuItems %}
&amp;lt;p&amp;gt;
  &amp;lt;strong&amp;gt;Name&amp;lt;/strong&amp;gt; {{ item.name }} &amp;lt;strong&amp;gt;Price&amp;lt;/strong&amp;gt; {{ item.price }}
&amp;lt;/p&amp;gt;
{% endfor %}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;That&apos;s it! We now have an Eleventy site fetching data from DatoCMS and building a
static site.&lt;/p&gt;
&lt;h2&gt;Caching Data&lt;/h2&gt;
&lt;p&gt;The current setup works, but you may see this in your console output:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;Writing _site/index.html from ./index.njk.
Benchmark (Data): `./_data/cms.js` took 581ms (66.0%)
Processed 2 files in 0.82 seconds (v0.9.0)
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Eleventy is noting that it took a noticeable amount of time to to handle our
&lt;code&gt;_data/cms.js&lt;/code&gt; file. We can avoid going over the network each time by writing the DatoCMS response
to a file and using that file if it exists:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;const { promisify } = require(&amp;quot;util&amp;quot;);
const path = require(&amp;quot;path&amp;quot;);
const fs = require(&amp;quot;fs&amp;quot;);

const writeFile = promisify(fs.writeFile);
const readFile = promisify(fs.readFile);

module.exports = async function Cms() {
  const token = process.env.DATO_API_TOKEN;
  const cachePath = path.join(__dirname, &amp;quot;cms.cache.json&amp;quot;);
  const cache = await getCache(cachePath);

  if (cache) {
    console.log(&amp;quot;&amp;gt;&amp;gt; Using cached data&amp;quot;);
    return cache;
  } else {
    console.log(&amp;quot;&amp;gt;&amp;gt; Fetching data from DatoCMS&amp;quot;);
    const data = await fetchData(token);
    await writeFile(cachePath, JSON.stringify(data, null, 2));
    return data;
  }
};

async function getCache(cachePath) {
  try {
    const cache = await readFile(cachePath);
    return JSON.parse(cache);
  } catch (err) {
    // If this fails, that means there is no cache. Return `undefined` to
    // fetch from the network
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Make sure ignore the cache file in the &lt;code&gt;.gitignore&lt;/code&gt; file:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-bash&quot;&gt;# Cached data
_data/cms.cache.json
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This will only fetch fresh data if the &lt;code&gt;_data/cms.cache.json&lt;/code&gt; does not exist.
In development, this is usually preferrable as your developing the site as you
probably don&apos;t need to fetch new data every time. In production, there will
never be any cache so we&apos;ll always fetch fresh data.&lt;/p&gt;
&lt;h2&gt;Deployment&lt;/h2&gt;
&lt;p&gt;Assuming you have Netlify and GitHub integrated, the only missing piece for
being able to deploy our site is telling Netlify what our DatoCMS token is.
This is easily done via the Netlify admin dashboard:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-netlify-token.png&quot; alt=&quot;DatoCMS token in Netlify dashboard&quot;&gt;&lt;/p&gt;
&lt;p&gt;Once that is in place, pushing new code to GitHub will trigger a build in Netlify,
which will fetch fresh data from DatoCMS!&lt;/p&gt;
&lt;h2&gt;Integrating DatoCMS with Netlify&lt;/h2&gt;
&lt;p&gt;Almost done! The only missing piece left is to be able to deploy a new version
of our site whenever the data content changes. To do that, we need to a
&amp;quot;Deployment Environment&amp;quot; in DatoCMS. A deployment environment in Dato is how you
configure DatoCMS to re-build your site based on the services you&apos;re using.
After you&apos;ve set up a deployment environment, you&apos;ll see these notifications
in the top right:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-up-to-date.png&quot; alt=&quot;DatoCMS deployment environment status displaying &amp;quot;Up to date&amp;quot;&quot;&gt;
&lt;img src=&quot;https://npbee.me/posts/dato-out-of-date.png&quot; alt=&quot;DatoCMS deployment environment status displaying &amp;quot;Out of date&amp;quot;&quot;&gt;
&lt;img src=&quot;https://npbee.me/posts/dato-in-progress.png&quot; alt=&quot;DatoCMS deployment environment status displaying &amp;quot;In progress&amp;quot;&quot;&gt;&lt;/p&gt;
&lt;p&gt;DatoCMS has a great integration with Netlify that essentially makes this a one-click
setup. You authorize DatoCMS to your Netlify site, and it will more-or-less
do the rest. That said, I actually had some issues with that because at the
time it seemed that outgoing webhooks were not allowed on the free plan of
Netlify. This meant that I could trigger a build from DatoCMS, but Dato would
never be notified of the status of the build. This looks to not be an issue
anymore so if the integration works for you, then you should use it! Regardless,
I thought it would be interesting to see how to set up a custom deployment
environment using Netlify functions.&lt;/p&gt;
&lt;h3&gt;Custom Deployment Environment with Netlify Functions&lt;/h3&gt;
&lt;p&gt;At the end of the day, communication between services is usually just each
service sending &lt;code&gt;POST&lt;/code&gt; requests to each other. By utilizing Netlify&apos;s &lt;a href=&quot;https://docs.netlify.com/functions/trigger-on-events/&quot;&gt;functions
and event triggers&lt;/a&gt;, we
can set up our own custom deployment environment.&lt;/p&gt;
&lt;p&gt;First, we need to set up a build hook in Netlify:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-build-hook.png&quot; alt=&quot;Netlify build hook&quot;&gt;&lt;/p&gt;
&lt;p&gt;This is the URL that we want DatoCMS to &lt;code&gt;POST&lt;/code&gt; whenever it wants to trigger a
new build.&lt;/p&gt;
&lt;p&gt;Then, within DatoCMS, choose &amp;quot;Custom webhook&amp;quot; to set up the custom deployment
environment:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-custom-webhook.png&quot; alt=&quot;DatoCMS custom webhook&quot;&gt;&lt;/p&gt;
&lt;p&gt;Paste in the build hook from Netlify in the &amp;quot;Trigger URL&amp;quot; input. In the &amp;quot;Status notifications&amp;quot;
section, Dato is displaying the information that we need to send &lt;em&gt;back&lt;/em&gt; to
Dato from Netlify when the builds are complete. This is how Dato knows what
happened from Netlify. We&apos;ll need to create a new environment variable in
Netlify with this info:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/dato-status-url.png&quot; alt=&quot;Netlify status URL environment variable&quot;&gt;&lt;/p&gt;
&lt;p&gt;Lastly, we need to create two new functions: one named &lt;code&gt;deploy-succeeded.js&lt;/code&gt;
and one named &lt;code&gt;deploy-failed.js&lt;/code&gt;. The names are significant as they indicate
to Netlify that these are functions to be triggered when those specific
deploy events happened. In a &lt;code&gt;functions&lt;/code&gt; folder:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;// functions/deploy-succeeded.js
const fetch = require(&amp;quot;node-fetch&amp;quot;);

const { DATO_STATUS_URL } = process.env;

const data = JSON.stringify({ status: &amp;quot;success&amp;quot; });

exports.handler = async function (_event, _context) {
  let response;

  try {
    response = await fetch(DATO_STATUS_URL, {
      method: &amp;quot;POST&amp;quot;,
      headers: {
        &amp;quot;Content-Type&amp;quot;: &amp;quot;application/json&amp;quot;,
      },
      body: data,
    });
  } catch (err) {
    return {
      statusCode: err.statusCode || 500,
      body: JSON.stringify({
        error: err.message,
      }),
    };
  }

  return {
    statusCode: 200,
    body: JSON.stringify({
      data: response,
    }),
  };
};
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;I&apos;ll leave the &lt;code&gt;deploy-failed.js&lt;/code&gt; out, but it&apos;s pretty much the same except
with a different payload.&lt;/p&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;Phew! After typing all of this out, I can definitely see how this type of
setup may seem overly complicated and you may be thinking that you might as
well just deploy a Wordpress site. In my case, I highly value a workflow that
allows me to iterate fast and also minimizes my overall maintenance cost.
Static sites are extremely low maintenance since there are no databases or
servers to deal with.&lt;/p&gt;
&lt;p&gt;I can say that this set up has been running smoothly for months now and my
friends love their new CMS setup. They previously &lt;em&gt;had&lt;/em&gt; a custom Wordpress
site built for them by someone who had since abandoned them, leaving them
with an out-of-date Wordpress deployment and a pretty horrible editing experience.
If you enjoy building static site and want to extend your offering to allow
for dynamic content, I highly recommend giving this setup a try!&lt;/p&gt;
</content:encoded></item><item><title>Rich Text on the Web in 2018</title><link>https://npbee.me/posts/rich-text-2018/</link><guid isPermaLink="true">https://npbee.me/posts/rich-text-2018/</guid><description>Thoughts on building a rich text editor</description><pubDate>Wed, 04 Jul 2018 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;If you&apos;re building a web app that allows users to write free-form text in 2018,
it&apos;s very likely that you&apos;ll come upon the need to present that text with
various formatting options like &lt;strong&gt;bold&lt;/strong&gt; or &lt;em&gt;italic&lt;/em&gt;, so called &lt;a href=&quot;https://techterms.com/definition/richtext&quot;&gt;&lt;em&gt;rich text&lt;/em&gt;&lt;/a&gt;.
In fact, I&apos;d wager to say that it&apos;s almost a requirement to have some kind of
rich text editing interface for any kind of business-user-facing web app because
it&apos;s such a universally needed feature.&lt;/p&gt;
&lt;p&gt;Dealing with rich text on the web is an interesting problem, but it&apos;s interesting
because it&apos;s...well, uninteresting. Users have been inputting rich text for years
in word processors like Microsoft Word, so the interaction details are somewhat known
and established. There&apos;s not much in the way of exciting, modern UX to build here,
so in that sense it&apos;s a little uninteresting. In that same sense, though, it&apos;s also
a &lt;em&gt;win&lt;/em&gt;. Anytime you can build a web experience that users already know how to
use and lets them get stuff done is a good thing in my opinion.&lt;/p&gt;
&lt;p&gt;However, just because it&apos;s fairly established as a UX pattern doesn&apos;t mean it&apos;s
completely solved as an implementation. It&apos;s been my personal mission the last
few weeks to solve this problem for an app we&apos;re building at &lt;a href=&quot;https://www.hellosign.com&quot;&gt;HelloSign&lt;/a&gt;,
so I&apos;ve been deep in the weeds of this topic. During my research I found lots
of good content on the surface-level implementation details, like which libraries
are out there and the various techniques for building a rich text editor component.
But I found it difficult to find information on some of the deeper, more practical
problems that I was facing, like:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;How do I store this in my database?&lt;/li&gt;
&lt;li&gt;How do I handle both the editing &lt;em&gt;and&lt;/em&gt; displaying of the rich text in different contexts? Are those two concepts the same thing?&lt;/li&gt;
&lt;li&gt;What about things like &amp;quot;mentions&amp;quot; that&apos;s not really just text?&lt;/li&gt;
&lt;li&gt;What about security?&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;So I thought I&apos;d write a bit about those particular aspects. This won&apos;t be an
article about the specifics of building a rich text editor, although I may add
one of those next!&lt;/p&gt;
&lt;h2&gt;What is rich text and why is it difficult?&lt;/h2&gt;
&lt;p&gt;Before going further it&apos;s probably best to give some context on what exactly I mean
when referring to rich text. Here&apos;s a quick screen shot of a rich text editor
from &lt;a href=&quot;https://atlaskit.atlassian.com/examples/editor/editor-core/full-page&quot;&gt;Atlassian&apos;s component library&lt;/a&gt;:&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://npbee.me/posts/rich-text.png&quot; alt=&quot;Example of a rich text editor&quot;&gt;&lt;/p&gt;
&lt;p&gt;The way I think about rich text is that it&apos;s plain text with additional structural
and formatting information attached directly to it. I also think of rich text as
having a few different vantage points:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;From the perspective of the user, it&apos;s just text that&apos;s visually displayed with the chosen formatting (we&apos;ll get to things like &amp;quot;mentions&amp;quot; later).&lt;/li&gt;
&lt;li&gt;From the perspective of the browser, it&apos;s HTML. This may seem obvious, but I find it helpful to call it out in order to distinguish this point of view from the next one.&lt;/li&gt;
&lt;li&gt;From the perspective of the developer, it&apos;s data. Ultimately, rich text cannot be represented with just text, so it needs to be represented as some
sort of data structure. This &lt;em&gt;could&lt;/em&gt; also be HTML but it could also be another format, like JSON or markdown. More on that later.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Having these three perspectives helped me work towards a solution that fit my
needs but it also highlights why this problem can be a difficult one to solve. Like most
problems in web development, I found that there was really no one &amp;quot;correct&amp;quot;
solution. Each piece of the solution relied on various aspects of my own
particular needs. Trade offs were made.&lt;/p&gt;
&lt;p&gt;For me, I found a few of the core considerations for the problem to be:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;What kind of content will users be allowed to enter?&lt;/li&gt;
&lt;li&gt;What are all of the rendering contexts that need to be supported?&lt;/li&gt;
&lt;li&gt;How will security be handled?&lt;/li&gt;
&lt;li&gt;What other processes need to interact with the rich text content?&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Continuing to ask these core questions along the way in my research helped me
work towards a reasonable (&lt;em&gt;I hope&lt;/em&gt; 😬) solution.&lt;/p&gt;
&lt;h2&gt;Database storage&lt;/h2&gt;
&lt;p&gt;Before moving forward with much else, I wanted to have an idea of the kinds of
inputs and outputs I&apos;d be dealing with and how I&apos;d store and retrieve those
values from the database. There were a few options that I&apos;d found being used
in the community.&lt;/p&gt;
&lt;h3&gt;HTML&lt;/h3&gt;
&lt;p&gt;Most WYSIWYG (&lt;em&gt;what-you-see-is-what-you-get&lt;/em&gt;) editors of the past worked strictly with
HTML. Meaning, you start with a blob of HTML and you get out a blob of HTML.
An example would be an editor like &lt;a href=&quot;https://www.tinymce.com/&quot;&gt;TinyMCE&lt;/a&gt; or &lt;a href=&quot;https://ckeditor.com/&quot;&gt;CKEditor&lt;/a&gt;.
This makes plenty of sense and existing libraries still do this today. After all,
HTML is the language of the web. It&apos;s a standardized, familiar syntax that&apos;s
easily interoperable with anything that can understand HTML.&lt;/p&gt;
&lt;p&gt;Storing the rich text value as HTML would mean storing a text value like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;p&amp;gt;Open the console to see the &amp;lt;em&amp;gt;html.get&amp;lt;/em&amp;gt; method working.&amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt;&amp;lt;span style=&amp;quot;font-size: 18px;&amp;quot;&amp;gt;HELLO&amp;lt;/span&amp;gt;&amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt;
  &amp;lt;span style=&amp;quot;font-size: 18px;&amp;quot;
    &amp;gt;&amp;lt;a href=&amp;quot;https://google.com&amp;quot;&amp;gt;GOOGLE LINK&amp;lt;/a&amp;gt;&amp;lt;/span
  &amp;gt;
&amp;lt;/p&amp;gt;
&amp;lt;p&amp;gt;&amp;lt;br /&amp;gt;&amp;lt;/p&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;If you&apos;re at all security-minded, storing user-generated HTML probably sets
off some red flags. Anytime you are storing user-generated content with the intent
of rendering that content back out on the screen, you are vulnerable to &lt;a href=&quot;https://www.owasp.org/index.php/Cross-site_Scripting_(XSS)&quot;&gt;XSS&lt;/a&gt; (Cross-site-scripting)
attacks. Technically while any user-generated content is vulnerable to this, I
feel it&apos;s particularly relevant when dealing with rich text stored as HTML because
it&apos;s likely that it will be rendered back out &lt;em&gt;as&lt;/em&gt; HTML (e.g. &lt;code&gt;element.innerHTML = storedHTML&lt;/code&gt;) which is where XSS usually
comes in to play.&lt;/p&gt;
&lt;p&gt;That said, storing HTML is perfectly valid and is still used today. There is a way to handle it that&apos;s
reasonable safe. A general strategy could be to sanitize the generated HTML for XSS concerns
and use a whitelist approached to strip out anything that you deem not appropriate.
There are plenty of libraries that do this (&lt;a href=&quot;https://github.com/cure53/DOMPurify&quot;&gt;DOMPurify&lt;/a&gt; is one).
And note that you usually want to do this on &lt;em&gt;both&lt;/em&gt; inputs and outputs, so sanitize
on the server before saving to the database and before rendering to the screen. This will give you a
reasonably safe implementation, but some security devs may still not love it.
Storing HTML in the database can feel a bit like a ticking time bomb that can blow
up some point way in the future if you forget to follow one of the security steps
when saving or rendering.&lt;/p&gt;
&lt;p&gt;A few interesting points I noticed about using HTML to store rich text values:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;It&apos;s very powerful for styling options&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This can be seen as either a good thing or bad thing. In the example above, to
be able to display a custom font size the &lt;code&gt;font-size&lt;/code&gt; property is added:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;span style=&amp;quot;font-size: 18px&amp;quot;&amp;gt;words&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This gives the client a pretty powerful mechanism for generating the exact
visual representation that it wants without much room for interpretation. This
could be a good thing if you need users to be able to expressive lots of
different visual formatting and you just want to retrieve this value from the
database and drop into an HTML page. However, there could be a case to be made
that it&apos;s &lt;em&gt;too&lt;/em&gt; powerful. The client could generate this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;span style=&amp;quot;font-size: 3000px&amp;quot;&amp;gt;words&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;It&apos;s unlikely clients need the power to render font sizes at 3000 pixels!&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;It&apos;s a more literal representation of the contents&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The HTML generated in the example above is a very literal representation of the
contents. Meaning, it represents text with &lt;em&gt;exactly&lt;/em&gt; a font size of 18 pixels.
If you&apos;re only rendering within the context of web browsers and you want to be able to
stick the generated content on a page and be done with it, this can be a good
option. However I find that in some cases it can be better to leave yourself
with room to evolve your UI. For example, instead of saving a literal font size
value maybe you save something like this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-html&quot;&gt;&amp;lt;span class=&amp;quot;f-1&amp;quot;&amp;gt;words&amp;lt;/span&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In most cases, that&apos;s probably not what you want. Sure you can validate this
on both the client and the server, but it may become difficult to keep up with
all of the different ways HTML can make for some horrible looking web pages.&lt;/p&gt;
&lt;p&gt;Similar to how you might style a regular webpage, you likely don&apos;t style with
exact pixel values but instead style with classes that represent relative values
that you can evolve and change over time. It also could allow you to represent
that text differently for different rendering contexts if you need to. For example,
maybe you&apos;re rendering to a PDF that uses a different font family so the pixel
value needs to be slightly different.&lt;/p&gt;
&lt;p&gt;Exploring the idea of storing my rich text as HTML began to highlight the fact that
there is a difference between storing the literal content of the rich text and
storing a &lt;em&gt;description&lt;/em&gt; of the rich text. For my use case, I wanted pretty tight
control over how my rich text rendered and even had different eventual rendering
targets (more on that later), so I realized that if I were to use HTML I would
essentially be using HTML as a data format. Meaning, I likely wouldn&apos;t allow
just &lt;em&gt;any&lt;/em&gt; HTML to be stored, it would be a controlled subset with a specific
structure that I could potentially render in different ways to different targets.
In fact, there&apos;s a good article by one of the project leads for CKEditor that
describes using HTML as the data format for rich text: &lt;a href=&quot;https://medium.com/content-uneditable/a-standard-for-rich-text-data-4b3a507af552&quot;&gt;A Standard for Rich-Text Data&lt;/a&gt;.&lt;/p&gt;
&lt;h3&gt;Markdown&lt;/h3&gt;
&lt;p&gt;To take a step back from HTML, my first thought for an MVP-like solution to this problem was to support &lt;a href=&quot;https://daringfireball.net/projects/markdown/syntax&quot;&gt;Markdown&lt;/a&gt;.
Markdown is a fairly well-known syntax for doing basic formatting. It&apos;s used on
developer-centric sites like Github and StackOverflow. Markdown is a nice solution
because it avoids a few of the security issues (but not all!) with HTML and doesn&apos;t require any
kind of special client-side components to work with. It&apos;s still plain text when
it&apos;s entered by the user and only turned into HTML when saved to the database or
rendered to the browser. The syntax is small and relatively standardized so it&apos;s
likely there will be plenty of existing libraries to choose from that can take
Markdown and spit out HTML.&lt;/p&gt;
&lt;p&gt;The issue with Markdown is that, by design, only supports a very limited set of
formatting. If you&apos;re just doing bold and italic formatting, then Markdown will
work just fine. If you&apos;re doing anything more complex, like colors or font families,
then vanilla Markdown won&apos;t help you. There are some extensions and &amp;quot;flavors&amp;quot; to
Markdown for extending the syntax, but at that point I think Markdown starts to
lose a little bit of its original value. Markdown is not really meant to do
much more than basic formatting. Anything outside of basic formatting and Markdown
yields to just allowing arbitrary HTML, in which case you&apos;re back to dealing
with all of the points mentioned in the above section.&lt;/p&gt;
&lt;p&gt;I like the idea of Markdown and I think it makes sense if you&apos;re able to stick with
basic formatting.&lt;/p&gt;
&lt;h3&gt;JSON&lt;/h3&gt;
&lt;p&gt;If you&apos;ve decided that you want to store a description of your rich text data to
your database, JSON seems like a natural choice. In fact, many modern rich text
editors represent their contents not with HTML but with a custom data structure
that can be easily serialized to JSON. QuillJS has a &lt;a href=&quot;https://quilljs.com/docs/delta/&quot;&gt;Delta&lt;/a&gt;
format, ProseMirror has a &lt;a href=&quot;https://prosemirror.net/docs/ref/#model.Document_Structure&quot;&gt;Document&lt;/a&gt;,
and DraftJS has its own &lt;a href=&quot;https://draftjs.org/docs/api-reference-editor-state.html&quot;&gt;EditorState&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;Based on what we&apos;ve discussed so far, here are some good things about storing rich
text as JSON:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It&apos;s more secure against XSS by default. You can&apos;t just pass a string of JSON
and render it as HTML.&lt;/li&gt;
&lt;li&gt;It can represent any kind of content and formatting you might need&lt;/li&gt;
&lt;li&gt;It can be easily parsed, validated, and manipluated by almost any system&lt;/li&gt;
&lt;li&gt;It&apos;s a description of the content, so it can be rendered differently to different targets&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Those good things also come with some downsides:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;No standardization. There is no &lt;em&gt;one&lt;/em&gt; JSON format for rich text. Each library
implements their own version which can lead to lock-in&lt;/li&gt;
&lt;li&gt;More code. Because you can&apos;t just render JSON to HTML, that means you need to
write code that knows how to do that.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;JSON can be a good option for any reasonably complex rich text editor needs if you&apos;re
willing to write more code. A way of dealing with library and JSON format
lock-in is to make sure you a strategy for migrating and making changes over time.
Using a &lt;a href=&quot;http://json-schema.org/&quot;&gt;JSON Schema&lt;/a&gt; definition with a version number
is a good way to do that.&lt;/p&gt;
&lt;p&gt;There are also explorations into standard-ish formats for representing rich text.
&lt;a href=&quot;https://github.com/bustle/mobiledoc-kit&quot;&gt;Mobiledoc&lt;/a&gt; and &lt;a href=&quot;https://github.com/portabletext/portabletext&quot;&gt;Portable Text&lt;/a&gt; are two that I&apos;ve seen in this area.&lt;/p&gt;
&lt;h2&gt;Rendering outside of the editor&lt;/h2&gt;
&lt;p&gt;Another interesting consideration when thinking about rich text is where you&apos;re
going to need to render that rich text. In some cases, you only need it in the
context of an editor. Something like Dropbox Paper or Google docs is an example.
You only ever pull that rich text up in the editor so you can be free to optimize
for that rendering target. But in some cases you have both the editing context
&lt;em&gt;and&lt;/em&gt; the rendering context. For example, you may be editing rich text in the
admin section of a blog, saving it to the database, and then rendering it back
out on a completely separate page. In those cases, you need a way to render that
rich text to the screen directly from the database. HTML has an advantage here
because it can just be rendered directly. JSON must be encoded to HTML somehow
first. Some solutions to this require that a read-only instance of a rich text
editor be loaded up to render the custom JSON format. I&apos;ve found most rich text
libraries to be pretty heavy so in my opinion this is not ideal. However, a
JSON format that is simple enough can be fairly easily encoded into HTML without
the need for the entire editor library. This also can help negate some of the
security issues with rendering user-generated content. A controlled &amp;quot;renderer&amp;quot;
will only render the things it knows about and likely will be rendering actual
user content as text, not HTML.&lt;/p&gt;
&lt;h2&gt;Summary&lt;/h2&gt;
&lt;p&gt;There&apos;s probably a lot more I could say about rich text.
I found it to be a deep, challenging, and, at times, overwhelming topic for a seemingly universal need for most web apps.
For my own use, I ended up going with &lt;a href=&quot;https://prosemirror.net/&quot;&gt;ProseMirror&lt;/a&gt; but it&apos;s not without its own tradeoffs.&lt;/p&gt;
&lt;h2&gt;Thanks&lt;/h2&gt;
&lt;p&gt;Big thanks to Atlassian for their open-source code in &lt;a href=&quot;https://atlaskit.atlassian.com/&quot;&gt;AtlasKit&lt;/a&gt; which was a great help in seeing how a real-world rich text eidtor could be built.&lt;/p&gt;
</content:encoded></item><item><title>Learning Elixir</title><link>https://npbee.me/posts/learning-elixir/</link><guid isPermaLink="true">https://npbee.me/posts/learning-elixir/</guid><description>Some thoughts on learning the Elixir language.</description><pubDate>Sun, 20 Aug 2017 00:00:00 GMT</pubDate><content:encoded>&lt;blockquote&gt;
&lt;p&gt;This is a post in a series of posts about learning back-end topics as a front-end developer.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Along with learning full-stack topics recently, I&apos;ve also been learning &lt;a href=&quot;https://elixir-lang.org/&quot;&gt;Elixir&lt;/a&gt;. I&apos;ll be honest, I&apos;m not sure I would have been so interested in learning about back-end things if it weren&apos;t for the added bonus of getting to use Elixir to do so. I&apos;ve always had an interest in functional programming and other functional languages. I typically write JavaScript in a functional fashion and I&apos;ve toyed with other specifically functional languages like Elm, Clojure, and even Haskell. In the little time that I&apos;ve spent venturing outside the comfortable world of JavaScript, I&apos;ve found that learning other languages can unlock patterns and paradigms that I may not have otherwise grasped. Even though these patterns may not be directly usable in JavaScript, they can still give perspective and sometimes even make the patterns that &lt;em&gt;do&lt;/em&gt; exist more understandable. It feels a little like &amp;quot;leveling up.&amp;quot;&lt;/p&gt;
&lt;h2&gt;First Impressions&lt;/h2&gt;
&lt;p&gt;Overall: fantastic. A few specific things that I enjoyed immediately:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Documentation&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Docs are a first-class concept in Elixir and it shows. Packages can easily build docs from code and they all follow a &lt;a href=&quot;https://hexdocs.pm/elixir/Kernel.html&quot;&gt;similar&lt;/a&gt; design layout. This makes browsing documentation familiar regardless of the package. And bonus, the documentation works in the REPL!&lt;/p&gt;
&lt;p&gt;&lt;img src=&quot;https://s3-us-west-2.amazonaws.com/npbee/2017/learning-elixir/iex-docs.png&quot; alt=&quot;iex docs&quot;&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Testing&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This is another first-class topic that has built-in support in Elixir. I&apos;ve found testing to be simple and intuitive for most cases.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Mix&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Mix is the build tool for Elixir that allows you to run tasks, compile, fetch dependencies, etc. As a front-end developer, it&apos;s similar to &lt;code&gt;npm&lt;/code&gt; so it quickly made sense.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Community&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;I&apos;ve found the community to be very friendly and inclusive. I even submitted a &lt;a href=&quot;https://github.com/elixir-lang/elixir/pull/6310&quot;&gt;pull request&lt;/a&gt; to the language!&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Functional Goodness&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;And of course, I love that it&apos;s a functional language. Writing in a functional style is one thing, but writing functional code in a functional language is another. Being able to write lots of concise functions and combine them into a larger applications is my preferred way to write applications and Elixir seems to be designed just for that.&lt;/p&gt;
&lt;p&gt;And &lt;a href=&quot;https://elixir-lang.org/getting-started/pattern-matching.html&quot;&gt;pattern matching&lt;/a&gt; is 😍.&lt;/p&gt;
&lt;h2&gt;Second Impressions&lt;/h2&gt;
&lt;p&gt;Overall: still great. A few things that I started to struggle with:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Composing Functions&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;One thing that I love about writing functional code is composing functions together. By that I mean:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;// In pseudo-javascript
const add1 = (x) =&amp;gt; x + 1;
const times2 = (x) =&amp;gt; x * 2;
const math = compose(add1, times2);

math(2);
//=&amp;gt; 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;But surprisingly, this way of composing functions is not really used much that I&apos;ve seen. The Elixir way of doing this might instead use the &lt;a href=&quot;https://elixir-lang.org/getting-started/enumerables-and-streams.html#the-pipe-operator&quot;&gt;pipe operator&lt;/a&gt;.&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-elixir&quot;&gt;defmodule Math do
	def add1(x) do
	  x + 1
	end

	def times(x) do
	  x * 2
	end

	def math(x) do
	  x
	  |&amp;gt; times2
	  |&amp;gt; add1
	end
end

Math.math(2)
#=&amp;gt; 5
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;While everything you can do with compose can be accomplished by just defining functions, I do miss the &lt;code&gt;compose&lt;/code&gt; function. The pipe operator is great, though!&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pragmatism&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;The pragmatic approach to the language is something that I&apos;ve seen referred to a number of times. Pragmatism may have a different meaning to other people, but for me it mostly just means it can help you get things done. Elixir is a functional language, but it&apos;s not &lt;em&gt;pure&lt;/em&gt; functional language. That means you can do things like perform side effects in functions. While I generally try my darnedest to &lt;em&gt;not&lt;/em&gt; rely on side effects, I will say that it&apos;s nice to be use them on occasion. Writing completely side-effect free code takes diligence from an entire team and I can understand how that may be a hinderance to small teams trying to push out features. Overall I&apos;ve found Elixir to have a nice balance of strictness and pragmatism that&apos;s resulted in some really maintainable code.&lt;/p&gt;
&lt;h2&gt;Similarities / Differences&lt;/h2&gt;
&lt;p&gt;As I&apos;ve gone through learning Elixir and implementing various features, I&apos;ve started to notice how things &lt;em&gt;somewhat&lt;/em&gt; relate to familiar front-end concepts for me. Most of these comparisons are definitely not one-to-one, but I think they have helped me solidify a few things in my mind.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Elixir Compiler ~ Babel&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Elixir is a compiled language, so that means before you can do anything with it, you have to transform it into something else. In the case of Elixir, your source code is compiled into Erlang. In the case of most modern JavaScript, your source code is compiled into...well, different JavaScript. Elixir is compiling into a completely different language whereas JavaScript is just compiling into a different version of itself. It might be an even closer comparison if you happen to be using experimental JavaScript syntax, like maybe the &lt;a href=&quot;https://github.com/tc39/proposal-pipeline-operator&quot;&gt;pipe operator&lt;/a&gt;. In that case, you&apos;re using syntax that &lt;em&gt;must&lt;/em&gt; be transformed into code that the browser can understand, so you&apos;re essentially writing a different language.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Pattern Matching ~ Destructuring&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This comparison is a bit of a stretch, but I can&apos;t help but note the syntactical similarities. In Elixir, you can use pattern matching to do something like:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-elixir&quot;&gt;# pattern matching
%{a: a, b: b} = %{a: 1, b: 2}
#=&amp;gt; a == 1
#=&amp;gt; b == 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;In JavaScript, you could do:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;// Destructuring
const { a, b } = { a: 1, b: 2 };
//=&amp;gt; a === 1
//=&amp;gt; b === 2
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;These two things are definitely &lt;em&gt;not&lt;/em&gt; the same, but somehow I think learning about restructuring first gave me a head start on pattern matching. The downside is that it can be a little sad when you try to write an Elixir pattern match in JavaScript and realize you can&apos;t!&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;OTP ~ Redux&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://elixirschool.com/en/lessons/advanced/otp-concurrency/&quot;&gt;OTP&lt;/a&gt; is one of the core principles of Elixir and Erlang. I can&apos;t say that I&apos;ve mastered it yet, but I can almost see similarities with &lt;a href=&quot;http://redux.js.org/&quot;&gt;Redux&lt;/a&gt;. When you use a &lt;a href=&quot;https://elixir-lang.org/getting-started/mix-otp/genserver.html&quot;&gt;GenServer&lt;/a&gt; in Elixir, there&apos;s this idea of functions that handle specific calls by receiving the state, doing something with it, and returning a new state:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-elixir&quot;&gt;defmodule SimpleGenServer do
  use GenServer

  ### ...

  def handle_call({:add, value}, _from, state) do
    {:reply, value, state + 1}
  end

  ### ...
end
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;This could be seen as a type of reducer from Redux:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-js&quot;&gt;function reducer(state, action) {
  switch (action.type) {
    case &amp;quot;ADD&amp;quot;:
      return state + 1;
    default:
      return state;
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Of course, OTP is much more robust.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Macros ~ Babel Transforms?&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;&lt;a href=&quot;https://elixir-lang.org/getting-started/meta/macros.html&quot;&gt;Macros&lt;/a&gt; are the sort of thing that can really break your brain the first time you try to learn about them. Using macros, you can write code that &lt;em&gt;writes&lt;/em&gt; code. Because Elixir is compiled, it allows you to hook into that compilation step and use it to your advantage to write things like custom syntax or help with code reuse. In JavaScript land, Babel transforms could be potentially thought of as macros. For example, &lt;a href=&quot;https://facebook.github.io/react/docs/jsx-in-depth.html&quot;&gt;JSX&lt;/a&gt; turns this:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;&amp;lt;div&amp;gt;hello&amp;lt;/div&amp;gt;
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;...into this when Babel compiles it:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-javascript&quot;&gt;React.createElement(&amp;quot;div&amp;quot;, {}, &amp;quot;hello&amp;quot;);
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;There&apos;s nothing stopping you from writing the compiled version, but using the Babel transform can make things clearer or faster to write (if you&apos;re into JSX).&lt;/p&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;I&apos;ve really enjoyed learning Elixir and I&apos;m excited to keep going with it. Besides JavaScript, it&apos;s the only other language I&apos;ve really taken a deep dive on and I think it&apos;s been a great second language to learn. Topics like macros and concurrency are challenging in any language, but I think learning them with Elixir has been very approachable.&lt;/p&gt;
</content:encoded></item><item><title>On Becoming Full Stack</title><link>https://npbee.me/posts/on-full-stack/</link><guid isPermaLink="true">https://npbee.me/posts/on-full-stack/</guid><description>Taking on new roles as a front-end engineer</description><pubDate>Sat, 19 Aug 2017 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;In the past few months I&apos;ve had the chance to work on features that required back-end work. While the features may have been typical tasks for a back-end developer, they were new territory for me. As a front-end developer, I&apos;ve generally been able to get pretty far only knowing the minimal amount of back-end subjects to get my front-end work done. As I mention below, I think there is some merit in being blissfully ignorant in some areas so that you can focus more on your specialty areas. But, I also think this approach can lead to knowledge gaps, which has definitely been the case for me. Black holes of web development topics that I &lt;em&gt;sort of&lt;/em&gt; understand, but not quite enough to explain. Getting out of my comfort zone has allowed me to explore those unknown areas and remove some amount of &amp;quot;magic&amp;quot; from my understanding.&lt;/p&gt;
&lt;h2&gt;Background&lt;/h2&gt;
&lt;p&gt;To give some context, I have had &lt;em&gt;some&lt;/em&gt; experience touching back-end areas, but this experience was limited to basic CRUD operations using Ruby and PHP. I do think this experience contributed in some way to my overall understanding, but not in a significant way. I might say up until a few months ago, I understood things like:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The basics of HTTP and communication between the front-end and back-end (e.g. &lt;code&gt;GET&lt;/code&gt;, &lt;code&gt;POST&lt;/code&gt;, etc.)&lt;/li&gt;
&lt;li&gt;Primitive database knowledge. I knew that there were tables of &amp;quot;things&amp;quot; that may have columns that point to other tables of other things.&lt;/li&gt;
&lt;li&gt;The gist of authorization and authentication. I understood as much as I needed to about session cookies and authentication to get by as a front-end developer.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;Specialist Vs. Generalist&lt;/h2&gt;
&lt;p&gt;I&apos;ve always considered myself more of a specialist than a generalist. I enjoy going deep on topics and really trying to become an expert on them. I&apos;m of the opinion that there are just too many topics to cover in web development to ever really &lt;em&gt;know&lt;/em&gt; all of them. Being a &amp;quot;full-stack&amp;quot; engineer was never something I aspired to because I felt like I&apos;d be overwhelmed trying to become an expert in too many topics. My experience working with full-stack engineers has been that most are closer to back-end engineers than front-end engineers. I also feel that a specialist may be a better career choice in the long-term, though I don&apos;t have any actual data to back that up.&lt;/p&gt;
&lt;p&gt;Despite my tendency towards being a specialist, I still love learning things and find it hard to turn down opportunities to do so. I&apos;ve found that learning opportunities that come up at my job are especially beneficial because they have &lt;em&gt;true&lt;/em&gt; business use cases. It&apos;s not a todo list tutorial, but something that might bring real value to the business. Not that todo list tutorials don&apos;t have their place, but the real-life context of learning things on the job adds an amount of motivation they may otherwise be hard to muster on your own.&lt;/p&gt;
&lt;h2&gt;Conclusion&lt;/h2&gt;
&lt;p&gt;I&apos;ve dubbed 2017 as &amp;quot;the year of learning back end&amp;quot; for me and I&apos;ve had a great experience so far. While I don&apos;t see myself transitioning to a full on back-end developer anytime soon, I think that becoming a better overall developer can absolutely help me become a better front-end developer. Who knows? Maybe I&apos;ll transition to a seemingly-rare full-stack engineer that leans towards the front-end instead of the back-end. I often look at web development as a big puzzle where I&apos;m just learning how different pieces fit together. These new back-end bits are just a few of those stubborn, oddly-shaped pieces that help me see the whole picture a little bit better.&lt;/p&gt;
</content:encoded></item><item><title>UX Case Study: Google Inbox</title><link>https://npbee.me/posts/ux-case-study-google-inbox/</link><guid isPermaLink="true">https://npbee.me/posts/ux-case-study-google-inbox/</guid><description>A hard look at one of my favorite interaction patterns</description><pubDate>Sat, 27 Feb 2016 00:00:00 GMT</pubDate><content:encoded>&lt;p&gt;At work we’ve been in the process of building a queue-like component for helping our admins deal with various tasks. As fans of Google Inbox we decided to use it as a reference for many of our UX decisions. It was for this reason that I started down the long and treacherous path of trying to figure out exactly how Google Inbox works. I spent more time than I care to admit wading through compressed and mangle code, so I thought I share the small bits that I learned along the way.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Disclaimer: I’m sure there are things that I’ve misunderstood or missed, so please don’t take each explanation as the complete truth.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;The Setup&lt;/h2&gt;
&lt;p&gt;First, I just want to do a quick run-through of the kind of environment we’re dealing with here. Unfortunately, there is no “one weird trick” to emulate what I saw. It’s a complex choreography of time, CSS keyframes, and a bunch of Javascript.&lt;/p&gt;
&lt;p&gt;Like any old site, when you first load the page you’ll get a base payload of CSS and Javascript to get things started. The magic comes when you actually open a message. When this occurs, a new &lt;code&gt;style&lt;/code&gt; tag is injected into the page. This &lt;code&gt;style&lt;/code&gt; tag has the very specific responsibility of animating each messages on screen to its next position. The exact rules that are supplied will change depending various other bits of information: which message is being open or closed, the dimensions of each message, how many other messages are on the screen, etc. And practically as soon as the &lt;code&gt;style&lt;/code&gt; tag is injected, it’s gone.&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;Style Injection&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/style_injection.gif&amp;quot; /&amp;gt;
&amp;lt;figcaption&amp;gt;&amp;lt;strong&amp;gt;Figure 1:&amp;lt;/strong&amp;gt; Notice the flashing style tag right before the body&amp;lt;/figcaption&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;Here’s a sampling of the kind of style rules that are injected:&lt;/p&gt;
&lt;pre&gt;&lt;code class=&quot;language-css&quot;&gt;.t
  .top-level-item[data-item-id-qs=&amp;quot;qs-gmail-thread-f-1526179305444074125-0&amp;quot;]
  &amp;gt; .V {
  display: block;
  height: 50px;
  left: 0px;
  opacity: 0.9999;
  -webkit-transform-origin: center top;
  width: 889px;
  will-change: -webkit-transform;
  -webkit-animation-name: swap-close-placeholder-fake-shadow-var-84,
    animation-placeholder-fake-shadow-swap;
}

@-webkit-keyframes swap-close-placeholder-fake-shadow-var-84 {
  0% {
    -webkit-transform: translate(0px, 0px) scale(1.0517435320584927, 27.34);
  }

  80%,
  100% {
    -webkit-transform: translate(0px, 0px) scale(1.0022497187851518, 1.00001);
  }
}

.t
  .top-level-item[data-item-id-qs=&amp;quot;qs-gmail-thread-f-1526179305444074125-0&amp;quot;]
  &amp;gt; .U {
  display: block;
  height: 48px;
  left: 0px;
  opacity: 0.9999;
  -webkit-transform-origin: center top;
  width: 889px;
  will-change: -webkit-transform;
  -webkit-animation-name: swap-close-placeholder-var-84;
}

@-webkit-keyframes swap-close-placeholder-var-84 {
  0% {
    -webkit-transform: translate(0px, 0px) scale(
        1.044994375703037,
        28.354166666666668
      );
  }

  80%,
  100% {
    -webkit-transform: translate(0px, 0px) scale(1.00001, 1.00001);
  }
}
&lt;/code&gt;&lt;/pre&gt;
&lt;p&gt;Notice that the CSS is targeting specific elements with extremely precise animation measurements. These are not rules that a human would write. These are rules that are most likely generated by an application of some sort. The rules are also armed with exact width and height measurements. If you’ve ever tried to animate height, you’ve no doubt felt some pain as it’s not easy. Knowing the exact height of the element you’re trying to animate makes a huge difference and Google Inbox takes full advantage.&lt;/p&gt;
&lt;h2&gt;A Few Examples&lt;/h2&gt;
&lt;p&gt;Now that we have a general idea of the kind of setup we’re dealing with, let’s dive into a few examples.&lt;/p&gt;
&lt;h3&gt;The Fixed Header&lt;/h3&gt;
&lt;p&gt;We’ll start with the simplest of the three: the fixed message header. This one is not particularly novel, but has a slight twist to make it interesting. The basic idea is that when a message is open, it’s header sticks to the top of the page as you scroll past it:&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;Fixed Header A&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/fixed_header_a.gif&amp;quot; /&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;This is done pretty much as you might expect. Javascript listens for the position of the top of the header message and once it’s been scrolled past the top the of the viewport, its position is fixed. A small detail here is that there is also a “pusher” div that makes sure to push the message contents down once the message header is fixed. This is needed because a fixed element removes it from the flow of the page, so the contents below it would have otherwise popped up. Here’s what I mean:&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;Fixed Header - No Pusher&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/fixed_header_b.gif&amp;quot; /&amp;gt;
&amp;lt;figcaption&amp;gt;&amp;lt;strong&amp;gt;Figure 2:&amp;lt;/strong&amp;gt; Notice how the messages contents jump when the header becomes fixed.&amp;lt;/figcaption&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;The twist is that the header will also switch to absolute positioning once you get to the point where the bottom of the header is the same as the bottom of the message. This gives a nice transition between fixed back to static, rather than just jumping straight back to static.&lt;/p&gt;
&lt;p&gt;&amp;lt;img alt=&amp;quot;Fixed Header - Absolute&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/fixed_header_c.gif&amp;quot; /&amp;gt;&lt;/p&gt;
&lt;p&gt;I’ve put together an example implementation on Codepen:&lt;/p&gt;
&lt;p&gt;&amp;lt;div class=&apos;embed&apos;&amp;gt;
&amp;lt;div data-height=&amp;quot;520&amp;quot; data-theme-id=&amp;quot;0&amp;quot; data-slug-hash=&amp;quot;bpGrmm&amp;quot; data-default-tab=&amp;quot;result&amp;quot; data-user=&amp;quot;npbee&amp;quot; data-embed-version=&amp;quot;2&amp;quot; data-pen-title=&amp;quot;Google Inbox -  Fixed Header&amp;quot; class=&amp;quot;codepen&amp;quot;&amp;gt;See the Pen &amp;lt;a href=&amp;quot;https://codepen.io/npbee/pen/bpGrmm/&amp;quot;&amp;gt;Google Inbox -  Fixed Header&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&amp;quot;https://codepen.io/npbee&amp;quot;&amp;gt;@npbee&amp;lt;/a&amp;gt;) on &amp;lt;a href=&amp;quot;https://codepen.io&amp;quot;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/div&amp;gt;
&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h3&gt;The Message Open&lt;/h3&gt;
&lt;p&gt;Now things get a bit trickier. First, a quick visual of the animation:&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;Message Open&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/message_open.gif&amp;quot; /&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;While this might look like a simple height and width animation, I assure you it’s not. What’s happening here involves timing a few different keyframe animations together as one. Keep in mind that the actual contents of the messages are completely hidden while the message is closed, as in &lt;code&gt;display: none&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;First, there is a &lt;code&gt;div&lt;/code&gt; in the markup that’s sole purpose is to do a &lt;a href=&quot;https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/scale&quot;&gt;scale&lt;/a&gt; animation when the message is opening. A scale animation is an interesting choice because it has no effect on the document flow, meaning that you can scale an element to 200% and the elements around won’t budge. So in order to give the effect that the height of the message is increasing as the message is opening, you have to actually translate any messages below it &lt;em&gt;down&lt;/em&gt; the page. This will be more relevant in the next section. The scale animation is also interesting because it’s essentially emulating a height animation of sorts. The “pusher” &lt;code&gt;div&lt;/code&gt; scales to the point where its height is exactly the height of the incoming message content. This is where knowing the exact dimensions comes in handy.&lt;/p&gt;
&lt;p&gt;Once the “scaler” div has done its thing, the content is brought into the DOM and begins to fade in. At this point, the flow of the document is restored and since everything was done to exact specificity, there’s not jumpiness with any other &lt;code&gt;div&lt;/code&gt;’s that had been moved out of the way for the scale animation.&lt;/p&gt;
&lt;p&gt;I’ll be going into more detail next about the translating, but here’s a sample implantation on Codepen:&lt;/p&gt;
&lt;p&gt;&amp;lt;p class=&amp;quot;codepen&amp;quot; data-height=&amp;quot;520&amp;quot; data-default-tab=&amp;quot;result&amp;quot; data-slug-hash=&amp;quot;ZWEJRg&amp;quot; data-user=&amp;quot;npbee&amp;quot; style=&amp;quot;height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;&amp;quot;&amp;gt;
&amp;lt;span&amp;gt;See the Pen &amp;lt;a href=&amp;quot;https://codepen.io/npbee/pen/ZWEJRg&amp;quot;&amp;gt;
Google Inbox -  Open Message&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&amp;quot;https://codepen.io/npbee&amp;quot;&amp;gt;@npbee&amp;lt;/a&amp;gt;)
on &amp;lt;a href=&amp;quot;https://codepen.io&amp;quot;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/span&amp;gt;
&amp;lt;/p&amp;gt;
&amp;lt;script async src=&amp;quot;https://cpwebassets.codepen.io/assets/embed/ei.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;/p&gt;
&lt;p&gt;&amp;lt;div data-height=&amp;quot;520&amp;quot; data-theme-id=&amp;quot;0&amp;quot; data-slug-hash=&amp;quot;ZWEJRg&amp;quot; data-default-tab=&amp;quot;result&amp;quot; data-user=&amp;quot;npbee&amp;quot; class=&apos;codepen&apos;&amp;gt;See the Pen &amp;lt;a href=&apos;http://codepen.io/npbee/pen/ZWEJRg/&apos;&amp;gt;Google Inbox -  Open Message&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&apos;http://codepen.io/npbee&apos;&amp;gt;@npbee&amp;lt;/a&amp;gt;) on &amp;lt;a href=&apos;http://codepen.io&apos;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/div&amp;gt;&lt;/p&gt;
&lt;h2&gt;The Message Swap&lt;/h2&gt;
&lt;p&gt;Now we get to the wild and crazy stuff, the message swap:&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;message swap&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/message_swap.gif&amp;quot; /&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;So, why is this interesting? To be honest, I wasn’t sure it was all that interesting myself until I actually tried implementing it. The first thing to notice is that it looks as if the opening message is animating its height in reverse. This is the what a natural height animation would look like. If you were to animate the second message’s height normally, it flow downwards increase the overall height of the page. The second interesting thing that’s not very visible in the above gif, is the scroll position.&lt;/p&gt;
&lt;p&gt;Take a look at this one (I have to speed up the animations for this to work):&lt;/p&gt;
&lt;p&gt;&amp;lt;figure&amp;gt;
&amp;lt;img alt=&amp;quot;scroll position&amp;quot; src=&amp;quot;https://s3-us-west-2.amazonaws.com/npbee/2016/ux-case-study-google-inbox/message_swap_b.gif&amp;quot; /&amp;gt;
&amp;lt;/figure&amp;gt;&lt;/p&gt;
&lt;p&gt;In this gif, I’ve already scrolled way down the page and I’m now opening the second message. If you imagine what would happen in the normal document flow, the first message would close and the page’s height would be substantially decreased, bringing the element below with it up the page. We’d open to somewhere in the middle of the second message. Instead, the scroll position appears to stay the exactly the same, the first messages closes, and the second message opens right in place. This is an example of a completely natural feeling animation that is extremely &lt;em&gt;unnatural&lt;/em&gt; to implement.&lt;/p&gt;
&lt;p&gt;So how’s it done? In short, the CSS &lt;code&gt;translate&lt;/code&gt; transform. But this is also another example of multiple animations being coordinated together to appear as one smooth interaction. As the first message is closing, it’s &lt;code&gt;translateY&lt;/code&gt; position is being animated from 0 up to the point where it would be visible on the screen at the current scroll position. Meaning, if the first message were above the viewport by 200px, we’d animate from &lt;code&gt;translateY(0px)&lt;/code&gt; to &lt;code&gt;translateY(200px)&lt;/code&gt; to bring it in view. Simultaneously, the second message’s &lt;code&gt;translateY&lt;/code&gt; property is animated from the offset created from the first message closing &lt;em&gt;down&lt;/em&gt; to the point where it needs to end up on the screen. All the while each message’s “scaler” divs are doing their thing. All of this put together makes it look these divs are basically animating their height without the page moving at all.&lt;/p&gt;
&lt;p&gt;But just those animations wouldn’t be enough. The last missing piece here is the scroll position. In this scenario, once we’re done animating we’ve actually translated all of the content forward with the &lt;code&gt;translateY&lt;/code&gt; property. So technically you could scroll up in the page and see a bunch of blank space. And since these animations are only temporary (remember the style is injected and then removed once the animations are done), the page contents will jump up once styles are removed because they don’t have the &lt;code&gt;translateY&lt;/code&gt; values that were applied. This is obviously no good. The solution is to manually set the scroll position forward the &lt;em&gt;exact&lt;/em&gt; amount that the page contents were translated. Because we’re dealing with exact calculations, doing this immediately before the injected styles are removed does not result in any page jumps and essentially resets the page to a fresh state.&lt;/p&gt;
&lt;p&gt;I’ve tried to narrow down the concepts to an implementation here (click the second message):&lt;/p&gt;
&lt;p&gt;&amp;lt;p class=&amp;quot;codepen&amp;quot; data-height=&amp;quot;395&amp;quot; data-default-tab=&amp;quot;result&amp;quot; data-slug-hash=&amp;quot;wMLgRY&amp;quot; data-user=&amp;quot;npbee&amp;quot; style=&amp;quot;height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;&amp;quot;&amp;gt;
&amp;lt;span&amp;gt;See the Pen &amp;lt;a href=&amp;quot;https://codepen.io/npbee/pen/wMLgRY&amp;quot;&amp;gt;
Google Inbox -  Message Swap&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&amp;quot;https://codepen.io/npbee&amp;quot;&amp;gt;@npbee&amp;lt;/a&amp;gt;)
on &amp;lt;a href=&amp;quot;https://codepen.io&amp;quot;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/span&amp;gt;
&amp;lt;/p&amp;gt;
&amp;lt;script async src=&amp;quot;https://cpwebassets.codepen.io/assets/embed/ei.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;/p&gt;
&lt;p&gt;Notice the two messages translating up and down and the scroll bar hopping up at the very last second once the animations are done.&lt;/p&gt;
&lt;p&gt;In attempt to make this more clear, I’ve made a step-able version here:&lt;/p&gt;
&lt;p&gt;&amp;lt;p class=&amp;quot;codepen&amp;quot; data-height=&amp;quot;554&amp;quot; data-default-tab=&amp;quot;result&amp;quot; data-slug-hash=&amp;quot;ONJQMa&amp;quot; data-user=&amp;quot;npbee&amp;quot; style=&amp;quot;height: 300px; box-sizing: border-box; display: flex; align-items: center; justify-content: center; border: 2px solid; margin: 1em 0; padding: 1em;&amp;quot;&amp;gt;
&amp;lt;span&amp;gt;See the Pen &amp;lt;a href=&amp;quot;https://codepen.io/npbee/pen/ONJQMa&amp;quot;&amp;gt;
Google Inbox -  Message Swap Stepper&amp;lt;/a&amp;gt; by Nick Ball (&amp;lt;a href=&amp;quot;https://codepen.io/npbee&amp;quot;&amp;gt;@npbee&amp;lt;/a&amp;gt;)
on &amp;lt;a href=&amp;quot;https://codepen.io&amp;quot;&amp;gt;CodePen&amp;lt;/a&amp;gt;.&amp;lt;/span&amp;gt;
&amp;lt;/p&amp;gt;
&amp;lt;script async src=&amp;quot;https://cpwebassets.codepen.io/assets/embed/ei.js&amp;quot;&amp;gt;&amp;lt;/script&amp;gt;&lt;/p&gt;
&lt;p&gt;Note that I’m calling these “steps” but really these all happen pretty much simultaneously.&lt;/p&gt;
&lt;h2&gt;Takeaways&lt;/h2&gt;
&lt;p&gt;I’m sure you’re wondering why I wasted so much time on this. I wondered that myself plenty of times, but came away with a few solid learnings:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Debugging Google code is hard.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Like any quality production app, Google Inbox’s output code is not meant to be readable. But Google really seems to go the extra mile with minified class names and injected style. They are building for scale and not for people like me to be able to decipher what’s happening in their web apps.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Subtlety is king.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;Most of the animations are incredibly subtle. Like &lt;em&gt;really&lt;/em&gt; subtle. They are the sort of animations that you don’t really know are there until you do. Additionally, many of these animations have a very fast duration. So after all of the work to achieve these animations, they’re gone in an instant. I think it’s a nice display of restraint by the designers. In the same situation, I could see myself wanting to show off all of these wonderful animations I had built.&lt;/p&gt;
&lt;p&gt;On the flip side of the above, I did see a bunch of injected code that was essentially worthless. I doubt that animating a div from &lt;code&gt;translateY(0, 0.000122)&lt;/code&gt; to &lt;code&gt;translateY(0, 0.00011)&lt;/code&gt; is actually perceivable to a real person. The amount of times where these extremely small animations are introduced, I’m not sure, but there is probably a tradeoff there somewhere.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Google takes their animations seriously.&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;I don’t consider myself well-versed in UX design, but it was quite fascinating to see just a glimpse of the amount of work it takes to get the level of polish that Google Inbox has. As I mentioned earlier, there are probably some non-humans writing at least part of the actual code that makes the animations run, but there are definitely humans &lt;em&gt;designing&lt;/em&gt; the animations. The interactions seemed to be envisioned first with the implementation details worked out later in whatever way was necessary, which is opposite of how I usually think about these things. I’m not sure I’ll ever have the resources at my disposal to build animations at this level of detail, but it was an impressive reminder that user experience is the ultimate goal and we should do whatever it takes to make it great.&lt;/p&gt;
</content:encoded></item></channel></rss>