DEV Community: Chris Garrett

Using Hyperkit to supercharge UI Development without writing JS

Chris Garrett — Mon, 21 Oct 2024 10:27:37 +0000

I’ve been working on Hyperkit over the past couple of weeks, and I’m excited to share the first release. Hyperkit is now live on npm. It’s a collection of headless custom elements/web components designed to simplify building rich UIs with server-side frameworks like Rails or Revel.

Why Hyperkit?

The pull of React, for me, has always been the clarity and DX that comes with colocating a component’s behaviour with its markup and styling. It makes building complex front-ends much more intuitive and easier to reason about. The counterpart in Rails is Stimulus, which often feels disconnected - relying on magic incantations of data attributes to apply behaviour, making it difficult to trace and debug.

For simpler UI components like a stylable select, or a click-to-copy button, I didn’t want to always rely on React. That’s where Hyperkit comes in. It’s a set of headless custom elements that help bridge that gap by bringing custom behaviour to plain HTML without the need for JavaScript-heavy frameworks.

What’s in Hyperkit?

Hyperkit covers a range of UX patterns, such as sortable lists, repeating fieldsets, and even calendars. Because Hyperkit uses custom elements, you write them as simple HTML tags, and the behaviour is encapsulated directly within the tag.

Here’s an example of a styled sortable list using Hyperkit:

<hyperkit-sortable class="bg-white rounded shadow-md w-64 overflow-hidden">
  <hyperkit-sortable-item class="flex items-center justify-between pr-4 pl-3 py-2 border-b border-b-zinc-200 data-[before]:border-t-2 data-[before]:border-t-blue-400 data-[after]:border-b-2 data-[after]:border-b-blue-400 text-zinc-800">
    <hyperkit-sortable-handle>
      <button class="cursor-move mr-2 text-zinc-400 select-none font-black px-1">&#8942;</button>
    </hyperkit-sortable-handle>
    <span class="text-xs font-medium flex-grow">Item 1</span>
  </hyperkit-sortable-item>
  <hyperkit-sortable-item class="flex items-center justify-between pr-4 pl-3 py-2 border-b border-b-zinc-200 data-[before]:border-t-2 data-[before]:border-t-blue-400 data-[after]:border-b-2 data-[after]:border-b-blue-400 text-zinc-800">
    <hyperkit-sortable-handle>
      <button class="cursor-move mr-2 text-zinc-400 select-none font-black px-1">&#8942;</button>
    </hyperkit-sortable-handle>
    <span class="text-xs font-medium flex-grow">Item 2</span>
  </hyperkit-sortable-item>
</hyperkit-sortable>

And here’s a styled calendar built with Hyperkit:

<hyperkit-calendar class="w-64 bg-white rounded-lg shadow-lg p-4 block">
  <div class="flex justify-between items-center mb-4">
    <hyperkit-previous-month>
      <button class="text-zinc-600 hover:text-zinc-800 text-xl">&lt;</button>
    </hyperkit-previous-month>
    <hyperkit-current-month class="text-xl font-bold text-zinc-800"></hyperkit-current-month>
    <hyperkit-next-month>
      <button class="text-zinc-600 hover:text-zinc-800 text-xl">&gt;</button>
    </hyperkit-next-month>
  </div>
  <div class="grid grid-cols-7 gap-1 mb-2">
    <div class="text-center text-xs font-semibold text-zinc-600">M</div>
    <div class="text-center text-xs font-semibold text-zinc-600">T</div>
    <div class="text-center text-xs font-semibold text-zinc-600">W</div>
    <div class="text-center text-xs font-semibold text-zinc-600">T</div>
    <div class="text-center text-xs font-semibold text-zinc-600">F</div>
    <div class="text-center text-xs font-semibold text-zinc-600">S</div>
    <div class="text-center text-xs font-semibold text-zinc-600">S</div>
  </div>
  <hyperkit-days-list class="grid grid-cols-7 gap-1"></hyperkit-days-list>
  <template slot="day-number">
    <hyperkit-day-number>
      <button class="w-8 h-8 flex items-center justify-center rounded-full cursor-pointer text-xs hover:bg-zinc-100 focus:ring-1 focus:ring-lime-500 focus:bg-lime-200 transition-colors duration-200 data-[today]:bg-lime-600 text-zinc-800 data-[today]:text-white data-[selected]:bg-lime-200 data-[other-month]:text-zinc-400 disabled:text-zinc-400"></button>
    </hyperkit-day-number>
  </template>
</hyperkit-calendar>

Floating Label Input with React and Tailwind

Chris Garrett — Tue, 25 Aug 2020 10:52:47 +0000

I've been working on the sign in page for Hyperlaunch this week, and wanted to add some nice touches (because first impressions count!).

One of these was to do a nice, "floating label" input - like you see in Material UI etc. It's a really nice pattern for functionality like user sign in, as it's a very streamlined presentation which gives a nice minimal feel.

You might think that this approach is just making use of the placeholder attribute - but unfortunately, that can cause a bit of an accessibility issue. The way around this is to use an absolutely positioned label instead - so screen readers can still interpret the form correctly. This approach has the added benefit of being able to add a subtle transition, to really up the UX game.

I implemented my floating label inputs with React and Tailwind CSS - using a state hook to toggle the class names based on user actions.

The result's a nice, succinct component:

function FloatingLabelInput({ type, name, children }) {
  const [active, setActive] = React.useState(false);

  function handleActivation(e) {
    setActive(!!e.target.value);
  }

  return (
    <div className="relative border rounded mb-2 bg-gray-600 text-white border-white border-opacity-25">
      <input
        className={[
          "outline-none w-full rounded bg-transparent text-sm transition-all duration-200 ease-in-out p-2",
          active ? "pt-6" : ""
        ].join(" ")}
        id={name}
        name={name}
        type={type}
        onChange={handleActivation}
      />
      <label
        className={[
          "absolute top-0 left-0 flex items-center text-white text-opacity-50 p-2 transition-all duration-200 ease-in-out",
          active ? "text-xs" : "text-sm"
        ].join(" ")}
        htmlFor={name}
      >
        {children}
      </label>
    </div>
  );
}

which is as easy to use as: <FloatingLabelInput name="username" type="text">Username</FloatingLabelInput>

You can see it in action on my Codepen

Technical Debt as a Tool

Chris Garrett — Sun, 09 Aug 2020 11:57:37 +0000

It's pretty hard to get away from the term technical debt these days; the bane of development projects, to be avoided at all costs. I prefer to think of it a little differently - as a tool.

Businesses use financial debt as a tool - why not technical debt? Financial debt works best when it bridges a short-term gap, when it helps a business achieve an outsized return that far exceeds the cost of borrowing.

We can use technical debt in the same way; a quick hack here, a bit of tight coupling there - it may offend the "purist" in your team, but it could be the difference between getting a revenue generating service online (and paying down that technical debt), or never actually getting to market.

Just make sure you don't miss your repayments.

Big CSV exports with Rails: streaming FTW

Chris Garrett — Wed, 08 Jul 2020 15:20:25 +0000

One of the projects we're working at the moment had a heavy reporting requirement: years of sales and transaction data - all of which needed to be exportable as CSV files. Big CSV files.

Normally, I might look at queuing the export and executing it as a background process - but this time I found a quick win: using a combination of ActiveRecord's find_each, and Ruby's Enumerator to stream the CSV - in batches, and straight from the controller. As with most things Rails, it was really quite easy:

require 'csv'

class ReportsController < ApplicationController
  def index
    headers.delete("Content-Length")
    headers["Cache-Control"] = "no-cache"
    headers["Content-Type"] = "text/csv"
    headers["Content-Disposition"] = "attachment; filename=\"report.csv\""
    headers["X-Accel-Buffering"] = "no"

    response.status = 200

    self.response_body = csv_enumerator
  end

  private

  def csv_enumerator
    @csv_enumerator ||= Enumerator.new do |yielder|
      ReportItem.find_each do |row|
        yielder << CSV.generate_line([
          row.id,
          row.name,
          row.total
        ])
      end
    end
  end
end

Using find_each saves me from:

Putting too much load on the database with a heavy query
Holding too much data in memory

and passing an Enumerator to response_body forces the browser to keep the connection open while it pipes down whatever data is yielded. I also do the usual stuff like setting the content-type and disposition so that the browser still treats it like a file download.

It worked exceptionally for our use case, and required dramatically less effort than adopting a queue - both in terms of code and UX.

Rails views not updating locally? This might be why...

Chris Garrett — Wed, 24 Jun 2020 10:59:06 +0000

We recently upgraded a Rails project from Rails 5 to 6. It was pretty smooth in general, but I noticed in development (with Docker) that views weren't updating with changes - as if they were being cached.

The culprit turned out to be this segment of config/development.rb:

# Use an evented file watcher to asynchronously detect changes in source code,
# routes, locales, etc. This feature depends on the listen gem.
config.file_watcher = ActiveSupport::EventedFileUpdateChecker

ActiveSupport::EventedFileUpdateChecker dislikes either Docker volumes or Windows - I'm leaning towards the latter and it being a dependency issue relating to FS notifications.

If you're hitting this issue: just comment out the config.file_watcher line and you'll be back on track.

Using recursion to build a slideshow with React

Chris Garrett — Wed, 17 Jun 2020 12:57:49 +0000

Ever since dabbling with Elixir, I've taken to working pure functional principles into a lot of my everyday coding. In particular, I really enjoy using recursion - I find it especially useful as a way of managing state, especially in combination with React hooks.

One simple way to illustrate how powerful this can be is this Slideshow example - a simple component which cycles through a series of slides, infinitely.

So let's break down some of what's happening in this example, starting with the state management:

const initialIndices = slides.map((_, index) => index);
const stepThroughSlides = async ({ remainingIndices }) => {
  setActiveSlideIndex(remainingIndices[0]);

  await sleep(3000);

  return stepThroughSlides({
    remainingIndices:
      remainingIndices.length > 1
        ? remainingIndices.slice(1)
        : initialIndices
  });
};
stepThroughSlides({ remainingIndices: initialIndices });

There are a few prerequisites to this:

We assume a slideshow essentially steps through an array of slides sequentially, by index.
We assume that the indices for all of the slides are stored in the initialIndices array.
We assume we've used a useState hook to hold the index of the current slide (activeSlideIndex).
We assume that the function will receive an array of slides still waiting to be displayed (remainingIndices).

Given all of this is true, on invocation our stepThroughSlides function will:

Update the state to set the first index in the remainingIndices array as the active slide index.
Sleep for 3 seconds.
Call itself again with either:
- The array of remaining slides indices, minus the one we've just made active.
- The array of initial slides indices, if we've run out of slides and need to loop back.

With our state changes underway, we just need to update the actual display of our slides:

{slides.map((slide, index) => (
  <div
    className={`slide ${activeSlideIndex === index && "active"}`}
  >
    {slide}
  </div>
))}

Nice and easy - I just map my slides and, if the activeSlideIndex state is equivalent to the index of the slide, I add a CSS class accordingly. Just a few lines of corresponding CSS and we're done:

.slide {
  position: absolute;
  top: 0;
  left: 0;
  opacity: 0;
  transition: opacity 1s ease-in-out;
}

.slide.active {
  opacity: 1;
}

I've glossed over some of the React nuance - like using useEffect to hook this all up - so it's worth having a proper look at the full working example on JSFiddle.

You might be thinking that I could have just used setInterval here - but using recursion:

Removes the need for cleanup (ie. clearInterval).
Encourages immutability by design - which in turn reduces the risk of bugs and race conditions.
As a technique, can be used to much greater effect and applied to more demanding use cases.

Dockerising a Next.js project

Chris Garrett — Wed, 10 Jun 2020 10:52:21 +0000

I recently made the switch from Mac to Windows - I won't get into the reasons why, other than to mutter a few grumbles about keyboards. What I will say is that having our projects well Dockerised proved to be invaluable in making the move. Where previously I'd have lost days to getting my dev environment setup, a simple docker-compose up dev worked seamlessly, out of the box.

My dev environment isn't the only area where Docker is valuable, of course. While it may seemingly go against convention, we generally choose to deploy our Next.js apps as Fargate services. I won't get into the many Dev Ops related reasons for this, but I will show you how we use Docker and Docker Compose to run our Next.js apps effectively, across environments...

I'm going to assume you have Docker Desktop installed, know the difference between Docker and Docker Compose, and have a working knowledge of Next.js.

With those prerequisites out of the way, let's start with our Dockerfile:

FROM node:current-alpine AS base
WORKDIR /base
COPY package*.json ./
RUN npm install
COPY . .

FROM base AS build
ENV NODE_ENV=production
WORKDIR /build
COPY --from=base /base ./
RUN npm run build

FROM node:current-alpine AS production
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /build/package*.json ./
COPY --from=build /build/.next ./.next
COPY --from=build /build/public ./public
RUN npm install next

EXPOSE 3000
CMD npm run start

This may not look like the Dockerfile you were expecting... This is a "multi-stage" Dockerfile, which can be used for both development and production deploys. There are various reasons you may want to do this, but the primary one is that the size of our docker images can be reduced dramatically as they only bundle the result of the final step.

Let's take a look at that first step:

FROM node:current-alpine AS base
WORKDIR /base
COPY package*.json ./
RUN npm install
COPY . .

This looks more or less like any other node related Dockerfile; it extends from the official node image, copies our package.json and installs it, then adds the working project files.

This next stage is where things get interesting - this is where we compile our next app:

FROM base AS build
ENV NODE_ENV=production
WORKDIR /build
COPY --from=base /base ./
RUN npm run build

Each stage of a multi-stage Dockerfile is self-contained, so we have to explicitly copy any files we want from the base step. This step only relates to a production build, so we're explicitly setting the NODE_ENV to production, copying the files from the base step, and running the build script specified in our package.json.

With our app compiled, we're on to the final step: creating a lean, production-ready image.

FROM node:current-alpine AS production
ENV NODE_ENV=production
WORKDIR /app
COPY --from=build /build/package*.json ./
COPY --from=build /build/.next ./.next
COPY --from=build /build/public ./public
RUN npm install next

EXPOSE 3000
CMD npm run start

From the previous build step, we copy our package.json, the .next directory which contains our compiled app, and the directory which contains our public assets across. Finally, it installs the next package, uses it to start our compiled app, and exposes it at localhost:3000. The only files this final image contains are the ones that we copied across - the essentials - keeping it super lean. We've ditched our heavy node_modules directory, among other things.

Note:
You may have noticed I specified `ENV NODE_ENV=production` again in this step. This is because `ENV` variables aren't shared between steps, so need to be duplicated.

That's our Dockerfile done; now how do we run next dev with this thing?

Simple: we need a docker-compose.yml file:

version: "3.7"

x-common-props: &common-props
  build:
    context: ./
    target: base
  working_dir: /base
  volumes:
    - ./app:/base
    - node_modules:/base/node_modules

services:
  npm:
    <<: *common-props
    entrypoint: npm
  dev:
    <<: *common-props
    ports:
      - "3000:3000"
    command: npm run dev
volumes:
  node_modules:

This gives me two local services; npm and dev. Both use the base step from our Dockerfile, but:

npm specifies the npm command as it's entry point, so I can write convenient commands like docker-compose run npm i -s moment.
dev specifies the dev script from our package.json, so I can start the whole thing up with docker-compose up dev and see my app running at localhost:3000.

I have some common-props to share attributes between services, and these include mounting a volume for my node_modules - a useful trick for sharing modules between containers and saving a lot of time.

To sum up: adding these two files to the root of any standard next.js project should have you up and running in no time - with:

Out of the box, cross-platform development for your whole team.
Blazing fast, fully containerized production deploys.

If you've any reservations about how performant a containerised next.js app, compared to one targetting serverless, I leave you with this timeline from the dynamic, database driven homepage of one of our projects:

Easy user authentication with Next.js

Chris Garrett — Wed, 03 Jun 2020 15:07:41 +0000

Over the past couple of releases, Next.js has made some impressive additions which have transformed the way I develop with it. One of my favourite new features is the getServerSideProps function; a function which can be appended to any page component, is executed on the server for each request, and injects the resulting data into the page as props.

Why do I like this so much? Well, put simply, it makes my life dramatically easier - and no piece of functionality better illustrates this than the ubiquitous user sign in...

Up until now, authentication within a general React/SPA project has been a complicated task, fraught with danger. In basic cases, it involves various hooks and API calls; in more extreme cases, jargonistic acronyms like JWT and PKCE come into play. But not anymore! With getServerSideProps, secure server sessions are back on the menu. Hear that thud? That's the sound of 100s of lines of redundant code dropping out of my project.

The code

Starting with a clean Next.js app, adding user sign in requires just three parts:

A page for the user sign in form.
An API endpoint for validating the user credentials and setting the user session.
A page which validates the user session or rejects the request.

We'll start with the sessions API endpoint, and by creating pages/api/sessions.js:

import { withIronSession } from "next-iron-session";

const VALID_EMAIL = "chris@decimal.fm";
const VALID_PASSWORD = "opensesame";

export default withIronSession(
  async (req, res) => {
    if (req.method === "POST") {
      const { email, password } = req.body;

      if (email === VALID_EMAIL && password === VALID_PASSWORD) {
        req.session.set("user", { email });
        await req.session.save();
        return res.status(201).send("");
      }

      return res.status(403).send("");
    }

    return res.status(404).send("");
  },
  {
    cookieName: "MYSITECOOKIE",
    cookieOptions: {
      secure: process.env.NODE_ENV === "production" ? true : false
    },
    password: process.env.APPLICATION_SECRET
  }
);

Let's break this down:

There are two prerequisites here: first we use the fantastic Next Iron Session package to simplify dealing with sessions, so you'll need to npm install --save next-iron-session; secondly you'll need to add a 32 character string called APPLICATION_SECRET to your .env, which is used to secure the session content.
My credentials check is very crude (email === VALID_EMAIL && password === VALID_PASSWORD) to keep the example simple; in reality you'd likely be doing a datastore lookup (and please use password hashing).
Next.js API routes aren't scoped by HTTP verb, hence I've added the if (req.method === "POST") check to lock this down a little.

Next we're going to create our private page, pages/private.jsx:

import React from "react";
import { withIronSession } from "next-iron-session";

const PrivatePage = ({ user }) => (
  <div>
    <h1>Hello {user.email}</h1>
    <p>Secret things live here...</p>
  </div>
);

export const getServerSideProps = withIronSession(
  async ({ req, res }) => {
    const user = req.session.get("user");

    if (!user) {
      res.statusCode = 404;
      res.end();
      return { props: {} };
    }

    return {
      props: { user }
    };
  },
  {
    cookieName: "MYSITECOOKIE",
    cookieOptions: {
      secure: process.env.NODE_ENV === "production" ? true : false
    },
    password: process.env.APPLICATION_SECRET
  }
);

export default PrivatePage;

So what's happening here?

Firstly, we're using getServerSideProps to check for the existence of the user session - which would have been set by our sessions API endpoint.
If there's no session, we're sending an empty 404 back to the browser. You could redirect to the sign in page instead, but I prefer this approach as it deters snooping bots/crawlers.
Finally, we're piping the contents of the user session into the page component as a prop.

So now we have a private page, and an API endpoint to open it up - we just need to add our sign in form to bring it all together, pages/signin.jsx:

import React, { useRef } from "react";
import { useRouter } from "next/router";

const SignInPage = () => {
  const router = useRouter();
  const emailInput = useRef();
  const passwordInput = useRef();

  const handleSubmit = async (e) => {
    e.preventDefault();

    const email = emailInput.current.value;
    const password = passwordInput.current.value;

    const response = await fetch("/sessions", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ email, password })
    });

    if (response.ok) {
      return router.push("/private");
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <div>
        <label>
          Email: <input type="text" ref={emailInput} />
        </label>
      </div>
      <div>
        <label>
          Password: <input type="password" ref={passwordInput} />
        </label>
      </div>
      <div>
        <button type="submit">Sign in</button>
      </div>
    </form>
  );
};

export default SignInPage;

It might seem like there's a lot going on with this one, but it's actually the most basic piece:

We're rendering out a form; using refs to capture the email and password inputs, and registering an onSubmit callback.
That onSubmit callback is then using fetch to call our sessions API endpoint with the supplied value.
If the sessions API endpoint responds with an ok header, we're assuming the user session has been set successfully, and redirecting the user to our private page.

But hey... If we're just checking the users details exist in the session, what's to stop someone creating a fake session and pretending to be someone else?

Very good question! Remember that 32 character APPLICATION_SECRET we added to our .env? That's used to encrypt the session contents, so it's not readable (or spoofable) to the outside world. All the client will see is something like this:

Just remember: it's called APPLICATION_*SECRET* for a reason, keep it that way.

That's all folks

That's it; we've added a functional, and secure user sign in function to our Next.js app - with minimal code overhead.

What's next?

I've kept the code deliberately blunt for the purpose of this article; there are some obvious and immediate improvements required to take this forward into a full application:

We don't want to be repeating the session lookup for all our secured pages - we could write a decorator/HoC that wraps getServerSideProps and performs the session validation in a reusable way.
I've not abstracted the iron session cookie name (cookieName: "MYSITECOOKIE") - this encourages developer error and bugs, so should be moved to a shared constant or the env.
Our sign in form doesn't provide any kind of validation messaging to the end user; we could add a useState hook to display helpful errors.
We've not added user sign out functionality; that could be added for DELETE calls to the sessions API endpoint.