DEV Community: Robert

A Quest to Find the Fastest Search Stack

Robert — Wed, 21 Jan 2026 13:56:44 +0000

Recently I was tasked with implementing search in a large eCommerce application. While researching hosted search applications, Algolia's InstantSearch mesmerized me with its speed - consistently delivering results in under 50ms globally. Essentially showing me results as I type!

Hosted search applications like Algolia specialize in providing a great search experience for users of applications, e-commerce or knowledge websites.

Inspired by Algolia, I challenged myself to see if I could replicate this kind of performance using familiar technologies. This turned out to be harder than expected. I went through four different architectures before finding something that worked well. Here's what I learned along the way.

My requirements:

Sub-50ms responses
Possibility to scale for fast responses globally
Possibility for integrating semantic search

The Architecture Journey: 4 Attempts

Attempt #1: Vercel + Neon Postgres

I started with my usual stack: Next.js deployed to Vercel with a Neon PostgreSQL database. Neon supports many extensions and comes with the powerful pg_search and pgvector extensions included, so I could store embeddings and do semantic search alongside regular keyword search.

The implementation was very quick to setup and worked great functionally.

The issue was latency. Even though my Next.js API routes were running at the edge via Vercel, every search still required a network call to Neon's centralized PostgreSQL instance. Database queries alone were taking 100-200ms due to network latency. Cold starts added another 100-200ms on top of that.

The takeaway was clear: database location matters more than compute location. Edge functions don't help if your data is centralized.

Attempt #2: The Cloudflare Workers + D1 Stack

Since data locality seemed to be the issue, I tried Cloudflare Workers with D1. Workers run globally, are known for their speed and support a massive network of edge locations. D1 replicates SQLite databases globally, so both compute and data would be close to users. Perfect!

The rebuild went reasonably well. D1's SQLite with FTS5 handles keyword search very efficiently when the database was co-located with the worker. But vector search was problematic.

D1 doesn't support vector operations natively, meaning I would have to implement a separate vector database and perform reranking calculations in Javascript. While this doesn't have to be an issue technically, I abandoned this slight increase in complexity.

My self-imposed limitation was clear: I needed native vector support in the database. Trying to work around it in application code wasn't viable.

Attempt #3: The Durable Objects Side-Quest

While working with Cloudflare, I read up on Durable Objects and took a small detour. What excited me about Durable Objects is the fact that they have a SQLite backed storage. This means the database was literally on the same machine as the search logic, reads would be disk-local and essentially instant.

Since Durable Objects are built on top of CF Workers, switching from a Worker + D1 to a Durable Objects with SQLite backed storage was quick. The performance was excellent - database reads were indeed nearly instantaneous. Combined with CF Workers speed this was great!

Setting aside the fact this SQLite storage also doesn't support vectors, the other problem is geographic distribution. A Durable Object created in one region remains locked to that region. Users close to the object will get great performance, but distant users still experience higher latencies. This problem is probably circumventable, but it felt iffy to do so. This is where my side-quest ended.

However the experiment was useful - it confirmed that co-locating data with compute was key. I just needed that same local performance available in multiple locations simultaneously.

Attempt #4: The Fly.io + Turso Solution

Then I heard about Turso. Turso's embedded replicas allow you to easily replicate your main central database on your local server, giving each region fast, local access to the data without the latency of remote queries.

The caveat is that embedded replicas will take up some disk space, and the initial synchronizing might take a couple seconds depending on the size of your data. This meant that I couldn't run it in a Cloudflare Worker or Vercel Function due to the limited size, plus I needed a long-running process to avoid synchronizing the database on every start.

For the new setup, I used Fly.io. Fly let's you easily run VM's in multiple regions and scale both horizontally and vertically. This let me deploy the search API and Turso database replicas in multiple regions, so each region could serve queries with low latency and near instant data access. I also swapped out Node.js for Bun for an extra little performance boost.

When configuring an appropriate Fly.io machine without cold-starts, this resulted in sub-50ms response times pretty consistently!

Key Technical Insights

A few things became clear after trying these different approaches.

Database location matters more than compute location. Edge compute doesn't help much if your database is in a single region. No matter how fast your API code runs, if every query crosses oceans to reach your data, performance suffers. Local database replicas were what actually enabled global speed.

SQLite works well in production. Modern SQLite, particularly LibSQL with vector extensions, handles production workloads effectively. The combination of FTS5 for full-text search and native vector operations for semantic search creates a capable search engine in a single lightweight database.

Choosing the right tool for the job. Each database and hosting option has its own strengths and tradeoffs. Matching your requirements—like vector search, full-text search, and global performance—to the right technology stack is more effective than trying to force a single tool to do everything.

What's Next

The current system achieves the original goal of sub-50ms global search latency. There are still many improvements to make, some more obvious than others.

Smart caching is the next logical step - implementing keyword and n-gram caching to make popular queries even faster. Streaming search results could improve user experience by showing full-text search results immediately while semantic results populate in the background.

Search analytics would help understand what users actually search for, enabling better optimization of queries and caching strategies. Auto-scaling based on search volume would keep the system responsive during traffic spikes.

Longer term, AI-powered query enhancement could improve search intent understanding, and personalization could tailor results to individual users. With the current architectural foundation, these improvements are more straightforward to implement.

Conclusion

Have suggestions to make this setup even faster? Let me know.

Interested in adding search to your application, webshop or website? Feel free to reach out.

Rapid Development with Next.js + FastAPI + Vercel + Neon Postgres

Robert — Mon, 19 Jan 2026 13:46:52 +0000

In the ever-evolving landscape of modern web development, the tools and workflows we choose can dramatically impact both developer productivity and project outcomes. At Wolk, we've curated a powerful stack that combines Next.js, FastAPI, Vercel, and Neon Postgres to create a smooth developer experience while delivering high-performance applications.

This article shares our journey to building our workflow and explains how you can implement a similar approach.

Introduction

Developer experience (DX) has emerged as a crucial factor in the success of software teams. Just as user experience determines how people interact with our products, developer experience shapes how efficiently teams can build, test, and deploy those products. A streamlined DX means faster iterations, fewer errors, more innovation, and ultimately, better software.

Our stack combines four powerful technologies:

Next.js: A React framework with built-in optimizations and a great developer experience.
FastAPI: A modern, high-performance Python web framework built for API development with automatic documentation.
Vercel: A deployment platform for fullstack frameworks that offers seamless preview deployments. Incidentally also the company behind Next.js
Neon Postgres: A serverless Postgres service with unique branching capabilities that enable isolated database environments for every feature branch.

This article is aimed at full-stack development teams, DevOps engineers, and technical leaders looking to improve their development workflows, particularly those working with JavaScript/TypeScript frontends and Python backends.

Local Development Environment

The foundation of a great developer experience is a smooth local development environment that minimizes friction between writing code and seeing it in action.

Setting Up the Stack

Our repository structure separates frontend and backend in a monorepo code while maintaining their relationship:

/
├── app/              # Next.js application
├── api/              # Vercel entrypoint for the backend
├── backend/          # FastAPI application
├── docker-compose.yml    # Local development orchestration
├── .env              # Environment configuration
├── requirements.txt  # Python dependencies
└── package.json      # Project dependencies and scripts

For local development, we use Docker Compose to orchestrate all necessary services. Our docker-compose.yml file sets up:

The Next.js frontend development server
The FastAPI backend with auto-reloading
A local Postgres database for development
Supporting services like email testing tools

Here's a simplified version of our Docker Compose configuration:

version: "3"

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - ./:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: npm run dev

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    volumes:
      - ./backend:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app
    command: uvicorn app.main:app --reload --host 0.0.0.0

  db:
    image: postgres:14
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=app
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Environment management is handled through a combination of .env files and Docker Compose environment variables. For team members, getting started is as simple as:

# Clone the repository
git clone <https://github.com/our-org/our-project.git>

# Start the development environment
docker compose up

Once the environment is set up, the day-to-day development flow becomes remarkably efficient. The entire loop from database model change to frontend rendering can be completed in minutes, with each step providing immediate feedback through hot reloading.

Stack quirks

Vercel is a great platform for developing web applications but it is mainly focused on Next.js and other Javascript frameworks. Running Python on Vercel is supported but it does come with some quirks.

Vercel deploys a serverless function for every file it finds in the /api folder. So if we would put our whole Python backend application in there we would create numerous functions as this backend consists of many files. Also the routing of API calls is by default done based on file naming, common Typescript frameworks but less used in Python web apps. To fix this problem, we build the backend application in a separate folder and add an entrypoint for Vercel to build a function from:

#/api/main.py
import sys
sys.path.append("./backend")
from app.main import app  # type: ignore
app

When this is done the only thing left to do is add some configuration so that all routes starting with /api are passed to the backend entrypoint so that FastAPI can handle the routing to the correct function itself. This can by defining a rewrite innext.config.ts :

const nextConfig: NextConfig = {
  rewrites: async () => {
    return [
      {
        source: "/api/:path*",
        destination: "/api/main.py",
      },
    ]
  },
}

Type Safety Across the Stack

One of the most significant productivity enhancements in this stack is the end-to-end type safety between frontend and backend.

FastAPI uses Python type hints and Pydantic models to validate data. We leverage these types to automatically generate TypeScript interfaces for our frontend, creating a single source of truth for data structures.

Our approach utilizes the OpenAPI schema that FastAPI generates automatically. We utilize OpenAPI Typescript to automatically generate Typescript types from the backend's OpenAPI schema. This gives us TypeScript interfaces that exactly match our API endpoints and data models.

This approach helps us:

Catch errors early: TypeScript will alert you immediately if you try to access a property that doesn't exist or has changed
Autocompletion: Your IDE can provide intelligent suggestions based on the actual API structure
Refactoring confidence: When you rename fields in the backend, TypeScript will identify all the places in the frontend that need updates
Documentation: The types serve as living documentation of your API interface.

This type-safety across the stack significantly reduces context switching cost when moving between frontend and backend code, allowing developers to work more confidently across the full stack.

Full-Stack Preview Environments with Vercel and Neon

Our personal favourite part of this workflow is the isolated preview environments enabled by Vercel and Neon.

Traditional development workflows often struggle with environment isolation. While features are developed in separate branches, testing often happens in shared environments, leading to:

Conflicts between features being tested simultaneously
Difficulty reproducing specific states for bug testing
Uncertainty about how changes will behave in production
Lengthy feedback cycles for stakeholders

Many teams solve this partially with frontend preview deployments, but often the backend and database remain shared resources. This creates an incomplete picture of how changes will actually behave in production.

The ideal solution needs to provide:

An isolated frontend deployment
A dedicated backend instance
An isolated database with the correct schema and test data
Automatic setup and teardown of all resources

Enter Vercel and Neon

Our solution combines Vercel's preview deployments with Neon's unique database branching capabilities:

Vercel automatically creates a deployment for every pull request, with its own URL
Neon Postgres allows us to create a complete database branch from our main database, with its own isolated state

When a developer opens a pull request, they get a complete, isolated environment with its own database. This environment is a perfect replica of production, but with only their changes applied.

This approach significantly accelerates the feedback loop, allowing stakeholders to review actual working features rather than mockups or descriptions!

Conclusion

The combination of Next.js, FastAPI, Vercel, and Neon Postgres has transformed our development workflow. Our team now enjoys:

A consistent, easy-to-use local development environment
End-to-end type safety between frontend and backend
Isolated preview environments for every pull request
Faster feedback cycles for both developers and stakeholders
Higher confidence in the changes being deployed

This stack has directly contributed to faster feature delivery, fewer production bugs, and a more enjoyable development experience.

If you're building with a JavaScript/TypeScript frontend and a Python backend, we highly recommend exploring this combination of technologies. The productivity benefits are substantial, and the enhanced collaboration between frontend and backend teams is invaluable.

Have you implemented a similar workflow? We'd love to hear about your experiences!

Accessible Tabs Using React & Tailwind CSS

Robert — Tue, 20 Oct 2020 12:39:03 +0000

We're going for tabs with automatic activation. This means a tab panel will be revealed as soon as it's respective tab receives focus either by click or by using the arrow keys.

We want to re-use the tabs functionality in many places, with many different styles. So the tab component must:

Be re-usable.
Be completely unstyled.
Integrate well with Tailwind CSS.

Requirements for accessibility From W3:

Tab: When focus moves into the tab list, places focus on the active tab element.
When focus is on a tab element in a horizontal tab list:
- Left Arrow: moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab.
- Right Arrow: Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab.
When focus is on a tab element in a vertical tab list:
- Up Arrow: moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab.
- Down Arrow: Moves focus to the next tab. If focus is on the last tab element, moves focus to the first tab.
When focus is on a tab in a tablist with either horizontal or vertical orientation:
- Space or Enter: Activates the tab.
- Home: Moves focus to the first tab.
- End: Moves focus to the last tab.

Funk

I've created a package called Funk, which contains a set of components to create Tabs.

yarn add @statikly/funk

npm install --save @statikly/funk

You can then use it in such fashion:

import React from 'react'
import { TabGroup } from '@statikly/funk'

const Page = () => {
  return (
    <div className="h-screen w-screen flex flex-col justify-center items-center">
      <TabGroup numTabs={3} direction={TabGroup.direction.HORIZONTAL}>
        <TabGroup.TabList>
          <TabGroup.Tab
            index={0}
            className="h-12 px-12 transition-colors duration-150"
            activeClassName="bg-black text-white"
            inactiveClassName="text-black"
          >
            Tab 1
          </TabGroup.Tab>
          <TabGroup.Tab
            index={1}
            className="h-12 px-12 transition-colors duration-150"
            activeClassName="bg-black text-white"
            inactiveClassName="text-black"
          >
            Tab with input
          </TabGroup.Tab>
          <TabGroup.Tab
            index={2}
            className="h-12 px-12 transition-colors duration-150"
            activeClassName="bg-black text-white"
            inactiveClassName="text-black"
          >
            Tab 3
          </TabGroup.Tab>
        </TabGroup.TabList>
        <TabGroup.TabPanel
          index={0}
          className="p-16 transition-all transform h-64"
          activeClassName="opacity-100 duration-500 translate-x-0"
          inactiveClassName="absolute opacity-0 -translate-x-2"
        >
          Content 1
        </TabGroup.TabPanel>
        <TabGroup.TabPanel
          index={1}
          className="p-16 transition-all transform h-64 flex flex-col"
          activeClassName="opacity-100 duration-500 translate-x-0"
          inactiveClassName="absolute opacity-0 -translate-x-2"
        >
          <label className="font-semibold mb-1" htmlFor="input">
            Input
          </label>
          <input
            id="input"
            type="text"
            className="border border-gray-400 px-8 h-12"
            placeholder="Focus me!"
          />
        </TabGroup.TabPanel>
        <TabGroup.TabPanel
          index={2}
          className="p-16 transition-all transform h-64"
          activeClassName="opacity-100 duration-500 translate-x-0"
          inactiveClassName="absolute opacity-0 -translate-x-2"
        >
          Content 3
        </TabGroup.TabPanel>
      </TabGroup>
      <button className="mt-12 h-12 px-12 bg-indigo-500 text-white">
        Outside button
      </button>
    </div>
  )
}

Check out the Codesandbox and give it a whirl!

Prefer to get the code yourself or take a look under the hood? Check out the repo here!

Big Heads - Easily generate characters for your projects

Robert — Thu, 09 Jul 2020 07:02:56 +0000

Big Heads

Hi all!

Today I launched my random character generator called Big Heads.

You can combine expressions, clothing, hair styles and colors into billions of different unique characters. Embed them on your website, use them in your favourite design software, or import them from the React library.

All for free!

Heavily inspired by Pablo Stanley's Avataaars

Go check it out!

Here's me as a Big Head!

Share your avatar in the comments! (You'll have to use a url shorten-er, because dev.to escapes the query params in the url).

Authorization in GraphQL

Robert — Sun, 05 Apr 2020 10:11:47 +0000

Authentication is figuring out who the user is.
Authorization is figuring out what the user is allowed to do.

For this article I'll be focusing on the latter.

Authenticate

Before we can focus on authorization, we do need to be authenticated. So without diving in too deep, this is how we'll let our resolvers (and other parts of our app, a you will see) know who we are.

export const handler = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    const user = await getUser(req.header.authorization)

    return { user }
  },
})

Basic Authorization

Now that we know if the user is authenticated or not, the most basic thing we can do is allow or deny them to do anything.

export const handler = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    const user = await getUser(req.header.authorization)

    if (!user) throw new AuthorizationError('You are not logged-in!');  

    return { user }
  },
})

The context function always runs before any requested query. IF there's no user found that matches the authorization header, the entire request is blocked!

Group Authorization

The next thing we want to do is allow the user access to parts of the schema if they are allowed. Let's say we only allow the doctors to access patient info. It would now be very tempting to go into the resolver for the patients query and do this:

patients: (root, args, context) => {
  // We could also throw an error again. That's up to you!
  if (context.user.role !== 'doctor') return [];

  return ['Carl', 'Hank'];
}

However, this could quickly become a problem when there's multiple to ways to query for patient data. If our full schema looked like this:

type Patient {
  name: String
}

type Hospital {
  name: String
  patients: [Patient!]!
}

type Query {
  patients: [Patient!]!
  hospitals: [Hospital!]!
}

Now we need to duplicate the doctor check inside the hospitals resolver!

Models

A better way to do this is by splitting your authorization logic into a separate layer, separated from your resolver logic. This is described in more detail in Thinking in Graphs

We can for instance create a model for the Patient type that looks like this:

const Patient = {
  getAll() {...}
  getById(id) {...}
  getByHospitalId(hospitalId) {...}
}

Now our Patient model is the single source of truth for business logic concerning our Patient type! We just need a way to tell our models about our authenticated user.

// models/Patient.js
export const createPatientModel = ({ user }) => ({
  getAll() {...}
  getById(id) {...}
  getByHospitalId(hospitalId) {...}
})

// graphl handler
export const handler = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    const user = await getUser(req.header.authorization)

    if (!user) throw new AuthorizationError('You are not logged-in!');

    const Patient = createPatientModel({ user })

    return { user, models: { Patient } }
  },
})

There we go! We pass the Patient model and any other models on the context as well, so they're accessible in our resolvers:

// Query.patients resolver
patients: (root, args, context) => {

  // The doctor authorization is handled in the Patient model
  return context.models.Patient.getAll()
}

Ownership Authorization

Let's say we want even more fine-grained authorization for our doctors. Doctors should only be able to view information about their own patients. We can now go into our Patient model and change the required permissions, as opposed to editing all the different resolvers. Here's an example of filtering a doctor's patients if you're using Prisma 2:

export const createPatientModel = ({ user }) => ({
  getAll() {
    return db.patient.findMany({ where: { doctor: { id: user.id } } })
  },
  getByHospitalId(hospitalId) {
    return db.patient.findMany({
      where: { doctor: { id: user.id }, hospital: { id: hospitalId } }
    })
  }
})

I'll leave it up to you to generalize the ownership part of the where clause!

Conclusion

There's many different ways to handle authorization in a GraphQL server. This is my favourite one. Separating your business/authorization logic from your resolver logic makes your code more readable and maintainable!

React Single File Components with XState

Robert — Sun, 29 Mar 2020 11:23:55 +0000

After reading React Single File Components Are Here by @swyx and trying out RedwoodJS's Cells I noticed these SFC's look a lot of state machines!

Shawn's first example (reduced for brevity):

export const QUERY = gql`
  query {
    posts {
      id
      title
      body
      createdAt
    }
  }
`;

export default function MyComponent() {
  const { loading, error, data: posts } = useQuery(QUERY);
  if (error) return <div>Error loading posts: {error.message}</div>;
  if (loading) return <div>Loading...</div>;
  if (!posts.length) return <div>No posts yet!</div>;

  return posts.map(post => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ));
}

Looks a lot like something you would do using xstate:

export const fetchMachine = Machine(...);

export default function MyComponent() {
  const [state, send] = useMachine(fetchMachine);
  const { error, posts } = state.context;

  if (state.matches("error"))
    return <div>Error loading posts: {error.message}</div>;

  if (state.matches("loading")) return <div>Loading...</div>;

  if (!posts.length) return <div>No posts yet!</div>;

  return posts.map(post => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ));
}

Redwood Cells

Here's what Redwood Cells look like:

export const QUERY = gql`
  query {
    posts {
      id
      title
      body
      createdAt
    }
  }
`;

export const Loading = () => <div>Loading...</div>;

export const Empty = () => <div>No posts yet!</div>;

export const Failure = ({ error }) => <div>Error loading posts: {error.message}</div>;

export const Success = ({ posts }) => {
  return posts.map(post => (
    <article>
      <h2>{post.title}</h2>
      <div>{post.body}</div>
    </article>
  ));
};

Behind the scenes, Redwood executes the exported GraphQL query and renders the component that matches the state of the request automatically.

What if we could write the UI for our state machine in such a way? For every state you could export a matching component. Let's say our state machine from the previous example looks something like this:

A basic machine that fetches an arbitrary request, saves the data on success and saves the error on failure. It could have the exact same SFC implementation as a Redwood Cell!

But what about a different state machine? Let's try this one:

It's a very basic machine for a flower that starts as a seedling, grows when you water it, wilts when you don't water it, and dies when you don't water it when it's wilting. Check it out in the sandbox below!

How would the code for this machine UI look in a SFC format? I'd say kind of like this:

export const Seedling = () => 🌱

export const Grown = () => 🌹

export const Wilting = () => 🥀

export const Dead = () => 💀

Cool, right? Now this example is pretty basic, but it makes the UI very readable. Another potential benefits to defining state UI this way could be that if you pass your machine's context to the SFC you can be certain of some piece of context being available inside a state component, eliminating the need for null checks. Kind of like with TypeStates

E.g. in the fetch example:

export const Success = ({ context }) => {
  // Here I am certain context.data is available. No need for
  // if (context.data) return </Stuff >
  // or even
  // state.matches('success') return <Stuff />
  // The latter is abstracted away in our tooling
}

Ok, but why?

Is this useful? I'm not sure! It has the benefits of single file components, it could make your state machine-driven UI more readable, it might prevent even more bugs than using state machines in general, but doing this would probably also have some downsides.

What if I want some piece of UI to be shared between multiple states? The plant example has 3 states that allow you to water (seedling, grown, wilting) and 1 state that doesn't (dead). Now what? Do I duplicate the watering UI 3 times? Maybe that piece of UI should live outside of my state component? Or perhaps I think about re-designing my machine. I could change my machine to look like this:

It now has 2 main states, alive and dead. You can only water it when it's alive. This would change my file to export 2 components: Alive and Dead. Where Alive needs some kind of way to display the sub machine. Perhaps a second file with Seedling, Grown and Wilting, I don't know, I didn't think this far yet!

To conclude; these are all just thoughts, and since you've made it this far, I'd love to hear yours as well! Do you think defining your UI this way could be useful, or it's just limiting?

Undo/Redo in React Using XState

Robert — Sun, 22 Mar 2020 14:11:23 +0000

I recently came across the need for undo and redo functionality in my app.

The app is an editor of sorts that allows you to add stuff and remove stuff using several different tools and keyboard shortcuts. All implemented using xstate.

It would be great to be able to undo and redo actions taken in the editor! Let's see how we can implement the undo/redo pattern from the Redux docs in XState.

Let's say we have the following machine:

const editorMachine = Machine(
  {
    id: "editor",
    context: {
      items: []
    },
    initial: "normal",
    on: {
      DELETE_SHAPE: {
        actions: ["deleteShape"]
      }
    },
    states: {
      normal: {
        on: {
          TOGGLE_MODE: "turbo",
          ADD_SHAPE: {
            actions: ["addShape"]
          }
        }
      },
      turbo: {
        on: {
          TOGGLE_MODE: "normal",
          ADD_SHAPE: {
            actions: ["addThreeShapes"]
          }
        }
      }
    }
  },
  {
    actions: {
      addShape: assign({
        items: (ctx, e) => [...ctx.items, e.shape]
      }),
      addThreeShapes: assign({
        items: (ctx, e) => [...ctx.items, e.shape, e.shape, e.shape]
      }),
      deleteShape: assign({
        items: (ctx, e) => [
          ...ctx.items.slice(0, e.index),
          ...ctx.items.slice(e.index + 1)
        ]
      })
    }
  }
);

Which matches the following visualization:

There's basically 2 states:

Normal, in which you can add 1 shape at a time to the list of items.
Turbo, in which you can add 3 shapes at a time to the list of items.

In both states you can delete a shape (you pass the shape's list index to the event, e.g. by clicking on it).

To be able to undo/redo our mutations to the items context, we need to do a few things (taken from The Redux Doc on Undo/Redo):

Handling Undo

Remove the last element from the past.
Set the present to the element we removed in the previous step.
Insert the old present state at the beginning of the future.

Handling Redo

Remove the first element from the future.
Set the present to the element we removed in the previous step.
Insert the old present state at the end of the past.

Handling Other Actions

Insert the present at the end of the past.
Set the present to the new state after handling the action.
Clear the future.

Here's what that looks like in our Machine:

const editorMachine = Machine(
  {
    id: "editor",
    context: {
      // Keep track of the past
      past: [],

      // Our present
      items: [],

      // Keep track of the future
      future: []
    },
    initial: "normal",
    states: {
      on: {
        DELETE_SHAPE: {
          // Update the past when we delete a shape
          actions: ["updatePast", "deleteShape"]
        },
        UNDO: {
          actions: ["undo"]
        },
        REDO: {
          actions: ["redo"]
        }
      },
      normal: {
        on: {
          TOGGLE_MODE: "turbo",
          ADD_SHAPE: {
          // Update the past when we add a shape
            actions: ["updatePast", "addShape"]
          }
        }
      },
      turbo: {
        on: {
          TOGGLE_MODE: "normal",
          ADD_SHAPE: {
            // Update the past when we add 3 shapes
            actions: ["updatePast", "addThreeShapes"]
          }
        }
      }
    },
  },
  {
    actions: {
      addShape: assign({
        items: (ctx, e) => [...ctx.items, e.shape]
      }),
      addThreeShapes: assign({
        items: (ctx, e) => [...ctx.items, e.shape, e.shape, e.shape]
      }),
      deleteShape: assign({
        items: (ctx, e) => [
          ...ctx.items.slice(0, e.index),
          ...ctx.items.slice(e.index + 1)
        ]
      }),

      // # Handling Other Actions
      updatePast: assign({
        // 1. Insert the present at the end of the past.
        past: ctx => [...ctx.past, ctx.items],

        // 2. Set the present to the new state after handling the action.
        // ! This happens in the 3 specific actions above

        // 3. Clear the future.
        future: []
      }),

      // # Handling Undo
      undo: assign(ctx => {
        const previous = ctx.past[ctx.past.length - 1];

        // 1. Remove the last element from the past.
        const newPast = ctx.past.slice(0, ctx.past.length - 1);
        return {
          past: newPast,

          // 2. Set the present to the element we removed in step 1.
          items: previous,

          // 3. Insert the old present state at the beginning of the future.
          future: [ctx.items, ...ctx.future]
        };
      }),

      // # Handling Redo
      redo: assign(ctx => {
        const next = ctx.future[0];

        // 1. Remove the first element from the future.
        const newFuture = ctx.future.slice(1);
        return {

          // 2. Set the present to the element we removed in step 1.
          items: next,

          // 3. Insert the old present state at the end of the past.
          past: [...ctx.past, ctx.items],
          future: newFuture
        };
      })
    }
  }
);

And that's all! Now we have all the benefits of state machines combined with an undo/redo system on our extended state. We can craft a robust, complex editor (think of all the tools in the Photoshop toolbox) while keeping our undo/redo system simple!

Check out the CodeSandbox for an implemented example.

Stateful Styles With XState and Styled System

Robert — Fri, 13 Mar 2020 15:17:31 +0000

You've probably seen a button like this one before:

<Button>Cool Button</Button>

One that has options:

<Button secondary>Secondary Cool Button</Button>

Maybe even more options:

<Button tertiary>Tertiary Cool Button</Button>

But what if I did this?

<Button secondary tertiary>Secondary? Cool Button</Button>

That's probably not allowed. I guess we'll change the API to avoid that:

<Button variant="secondary">Secondary Cool Button</Button>

This is kind of a state machine! Your Button can only be in one variant (state) at a time.

Here's what a parallel state machine (basically multiple independent state machines) would look like:

<Button variant="secondary" mode="dark">Dark Secondary Cool Button</Button>

I've found that these kind of style props work very well with logical state machines. Check out the following example of a... thing:

It's a parallel state machine with 3 sub machines:

One machine that let's you change the shape:
- From Circle to Square
- From Square to Diamond
- From Square to Circle
- From Diamond to Square
One machine that let's you change the color:
- From Red to Blue
- From Blue to Green
- From Green to Red
One machine that let's you change the size:
- From Small to Big
- From Big to Small

If we want to craft some stateful styles for this thing, we'd need a component with an API like this:

<Thing shape="circle|square|diamond" color="red|blue|green" size="small|big" />

You can implement it however you like, but what I like to do is use styled-system's variant API, because it maps nicely to the state machines we defined:

import styled from 'styled-components'
import { variant } from 'styled-system'

const Thing = styled(
  variant({
    prop: 'shape',
    variants: {
      square: {
        /** Make it square */
      },
      circle: {
        /** Make it circular */
      },
      diamond: {
        /** Make it a diamond */
      },
    },
  }),
  variant({
    prop: 'color',
    // ...
  }),
  variant({
    prop: 'size',
    // ...
  })
)

(You can use it with either Emotion or Styled Components)

Now to wire it up to our state machine using xstate and @xstate/react

function App() {
  const [state, send] = useMachine(shapeMachine);

  return <Shape {...state.value} />
}

Ta-da! A little explanation:
In case of a hierarchical or parallel state machine, ours being the latter, state.value contains an object representation of our current state (check the docs for more info). Our state could look something like this:

// state.value
{
  shape: "circle",
  color: "red",
  size: "small"
}

Which happens to look exactly like our component's prop interface! Of course you can also do this if you want your code to be a bit more explicit and readable:

function App() {
  const [state, send] = useMachine(shapeMachine);

  const { shape, size, color } = state.value
  return <Shape shape={shape} size={size} color={color} />
}

Here's a CodeSandbox with a fully working example.

Building a Generic State Machine for Form Handling Using XState

Robert — Sun, 08 Mar 2020 13:32:03 +0000

If you're a computer scientist or follow @davidkpiano you've probably heard about state machines.

They are awesome.

Here's an example of how to use one for form handling!

Our designer says the form should look like this:

From this concept we can deduce four "states":

Editing
Submitting
Error
Success

Let's define the states in a machine:

const formMachine = Machine({
  // We'll start in the editing state
  initial: 'editing',
  states: {
    editing: {},
    submitting: {},
    error: {},
    success: {},
  },
})

Editing State

While in the editing state, we can do 2 things:

Type in the fields. We stay in the same state. We of course also want the input to be saved.
Submit the form. We transition to the submitting state.

Let's define the transitions and actions:

const formMachine = Machine(
  {
    initial: 'editing',
    // Context contains all our infinite state, like text input!
    context: {
      values: {},
    },
    states: {
      editing: {
        on: {
          CHANGE: {
            // Stay in the same state
            target: '',

            // Execute the onChange action
            actions: ['onChange'],
          },
          SUBMIT: 'submitting',
        },
      },
      submitting: {},
      error: {},
      success: {},
    },
  },
  {
    actions: {
      // Assign
      onChange: assign({
        values: (ctx, e) => ({
          ...ctx.values,
          [e.key]: e.value,
        }),
      }),
    },
  },
)

Submitting State

After submitting the form, our life could go one of two ways:

The submission is succesful, we move to the success state.
The submission failed, we move to the error state.

To keep our machine generic, we'll leave the whatever happens during the submission up to the consumer of the machine by invoking a service. Allowing the consumer to pass in their own service (See Invoking Services). Be it frontend validation, backend validation or no validation, we don't care! The only thing we'll do is transition based on a succesful or unsuccesful response, storing the error data on an unsuccesful response.

const formMachine = Machine(
  {
    initial: 'editing',
    context: {
      values: {},
      errors: {},
    },
    states: {
      editing: {
        on: {
          CHANGE: {
            target: '',
            actions: ['onChange'],
          },
          SUBMIT: 'submitting',
        },
      },
      submitting: {
        invoke: {
          src: 'onSubmit',
          // Move to the success state onDone
          onDone: 'success',
          onError: {
            // Move to the error state onError
            target: 'error',

            // Execute onChange action
            actions: ['onError'],
          },
        },
      },
      error: {},
      success: {},
    },
  },
  {
    actions: {
      onChange: assign({
        values: (ctx, e) => ({
          ...ctx.values,
          [e.key]: e.value,
        }),
      }),
      onError: assign({
        errors: (_ctx, e) => e.data,
      }),
    },
  },
)

Error State

Uh-Oh! We've stumbled upon a few errors. The user can now do two things:

Change the inputs.
Submit the form again.

Hey, these are the same things we could do in the editing state! Come to think of it, this state is actually pretty similar to editing, only there are some errors in the screen. We could now move the transitions up to the root state, allowing us to ALWAYS change the inputs and ALWAYS submit the form, but obviously we don't want that! We don't want the user to edit the form while it's submitting. What we can do is make the editing state hierarchical with 2 substates: pristine (not submitted) and error (submitted and wrong):

const formMachine = Machine(
  {
    initial: 'editing',
    context: {
      values: {},
      errors: {},
    },
    states: {
      editing: {
        // We start the submachine in the pristine state
        initial: 'pristine',
        // These transitions are available in all substates
        on: {
          CHANGE: {
            actions: ['onChange'],
          },
          SUBMIT: 'submitting',
        },
        // The 2 substates
        states: {
          pristine: {},
          error: {},
        },
      },
      submitting: {
        invoke: {
          src: 'onSubmit',
          onDone: 'success',
          onError: {
            // Note that we now need to point to the error substate of editing
            target: 'editing.error',
            actions: ['onError'],
          },
        },
      },
      success: {},
    },
  },
  {
    actions: {
      onChange: assign({
        values: (ctx, e) => ({
          ...ctx.values,
          [e.key]: e.value,
        }),
      }),
      onError: assign({
        errors: (_ctx, e) => e.data,
      }),
    },
  },
)

Success State

We did it! A succesful submission. According to the designs there's only one thing left to do here:

Add another form submission.

Easy peasy, we just transition back to the initial form!

const formMachine = Machine(
  {
    initial: 'editing',
    context: {
      values: {},
      errors: {},
    },
    states: {
      editing: {
        initial: 'pristine',
        on: {
          CHANGE: {
            actions: ['onChange'],
          },
          SUBMIT: 'submitting',
        },
        states: {
          pristine: {
            // This is up to you, but I felt like the form needed to be cleared before receiving a new submission
            entry: ['clearForm'],
          },
          error: {},
        },
      },
      submitting: {
        invoke: {
          src: 'onSubmit',
          onDone: 'success',
          onError: {
            target: 'editing.error',
            actions: ['onError'],
          },
        },
      },
      success: {
        on: {
          AGAIN: 'editing',
        },
      },
    },
  },
  {
    actions: {
      onChange: assign({
        values: (ctx, e) => ({
          ...ctx.values,
          [e.key]: e.value,
        }),
      }),
      clearForm: assign({
        values: {},
        errors: {},
      }),
      onError: assign({
        errors: (_ctx, e) => e.data,
      }),
    },
  },
)

And that's it! A basic generic state machine that you could use on "any" form using any validation library or method that you want.

Checkout the interactive visualization here

For the full machine code and an implementation in React using @xstate/react, check out this CodeSandbox

UI is implemented using the awesome Chakra UI

Multiple Authentication Types in AWS Amplify

Robert — Mon, 02 Mar 2020 17:34:52 +0000

The goal is to create a backend that allows us to:

Signup and login
Create and manage posts through a GraphQL API
Enable everyone (also unauthenticated users) to READ all posts
Prevent users from editing posts by others

We run the following commands to setup our Amplify project:

amplify init
? Initialize amplify with your prefered settings

amplify add auth
? Do you want to use the default authentication and security configuration
Default configuration

? How do you want users to be able to sign in?
Username

? Do you want to configure advanced settings?
No, I am done.

# I went with all the defaults. Configure however you'd like!

amplify add api

? Please select from one of the below mentioned services: 
GraphQL

? Provide API name: 
amplifyPosts

? Choose the default authorization type for the API Amazon Cognito User Pool
Use a Cognito user pool configured as a part of this project.
# Using cognito user pool for signing up and logging in users

? Do you want to configure advanced settings for the GraphQL API 
Yes, I want to make some additional changes.

? Configure additional auth types? 
Yes

? Choose the additional authorization types you want to configure for the API 
API key
# A public API Key is needed to read ALL the posts

API key configuration
? Enter a description for the API key: 
amplifyPosts

? After how many days from now the API key should expire (1-365): 
7

? Configure conflict detection? 
No

? Do you have an annotated GraphQL schema? 
No

? Do you want a guided schema creation? 
Yes

? What best describes your project: 
Single object with fields (e.g., “Todo” with ID, name, description)

? Do you want to edit the schema now? 
Yes
# This is where you copy and paste the schema below

✔ GraphQL schema compiled successfully.

amplify add codegen

? Choose the code generation language target 
javascript

? Enter the file name pattern of graphql queries, mutations and subscriptions
src/graphql/**/*.js

? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions 
Yes

? Enter maximum statement depth [increase from default if your schema is deeply nested] 
2

✔ Generated GraphQL operations successfully and saved at src/graphql

The schema:

type Post
  @model
  @auth(
    rules: [
      # The owner is allowed to do everything
      { allow: owner }
      # The public is only allowed to read posts
      { allow: public, operations: [read] }
    ]
  ) {
  id: ID!
  title: String!
  content: String
  owner: String
}

At this point we can either run amplify push to deploy our backend, or amplify mock to mock our backend locally (this still required you to deploy the auth module first, but the mock command will guide you through that!)

At this point, add some users and posts to the backend by writing some mutations in the Amplify Console (or in the GraphiQL client at http://localhost:20002 if you used amplify mock).

After you push or mock your backend, Amplify will generate some files for you in your specified src directory:

aws-exports.js - A configuration file for our frontend to communicate with our backend
src/graphql/{mutations,queries,subscriptions}.js - A starting point for GraphQL queries so we don't have to write them ourselves (you can write more optimized ones tho if you want!)

Now's the time to consume the backend in our frontend.

Install aws-amplify and whatever aws package that fits your framework (We use react and aws-amplify-react):

yarn add aws-amplify aws-amplify-react

Somewhere high up in our component tree, we configure Amplify:

import Amplify from 'aws-amplify'
import awsconfig from '../aws-exports'

Amplify.configure(awsconfig)

To query for the posts created by the authenticated user:

import React, { useState, useEffect } from 'react'
import { API, graphqlOperation } from 'aws-amplify'
import { withAuthenticator } from 'aws-amplify-react'
import { listPosts } from '../graphql/queries'

const MyPostsScreen = () => {
  const [myPosts, setMyPosts] = useState([])

  useEffect(() => {
    async function getPosts() {
      const { data } = await API.graphql(graphqlOperation(listPosts))
      setMyPosts(data.listPosts.items)
    }

    getPosts()
  }, [])

  return (
    <div>
      My Posts:
      <ul>
        {myPosts.map(post => (
          <Post key={post.id} post={post} />
        ))}
      </ul>
    </div>
  )
}

// withAuthenticator wraps our components in a signup/login, which makes sure we are logged in when accessing this component!
export const AuthenticatedMyPostsScreen = withAuthenticator(MyPostsScreen)

Now, to query for ALL posts, all we need to do is switch the authMode to API_KEY:

import React, { useState, useEffect } from 'react'
import { API } from 'aws-amplify'
import { listPosts } from '../graphql/queries'

export const AllPostsScreen = () => {
  const [allPosts, setAllPosts] = useState([])

  useEffect(() => {
    async function getPosts() {
      // Switch authMode to API_KEY
      const { data } = await API.graphql({ 
        query: listPosts, 
        authMode: 'API_KEY',
      })
      setPosts(data.listPosts.items)
    }

    getPosts()
  }, [])

  return (
    <div>
      All Posts:
      <ul>
        {allPosts.map(post => (
          <Post key={post.id} post={post} />
        ))}
      </ul>
    </div>
  )
}

That's it! Because of the way our GraphQL schema uses the @auth directive, it is still impossible to edit posts that you don't own. Trying to run a mutation using authMode: 'API_KEY' will result in an Unauthorized error.

It took me a while to figure out you need to switch the authMode. If there's a better or easier way to do this, I'd love to hear about it!

Cheers.

Quick Tip - Memoizing change handlers in React Components

Robert — Mon, 01 Oct 2018 15:58:49 +0000

Let's consider a basic form with a controlled component in react:

class Form extends React.Component {
  state = {
    value: '',
  };

  handleChange = e => {
    this.setState({
      value: e.target.value,
    });
  };

  render() {
    return (
      <div>
        <InputComponent type="text" value={this.state.value} onChange={this.handleChange} />
      </div>
    )
  }
}

We keep a state, pass the value to our InputComponent, and update the value with the value we get from it.

Now consider this larger form. I like to use this arrow-function-that-returns-another-arrow-function (what do you call this?) syntax for brevity and to not have to repeat myself with multiple change handlers.

class BiggerForm extends React.Component {
  state = {
    a: '',
    b: '',
    c: '',
  };

  handleChange = key => e => {
    this.setState({
      [key]: e.target.value,
    });
  };

  render() {
    return (
      <div>
        <InputComponent type="text" value={this.state.a} onChange={this.handleChange('a')} />
        <InputComponent type="text" value={this.state.b} onChange={this.handleChange('b')} />
        <InputComponent type="text" value={this.state.c} onChange={this.handleChange('c')} />
      </div>
    )
  }
}

Looks easy, right? The problem with this is that this.handleChange() will create a new function every time it is called. Meaning everytime BiggerForm re-renders, all the InputComponents will re-render. Meaning EVERYTHING will re-render on EVERY keystroke. You can imagine what this would do to a huge form.

Now what we could do is either split handleChange into specific change handlers, e.g. handleChangeA, handleChangeB, handleChangeC, and this would solve our issue. But this is a lot of repetition, and considering we are considering huge forms; a lot of tedious work.

Luckily there's this thing called memoization! Which in short is a caching mechanism for our functions. Sounds fancy, but all it does is remember which arguments yield what result when calling a function. When the function is called again with the same arguments, it will not execute the function, but just return the same result. In our example:

class MemoizeForm extends React.Component {
  state = {
    a: '',
    b: '',
    c: '',
  };

  handleChange = memoize(key => e => {
    this.setState({
      [key]: e.target.value,
    });
  });

  render() {
    return (
      <div>
        <InputComponent type="text" value={this.state.a} onChange={this.handleChange('a')} />
        <InputComponent type="text" value={this.state.b} onChange={this.handleChange('b')} />
        <InputComponent type="text" value={this.state.c} onChange={this.handleChange('c')} />
      </div>
    )
  }
}

That was easy! In this example, on the first render of MemoizeForm, the handleChange function is called for every InputComponent with their specific key as an argument. Whenever MemoizeForm re-renders, handleChange is called again. However, since it's called with the same argument as before, the memoization mechanism returns the same function (with the same reference), and the InputComponent is not re-rendered (unless the value is changed ofcourse!).

🎉

P.S. Any memoization library will do, I like to use fast-memoize

-- EDIT --

I've only recently learned that event.target contains a lot more stuff! Using hooks you could just do:

const [state, setState] = useState(initialValues)

const handleChange = useCallback(e => {
  setState(values => ({ ...values, [e.target.name]: e.target.value }))
}), [])