Instead, I prefer to use an agent in the terminal to do rough sketching for a feature, and fill the gaps myself in a distraction-free environment. I might even ask for validation ("be critical, not a sycophant") for an approach, without requesting any code changes. For people like me who work in isolation and build features e2e, having an assistant that operates this way is very helpful.

Of course, I'll delegate some chore work, but in principle I want to write my own code.

I find that this works best for me, because it avoids the three deadly AI sins:

1. Making me lazy. I take pride in my work and don't want to push sloppy code.
2. Causing my skills to atrophy. I don't want my brain to switch off. The model might have good ideas, but most of the time I have better ones. These come from real-world experience, and that's what differentiates me from some other AI operator.
3. Making me lose the feeling of ownership. This is where teams fail. No one wants to take ownership, stuff falls through cracks, and bad things happen. In contrast, when I write the code, I know exactly why I did it this way, and it's my responsibility to maintain it.

So this is where I draw the line with AI in my workflow. Things might change, but I get a significant productivity boost without noticeable drawbacks.

I find the best kind of onboarding (if the team allows it), is to look at the long-standing issues and try to fix them. It helps you understand the codebase much better. That's what I did.

The Rails/Webpacker/React crossroad

Last year, I was facing the following issue in a codebase that was running on Rails and React:

• Webpacker was used to bundle the React code. But it was discontinued in Rails 7 without a clear and easy upgrade path to anything
• With Webpacker in limbo, the Node version was stuck on 16.x, with 22.x being the latest LTS
• The tests were written with Enzyme, which was abandoned after 2021
• Enzyme was blocking the React upgrade, as it was incompatible with React 18.x
• The legacy context API was used
• Apollo Client, Jest, and MSW were outdated as well

Essentially, we had two big blockers.

Node was blocked by Webpacker, and React was blocked by Enzyme. Everything else was blocked due to the first two.

Looking for a Webpacker replacement

While the JavaScript ecosystem is often messy, nothing prepared me for this letdown from the Ruby world. I was also slightly annoyed that DHH celebrated moving away from Webpack as a win, while teams were left holding the hot potato.

Anyway, the last Webpacker version was v5. There was no v6 released except for a release candidate (v6.0.0-rc.6).

If you wanted to keep your webpack config, the two options were shakapacker & jsbundling-rails.

I initially looked at shakapacker, and the steps I had to take were:

• Upgrade from webpacker v5 to v6.0.0-rc.6 (handle whatever breaking changes there were)
• Migrate from webpacker v6.0.0-rc.6 to shakapacker v6 (can't upgrade from webpacker v5 directly)
• Upgrade to shakapacker v6.5.2 (there were a few changes needed)
• Upgrade to shakapacker v7 (a lot of breaking changes)

That said, I didn't go into that rabbit hole. Upgrading to v6.0.0-rc.6 was breaking already as we were on a newer Ruby version (v3.3.0).

bundle exec rails webpacker:install

       apply  /Users/dnlytras/.asdf/installs/ruby/3.3.0/lib/ruby/gems/3.3.0/gems/webpacker-6.0.0.rc.6/lib/install/template.rb
   identical    config/webpacker.yml
   identical    package.json
  Copying webpack core config
       exist    config/webpack
   identical    config/webpack/base.js
   identical    config/webpack/development.js
   identical    config/webpack/production.js
   identical    config/webpack/test.js
bin/rails aborted!
NoMethodError: undefined method `exists?' for class Dir (NoMethodError)

if Dir.exists?(Webpacker.config.source_path)
      ^^^^^^^^
Did you mean?  exist?

What a mess. I decided then, that even if I kept the webpack config, I still wouldn't want to maintain that pipeline. As much as I was annoyed with the rug pull, I never liked Webpack.

So, I opted for a move away from Webpack to Vite. I've used Vite before, and I was very happy with it. The only issue here is if there's a good integration with Rails.

I'm not a Ruby developer; this was my first Rails project. I had to learn a lot of things on the go. The team also had created an issue to migrate off Webpacker. So I wasn't being a weird newcomer suggesting to change the whole stack. I just took the opportunity to do it.

Moving from Webpacker to the Vite & Vite-Ruby

To my surprise, I found vite-ruby that has great integration with Rails, and gives a few pointers on how to migrate from Webpacker.

Eventually, I made it work. I don't want to expand much on the details, but it was mostly:

• Writing a new Vite config
• Moving from Webpacker packs to Vite entrypoints
• Trimming down unused dependencies
• Finding workarounds for some stimulus controllers to work with Vite
• Upgrading node versions in CI and locally, unlocking fetch
• Enabling fast refresh (no more full page reloads!)
• Dropping most of the Babel plugins, and only keeping what was needed (mostly for Jest)
• Enabled code splitting and lazy loading, reducing the bundle size by 60%. (Could also be done with Webpack, but it wasn't set up)

I hit pause for a few days to let the dust settle and monitor production. By that time, I had pretty much tested every flow in the app - what an onboarding experience! Nothing of note happened, so I label this a great success.

The only thing I missed was enabling emptyOutDir in the Vite config. As a consequence I would keep the outdated assets around, but that was an easy fix.

import react from '@vitejs/plugin-react';
import {defineConfig} from 'vite';
import commonjs from 'vite-plugin-commonjs';
import RubyPlugin from 'vite-plugin-ruby';

export default defineConfig({
  plugins: [
    RubyPlugin(),
    commonjs(),
    react({
      babel: {
        plugins: [''],
      },
    }),
  ],
  build: {
    emptyOutDir: true, // this was missing
    commonjsOptions: {
      transformMixedEsModules: true,
    },
    optimizeDeps: {
      include: [''],
    },
  },
});

Moving from Enzyme to React Testing Library

With hot-reload working, it was time to work on the React side of things. My team was using Enzyme for testing, but had already started writing new tests with React Testing Library (RTL).

As you might imagine, the migration process is very frustrating. Enzyme tests the implementation details, while React Testing Library tests the user experience, simulating normal user actions.

So let's say you're testing a chart component. Enzyme would check if the props are passed correctly, and if the lifecycle methods are called. You can change all props at will and simulate any scenario. With that out of the way, you face the harsh truth that your tests might have blind spots. To test the same component with RTL, you have to manually hover over the lines and bars, check the tooltips, axis calculations, and so on. Essentially you rewrite the whole test, there's zero overlap.

I started migrating a few tests per day. This unearthed a few bugs in the codebase (mostly due to the shallow rendering of Enzyme), but it gave me confidence that we actually test the right things.

It wasn't hard per se, but more of a tedious task that someone had to tackle consistently bit by bit. I also started experimenting with LLMs at that time, but I found that currently available models couldn't provide meaningful assistance for this task. Pain.

Upgrading React to v18

With Enzyme gone, the React upgrade was unblocked.

To my dismay though, I found a blocker for React 19. The PropTypes were discontinued. Moving to TypeScript is not an option for everyone, especially when your team writes the business logic in a dynamic language like Ruby. So I feel like React is dropping the ball here.

Anyway, that's a problem for the future, let's move on to React 18 first. Some of the changes I made was:

• Dropping the legacy context API
• Debugging some issues (hint: there were useEffect hooks returning null instead of undefined)
• Rewriting a few critical class components that were using UNSAFE_componentWillMount
• Removing defaultProps

Overall the process wasn't hard, it only had been delayed for a long time. Did we gain anything? I assume automatic batching, but I didn't see any noticeable performance improvements.

Upgrading Jest & React Testing Library

Lastly, I made a big version bump from v12 to v16 in React Testing Library. The details are kinda hazy right now, but the biggest changes were dropping the @testing-library/react-hook package, fixing some race conditions, and adding a few waitFor calls.

As for Jest, I took a jab at removing it in favour of Vitest, but I didn't have the energy. I just wanted to move on. Instead I decided to upgrade Jest from v27 to v29. Nothing much changed, I removed the resize-observer-polyfill, fixed a few issues with the snapshots, and had to install jest-environment-jsdom separately for my troubles.

I finished the refactor happy with the Vite migration, but the rest felt like a chore to be done. I didn't feel like I was getting anything out of it, and I was just upgrading stuff for the sake of it.

Other changes happening in the background

While I was doing the above, my team continued with:

• Migrating from Yarn v1 to NPM
• Upgrading Storybook
• Upgrading Eslint (still don't get what flat config offers to us)
• Class components to function components refactors
• Normal work that actually makes money

I was also doing normal work. My favorite feature was building a new charts library (that came with a D3 major bump upgrade as well).

I hadn't worked with D3 that intensely before, so I had to find a nice way to tie that with React, and implement features like zooming, comparing charts, toggling outliers, applying themes, locking, maintaining performance for big datasets, and so on.

I also worked on the Rails side of things, mumbling under my breath "OOP isn't real, OOP won't hurt you".

MSW and Apollo Client

The refactors took a pause, and a good deal of months passed. Recently I went back to the drawing board and picked two leftovers.

• Upgrading MSW from v0 to v1
• Upgrading Apollo Client from v2 to v3

The MSW upgrade was very tricky and the kind of refactors I hate the most. It's package that only serves purpose for development purposes, has breaking changes, and you don't really care to upgrade. I wasn't even sure if I should do it, but there were a few flakey tests related to MSW's setup, that were bothering me. Thankfully, LLMs were a much better help this time around. I also have the v2 version to upgrade to, but I'll get to that some other time.

After that, I focused on the Apollo Client. The biggest issue (and I'm glad for this change), was that the data became immutable/frozen. There were some runaway mutations happening in the codebase, and I was delighted to catch them.

Future improvements

I'm happy with the state of the codebase now. There are no dependencies that can block us from building features, and we can move forward with confidence. The only real thorn is how to upgrade to React 19.

• Do we move to TypeScript? I don't think so. I want to minimize the front-end logic, and simplify things.
• Do we drop prop-types and lose the implicit documentation that comes with it? It feels like going backwards. I don't want to have outdated JSDocs instead.
• Is the new RSC direction of React something that interests us? No, we use Rails. I'm excited to try it in Tanstack Start or React Router 7, but in the context of Rails it's absolutely useless.

This is something that I haven't come to terms yet. Not sure what to do.

Other than that, my only other goal is to re-evaluate Vitest and its browser-mode feature. I feel we can make tests faster, drop the leftover babel plugins, and simplify our tests without mocking stuff like getComputedStyle.

Final thoughts

As I proofread this, I can't help to think that a good chunk of this work could have been avoided if we didn't combine React with Rails. Webpacker really slowed us down, and the unexpected retirement made things even worse.

I can't speak about Turbo, Hotwire or Stimulus, as I haven't developed with them. My only experience is with using applications built with them that feel sluggish and slow. I don't know if it's the framework, or the implementation, but I don't like it.

If I were to suggest a different approach, I would pick Inertia and completely drop Apollo as well. Of course Inertia wasn't as mature or widely known back then, but if anyone is considering between their in-house solution or shipping two apps, put Inertia on the table as well. Here are the docs for Rails and a great introduction by Evil Martians.

As for the never ending stream of dependency upgrades on the Javascript front, I don't mind it that much. I usually run npx check-updates -i and handle them every week. It only becomes a problem that compounds over time if not addressed regularly. That said, I still can't shake the feeling that we, developers, waste time on unnecessary upgrades like Eslint and Storybook.

I hope this was a fun read. If you find yourself in the same situation regarding React 19 and PropTypes, feel free to reach out. I would love to hear your thoughts on it.

Resources:

• Modern web apps without JavaScript bundling or transpiling (DHH)
• Upgrading from Webpacker v5 to Shakapacker v6
• Switch from Webpacker 5 to jsbundling-rails with webpack
• Vite Ruby
• Enzyme is dead, now what
• Migrate from Enzyme
• How to Upgrade to React 18
• React 19 Upgrade Guide
• Inertia.js in Rails: a new era of effortless integration

• Introduction
• Why not LiveView
• What's Inertia exactly?
• Setting up Inertia
• Code splitting
• Routing
• Pages and controllers
• Authentication
• Caveats
• Final thoughts

Introduction

I love React. I've worked with various people and companies, and I've seen its power in action. I've also seen some of the worst things done with it, but fixing those buys "Little Dutch" toys for my daughter, so I have no complaints there.

Jokes aside, React has a massive ecosystem and, most importantly, known unknowns. It's considered boring technology now (at least the SPA parts), and the problem you might have has already been tackled and documented somewhere.

My pain point has always been the back-end of things in JavaScript. Next.js is utterly unreliable for reasons I won't expand on here, and everything else (Remix/RR, TanStack) doesn't have opinions on trivial stuff I don't want to configure. On the other hand, frameworks like Rails and Laravel have great solutions but use languages I don't enjoy that much. So, Phoenix strikes the perfect balance.

To put these two frameworks together without having to ship two separate applications, I use Inertia.

Why not LiveView

While writing this post, I realized that I had to justify why I'm not using LiveView. If you're aware of Phoenix, chances are that you've heard of LiveView as well; there's a lot of hype around it.

Ultimately, I wrote too much about it and had to move it to a separate post. You can find my ramblings here.

In short, LiveView is not a good fit for my apps. For the past few years, I've worked heavily on building charts and data visualizations across different companies. My ability to build these in React, prototype something quickly, and then hand it off to a designer to polish is unmatched.

LiveView is a phenomenal choice if your use case doesn't need a lot of interactivity. Use it, and don't bother what I think.

What's Inertia exactly?

The idea behind Inertia is simple.

We want to replace the server-rendered views with JavaScript page components.

On the very first user visit, we return the full page. We also include a JSON payload with the initial data in the HTML. Then, the JavaScript framework of our choosing boots up and takes over.

It will listen for clicks, form submissions, and other events and send XHR requests to the server. Even simple links will be intercepted, and an HXR request will be sent. Assuming these requests to the backend have the X-Inertia header, the server responds with a JSON payload.

This JSON payload contains everything the front-end needs to render the page. It includes the component to render, any shared props, errors from validations, and flash messages.

While the idea is simple, many small details make it great. For example, you can request a subset of the data if you're revisiting the same page.

So, Inertia is not exactly a framework but a protocol implemented by different adapters. There are three server-side adapters (Laravel, Rails, and Phoenix), and three client-side adapters (React, Vue, Svelte).

Feel free to check out the docs page for more details.

Setting up Inertia

Everything I needed was perfectly documented in the Phoenix adapter.

Surprisingly, I didn't have to do much—mostly just copy-pasting the instructions. I made a few modifications in the config.ex and added a plug in router.ex.

After setting everything up, the front-end side of things works exactly as expected. We take advantage of Phoenix's asset pipeline (esbuild), and we're good to go.

I honestly expected some friction, but there was none. Here's what my front-end entry point looks like:

import {createInertiaApp} from '@inertiajs/react';
import axios from 'axios';
import React from 'react';
import {createRoot} from 'react-dom/client';

axios.defaults.xsrfHeaderName = 'x-csrf-token';

createInertiaApp({
  title: (title) => `${title} - horionos`,
  resolve: async (name) => {
    return await import(`./pages/${name}.jsx`);
  },
  setup({App, el, props}) {
    createRoot(el).render(<App {...props} />);
  },
});

and what the rest of the assets folder looks like:

assets/
├── css/
├── js/
│   ├── components/
│   ├── hooks/
│   ├── layouts/
│   ├── lib/
│   └── pages/
│       ├── auth/
│       ├── 404.jsx
│       ├── 500.jsx
│       ├── home-page.jsx
│       ├── user-preferences-page.jsx
│       ├── user-settings-page.jsx
│       └── app.jsx
├── .prettierrc
├── eslint.config.mjs
├── package-lock.json
├── package.json
├── tailwind.config.js # Luckily, soon to be removed in tailwindcss v4
└── tsconfig.json

I appreciate the simplicity of this setup.

On the backend, my business logic in lib is untouched, and I only have my controllers to update. For example, I only replaced the render function with render_inertia in my generated user_session_controller.

defmodule HorionosWeb.UserSessionController do
  use HorionosWeb, :controller

  alias Horionos.Accounts
  alias HorionosWeb.UserAuth

  def new(conn, _params) do
    # render(conn, :new, error_message: nil) # Before
    render_inertia(conn, "auth/login-page")  # After
  end

  def create(conn, %{"user" => user_params}) do
    %{"email" => email, "password" => password} = user_params

    if user = Accounts.get_user_by_email_and_password(email, password) do
      UserAuth.log_in_user(conn, user, user_params)
    else
      # In order to prevent user enumeration attacks, don't disclose whether the email is registered.
      conn
      |> put_flash(:error, "You have entered an invalid email or password.")
      |> redirect(to: ~p"/users/log_in")
    end
  end

  def delete(conn, _params) do
    UserAuth.log_out_user(conn)
  end
end

Code splitting

The first challenge I had to solve was optimizing the bundle size. Without any modifications, you download everything at once, even pages you won't visit, and that isn't ideal.

I took a jab to fix it with React.lazy but realized there's nothing React or Inertia specific here. Since Phoenix uses esbuild, this is where I should look.

Enabling code splitting was straightforward, with the caveat that I had to ship the code as ES modules. For the full instructions, here's my PR to the Phoenix adapter.

In short, the changes needed are --splitting & --format=esm.

config :esbuild,
  version: "0.21.5",
  horionos: [
    args:
      ~w(js/app.jsx --bundle --chunk-names=chunks/[name]-[hash] --splitting --format=esm --target=es2020 --outdir=../priv/static/assets --external:/fonts/* --external:/images/* --loader:.js=jsx --loader:.jsx=jsx --loader:.ts=ts --loader:.tsx=tsx ),
    cd: Path.expand("../assets", __DIR__),
    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
  ]

With that out of the way, we only have to download the code we need.

Using ES modules might be a blocker for some. It's a limitation of esbuild, and not Inertia. Laravel for example, uses Vite which in turn uses Rollup for the production builds. I don't know what Rails uses this year, so I can't comment. (I'm still salty about a painful Webpacker migration)

Routing

Here's another thing that I love about Inertia. It has no opinions on routing. Our backend is responsible for these decisions.

Of course you still have to make some decisions on the front-end side, especially regarding how to structure your nested layouts (if applicable).

Here's what my router looks like:

# .. imports and plugs

# Guest routes
scope "/", HorionosWeb do
  pipe_through [:browser, :redirect_if_user_is_authenticated]

  get "/users/register", UserRegistrationController, :new
  post "/users/register", UserRegistrationController, :create
  get "/users/log_in", UserSessionController, :new
  post "/users/log_in", UserSessionController, :create
  get "/users/reset_password", UserResetPasswordController, :new
  post "/users/reset_password", UserResetPasswordController, :create
  get "/users/reset_password/:token", UserResetPasswordController, :edit
  put "/users/reset_password/:token", UserResetPasswordController, :update
end

# Authenticated routes
scope "/", HorionosWeb do
  pipe_through [:browser, :require_authenticated_user]

  get "/", HomeController, :home

  get "/users/preferences", UserPreferencesController, :edit
  put "/users/preferences", UserPreferencesController, :update

  get "/users/settings", UserSettingsController, :edit
  put "/users/settings", UserSettingsController, :update
  get "/users/settings/confirm_email/:token", UserSettingsController, :confirm_email
end

# Mixed routes
scope "/", HorionosWeb do
  pipe_through [:browser]

  delete "/users/log_out", UserSessionController, :delete
  get "/users/confirm", UserConfirmationController, :new
  post "/users/confirm", UserConfirmationController, :create
  get "/users/confirm/:token", UserConfirmationController, :edit
  post "/users/confirm/:token", UserConfirmationController, :update
end

# Catch all route
scope "/", HorionosWeb do
  pipe_through [:browser]

  get "/*path", ErrorController, :not_found
end

I love how clean and simple this is. Using live_sessions made this so hard for me to follow and reason about.

Pages and controllers

Now, let's see how we render a page in more detail. Let's take the users/preferences path and check out the controller:

defmodule HorionosWeb.UserPreferencesController do
  use HorionosWeb, :controller

  alias Horionos.Accounts

  def edit(conn, _params) do
    render_inertia(conn, "user-preferences-page")
  end

  def update(conn, params) do
    user = conn.assigns.current_user

    case Accounts.update_user_preferences(user, params) do
      {:ok, _user} ->
        conn
        |> put_flash(:info, "Preferences updated successfully")
        |> redirect(to: ~p"/users/preferences")

      {:error, changeset} ->
        conn
        |> assign_errors(changeset)
        |> redirect(to: ~p"/users/preferences")
    end
  end
end

There's nothing special here. Instead of rendering a template, we give the name of the JavaScript file to render.

You might notice the assign_errors function. It's a helper provided by the Phoenix adapter, which converts changeset errors to a client-side friendly format.

Now here's my user-preferences-page.jsx, which gets rendered:

import ComputerDesktopIcon from '@heroicons/react/20/solid/ComputerDesktopIcon';
import MoonIcon from '@heroicons/react/20/solid/MoonIcon';
import SunIcon from '@heroicons/react/20/solid/SunIcon';
import {Head} from '@inertiajs/react';
import {useForm} from '@inertiajs/react';
import React from 'react';

import {Button} from '~/components/button';
import {Divider} from '~/components/divider';
import {ErrorBoundary} from '~/components/error-boundary';
import {ErrorMessage, Field, Label} from '~/components/fieldset';
import {Heading, Subheading} from '~/components/heading';
import {Listbox, ListboxLabel, ListboxOption} from '~/components/listbox';
import {Text} from '~/components/text';
import {useCurrentUser} from '~/hooks/use-current-user';
import {MainLayout} from '~/layouts/main';

const THEMES = [
  {value: 'system', label: 'System', icon: ComputerDesktopIcon},
  {value: 'light', label: 'Light', icon: SunIcon},
  {value: 'dark', label: 'Dark', icon: MoonIcon},
];

const DATE_FORMATS = [
  {value: 'YYYY-MM-DD', label: 'YYYY-MM-DD'},
  {value: 'MM-DD-YYYY', label: 'MM-DD-YYYY'},
  {value: 'DD-MM-YYYY', label: 'DD-MM-YYYY'},
];

function Page() {
  const user = useCurrentUser();
  const preferencesForm = useForm({
    theme: user.preferences.theme,
    date_format: user.preferences.date_format,
  });

  function onPreferencesChangeSubmit(event) {
    event.preventDefault();

    preferencesForm.put('/users/preferences');
  }

  return (
    <MainLayout>
      <Head title="Preferences" />
      <div className="mx-auto max-w-4xl">
        <Heading>Preferences</Heading>
        <Divider className="my-10 mt-6" />
        <form onSubmit={onPreferencesChangeSubmit}>
          <section className="grid gap-x-8 gap-y-6 sm:grid-cols-2">
            <div className="space-y-1">
              <Subheading>Theme</Subheading>
              <Text className="text-balance">
                Choose a theme for the application. The theme will be applied to
                all pages.
              </Text>
            </div>
            <Field>
              <Label>Theme</Label>
              <Listbox
                name="theme"
                value={preferencesForm.data.theme}
                onChange={(value) => preferencesForm.setData('theme', value)}
                disabled={preferencesForm.processing}
              >
                {THEMES.map(({value, label, icon: Icon}) => (
                  <ListboxOption key={value} value={value}>
                    <ListboxLabel className="flex gap-2 items-center">
                      <Icon className="size-4" />
                      <span>{label}</span>
                    </ListboxLabel>
                  </ListboxOption>
                ))}
              </Listbox>
              {preferencesForm.errors.theme && (
                <ErrorMessage>{preferencesForm.errors.theme}</ErrorMessage>
              )}
            </Field>
          </section>
          <Divider className="my-10" soft />
          <section className="grid gap-x-8 gap-y-6 sm:grid-cols-2">
            <div className="space-y-1">
              <Subheading>Date format</Subheading>
              <Text className="text-balance">
                Choose how you want dates to be displayed.
              </Text>
            </div>
            <Field>
              <Label>Date format</Label>
              <Listbox
                name="date_format"
                value={preferencesForm.data.date_format}
                onChange={(value) =>
                  preferencesForm.setData('date_format', value)
                }
                disabled={preferencesForm.processing}
              >
                {DATE_FORMATS.map(({value, label}) => (
                  <ListboxOption key={value} value={value}>
                    <ListboxLabel>{label}</ListboxLabel>
                  </ListboxOption>
                ))}
              </Listbox>
              {preferencesForm.errors.date_format && (
                <ErrorMessage>
                  {preferencesForm.errors.date_format}
                </ErrorMessage>
              )}
            </Field>
          </section>
          <Divider className="my-10" soft />
          <div className="flex justify-end gap-4">
            <Button
              type="button"
              plain
              onClick={() => {
                preferencesForm.reset();
              }}
            >
              Reset
            </Button>
            <Button type="submit" disabled={preferencesForm.processing}>
              Save changes
            </Button>
          </div>
        </form>
      </div>
    </MainLayout>
  );
}

export default function UserPreferencesPage(props) {
  return (
    <ErrorBoundary>
      <Page {...props} />
    </ErrorBoundary>
  );
}

I'm bringing my favourite UI library, and I iterate without caring about the backend. I love it. I have complete front-end control.

If I want to tweak the backend response, I update my .ex files without opening a second repo. Everything works in harmony.

Now, you'll notice the useForm helper. This is the glue code that Inertia provides to handle form submissions.

You might also notice that I use snake_case sometimes. You have the option to camelize the props in the Inertia adapter config, but somehow mixing them doesn't annoy me 🤔

I won't lie. I miss the way I handle forms with Remix/RR. I don't enjoy having to event.preventDefault my forms or not using FormData. But I'm willing to make that trade-off for the productivity I get here. You can read more about the form helpers from Inertia here.

Authentication

No opinions here what so ever. I use the phx.gen.auth generator, and I'm good to go.

If the user is logged in, I just pass their details as shared data. Here's how.

First, I pick the fields I want to expose from the User schema:

defmodule Horionos.Accounts.Schemas.User do
# ...
  @derive {Jason.Encoder, only: [:id, :full_name, :email, :confirmed_at, :preferences]}
# ...
end

Then, I update my require_authenticated_user plug to include the user:

def require_authenticated_user(conn, _opts) do
  user = conn.assigns[:current_user]

  if user do
    conn
    |> assign_prop(:current_user, user)
  else
    conn
    |> put_flash(:error, "You must log in to access this page.")
    |> maybe_store_return_to()
    |> redirect(to: ~p"/users/log_in")
    |> halt()
  end
end

And the front-end takes over with a simple re-usable hook.

import {PageProps} from '@inertiajs/core';
import {usePage} from '@inertiajs/react';

interface UserPreferences {
  theme: 'light' | 'dark' | 'system';
  date_format: 'YYYY-MM-DD' | 'DD/MM/YYYY' | 'MM/DD/YYYY';
}

interface CurrentUser {
  email: string;
  full_name?: string;
  confirmed_at: string | null;
  preferences: UserPreferences;
}

export function useCurrentUser() {
  const {props} = usePage<PageProps & {current_user: CurrentUser}>();
  return props.current_user;
}

export type {CurrentUser, UserPreferences};

I haven't decided if using TypeScript makes sense here.

I just wanted to see how easy it was to set up. Turns out it's trivial, and you only need to add the loader to your esbuild config.

Caveats

There are a few caveats we should be aware of.

1. The Phoenix adapter is the biggest point of failure. We depend on the maintainers to keep it up to date with the latest Inertia changes. Inertia isn't that widely used in the Phoenix space (compared to Laravel which has first-class support), so it's good to keep that in mind.
2. Phoenix bets heavily on LiveView. If you're picking Phoenix expecting some feature parity with frameworks like Laravel, you will be disappointed. You'll see releases that may not interest you.
3. Now, this isn't related to Inertia, but React seems to be eyeing the server-side rendering space. I don't see that much love for SPA's anymore, and the React docs don't even mention Vite, the best way to run SPAs in production. If you want to use React, like I do, maybe we're not the target audience anymore.

I'm okay with React exporting a different space, and focusing on RSC. I'm also okay with Phoenix polishing its LiveView offering. I'm only keeping an eye on the Phoenix adapter, but there's always the option to fork it if things go south.

Final thoughts

I tried hard to make full-stack JS work, but I keep working on the same (solved) problems that Javascript frameworks don't care about. Examples include:

• emails, trapping them during development, and testing
• async jobs
• file uploads
• orm or query builder, migrations
• multi-tenancy, authorization, roles
• impersonation
• logs
• tracing
• .. more

I'm doing all of these because I'm silly and like to write JSX. It is probably not a reasonable tradeoff.

With Inertia, I can have my cake and eat it too. I bring the backend framework I like, and I let React take over my front-end. One toolchain, one repo, one deployment pipeline.

Being able to combine Elixir and React is a game changer. I've experienced some years of burnout and not enjoying coding professionally, and this has been a breath of fresh air.

So, to conclude, I'm very happy with this setup. If you love LiveView and it gives you that newfound enthusiasm for coding, I'm so happy for you. Likewise, for the Rails renaissance.

While this post is React-centric, nothing stops you from using Vue or Svelte with Phoenix instead. I hope you try Inertia and see if it fits your workflow.

Resources:

• Inertia.js docs
• Inertia.js Phoenix adapter (GitHub.com)
• Simplify React and Phoenix using Inertia JS (YouTube.com)
• Inertia.js in Rails (evilmartians.com)

• JavaScript interop
• Components
• Code organization
• live_session and on_mount
• You still need controllers
• GenServer centric API
• Final thoughts

I've been experimenting with Phoenix LiveView for a while now. I have a net-positive experience but can't bring myself to love it or use it for my production projects.

It's an exciting technology where things work, but they don't quite feel right.

JavaScript interop

The biggest issue for me is the interop with JavaScript.

At some point, no matter what your initial expectations were, you need to bridge this gap and use JavaScript. That's where things get hairy.

Initially, you try to make things work with JS hooks, but this quickly becomes difficult to work with. Here's an example from the LiveBeats repo. The LiveView markup can very easily get out of sync with JavaScript. Maintainability is also an issue.

Some people pull Alpine, or libraries like LiveSvelte to help with this. But this seems like a weird choice to me. You're niching down your stack even further, and the initial quest to reduce front-end complexity ends up increasing it. The no-js-needed premise is gone, and along with it, you're left with a weird hybrid stack.

You get a bit of styling here, a little bit of front-end logic there, and a little bit of front-end state management over there. All of this, mushed together in the same codebase with the backend. It works, but stepping away for some time, and returning for a new feature, doesn't feel right. You have to reorient yourself, and remember how all this plumbing works.

JavaScript interop should be a first-class citizen and not an afterthought.

Components

The ecosystem is obviously small. That's, of course, expected when you're picking Elixir.

But now, when your front-end uses LiveView and HEEx, you're closing the door to a lot of good stuff out there.

Authoring components in HEEx can be very awkward. Here's part of the input component from the Phoenix skeleton.

It's a god-component that accepts a lot of options, and then does pattern matching to render the appropriate input.

attr :id, :any, default: nil
attr :name, :any
attr :label, :string, default: nil
attr :value, :any

attr :type, :string,
  default: "text",
  values: ~w(checkbox color date datetime-local email file month number password
             range search select tel text textarea time url week)

attr :field, Phoenix.HTML.FormField,
  doc: "a form field struct retrieved from the form, for example: @form[:email]"

attr :errors, :list, default: []
attr :checked, :boolean, doc: "the checked flag for checkbox inputs"
attr :prompt, :string, default: nil, doc: "the prompt for select inputs"
attr :options, :list, doc: "the options to pass to Phoenix.HTML.Form.options_for_select/2"
attr :multiple, :boolean, default: false, doc: "the multiple flag for select inputs"

attr :rest, :global,
  include: ~w(accept autocomplete capture cols disabled form list max maxlength min minlength
              multiple pattern placeholder readonly required rows size step)

def input(%{field: %Phoenix.HTML.FormField{} = field} = assigns) do
  errors = if Phoenix.Component.used_input?(field), do: field.errors, else: []

  assigns
  |> assign(field: nil, id: assigns.id || field.id)
  |> assign(:errors, Enum.map(errors, &translate_error(&1)))
  |> assign_new(:name, fn -> if assigns.multiple, do: field.name <> "[]", else: field.name end)
  |> assign_new(:value, fn -> field.value end)
  |> input()
end

def input(%{type: "checkbox"} = assigns) do
  assigns =
    assign_new(assigns, :checked, fn ->
      Phoenix.HTML.Form.normalize_value("checkbox", assigns[:value])
    end)

  ~H"""
  <div>
    <label class="flex items-center gap-4 text-sm leading-6 text-zinc-600">
      <input type="hidden" name={@name} value="false" disabled={@rest[:disabled]} />
      <input
        type="checkbox"
        id={@id}
        name={@name}
        value="true"
        checked={@checked}
        class="rounded-sm border-zinc-300 text-zinc-900 focus:ring-0"
        {@rest}
      />
      {@label}
    </label>
    <.error :for={msg <- @errors}>{msg}</.error>
  </div>
  """
end

def input(%{type: "select"} = assigns) do
end

def input(%{type: "textarea"} = assigns) do
end

# etc..

From an Elixir POV, it's fantastic, I love that we can do this. But from a front-end perspective, it doesn't excite me or give me confidence. When switching context from Remix and Next.js projects, I feel slower and less productive. I can't do quick prototypes.

There are some third-party component libraries (mostly paid), but they are not as polished as the ones you get with React or Vue.

Code organization

No back-end framework, to my knowledge, provides a good solution for organizing your front-end code, and Phoenix is no exception.

When you start a new Phoenix project, you get all your re-usable components in a core-components.ex file. How you organize, grow, and maintain this file is up to you.

I agree that this is something unique to each application, but I can't help but feel that the lack of a good solution is a missed opportunity.

When you add LiveComponents to the mix, things get more annoying. Moving stuff around also has the negative of having to update the module name if you want to follow Elixir's naming conventions.

live_session and on_mount

Let's move on. live_session lets you share the state with multiple LiveViews. So let's say we have this in our router:

scope "/", MyAppWeb do
  pipe_through [:browser, :require_authenticated_user]

  live_session :authenticated, on_mount: {MyAppWeb.UserAuth, :ensure_authenticated} do
    live "/dashboard", DashboardLive
    live "/settings", SettingsLive
  end
end

Before we render the DashboardLive or SettingsLive, we double-check that the user is authenticated in the ensure_authenticated function.

def on_mount(:ensure_authenticated, _params, session, socket) do
  if socket.assigns[:current_user] do
    {:cont, socket}
  else
    {:halt, redirect(socket, to: ~p"/login")}
  end
end

This looks good on the surface but gets annoying when you have to do multiple checks.

scope "/", MyAppWeb do
  pipe_through [
    :browser,
    :require_authenticated_user,
    :require_email_verified,
    :require_unlocked_account,
    :require_organization
  ]

  # Controllers need to be used for some things
  post "/organization/select", OrganizationSessionController, :update
  post "/users/clear_sessions", UserSessionController, :delete_other_sessions

  live_session :authenticated_with_organization,
    on_mount: [
      {UserAuthLive, :ensure_authenticated},
      {UserAuthLive, :ensure_current_organization},
      {UserAuthLive, :ensure_email_verified},
      {UserAuthLive, :redirect_if_locked},
      {LiveHelpers, :default}
    ] do
    live "/", DashboardLive, :home

    # User settings
    live "/users/settings", UserSettings.IndexLive, :edit
    live "/users/settings/security", UserSettings.SecurityLive, :security
    live "/users/settings/confirm_email/:token", UserSettings.IndexLive, :confirm_email

    # Organization management
    live "/organization", Organization.IndexLive, :index
    live "/organization/invitations", Organization.InvitationsLive, :index
  end
end

This becomes a headache for me. I understand why you need to do things twice, but it feels awkward, and you can easily mess it up.

In fact, I'm certain that there might be a better way to do this, but if I have to think about it that much, then it's not a good API.

You still need controllers

When I was exploring LiveView, I was hoping that I could drop the controllers and go full-on with this new paradigm, similar to React Server Components.

Essentially, have a single file that does everything for that page.

Unfortunately, LiveView can't do it; you still need controllers. For example, you need to POST to a controller to set the session.

Here's an example from the authentication generator. You create the user in LiveView, but for the session, you need to hit a controller.

defmodule MyAppWeb.UserRegistrationLive do
  use MyAppWeb, :live_view

  alias MyApp.Accounts
  alias MyApp.Accounts.User

  def render(assigns) do
    ~H"""
    <div class="mx-auto max-w-sm">
      <.header class="text-center">
        Register for an account
        <:subtitle>
          Already registered?
          <.link navigate={~p"/users/log_in"} class="font-semibold text-brand hover:underline">
            Log in
          </.link>
          to your account now.
        </:subtitle>
      </.header>

      <.simple_form
        for={@form}
        id="registration_form"
        phx-submit="save"
        phx-change="validate"
        phx-trigger-action={@trigger_submit}
        # Here ----------v
        action={~p"/users/log_in?_action=registered"}
        method="post"
      >
        <.error :if={@check_errors}>
          Oops, something went wrong! Please check the errors below.
        </.error>

        <.input field={@form[:email]} type="email" label="Email" required />
        <.input field={@form[:password]} type="password" label="Password" required />

        <:actions>
          <.button phx-disable-with="Creating account..." class="w-full">Create an account</.button>
        </:actions>
      </.simple_form>
    </div>
    """
  end

  def mount(_params, _session, socket) do
  # omitted
  end

  def handle_event("save", %{"user" => user_params}, socket) do
    # And here ----------v
    case Accounts.register_user(user_params) do
      {:ok, user} ->
        {:ok, _} =
          Accounts.deliver_user_confirmation_instructions(
            user,
            &url(~p"/users/confirm/#{&1}")
          )

        changeset = Accounts.change_user_registration(user)
        {:noreply, socket |> assign(trigger_submit: true) |> assign_form(changeset)}

      {:error, %Ecto.Changeset{} = changeset} ->
        {:noreply, socket |> assign(check_errors: true) |> assign_form(changeset)}
    end
  end

  def handle_event("validate", %{"user" => user_params}, socket) do
    # omitted
  end

  defp assign_form(socket, %Ecto.Changeset{} = changeset) do
    # omitted
  end
end

I understand the technical limitations, but it's a bummer.

I was hoping for a more holistic approach. It feels weird that I do a mutation in LiveView and then a side effect in the controller.

No matter how you slice it, it's suboptimal.

GenServer centric API

Finally, the API is very GenServer centric. I believe this is intended, as the maintainers want to show you that it's nothing more than a GenServer under the hood.

In my opinion, this is a mistake, and it hurts the adoption. Imagine trying to convince your front-end team to evaluate LiveView, and you show them this:

def handle_event("increment", _params, socket) do
  {:noreply, assign(socket, count: socket.assigns.count + 1)}
end

What is this :noreply? Is this a side-effect?

Say we generate some boilerplate with mix phx.gen.live Things Thing things name:string description:text and look at the form_component.ex.

On version 1.7.18 I get the following:

@impl true
def handle_event("validate", %{"thing" => thing_params}, socket) do
end

def handle_event("save", %{"thing" => thing_params}, socket) do
end

defp save_thing(socket, :edit, thing_params) do
end

defp save_thing(socket, :new, thing_params) do
end

defp notify_parent(msg), do: send(self(), {__MODULE__, msg})

What is this send(self(), {__MODULE__, msg}) and why is only one handle_event having @impl: true? Why do we need this ceremony for a simple form?

If I hadn't read Elixir in Action before picking up Phoenix, I would have quit in the first 10 minutes. There's no "Aha!" moment. The API should be simpler, there's no need for the plumbing to be visible.

Final thoughts

LiveView is a great tool for internal applications or applications without lots of interactions. You can do cool things and ship them quickly. It's honestly amazing that our solutions are not just React, Vue, or Angular. If it doesn't suit my needs, there are 100 developers who might adore it.

But it's not the silver bullet some people make it out to be.

I wanted to write this post to share my thoughts, and balance the discussion, as most of the posts I've read don't mention some of the issues I've faced.

For the past weeks, I've been toying with Inertia & its Phoenix adapter.

I have to say, it's the most fun I've had coding for a while. I get the things I love about Elixir, and then throw in some React. If you're looking for a way to get the best of both worlds, I highly recommend it. Feel free to reach out if you have any questions, I'll write about it soon as well.

create table(:users_tokens) do
  add :user_id, references(:users, on_delete: :delete_all), null: false
  add :token, :binary, null: false
  add :context, :string, null: false
  add :sent_to, :string

  timestamps(type: :utc_datetime, updated_at: false)
end

I'm not a big fan of this, because I consider it to be a leaky abstraction.

Why would my session tokens need sent_to ? This is for the email-change flow.

What if I want to add extra metadata, like the user-agent, or the IP address? I shouldn't do that in this table. My password reset token flow doesn't care about that.

I believe it's best to make this change early, before we get to unicorn status, and not have to deal with the migration when it's painful. In this post I'll focus on the session tokens, but the same principle applies to all others.

Step 1: Generate the migration

We keep the same structure, but without context & sent_to. Let's also add a unique index on the token. There are no surprises here.

defmodule MyApp.Repo.Migrations.CreateSessionTokensTable do
  use Ecto.Migration

  def change do
    create table(:session_tokens) do
      add :user_id, references(:users, on_delete: :delete_all), null: false
      add :token, :binary, null: false

      timestamps(type: :utc_datetime, updated_at: false)
    end

    create index(:session_tokens, [:user_id])
    create unique_index(:session_tokens, [:token])
  end
end

Optional Step: Centralize the token generation

Well, here's a second pet-peeve. I don't enjoy having to call :crypto.strong_rand_bytes/1 everywhere in my code. It's a bit of a code smell. The hash_algorithm and rand_size are also things that are not going to change module to module.

So I like to centralize this in a helper module.

defmodule MyApp.Helpers.TokenService do
  alias MyApp.Constants

  @hash_algorithm Constants.hash_algorithm()
  @rand_size Constants.rand_size()

  @spec generate_token() :: binary()
  def generate_token do
    :crypto.strong_rand_bytes(@rand_size)
  end

  @spec hash(binary()) :: binary()
  def hash(token) do
    :crypto.hash(@hash_algorithm, token)
  end

  @spec generate() :: {binary(), binary()}
  def generate do
    raw_token = generate_token()
    {raw_token, hash(raw_token)}
  end

  @spec encode(binary()) :: binary()
  def encode(token) do
    Base.url_encode64(token, padding: false)
  end

  @spec decode(binary()) :: {:ok, binary()} | :error
  def decode(encoded_token) do
    Base.url_decode64(encoded_token, padding: false)
  end
end

Step 2: Create the schema

OK, back to the juicy stuff. Let's create the SessionToken schema. There's only a single changeset method that generates the token, and prepares the changeset.

defmodule MyApp.Accounts.SessionToken do
  use Ecto.Schema

  import Ecto.Changeset

  alias MyApp.Accounts.User
  alias MyApp.Helpers.TokenService

  schema "session_tokens" do
    field :token, :binary

    belongs_to :user, User

    timestamps(type: :utc_datetime, updated_at: false)
  end

  def changeset(user) do
    token = TokenService.generate_token()

    attrs =
      %{
        token: token,
        user_id: user.id
      }

    changeset =
      %__MODULE__{}
      |> cast(attrs, [:token, :user_id])
      |> validate_required([:token, :user_id])
      |> foreign_key_constraint(:user_id)

    {token, changeset}
  end
end

Step 3: Update the Accounts context

Finally, let's make small adjustments to the Accounts context. I'm also going to add a few new ones, revoke_other_sessions/2 and list_sessions/2.

## Session

@doc """
Generates a session token.
"""
def generate_user_session_token(user) do
  {token, session_token_changeset} = SessionToken.changeset(user)
  Repo.insert!(session_token_changeset)
  token
end

@doc """
Gets the user with the given signed token.
"""
def get_user_by_session_token(token) do
  days = Constants.session_validity_in_days()

  SessionToken
  |> where([st], st.token == ^token)
  |> join(:inner, [st], u in assoc(st, :user))
  |> where([st], st.inserted_at > ago(^days, "day"))
  |> select([st, u], u)
  |> Repo.one()
end

@doc """
Deletes the signed token with the given context.
"""
def delete_user_session_token(token) do
  Repo.delete_all(from st in SessionToken, where: st.token == ^token)
  :ok
end

@doc """
Revokes all session tokens for a user except the current one.

## Parameters
  - user: User struct
  - current_token: Token to keep active

## Returns
  - {number_of_revoked_sessions, nil}
"""
def revoke_other_sessions(user, current_token) do
  Repo.delete_all(
    from st in SessionToken,
      where: st.user_id == ^user.id and st.token != ^current_token
  )
end

@doc """
Lists all active sessions for a user.

## Parameters
  - user: User struct
  - current_token: Current active session token

## Returns
  - List of session details
"""
def list_sessions(user, current_token) do
  SessionToken
  |> where(user_id: ^user.id)
  |> select([st], %{
    id: st.id,
    is_current: st.token == ^current_token
  })
  |> Repo.all()
end

Let's also update the reset_user_password/2 method to delete all the session tokens for the user.

@doc """
Resets the user password.

## Examples

    iex> reset_user_password(user, %{password: "new long password", password_confirmation: "new long password"})
    {:ok, %User{}}

    iex> reset_user_password(user, %{password: "valid", password_confirmation: "not the same"})
    {:error, %Ecto.Changeset{}}

"""
def reset_user_password(user, attrs) do
  Ecto.Multi.new()
  |> Ecto.Multi.update(:user, User.password_changeset(user, attrs))
  |> Ecto.Multi.delete_all(:tokens, UserToken.by_user_and_contexts_query(user, :all))
  |> Ecto.Multi.delete_all(
    :session_tokens,
    from(t in SessionToken, where: t.user_id == ^user.id)
  )
  |> Repo.transaction()
  |> case do
    {:ok, %{user: user}} -> {:ok, user}
    {:error, :user, changeset, _} -> {:error, changeset}
  end
end

I find Ecto.Multi.delete_all(:tokens, UserToken.by_user_and_contexts_query(user, :all) to be sub-optimal as well, but I'll leave it as is for now.

Step 4: Update the Accounts context tests

Last but not least, let's update the tests. There's not much to change here (intentionally), we just have to ensure we're referencing the correct schema.

describe "generate_user_session_token/1" do
  setup do
    %{user: user_fixture()}
  end

  test "generates a token", %{user: user} do
    token = Accounts.generate_user_session_token(user)
    assert user_token = Repo.get_by(SessionToken, token: token)

    # Creating the same token for another user should fail
    assert_raise Ecto.ConstraintError, fn ->
      Repo.insert!(%SessionToken{
        token: user_token.token,
        user_id: user_fixture().id
      })
    end
  end
end

describe "get_user_by_session_token/1" do
  setup do
    user = user_fixture()
    token = Accounts.generate_user_session_token(user)
    %{user: user, token: token}
  end

  # other tests omitted
  test "does not return user for expired token", %{token: token} do
    {1, nil} = Repo.update_all(SessionToken, set: [inserted_at: ~N[2020-01-01 00:00:00]])
    refute Accounts.get_user_by_session_token(token)
  end
end

describe "reset_user_password/2" do
  setup do
    %{user: user_fixture()}
  end

  # other tests omitted
  test "deletes all tokens for the given user", %{user: user} do
    _ = Accounts.generate_user_session_token(user)
    {:ok, _} = Accounts.reset_user_password(user, %{password: "new valid password"})

    refute Repo.get_by(UserToken, user_id: user.id)
    refute Repo.get_by(SessionToken, user_id: user.id)
  end
end

Step 5: Remove old session tokens

One last thing, be sure to remove the leftover session tokens in the users_tokens table, any way you see fit. I'm not going to provide an example here, as it's a one-time operation. You can do it manually, or write a migration for it.

Optional Step: Add some metadata

Let's make this change useful. We will expand the session token table, to include some metadata about the device that the user is using. The point here is to allow them inspect their active sessions, and see if there's anything suspicious.

We start by generating a migration to add the fields.

defmodule MyApp.Repo.Migrations.AddDeviceMetadataToSessionTokens do
  use Ecto.Migration

  def change do
    alter table(:session_tokens) do
      add :device, :string, default: "Unknown"
      add :os, :string, default: "Unknown"
      add :browser, :string, default: "Unknown"
      add :browser_version, :string, default: ""
    end
  end
end

Next, we have to update the SessionToken schema to include the device metadata.

schema "session_tokens" do
  field :token, :binary
  field :device, :string
  field :os, :string
  field :browser, :string
  field :browser_version, :string

  belongs_to :user, User

  timestamps(type: :utc_datetime, updated_at: false)
end

Then, update the changeset/1 method (now changeset/2) to accept these fields.

  def changeset(user, device_info) do
    token = TokenService.generate_token()

    attrs =
      %{
        token: token,
        user_id: user.id
      }
      |> Map.merge(device_info)

    changeset =
      %__MODULE__{}
      |> cast(attrs, [:token, :user_id, :device, :os, :browser, :browser_version])
      |> validate_required([:token, :user_id, :device, :os, :browser, :browser_version])
      |> foreign_key_constraint(:user_id)

    {token, changeset}
  end

Finally, we update generate_user_session_token/1 method (now generate_user_session_token/2), and the list_sessions/2.

def generate_user_session_token(user, device_info) do
  {token, session_token_changeset} = SessionToken.changeset(user, device_info)
  Repo.insert!(session_token_changeset)
  token
end

def list_sessions(user, current_token) do
  SessionToken
  |> where(user_id: ^user.id)
  |> select([st], %{
    id: st.id,
    is_current: st.token == ^current_token,
    device: st.device,
    os: st.os,
    browser: st.browser,
    browser_version: st.browser_version
  })
  |> Repo.all()

After that, we just have to parse our headers in our session controller, and extract the device info. Even if you're using LiveView for everything, you can't get away without having a session controller. So the same step applies.

In order to collect the device info, we can use various User-Agent parsers (like UAParser). That said, it's not a foolproof method. For example Brave sometimes gets detected as Chrome. You need client-hints to get the real info there.

MacOS has also stopped updating the User-Agent string, so it's not reliable. I believe it's stuck on 10_15_7, and it's not going to change.

So, I won't go into the details of how to parse the User-Agent string, it depends on how serious you want to get with this.

But essentially, you need something along these lines:

defmodule MyApp.UserSessionController do
  # other methods and imports omitted
  def create(conn, %{"user" => user_params}) do
    %{"email" => email, "password" => password} = user_params

    if user = Accounts.get_user_by_email_and_password(email, password) do
      device_info = extract_user_agent_info(conn)

      conn
      # Which passes it to `Accounts.generate_user_session_token/2`
      |> UserAuth.log_in_user(user, user_params, device_info)
    else
      # In order to prevent user enumeration attacks, don't disclose whether the email is registered.
      conn
      |> put_flash(:error, "You have entered an invalid email or password.")
      |> redirect(to: ~p"/users/log_in")
    end
  end

  def extract_user_agent_info(conn) do
    conn
    |> Plug.Conn.get_req_header("user-agent")
    |> List.first()
    |> parse_user_agent()
  rescue
    _ -> default_user_agent_info()
  end

  defp parse_user_agent(nil), do: default_user_agent_info()
  defp parse_user_agent(user_agent) do
    # parse the user agent
  end
end

Final thoughts

That's it, we now have a separate table for session tokens, that can be easily extended with relevant metadata.

Now, let's recap why we did it.

The generator, creates what's effectively a "God Table", it kind of knows too much, and handles different concerns.

When you get a session token, you notice a sent_to. If you are not aware of the generator structure, and you see this, you have every right to be concerned. Session management, has nothing to do with email delivery. This is a classic example of a leaky abstraction, where implementation details of one concern are leaking into another.

So we separate them.

Let’s try to clarify them.

Alias

alias allows us to use a shorter name for a module, making it easier to reference in the code. So, when a module has a long (nested) name, we can omit the full name by using an alias. Instead, we only need to type the last part of the module's name.

defmodule MyApp.Workers.LockUnverifiedAccountsWorker do
  use Oban.Worker, queue: :unverified_accounts

  # Let’s look at how to use alias
  alias MyApp.Domain.Accounts
  alias MyApp.Services.AdminNotifications

  @impl Oban.Worker
  def perform(_job) do
    # Using `Accounts` instead of `MyApp.Domain.Accounts`
    {locked_count, locked_users} = Accounts.lock_expired_unverified_accounts()

    for user <- locked_users do
      # Using `AdminNotifications` instead of `MyApp.Services.AdminNotifications`
      AdminNotifications.notify(:user_locked, user)
    end

    {:ok, locked_count}
  end
end

We can also specify a custom alias using the :as option. This can be useful when we have multiple modules with the same name or when we want to give the alias a more descriptive name.

alias MyApp.Services.AdminNotifications, as: Snitch

Snitch.notify()

Pretty straightforward. With alias we can remove the extra baggage of long module names and make our code more readable. More about aliasing in Elixir can be found here.

Import

import allows us to bring functions or macros (more on macros later) from another module into the current scope without prefixing them with the module name.

Let’s see how we can use import in the same example.

defmodule MyApp.Workers.LockUnverifiedAccountsWorker do
  use Oban.Worker, queue: :unverified_accounts

  # Let’s focus on these again
  import MyApp.Domain.Accounts, only: [lock_expired_unverified_accounts: 0] # `0` means we are importing the function with 0 arity, i.e. no arguments.
  import MyApp.Services.AdminNotifications

  @impl Oban.Worker
  def perform(_job) do
    # No need to prefix with `Accounts`.
    # We only imported `lock_expired_unverified_accounts` from it
    {locked_count, locked_users} = lock_expired_unverified_accounts()

    for user <- locked_users do
      # No need to prefix with `AdminNotifications`,
      # but as a side-effect, we have access to all its functions, for better or worse
      notify(:user_locked, user)
    end

    {:ok, locked_count}
  end
end

There’s a downside to using import, though. Sometimes it’s not immediately clear where a function is coming from. So if you’re using import, opt for only or except to avoid naming conflicts. In this example everything that AdminNotifications has, is now available in the current scope, which can be a bit dangerous.

I try to avoid import but make an exception for tests. For example, in my tests, I don’t mind importing all the fixtures I wrote, but in the actual code, I prefer explicitness, even if things get a bit lengthy.

Read more about import here.

Require

Macros are a metaprogramming primitive; code that generates code. They are executed at compile time, contrary to functions that get called at runtime.

So, if we want to use a module with macros, we need to require it first so it will be available at compile time.

Let’s create a simple module with a macro :

defmodule MyApp.Helpers.LogThisPlease do
  # In our compiled code, this will be replaced with `IO.puts("Hello, world!")`
  # A normal function instead, would be referenced and executed at the runtime
  defmacro info(message) do
    quote do
      IO.puts "[INFO] #{unquote(message)}"
    end
  end
end

And let’s put it to use in our worker module.

defmodule MyApp.Workers.LockUnverifiedAccountsWorker do
  use Oban.Worker, queue: :unverified_accounts

  alias MyApp.Domain.Accounts
  alias MyApp.Services.AdminNotifications

  # We need to require the module with the macro
  require MyApp.Helpers.LogThisPlease

  @impl Oban.Worker
  def perform(_job) do
    {locked_count, locked_users} = Accounts.lock_expired_unverified_accounts()
    # Using the full name of the module
    MyApp.Helpers.LogThisPlease.info("Found #{locked_count} users to lock")

    MyApp.Helpers.LogThisPlease.info("Locking users")
    for user <- locked_users do
      AdminNotifications.notify(:user_locked, user)
      MyApp.Helpers.LogThisPlease.info("User locked: #{user.id}")
    end

    {:ok, locked_count}
  end
end

Everything works, but it looks pretty busy.

If we want, we can replace require with import. By doing this import pulls everything from the module into the current scope, and implicitly runs require for us.

This isn’t true for alias as that only creates a shorter alias for the module, and we still need to require it ourselves.

More about require can be found here.

Use

Speaking of macros, use is a macro itself. It invokes the __using__/1 macro of another module. This is often used to set up behaviors or inject code into the current module.

That's a bit abstract, so let’s revisit our previous example.

defmodule MyApp.Helpers.LogThisPlease do
  defmacro __using__(_opts) do
    quote do
      def info(message) do
        IO.puts "[INFO] #{message}"
      end
    end
  end
end

Now, we can use this module in our worker.

defmodule MyApp.Workers.LockUnverifiedAccountsWorker do
  use Oban.Worker, queue: :unverified_accounts

  alias MyApp.Domain.Accounts
  alias MyApp.Services.AdminNotifications

  use MyApp.Helpers.LogThisPlease

  @impl Oban.Worker
  def perform(_job) do
    {locked_count, locked_users} = Accounts.lock_expired_unverified_accounts()
    info("Found #{locked_count} users to lock")

    info("Locking users")
    for user <- locked_users do
      AdminNotifications.notify(:user_locked, user)
      info("User locked: #{user.id}")
    end

    {:ok, locked_count}
  end
end

By doing this, we eliminated the need to call MyApp.Helpers.LogThisPlease.info and can now call info directly. It is a typical pattern in Elixir, especially in libraries. For example, Oban uses use Oban.Worker to set up all the necessary plumbing to make this module work as an Oban job.

Of course, it poses the same problem as import - it’s not immediately clear where the function comes from.

TL;DR:

1. Alias provides shorter names for modules, making them easier to reference.
2. Import brings specific or all functions and macros into the current scope.
3. Require ensures a module is loaded and is necessary for using macros.
4. Use invokes the __using__/1 macro of another module, often used for setting up behaviors or injecting code.

The JavaScript community has a flaw. It’s too big. There’s a lot of money to be made, and every new solution has a marketing push that makes it seem like the best thing since sliced bread.

For example, Next.js (which I mostly enjoy using) is advertised on Twitter circles as the best full-stack framework, with a very annoying and loud marketing push.

A full-stack framework has a lot of responsibilities. How do you handle emails? Writing templates? How do you test them? What about:

• Background jobs
• File uploads
• Authorization
• User impersonation
• Multi-tenancy
• Tracing
• Logs

When there’s a lot of buzz, people are curious how exactly the JavaScript ecosystem is solving these problems. And this is where the friction comes in.

I don’t love opinionated full-stack frameworks, but I have built projects on the side with Laravel and Django, and they were a joy to use. There’s an undeniable productivity boost with these battle-tested frameworks. And it’s also a fantastic point of reference when you’re starting out.

But they are not perfect. No matter which client-side solutions they push, they don’t hold a candle to the JavaScript ecosystem. That's subjective, of course, but that's my experience.

Full-stack frameworks also ask you to commit to a certain way of doing things. Personally, I’m closer to the functional programming camp, and I don’t mind tweaking my stack to fit my quirks. But I know what I must re-implement when not using a full-stack framework, and I respect their solutions.

So what irks me is that these discussions lack nuance. There's no real discussion happening. It's just chatter that confuses beginners and makes them feel like they have to pick a side. Both cases have their merits.

Ultimately, I’m not here to tell you what to use. Context matters, and different people build different projects. I just want you to be aware of the biases of the people pushing you to use their tools.

For example, if a company pushes you to use its framework and promotes another service for its missing features, how would you feel if half their team has angel investments in that service? Do they care for your app, or do they want to pad their user stats?

If an influencer has that secret silver bullet tool to share with you, how can they vouch for it without shipping anything?

Do all these people have your best interest in mind or their own? And how do you know?

Everyone wants to make you a fan, but don’t take sides; it’s pointless. Be critical of the tools you use and prioritize sanity for yourself and your team.

Rapid fire questions:

• Why use Effect-ts?: Because I want to treat errors as values and nicely handle them.
• Is it functional programming mambo jambo?: I write my code using Effect-ts in an imperative way. It’s inspired by functional libraries, it gives you all the tools to write in a functional way, but it’s not dogmatic. If anything, sometimes using Classes is more convenient.
• Do I have to rewrite everything?: No, you can scope it to a part of your app, or even a single function. I purposely avoid using it everywhere and keep it to the parts of my app that make sense for it.
• Is it hard to learn?: It’s not easy, but it’s not hard. It depends on how deep you want to go. The documentation is good, and the community is very helpful.

Alright, let’s dive in.

Error handling

Let’s take a look at this example:

const validationSchema = Schema.Struct({
  email: emailSchema,
  role: membershipRoleSchema,
});

export type CreateInvitationProps = Schema.Schema.Type<typeof validationSchema>;

export function createInvitation({pool, db}: {pool: PgPool; db: DB}) {
  function execute({
    props: {email, role},
    userId,
    orgId,
  }: {
    props: CreateInvitationProps;
    userId: User['id'];
    orgId: Org['id'];
  }) {
    return Effect.gen(function* () {
      yield* Effect.log(
        `(create-invitation): Creating invitation for ${email}`
      );

      // Check if the user can create an invitation
      yield* invitationAuthorizationService({pool, db}).canCreate({
        userId,
        orgId,
      });

      // Generate a UUID for the invitation
      const invitationId = yield* generateUUID();

      // Delete any previous invitations for the same email
      yield* Effect.tryPromise({
        try: () =>
          db
            .deletes('membership_invitations', {org_id: orgId, email})
            .run(pool),
        catch: () => new DatabaseError(),
      });

      // Check if the user is already a member
      const existingMember = yield* Effect.tryPromise({
        try: () =>
          db
            .selectOne(
              'users',
              {email: email},
              {
                lateral: {
                  membership: db.selectOne('memberships', {
                    org_id: orgId,
                    user_id: db.parent('id'),
                  }),
                },
              }
            )
            .run(pool),
        catch: () => new DatabaseError(),
      });

      // If the user is already a member, return an error
      if (existingMember?.membership) {
        return yield* Effect.fail(
          new InviteeAlreadyMemberError({
            inviterId: userId,
            orgId,
            inviteeEmail: existingMember.email,
            inviteeId: existingMember.id,
          })
        );
      }

      const orgRecord = yield* Effect.tryPromise({
        try: () => db.selectOne('orgs', {id: orgId}).run(pool),
        catch: () => new DatabaseError(),
      });

      if (!orgRecord) {
        return yield* Effect.fail(new OrgNotFoundError());
      }

      // Insert the invitation
      const invitationRecord = yield* Effect.tryPromise({
        try: () =>
          db
            .insert('membership_invitations', {
              id: invitationId,
              role: role,
              email: email,
              org_id: orgId,
            })
            .run(pool),
        catch: () => {
          return new DatabaseError();
        },
      });

      const invitation = yield* MembershipInvitation.fromRecord({
        record: invitationRecord,
        org: {
          slug: orgRecord.slug,
          name: orgRecord.name,
          id: orgRecord.id,
        },
      });

      return invitation;
    }).pipe(
      Effect.catchTags({
        DatabaseError: () =>
          Effect.fail(new InternalServerError({reason: 'Database error'})),
        MembershipInvitationParse: () =>
          Effect.fail(
            new InternalServerError({
              reason: 'Membership invitation parse error',
            })
          ),
        UUIDGenerationError: () =>
          Effect.fail(
            new InternalServerError({reason: 'UUID generation error'})
          ),
      })
    );
  }

  const validate = schemaResolver(validationSchema);

  return {
    execute,
    validate,
  };
}

It’s a big one. I’m not going to "Hello World" you. I know I’m mixing concerns; some might say I should split it into smaller functions, pull an ORM, or do things differently. But I’m not here to talk about that.

Chances are that generators aside, you can read it just fine. There’s some syntax sugar, but it’s familiar.

• I log some stuff
• I check if the User can create an invitation (throws ForbiddenActionError) otherwise
• I generate a UUID (throws UUIDGenerationError, impossible to happen IRL, but maybe my version of uuid is broken)
• I delete any previous invitations (throws DatabaseError, could be much more refined)
• I check if the User is already a member (throws InviteeAlreadyMemberError)
• I check if the Org exists (throws OrgNotFoundError) - unlikely to happen
• I insert the invitation (throws DatabaseError)
• I parse the invitation (throws MembershipInvitationParse) to the types that the frontend understands
• I return the invitation

If I hover over execute, I see this function signature (you might have to scroll a bit):

(local function) execute({ props: { email, role }, userId, orgId, }: {
    props: CreateInvitationProps;
    userId: User['id'];
    orgId: Org['id'];
}): Effect.Effect<MembershipInvitation, InviteeAlreadyMemberError | OrgNotFoundError | ForbiddenActionError | InternalServerError, never>

The above means that my function has the following properties:

• Returns a MembershipInvitation
• Can error with InternalServerError, ForbiddenActionError, InviteeAlreadyMemberError, OrgNotFoundError
• No dependencies (never as the last type parameter. Let’s discuss that in a second)

For me, this is a big deal. I can see at a glance what my function does and what can go wrong. I don’t have to read the implementation to identify the errors. More importantly, I don’t have to be defensive when using this function. I have a clear contract.

In the example, even though my other functions throw UUIDGenerationError and MembershipInvitationParse, I don’t find these errors meaningful for the consumer. So I catch them and group them under InternalServerError. The rest can go through. The consumer then can decide on the appropriate server response based on what happened.

• ForbiddenActionError -> 403
• InviteeAlreadyMemberError -> 409
• OrgNotFoundError -> 404 (or even a full redirect to /login)
• InternalServerError -> 500

Now, let’s take a closer look at one of these errors. Specifically the InternalServerError. I defined it as a class and can pass a reason and metadata to it. Nothing will reach the consumer; they are meant to be logged and reported.

export class InternalServerError extends Data.TaggedClass(
  'InternalServerError'
)<{
  readonly reason?: string;
  readonly metadata?: unknown;
}> {
  constructor(props: {reason?: string; metadata?: unknown}) {
    super(props);
    console.log('[InternalServerError]', props);
    // send to reporting service
  }
}

Schema

As you move further into Effect-ts, you might notice that it also makes various other libraries obsolete. One of them is zod which I can replace with Schema. Let’s take a look at my User class:

import type {ParseError} from '@effect/schema/ParseResult';
import * as Schema from '@effect/schema/Schema';
import {Data, Effect} from 'effect';
import {compose} from 'effect/Function';
import type {users} from 'zapatos/schema';

import {db} from '~/core/db/schema.server.ts';

import {emailSchema} from './email.server.ts';
import {uuidSchema} from './uuid.server.ts';

class UserIdParseError extends Data.TaggedError('UserIdParseError')<{
  cause: ParseError;
}> {}

class UserParseError extends Data.TaggedError('UserParseError')<{
  cause: ParseError;
}> {}

export const userNameSchema = Schema.Trim.pipe(
  Schema.minLength(2, {
    message: () => 'Name must be at least 2 characters',
  }),
  Schema.maxLength(100, {
    message: () => 'Name cannot be more than 100 characters',
  })
);

const UserIdBrand = Symbol.for('UserIdBrand');
export const userIdSchema = uuidSchema.pipe(Schema.brand(UserIdBrand));

export class User extends Schema.Class<User>('User')({
  id: userIdSchema,
  name: userNameSchema,
  email: emailSchema,
  emailVerified: Schema.Boolean,
  createdAt: Schema.Date,
  updatedAt: Schema.Date,
}) {
  static fromUnknown = compose(
    Schema.decodeUnknown(this),
    Effect.mapError((cause) => new UserParseError({cause}))
  );

  static fromRecord(record: users.JSONSelectable) {
    return User.fromUnknown({
      id: record.id,
      name: record.name,
      email: record.email,
      emailVerified: record.email_verified,
      createdAt: record.created_at,
      updatedAt: record.updated_at,
    });
  }

  getRecord() {
    return {
      id: this.id,
      name: this.name,
      email: this.email,
      email_verified: this.emailVerified,
      updated_at: db.toString(this.updatedAt, 'timestamptz'),
      created_at: db.toString(this.createdAt, 'timestamptz'),
    };
  }
}

export const parseUserId = compose(
  Schema.decodeUnknown(userIdSchema),
  Effect.mapError((cause) => new UserIdParseError({cause}))
);

Again too much code, but I want to show you the Schema part. I define the schema for my User class, and then I can use it to parse a database record or an unknown object.

Just like that...

// Effect.Effect<User, UserParseError, never>
const user = User.fromUnknown(unknownObject);

If something odd happens, I get a UserParseError, and I can handle it accordingly.

You might noticed that I use Brand to create a new type for my UserId. It is a convenient feature, and I blogged about it here. Essentially, I never want to confuse a UserId with an OrgId or an AnnouncementId. They are all UUIDs, but they are identifiers of different resources.

Let’s take a look at a password module. I use bcrypt to hash and compare passwords and Schema to validate them.

import type {ParseError} from '@effect/schema/ParseResult';
import * as Schema from '@effect/schema/Schema';
import bcrypt from 'bcryptjs';
import {Data, Effect} from 'effect';
import {compose, pipe} from 'effect/Function';

const SALT_ROUNDS = 10;
const PasswordBrand = Symbol.for('PasswordBrand');

export const passwordSchema = Schema.String.pipe(
  Schema.minLength(8, {
    message: () => 'Password should be at least 8 characters long',
  }),
  Schema.maxLength(100, {
    message: () => 'Password should be at most 100 characters long',
  }),
  Schema.brand(PasswordBrand)
);

export type Password = Schema.Schema.Type<typeof passwordSchema>;

export class PasswordHashError {
  readonly _tag = 'PasswordHashError';
}
class PasswordParseError extends Data.TaggedError('PasswordParseError')<{
  cause: ParseError;
}> {}

export const parsePassword = compose(
  Schema.decodeUnknown(passwordSchema),
  Effect.mapError((cause) => new PasswordParseError({cause}))
);

export function hashPassword(password: Password) {
  return pipe(
    Effect.tryPromise(() => bcrypt.hash(password, SALT_ROUNDS)),
    Effect.mapError(() => new PasswordHashError())
  );
}

export function comparePasswords({
  plainText,
  hashValue,
}: {
  plainText: string;
  hashValue: string;
}) {
  return Effect.tryPromise({
    try: () => bcrypt.compare(plainText, hashValue),
    catch: () => new PasswordHashError(),
  });
}

And this is where I stop

I mentioned that Effect-ts has a lot of features (Queues , PubSub , Scheduling , Streams , Dependency Injection, etc)

Here’s the deal. I showed you some of the parts that I use. For me, they work nicely, and they solve my problems. But I’m certain that I’m not doing things the conventional way. Here’s an example:

Remember this type signature?

Effect.Effect<MembershipInvitation, InviteeAlreadyMemberError | OrgNotFoundError | ForbiddenActionError | InternalServerError, never>

I said the last type parameter is a union of the dependencies, and in this case, it’s empty, just never. I’m using a database, and a query builder (specifically the Zapatos library), so why is it not listed? Effect-ts offers a way to do dependency injection, and it’s nice. But I prefer not to do it that way. I pass the pool and db as arguments to my function instead.

I’m trying to figure out how to put this; I want to use Effect-ts but not to be tied to it. While I was trying to understand and use the library, I found myself in a rabbit hole. I was always searching for how to do it the right way. And this led me to look at other people's snippets and repos, and I became overwhelmed. I didn’t understand half of it, and I always thought I was doing everything wrong.

Instead of using a library, I spent my time trying to learn a new framework, refactoring code, and rewiring my brain. My side project was on hold, and I was not productive. (Oh, the horror)

I decided to use Effect-ts for validation and error handling. Essentially write the annoying code that can be modeled more efficiently with Effect, and use runPromiseExit to get the result. I’m losing a lot of the library's power, but I also reduce the surface of the things I have to learn and maintain.

If things don’t work out, I can keep the Error classes, replace the validation library, and remove the yield* and Effect.gen, and I’m back where I started. I won’t have invested that much.

Don’t get me wrong, I can only speak highly of the Effect and am grateful for the maintainers. If anything, I hope it will get more traction, as it’s a fantastic piece of software. If my team was using Effect, I would 100% use it to its full potential and I would be singing a different song.

i love @EffectTS_ it’s the exact mental model i want but regrettably i'll never put it in a serious application. Libraries that make your code look non-standard always ends up creating pain down the road. Hardest part about js is convincing devs to use fewer tools

— Dax (@thdxr)

source

Community

Effect has a vibrant community; you can find them on Discord.

I have only good things to say. I have asked a ton of stupid questions and always got a response. I even had feature requests that were implemented in a matter of days.

There are also great people tweeting about it, so you can follow them and get some insights. Here are some of them:

• Michael Arnaldi
• Jean-Baptiste Musso
• Antoine Coulon
• Patrick Roza
• Johannes Schickling

Resources:

• Documentation
• Blog
• Discord
• Effect-introduction (github.com) (recommended)
• From FP-TS to effect-ts (sandromaglione.com)
• effect for beginners (youtube.com)
• Quick thoughts on EffectTS (linkedin.com)
• effect-ts-app/boilerplate (github.com)
• sqlfx (github.com)

In short, I find the Remix approach simpler. I write my backend, and I use the loader & action functions to communicate with React. I’m oversimplifying, but that's all I perceive. In reality, it’s a well thought, and complex framework that does such a good job hiding all the complexity from me. And it just works, everywhere.

Anyway, let’s go through some conventions I decided on.

Contents:

• Throw in loaders, return in actions
• Parse formData
• Improved response types
• Parse ENV variables on load
• Feature organization & business logic
• Final thoughts

Throw in loaders, return in actions

By reading the documentation you might have noticed some snippets like this one:

export async function loader({request, params}: LoaderArgs) {
  // ...
  if (invoice === null) {
    throw json('Not Found', {status: 404}); // new Response with `application/json` header
  }
}

Take a look at the docs for redirect & json, if you’re not familiar

Now a question is what's the difference between throwing and returning a response?

When it comes to redirects (30X status codes), there’s no visible difference. It’s down to semantics. Let’s see two examples:

• Password reset success - Let’s take the user to the login page return redirect('/login')
• No session found - Nope. No access for you throw redirect('/login')

By throwing, you let the next developer understand that the redirect is forced due to some bad request.

When it comes to every other response (non-30X status) though, it’s all about how you handle the errors. When throwing a response, we diverge from the happy path, and the error is handled in the closest ErrorBoundary. This isn’t very helpful at times, as you don’t want to show an ErrorBoundary if a username is taken.

I usually like to do the following:

1. Throw in loaders. The page can’t be rendered properly. Many things can happen here. (Missing permissions, database errors, etc.) The page is broken, so rendering the ErrorBoundary makes sense.
2. Return in actions. Handle the errors as values, and depending on the severity render the appropriate UI. Validation error? Inline the error message. Database hiccup? Could be a toast.

Of course, this isn’t set in stone, but a good rule of thumb for me.

Parse formData

What fresh air to just use uncontrolled components, and gather everything in a FormData instance, right? Unfortunately, everything you pick from it is typed as FormDataEntryValue | null.

There are all sorts of validation libraries you can use, but I like to keep it simple. I gather the formData, parse them on the server with zod, and return validation errors instead.

Something like this:

export async function action({request}: {request: Request}) {
  const formData = await request.formData();
  const validation = validate(Object.fromEntries(formData));

  if (!validation.success) {
    return json({ok: false}, {status: 422});
  }

  // continue
}

Unrelated to Remix, I’m experimenting with effect-ts, so here’s what I really do:

export const action = withAction(
  Effect.gen(function* (_) {
    const {request} = yield* _(ActionArgs);
    const formData = yield* _(Effect.promise(() => request.formData()));

    const {validate, execute} = resetPassword();
    const props = yield* _(validate(Object.fromEntries(formData)));

    yield* _(execute(props));

    return new Redirect({
      to: '/login?resetPassword=true',
      init: request,
    });
  }).pipe(
    Effect.catchTags({
      InternalServerError: () => Effect.fail(new ServerError({})),
      UserNotFoundError: () =>
        Effect.fail(new BadRequest({errors: ['User not found']})),
      PasswordResetTokenNotFoundError: () =>
        Effect.fail(new BadRequest({errors: ['Token not found']})),
      ValidationError: (error) =>
        Effect.fail(new BadRequest({errors: error.messages})),
    })
  )
);

If this scares you ignore it. What I want to highlight is how flexible Remix is. If I want to overengineer something, I can do so.

Improved response types

I find the infered types that useLoaderData, useActionData & useFetcher return to be slightly incorrect (Issue-3931). For that case I use remix-typedjson and its hooks. So instead of useFetcher I use useTypedFetcher and so on.

// (taken from remix-typedjson docs)
const fetcher = useTypedFetcher<typeof action>();
fetcher.data; // data property is fully typed

I’m on the fence about this, as I’m using a "patched" version of Remix's helpers. There might be dragons here, so feel free to ignore this advice.

Parse ENV variables on load

This isn’t something groundbreaking, or strictly related to Remix, but I never notice it when reading similar introductory articles.

Essentially, don’t do this:

const SESSION_SECRET = process.env.SESSION_SECRET as string;

Instead, parse process.ENV, and let the application crash if something is missing. You don’t want to have your app running, only to find out that your emails were never sent.

Here’s what to do instead:

const envValidationSchema = zod.object({
  SESSION_SECRET: zod.string().nonempty(),
});

// Throw on-load if missing
const config = envValidationSchema;
// from here on config.SESSION_SECRET is populated

The same goes for all other similar instances. Initializing database/SMTP connections, etc

const envValidationSchema = zod.object({
  SMTP_HOST: zod.string().nonempty(),
  SMTP_SECURE: zod.coerce.boolean(),
  SMTP_USER: zod.string().min(2),
  SMTP_PASSWORD: zod.string().min(8),
  SMTP_PORT: zod.coerce.number(),
  //
  EMAIL_FROM: zod.string().email(),
});

// Throw on-load if missing
const config = envValidationSchema.parse(process.env);

const transporter = createTransport({
  host: config.SMTP_HOST,
  port: config.SMTP_PORT,
  secure: config.SMTP_SECURE,
  auth: {
    user: config.SMTP_USER,
    pass: config.SMTP_PASSWORD,
  },
  pool: true,
});

You can colocate this in a single env.server.ts file, but whatever you do, parse your env variables.

Feature organization & business logic

Here’s how I organize my projects (so far)

/modules
  /domain
    # example
    - membership-invitation.ts
    - membership.ts
    # ..
    - org.ts
    - user.ts
  /services
    # example (a bit mouthful, might need to rethink this)
    - invitation-authorization-service.server.ts
  /use-cases
    # example
    /create-user
      - create-user.server.ts
      - validation.server.ts
/routes
  # all public routes
  /_auth
    # example
    /register
      - _route.tsx
      - action.server.ts
      - register-form.tsx
      - register-page.tsx
  # all protected routes
  /_dashboard
  - &.tsx

I don’t like these oversimplified examples where you do everything in your actions. Take that business logic, and create a dedicated file for it. I like to group them under modules/use-cases. There are many approaches, you can go wild with DDD, whatever - just don’t blindly add everything to the loaders.

As for the front end, I try to keep my component library in a different (PNPM) workspace. One-offs can live inside the route, while exceptions (e.g. <TeamSwitcher />, <UserNav />) can go in a /components folder.

Oh, almost forgot. I like to colocate everything I need inside the same route. A single folder _route.tsx re-exports everything (meta, default-page, loader, action). I’m writing this piece before Remix V2 lands, so I’m using the Remix Flat Routes package to make it happen.

I’m not dogmatic. I’ll happily throw everything out of the window if it’s slowing me down. For now, this setup works, but will change in the future.

Final thoughts

I want a couple of things from my SSR framework:

1. Let me run my business logic on the server. Don’t be too smart about it.
2. Make the transition to React seamless.

So far, Remix covers all. There are sharp edges, but nothing blocking.

Is it a batteries-included framework like Laravel, Rails, or (the closest thing in the Node.js land) Adonis.js?

Nope, and I don’t mind. If anything the JS ecosystem has so many tools and options, that I would dislike having certain libraries shoehorned.

Remix gets out of my way and lets me just write code. It has the right amount of conventions, without being restricting or weird.

Resources:

• Remix docs
• Remix Guide (content aggregator)
• How to Think About Remix (afloat.dev)
• remix-flat-routes (GitHub)
• remix-typed-json (GitHub)
• Throwing vs. Returning responses in Remix (sergiodxa.com)
• Colocate your routes into feature folders with Remix Custom Routes (jacobparis.com)
• Typesafe environment variables with Zod (jacobparis.com)

Recently I worked on building a browser extension. It was unexplored territory for me, and the road was a bit bumpy. I wanted to share some of my findings, as most of the Stack Overflow discussions I found were outdated or slightly misleading. Especially with the transition from Manifest v2 to Manifest v3.

My target was Chromium-based browsers, so I can’t speak for Firefox or Safari. Although Firefox supports the same WebExtensions APIs, I haven’t tested it.

Stack

Here’s a quick overview of the technologies I used:

• Lit: Perfect fit this use-case. It’s a lightweight library that allows you to write Web Components with ease.
• TypeScript: No-brainer really. chrome-types were a massive help.
• Storybook: Mandatory for development if you start coupling your app with browser extension APIs
• Vite: Vite was used for two purposes. To provide a preview environment where I could test my extension, and for bundling the extension in library mode (only JS output, no HTML).
• Vitest: Super fast, no-config test runner. If you have used Jest with TypeScript you probably understand how annoying it is. Vitest just works.

Types of browser extensions

There are a few different options when building an extension.

First, you can build a "Popup" extension. Something like "Save to Notion". These are small web apps that load in the sandbox environment of a popup window, located in the extensions toolbar. You can use all of the browser extension APIs available, and you have great flexibility. If you want to bring in a framework like React, you can do it without any issues. It’s an isolated environment, where you can go wild.

Browser extension APIs are about accessing the state of Tabs, Cookies, Bookmarks, and more. Here’s an overview of the available APIs.

Second, you can build an extension that simply injects a script (called content scripts) into the pages of your choosing. There you can manipulate the DOM. A common use case is something like Fantasy Football extensions, which just add more metadata, like points, and schedules to the usually boring official pages. In that case, things get trickier. You can’t use the Browser APIs directly. You have to rely on a service worker to do the heavy lifting for you.

Also, the content script is loaded in the context of the page, so it’s probably not a good idea to bring in a framework like React.

Lastly, you can have a combination of both, something like Grammarly or 1Password. You can have both your content script, but also a popup where you can prompt the user to tweak their settings

In my case, I had to create an inline call-to-action button, that opens a sidebar, so using the first popup approach wasn’t viable. Everything that I’ll be sharing here is based on the second approach.

React, Lit & conflicting styles

Right off the bat, I was thinking of building a React/Tailwind application. I quickly realized that since I can’t use the popup route, I wouldn’t run my application in a sandbox environment. I didn’t want to load React (maybe a second version of it, if the page already does), or bother with conflicting styles.

Tailwind allows you to set a custom prefix. It helps with the same problem, albeit without 100% safety.

There’s one elegant solution that handles both, and that's Web Components. Thankfully there’s Lit where you can hit the ground running without any boilerplate. For a newbie to Web Components like me, it helped immensely.

Let’s see a quick example of how a LitElement looks.

Here we have a simple component that handles the sidebar positioning. It doesn’t have any other responsibility. And by using composition (slots) we render the content. Similar to what we would use {children} for in React

import {css, html, LitElement} from 'lit';
import {customElement, property} from 'lit/decorators.js';

import {noop} from '../utils/noop';
import {icons} from './icons';

@customElement('sidebar-container')
export class SidebarContainer extends LitElement {
  static styles = css`
    :host {
      /* */
    }
    .sidebar {
      /* */
    }
    .content {
      /* */
    }
    .close-button {
      /* */
    }
    .header {
      /* */
    }
    .list {
      /* */
    }
  `;

  @property({type: Function})
  onClose: VoidFunction = noop;

  render() {
    return html`<div class="sidebar">
      <div class="content">
        <div class="header">
          <button @click=${this.onClose} class="close-button">
            ${icons.xCircle}
          </button>
        </div>
        <div>
          <ul class="list">
            <slot></slot>
          </ul>
        </div>
      </div>
    </div>`;
  }
}

And here’s an idea of how it would be used. You can pass reactive props, callbacks, or slotted elements, giving you all the tools you need.

switch (this.state.status) {
  case 'loading':
    return html`<loading-state></loading-state>`;
  case 'unauthenticated':
    return html`<unauthenticated-state></unauthenticated-state>`;
  case 'error':
    return html`<error-state></error-state>`;
  case 'empty':
    return html`<empty-state></empty-state>`;
  case 'ready':
    return html`<sidebar-content .onClick=${this.handleClose}>
      ${this.data.map(
        (entry) => html`<li>
          <my-sidebar-row .entry=${entry}></my-sidebar-row>
        </li>`
      )}></sidebar-content
    >`;
}

Honestly, Web Components are the best option when writing browser extensions (of that kind at least). They're lightweight, well supported, solve the problem of conflicting styles, and they're easy to use.

I’m planning to write more about them in a future post, as I’m still learning about them. For now, I’ll leave you with a link to the Lit documentation.

Posting messages from the content script to service worker

The main point of my application was to fetch data from a remote server. Unfortunately, we can’t just use fetch from our injected script. We'll be slapped in the face by a CORS error. We have to create a service worker to do this for us.

First, we need to let our service-worker know that we want to fetch some data. To communicate with the service worker from the content script, we have to use the chrome.runtime.sendMessage API.

In the following example, I’m asking the service-worker to fetch some data the moment the component gets added to the DOM.

@customElement('some-root-component')
export class SomeRootComponent extends LitElement {
  // ...

  connectedCallback() {
    super.connectedCallback();

    // On load, kindly ask the service-worker to fetch the data
    chrome.runtime.sendMessage(
      {type: 'fetchSomething', payload: {id: this.someId}},
      // and assign a callback to run when the service-worker responds
      (response: RequestState<MyResponse>) => {
        this._doSomething(response);
      }
    );
  }
}

And then we have the service worker lurking, waiting for the message.

import {MessageType} from '../types';
import {requests} from './requests';

type MessageSender = chrome.runtime.MessageSender;

// Listen on messages from the content script
chrome.runtime.onMessage.addListener(function (
  message: MessageType,
  _: MessageSender,
  sendResponse: (response: unknown) => void
) {
  if (message.type === 'fetchSomething') {
    requests
      .fetchSomething(message.payload.id)
      .then((response) => {
        sendResponse(response);
      })
      .catch(() => {
        sendResponse({status: 'error', error: 'UNKNOWN_ERROR'});
      });
  }
  return true; // respond async
});

The message can be anything. Maybe we ask to create a bookmark. It depends on the use case. All it matters is that for all messages, we have a handler in the service worker.

CORS & consistent extension key

Now let’s talk about CORS. To allow CORS requests I had to make two tweaks:

1. Explicitly state the remote-server URL in my manifest (under host_permissions in my manifest.json)
2. Whitelist the extension in my CORS config on my server

Here’s the problem. Every time you load an unpacked application, a new id is assigned to your extension. If you have beta users, or your users are side-loading the extension, you don’t have a single origin to whitelist. The solution is assigning a unique extension id (key in manifest.json) to your extension.

Now to ensure that this is unique and no other extension will share the same key, we have to create a draft entry in the Chrome web store (and/or Edge store). Even if you don’t plan to publish your extension, you have to do this.

After you've created a draft entry, we add the key to our manifest.json and we're good to go. Every-time you remove and re-add the extension, it will have the same id. This way we can safely whitelist a single chrome-extension:// URI.

Here’s more about this approach

The same applies for the Edge store. In my extension I produce two builds extensions/edge & extensions/chrome each with different extension-ids in the manifest.json. This way I whitelist only these two origins in my backend.

Cookies & Authentication

Now, here’s a question. How do you authenticate your user? We assume that we make a call to our server, but how do we ensure that the user is authenticated?

One approach is to prompt them to fill in their credentials. But that's not great UX. In my case, I had to use the same authentication flow as the main application. If a user is authenticated in the application, I want to reuse their cookie. I don’t want to prompt them to log in again, just to use the extension.

Turns out there’s a way to do this. First, you need to add the cookies permission in the manifest.json file, then ensure that your application's domain exists in the host_permissions array.

{
  "name": "My Extension",
  "version": "1.0",
  "manifest_version": 3,
  "description": "My Extension",
  "permissions": ["cookies"],
  "host_permissions": ["https://my-website.com"]
}

Now if you include cookies in your fetch/axios requests, they will be sent to the server. And if the user is authenticated, you'll get the same response as if you were using the application directly. This is a great way to reuse your authentication flow, without re-inventing the wheel. I was honestly surprised that this was possible.

Posting messages from the service worker to the content scripts

Alright, let’s do the reverse now. How do you send a message from the service-worker to the content-script? Well, you can’t.

Each tab will have its content-script. So if you want to send a message to a specific tab, you need to know the tab's id. And to get that piece of info, we need access to the tabs permission.

Check again our lovely example if you’re confused.

Alright, let’s add the tabs permission to our manifest.json file.

{
  "name": "My Extension",
  "version": "1.0",
  "manifest_version": 3,
  "description": "My Extension",
  "permissions": ["cookies", "tabs"],
  "host_permissions": ["https://my-website.com"]
}

Now, we can use the chrome.tabs.query API to query for any tabs that match our filters. And then we can use the chrome.tabs.sendMessage API to send a message to the content-scripts of those tabs.

Here’s a little helper function that will send a message to all the tabs that match a specific URL pattern. It’s a bit naive, but you get the idea.

function notifyAllContentScripts(message: MessageType, urlPattern: string) {
  chrome.tabs.query({url: urlPattern}, function (tabs) {
    for (const tab of tabs) {
      if (tab.id) {
        // send the message, ignore the callback
        chrome.tabs.sendMessage(tab.id, message, () => undefined);
      }
    }
  });
}

And finally, the component has to attach a listener to accept the message. Note that the chrome.runtime.onMessage && chrome.runtime.sendMessage are the only API's available to the content script.

@customElement('some-root-component')
export class SomeRootComponent extends LitElement {
  // ...

  connectedCallback() {
    super.connectedCallback();

    chrome.runtime.onMessage.addListener((request: MessageType) => {
      if (request.type === 'some-action') {
        this._doSomething();
      }
    });
  }
}

Listening to cookies change

Now let’s combine some of the previous sections.

1. We can reuse the cookies
2. We can send messages from the content script to the service worker
3. We can notify all content scripts from the service worker

So, imagine that the user is initially logged out, and we prompt them to log in. How would we implement a feature, where we would try to fetch data, after a successful login on another tab?

Thankfully there’s the cookies.onChanged event that will notify us when a cookie changes.

Unfortunately I've found that the event is spamming quite a bit (maybe it’s my login flow code). So I've added a debounce function to only keep the last call.

function onCookieChange(changeInfo: chrome.cookies.CookieChangeInfo) {
  // Cookie was added - weird API design
  if (!changeInfo.removed) {
    if (changeInfo.cookie.domain.includes(appHostname)) {
      notifyContentScripts({type: 'refreshArticle'}, myTargetUrlPattern);
    }
  }
}

// Debounce the function to avoid spamming the content scripts
chrome.cookies.onChanged.addListener(debounce(onCookieChange, 500));

Then we notify the appropriate content scripts, and they can do whatever they want. They can post back and ask the service worker to do something, or they can do some logic themselves.

Custom fonts

Ok, enough with the data flow. Let’s add some custom fonts.

I read various approaches online, but I found that creating a font-script programmatically works just fine.

const gf = document.createElement('link');
gf.href =
  'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap';
gf.rel = 'stylesheet';
document.body.appendChild(gf);

Maybe there’s a strong reason to use web_accessible_resources instead, so I’ll keep an eye on that. For now, if the user blocks Google Fonts, I’m happy with system fonts.

Reacting to outside events

One requirement I had was to react to outside events. For example, if the user clicks on another DOM element, I want to close my extension. I used this very simple snippet.

@customElement('some-root-component')
export class SomeRootComponent extends LitElement {
  connectedCallback() {
    super.connectedCallback();
    // ... more
    window.addEventListener('click', this._handleClickOutside);
  }

  disconnectedCallback() {
    window.removeEventListener('click', this._handleClickOutside);
    super.disconnectedCallback();
  }

  private _handleClickOutside = (event: Event) => {
    if (!event.composedPath().includes(this)) {
      this._handleSidebarVisibility(false);
    }
  };
}

I’m unsure if attaching a listener with window is the best approach, so I’m still in the lookout for a better solution.

Development

As for development and testing, I went with Vite, Vitest & Storybook. Storybook is mandatory as the moment you add Browser extension APIs, you break Vite's development mode. Storybook supports Lit so it just works nicely. Here’s the documentation on writing Lit elements in Storybook.

As for my very light Vite config, there’s nothing special. Just picking the right entry points.

/// <reference types="vitest" />
import {defineConfig} from 'vite';

// https://vitejs.dev/config/
export default defineConfig({
  test: {
    globals: true,
  },
  build: {
    lib: {
      entry: ['src/client/main.ts', 'src/server/service-worker.ts'],
      formats: ['es'],
      name: 'MyExtension',
    },
  },
});

And here’s the full content script entry point. The whole logic is in the some-root-component.ts file. The React App.ts equivalent.

// Import the polyfills :(
import '@webcomponents/custom-elements';
// Import the web components
// import './components/a.ts';
// import './components/b.ts';
// import './components/c.ts'; etc...
import './components/some-root-component';

// Add to the page
document.body.appendChild(document.createElement('some-root-component'));

// Load the fonts
const gf = document.createElement('link');
gf.href =
  'https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap';
gf.rel = 'stylesheet';
document.body.appendChild(gf);

Bundling

My final output is two folders, one extensions/chome and one extensions/edge. I’ll omit posting my build script, but here’s the gist of it:

1. Build the Vite project, keep it in a temp folder
2. Create two folders, one for Chrome and one for Edge
3. Copy the Vite output to both folders
4. Build the manifest.json file, merging my base config with the Chrome specific config
5. Move it to the Chrome folder
6. Build the manifest.json file, merging my base config with the Edge specific config
7. Move it to the Edge folder

Publishing

I've used the Chrome Developer Dashboard to publish the extension. It’s a simple process, but it will set you back 5$. The whole reviewing process took about 2 days, so no complaints there.

Final thoughts

Building a browser extension isn’t as intimidating as I thought. It has its quirks, and some unknowns due to the introduction of Manifest v3, but nothing that can’t be overcome.

I specifically am proud of using Web Components and Lit on this project. It has been on my radar for so long, but never had the chance to use it. One possible extension would be to use Shoelace for styling, but I’ll leave that for another day.

So there’s that. A simple browser extension, built and published in a few days. I hope you found it useful.

Resources:

• Chrome Extensions Documentation
• Lit Documentation
• Generating a constant extension Key
• CSS Tricks - How to transition to Manifest v3

Probably not what you're looking for

This was written on 2022, targeting Next.js 13 & the Pages router. Since then I have made a few modifications and moved everything to RSC. If you're looking for help, I can share with you my solutions, but they don't warrant a full blog post. RSS specifically is a pain point.

TL;DR:

• Gatsby is excellent for static sites. I don’t like it for dynamic sites, and its workarounds are not ideal.
• Next.js is excellent too, but recreating the same functionality (Markdown pipeline, RSS, Image optimizations) as Gatsby is a pain.
• Next.js has the market share, and the backing of the React core team, so it should be future-proof.
• The current stack is Next.js, Tailwind, Floating-UI, MDX, Cloudinary, and Netlify.
• I've introduced some fun new features, like better snippets, static tweets, and more.
• Overall the rewrite was a success, I’m happy with the result but it’s far from perfect.

Moving on from Gatsby

I've been using Gatsby since v0, and it’s perfect for my use case. That said I had a few reasons for moving on.

1. I mostly work with Next.js. My only Gatsby project is my blog and I don’t like the context-switching.
2. There’s nothing that interests me in the latest Gatsby releases. For example in Gatsby 5, the two big changes are Partial Hydration and the Slices API.
3. I just don’t like the GraphQL layer and its plugin ecosystem.

I can’t stress enough the last point. I wanted to use MDX in my Gatsby blog, and I was debugging some GraphQL weirdness that pushed me to rewrite it all with Next.js.

Rewriting with Next.js

I wanted to pick a framework that supports SSR out of the box. I was torn between Remix & Next.js but decided to go for the more "mature" Next.js. Had I seen the Shopify acquisition news earlier, I might have picked Remix.

I was also a bit hyped by the Next.js 13 release and wanted to try out the new features. My enthusiasm didn’t last long, as I realized it was a paper release, and the new features were still in beta or experimental. Anyhow, I decided to stick with it, use the /pages folder for now and see how it goes.

Next.js on Netlify

I have various projects and they all live on Netlify. Even if Vercel is a better fit for Next.js, I’m not going to change hosting providers. I’m also a bit stubborn, and I don’t like vendor lock-in. If Next.js starts to become problematic to deploy elsewhere, I’ll move to Remix.

So far the experience has been smooth. CSP headers were not applying correctly, but I fixed it by adding a netlify.toml file. I also cached my fonts and static assets, something Vercel supposedly does out of the box.

Here’s my config so far:

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"
    Content-Security-Policy = '''
    default-src 'self';
    script-src 'self' 'unsafe-eval' 'unsafe-inline';
    child-src codesandbox.io;
    style-src 'self' 'unsafe-inline';
    img-src 'self' blob: data: *.cloudinary.com pbs.twimg.com i.scdn.co;
    media-src 'none';
    connect-src *;
    font-src 'self';'''
    Referrer-Policy = "no-referrer"
    X-Content-Type-Options = "nosniff"
    X-DNS-Prefetch-Control = "off"
    Strict-Transport-Security = "max-age=31536000; includeSubDomains; preload"
    Permissions-Policy = "camera=(), microphone=(), geolocation=()"

[[headers]]
  for = "/fonts/*"
    [headers.values]
      cache-control = 'public, max-age=31536000, immutable'

[[headers]]
  for = "/_next/static/*"
    [headers.values]
      cache-control = 'public, max-age=31536000, immutable'

Refactoring the code

This list is not exhaustive, but it’s a good summary of the changes I made. The snippets I’ll post are meant to provide some general idea, and might not show the whole implementation. I’ll try to keep it updated as I make more changes.

1. Updating pages and components

I decided to start a new project from scratch and add TypeScript. Thankfully, I had abstracted most of the Gatsby-related stuff, so it was painless moving everything to their new folders.

export default function GatsbyBlogPage() {
  const postsByYear = useGroupedPosts();

  return (
    <Layout>
      <Container>
        <Cover
          title="Blog"
          text="Writing about coding, life, productivity & more"
        />
        <PostGrid postsByYear={postsByYear} />
      </Container>
    </Layout>
  );
}

export function Head() {
  return (
    <MetaTags
      title="Blog"
      path="/blog"
      description="Writing about coding, life, productivity & more"
    />
  );
}

export default function NextBlogPage({
  postsByYear,
}: {
  postsByYear: GroupedPosts;
}) {
  return (
    <>
      <MetaTags
        title="Blog"
        path="/blog"
        description="Writing about coding, life, productivity & more"
      />
      <Layout>
        <Container>
          <Cover
            title="Blog"
            text="Writing about coding, life, productivity & more"
          />
          <PostGrid postsByYear={postsByYear} />
        </Container>
      </Layout>
    </>
  );
}

export async function getStaticProps() {
  const postsByYear = getAllGroupedPosts();
  return {props: {postsByYear}};
}

2. Updating navigation

My first issue was replacing the very clever <GatsbyLink />. Unfortunately, Next.js needs some help with highlighting the active navigation link. I also had to update the prefetch functionality, so that linked pages were fetched only on hover. Otherwise, it was a simple change.

import React from 'react';
import {Link as GatsbyLink} from 'gatsby';

export function Link({children, to, ...props}) {
  return (
    <GatsbyLink to={to} {...props}>
      {children}
    </GatsbyLink>
  );
}

import NextLink, {LinkProps} from 'next/link';
import {useRouter} from 'next/router';

type ActiveLinkProps = LinkProps & {
  activeClassName?: string;
  className?: string;
};

export function Link({
  href,
  children,
  className: targetClassName = '',
  activeClassName,
  prefetch = false,
  ...props
}: React.PropsWithChildren<ActiveLinkProps>) {
  const {asPath} = useRouter();
  const className =
    targetClassName +
    (asPath === href && activeClassName ? ' ' + activeClassName : '');

  return (
    <NextLink href={href} {...props} className={className} prefetch={prefetch}>
      {children}
    </NextLink>
  );
}

3. Nit changes

There were some smaller changes, like font loading, analytics configuration, and CSS loading. In short, whatever goes in gatsby-browser.js in Gatsby, goes in pages/_app.js in Next.js.

import '@/styles/global.css';

import {Inter} from '@next/font/google';
import type {AppProps} from 'next/app';

import {Analytics} from '@/components/Analytics';

const interVariable = Inter({subsets: ['latin'], display: 'swap'});

export default function App({Component, pageProps: {...pageProps}}: AppProps) {
  return (
    <>
      <Analytics />
      <div className={interVariable.className}>
        <Component {...pageProps} />
      </div>
    </>
  );
}

4. Dropping GatsbyImage, and using Cloudinary

Boy, oh boy. <GatsbyImage /> is awesome. I really didn’t have to think about images in my Gatsby blog at all. Vercel pretty much vendor locks <NextImage />, and I deploy on Netlify, so I decided to use Cloudinary and call it a day. I know Netlify does its best with its own Next Runtime, but I wanted to trust a dedicated service for optimizing my images. Here’s what I’m using:

import Image from 'next/image';

import {CLOUDINARY_URL} from '@/links';

type CloudinaryImageProps = {
  src: string;
  alt: string;
  width: number;
  height: number;
  title?: string;
  className?: string;
  blurDataURL?: string;
  quality?: number;
};

type CloudinaryLoaderProps = Pick<
  CloudinaryImageProps,
  'src' | 'width' | 'height'
>;

function cloudinaryLoader({src, width, quality = 90}: CloudinaryLoaderProps) {
  return `${CLOUDINARY_URL}/w_${width},q_${quality},f_webp${src}`;
}

export function CloudinaryImage({
  src,
  alt,
  width,
  height,
  title,
  className,
  blurDataURL,
  quality,
}: CloudinaryImageProps) {
  return (
    <Image
      quality={quality}
      src={src}
      loader={cloudinaryLoader}
      alt={alt}
      title={title}
      width={width}
      height={height}
      className={className}
      {...(blurDataURL ? {placeholder: 'blur', blurDataURL: blurDataURL} : {})}
    />
  );
}

As for the blurDataURL, I created a function to generate them on demand

export async function getBase64Image(imageId: string): Promise<string> {
  const response = await fetch(
    `${CLOUDINARY_URL}/w_100/e_blur:1000,q_auto,f_webp${imageId}`
  );
  const buffer = await response.arrayBuffer();
  const data = Buffer.from(buffer).toString('base64');
  return `data:image/webp;base64,${data}`;
}

..and include them in the MDX files.

---
title: 'Migrating from Gatsby to Next.js'
date: '2022-11-10'
description: 'Documenting website rewrite with Next.js'
category: 'React'
featuredImage: '/v1667896248/blog-images/covers/gatsby-to-next.jpg'
blurHash: 'data:image/webp;base64,UklGRi4BAABXRUJQVlA4ICIBAACQCgCdASpkAEMAPrFEmEopKqIhtBuacVAWCWctgApEhfgL6cVs+EP+L7eCBMs6WxuBdNhnrhgZBc3o3T07pyMmL/33nE0QwO5CRL7Rcmu4dPcZyTC4MBUkUest3AAA/vCwN7ITIh1amqRK9uZ9e8L+JX4epgvVOoHWyh61Nr2+j3iJ1n5+tTV1e8qSP1QjANudOvbZEuBwQa9ipePIbKgS4Q5u5hroxOh4PorEJQgLU0HpsMc8BorpBdCX9VTbR4lYvZ9cZ34FW5j9pTYfkDICNcGYDODTMFeWGroq5PG5p6X6BMdLTOLEgfKWZYzwyjObVdLf7A0FeBoPihEMEILwKlUghr/eFH8vKHeKgdhCwhCLhB1qGhoCBzA7e8c4HyNIAA=='
---

I have [written a post](/blog/state-of-blog) about my blog's stack and why I don’t plan on rewriting it with a different framework. Turns out, this was a lie, and I rewrote it.

Finally, I can use the <CloudinaryImage /> component anywhere in my app, including MDX files.

export function Post({post}: {post: PostType}) {
  return (
    <Link
      className="overflow-hidden h-full z-0 grid sm:grid-cols-1 ring-gray-100 ring-offset-8 hover:ring-4 rounded-lg group"
      href={`/blog/${post.slug}`}
      key={post.slug}
      aria-label={`Read the article '${post.frontmatter.title}'`}
    >
      <div>
        <div className="shrink-0 relative rounded-lg overflow-hidden">
          <CloudinaryImage
            alt={`Cover image of '${post.frontmatter.title}'`}
            src={post.frontmatter.featuredImage}
            width={480}
            height={320}
            className="max-h-full w-full rounded-lg overflow-hidden brightness-75 object-cover"
            blurDataURL={post.frontmatter.blurHash}
          />
        </div>
        {/* ... */}
    </Link>
  );
}

Could I do better? Probably. For now, it works fine and I can focus on other things. Most importantly I can focus on writing content, and if I feel inspired, build something like Kent C. Dodds' getImageBuilder.

5. Replacing Gatsby's Markdown plugins, and introducing MDX

Here’s the juicy part. I wanted to create some custom components in my markdown files. Essentially I had to replicate the functionality of these plugins:

// This is not my full config, just the relevant parts
module.exports = {
  plugins: [
    `gatsby-transformer-json`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`,
    `gatsby-plugin-image`,
    `gatsby-plugin-twitter`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/src/content/`,
        name: 'data',
      },
    },
    {
      resolve: `gatsby-transformer-remark`,
      options: {
        plugins: [
          {
            resolve: `gatsby-remark-autolink-headers`,
            options: {
              offsetY: `100`,
              icon: `<svg aria-hidden="true" height="20" version="1.1" viewBox="0 0 16 16" width="20"><path fill='#2A506F' fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg>`,
              maintainCase: true,
            },
          },
          {
            resolve: `gatsby-remark-vscode`,
            options: {
              theme: `GitHub Dark`,
              extensions: [
                path.resolve(__dirname, './github-vscode-theme.zip'),
              ],
            },
          },
          `gatsby-remark-copy-linked-files`,
          `gatsby-remark-external-links`,
          `gatsby-remark-responsive-iframe`,
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 900,
              quality: 100,
              withWebp: true,
            },
          },
        ],
      },
    },
    {
      resolve: `gatsby-plugin-feed`,
      options: {},
    },
  ],
};

Alright, first I created a /lib/posts.ts file with all the relevant functions to get the posts. I’ll spare you most of the implementation details. Essentially I’m reading from the file system and parsing the frontmatter and markdown body.

import fs from 'fs';
import matter from 'gray-matter';
import {join} from 'path';

import {PaginatedPreviewPost, Post, PostWithMdx} from '@/types/types';

import {mdxToHtml} from './mdxToHtml';

const postsDirectory = join(process.cwd(), 'content/blog');

export function getPostMetadataBySlug(slug: string): Post {}

export async function getFullPostBySlug(slug: string): PostWithMdx {
  const fullPath = join(postsDirectory, slug, 'index.md');
  const fileContents = fs.readFileSync(fullPath, 'utf8');
  const {data: frontmatter, content} = matter(fileContents);

  const mdxContent = await mdxToHtml(content);

  return {slug, frontmatter, content: mdxContent};
}

export function getAllPosts(): Array<Post> {}

export function getLatestPosts(numberOfPosts = 4): Array<Post> {}

export function getAllGroupedPosts(): Record<number, Array<Post>> {}

export function getPrevAndNextPosts(slug: string) {}

As for the MDX transformations, I’m using next-mdx-remote with a bunch of rehype plugins. Pretty much what Gatsby does under the hood.

import {serialize} from 'next-mdx-remote/serialize';
import readingTime from 'reading-time';
import {rehypeAccessibleEmojis} from 'rehype-accessible-emojis';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
import rehypePrettyCode from 'rehype-pretty-code';
import rehypeSlug from 'rehype-slug';
import remarkGfm from 'remark-gfm';

import {MdxContent} from '@/types/types';

import {shikiOptions} from './shiki';

export async function mdxToHtml(source: string): Promise<MdxContent> {
  const mdxSource = await serialize(source, {
    mdxOptions: {
      format: 'mdx',
      remarkPlugins: [remarkGfm],
      rehypePlugins: [
        rehypeSlug,
        [rehypeAutolinkHeadings, {properties: {className: ['anchor']}}],
        [rehypePrettyCode, shikiOptions],
        rehypeAccessibleEmojis,
      ],
    },
  });

  return {
    html: mdxSource,
    wordCount: source.split(/\s+/gu).length,
    readingTime: readingTime(source).text,
  };
}

I’m using Shiki for the syntax highlighting. I tried both Prism.js & Highlight.js and neither come close to it. I can use any VSCode theme, just like I was used to with gatsby-remark-vscode. Currently, I’m using the "Tokyo Night Storm" theme.

That said, I have heavily patched the rehype-pretty-code plugin. Since I’m not doing client-side highlighting, my bundle is a bit bloated, so I had fix some stuff.

Finally, consuming the data on the pages.

import {PostCover} from '@/components/blog/PostCover';
import {PostFooter} from '@/components/blog/PostFooter';
import {Container} from '@/components/Container';
import {Layout} from '@/components/Layout';
import {MDXRenderer} from '@/components/mdx/Mdx';
import {MetaTags} from '@/components/MetaTags';
import {getAllPosts, getFullPostBySlug, getPrevAndNextPosts} from '@/lib/posts';
import type {PaginatedPreviewPost, PostWithMdx} from '@/types/types';

export default function BlogPage({
  post,
  prevPost,
  nextPost,
}: {
  post: PostWithMdx;
  prevPost: PaginatedPreviewPost;
  nextPost: PaginatedPreviewPost;
}) {
  return (
    <>
      <MetaTags
        title={post.frontmatter.title}
        path={post.slug}
        description={post.frontmatter.description}
      />
      <Layout>
        <Container>
          <PostCover post={post} />
        </Container>
        <article className="prose max-w-3xl mx-auto px-6 pt-6">
          <MDXRenderer {...post.content.html} />
        </div>
        <div className="max-w-3xl mx-auto px-6">
          <hr className="my-12 text-zinc-100" />
          <PostFooter prevPost={prevPost} nextPost={nextPost} />
        </div>
      </Layout>
    </>
  );
}

export async function getStaticPaths() {
  const paths = getAllPosts();
  return {
    paths: paths.map(({slug}) => ({params: {slug}})),
    fallback: 'blocking',
  };
}

export async function getStaticProps({params}: {params: {slug: string}}) {
  const post = await getFullPostBySlug(params.slug);

  if (!post) {
    return {notFound: true};
  }

  const {prevPost, nextPost} = getPrevAndNextPosts(post.slug);

  return {
    props: {
      post: {
        ...post,
        frontmatter: {
          ...post.frontmatter,
          featuredImage: '',
          blurHash: '',
        },
      },
      prevPost,
      nextPost,
    },
  };
}

6. Building custom components

The process is straightforward. Write a React component..

export function InfoBox({children}: {children: React.ReactNode}) {
  return (
    <blockquote className="text-md relative border border-indigo-300 bg-indigo-50">
      <InformationCircleIcon className="absolute -top-3 -left-3 h-8 w-8 rounded-full bg-indigo-300 text-white" />
      {children}
    </blockquote>
  );
}

...and add it in the MDXRenderer's list of custom components.

import type {MDXRemoteSerializeResult} from 'next-mdx-remote';
import {MDXRemote} from 'next-mdx-remote';

import {InfoBox} from './BlockQuotes';

export const components = {InfoBox};

export function MDXRenderer(props: MDXRemoteSerializeResult) {
  return <MDXRemote {...props} components={components} />;
}

Then in my MDX file, I can call it as a normal React component. This makes it very easy to build fancy stuff like Charts, Code Blocks, DataTables, or some silly stuff I’m planning next.

<InfoBox>
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ultrices
  faucibus massa, vitae placerat leo lacinia non. Integer malesuada velit in
  magna luctus sodales sed eu justo.
</InfoBox>

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ultrices faucibus massa, vitae placerat leo lacinia non. Integer malesuada velit in magna luctus sodales sed eu justo.

7. RSS

My RSS implementation makes me sad. At this point, I contemplated if writing my blog in Next.js makes any sense. I’m using this approach. This will be improved in the future.

Final thoughts

Was it worth it?

My previous stack wasn’t broken, so it didn’t need fixing. There isn’t any wow moment, I just had to scratch that itch. I’m happy with the result, even though it feels very hacky at various places, but I’m sure I’ll improve it moving forward.

If anything, I’m particularly happy with the bundle size decrease, as well as my fancy new code blocks.

I shouldn’t be hard on Next.js, as I’m building a blog and not a complex app. If anything I make things harder for myself by not using a CMS.

Resources:

• Next.js 13
• How I Built My Blog (joshwcomeau.com)
• How I Migrated from Gatsby to Next.js (jeffjadulco.com)
• A Walkthrough of migrating MaxRozen.com from Gatsby to Next.js
• Migrating this Blog to Next.js from Gatsby (eyas.sh)

Well, that's never the case. Chances are that this value will also be required or set by some other component. So what do we do? We're moving useState higher in the component hierarchy and we pass it around using composition/context.

Then, we might want to fetch some data. React-query might do the job, but we start fragmenting the code. Who initializes the request? Where are we invalidating our queries? What happens if we need dependent queries? Where do all these live, in a messy useEffect hook?

Even the most coherent implementation will have some hacks to comply with Reacts lifecycle. After having been bitten by this for quite some time, I prefer to keep my business logic written outside React.

You can use Redux, or Zustand. Any will do. I prefer to use RxJS! You can still get the same sense of organization, with more fine-grained control over the data flow.

I know that RxJS isn’t very loved by a part of the React community. I understand this. If you’re going to take anything from this blog let this be this. There’s no harm in using Redux, or Zustand. If you’re stuck with a SPA, and the URL state is limiting you, by all means, use them. Don’t reinvent the wheel. Here’s a great article about how tedious it is making the useReducer/useContext combo performant.

Store set-up

The core idea is that all business logic for our feature page (or complex component) lives inside a closure, outside React. This is where all the nitty-gritty of our application logic happens.

Our React app will receive only the bare minimum it needs to render our components. It will not know any transformations. This allows us to limit the complexity in a single file, easily testable without having to bother with the React lifecycle.

We should still write our integration tests to discover any regressions in our React components. We just have the added benefit that we can test in isolation our business logic.

He's a simple case. We don’t have to guess who will use orderBy next.

I prefer to export regular Observables instead of BehaviorSubjects. BehaviorSubjects can be updated by using .next(myValue) from the outside world.

Alright, code...

type OrderBy = 'NAME_DESC' | 'NAME_ASC';

export function createExampleStore() {
  const setOrderByEvent$ = new Subject<OrderBy>();
  const orderBy$ = setOrderByEvent$.pipe(
    map((orderBy) => orderBy),
    startWith('NAME_ASC'),
    shareReplay(1)
  );

  return {
    state: {
      orderBy$: withInitialValue(orderBy$, 'NAME_ASC'),
    },
    actions: {
      setOrderBy: (orderBy: OrderBy) => setOrderByEvent$.next(orderBy),
    },
  };
}

I can hear you saying, "But isn’t this very ceremonial? useState is simpler".

const [orderBy, setOrderBy] = useState<OrderBy>('NAME_DESC');

And I agree, it’s simpler. But what happens when:

• We're asked to reset some other filter, every-time orderBy changes. It’s irrelevant to our component.
• And then we need to reuse controls like these in a modal/sidebar? We probably need to change our component hierarchy.

Let’s see one case where a value depends on another. Look how elegantly we update the pageIndex. We either set it explicitly, or it resets when the page size updates. No useEffect or mixing side-effects in callbacks like handlePageIndexChange.

No matter who uses these, we ensure that we have separated our design from our application state.

export function createExampleStore() {
  const setPageLimitEvent$ = new Subject<number>();
  const pageLimit$ = setPageLimitEvent$.pipe(
    map((pageLimit) => pageLimit),
    startWith(50),
    shareReplay(1)
  );

  const setPageIndexEvent$ = new Subject<number>();
  const pageIndex$ = merge(
    setPageIndexEvent$.pipe(
      map((pageIndex) => pageIndex),
      startWith(0),
      shareReplay(1)
    ),
    setPageLimitEvent$.pipe(mapTo(0)) // Reset the current page, on page-size change
  );

  return {
    state: {
      pageIndex: withInitialValue(pageIndex$, 0),
      pageLimit: withInitialValue(pageLimit$, 50),
    },
    actions: {
      setPageIndex: (pageIndex: number) => setPageIndexEvent$.next(pageIndex),
      setPageLimit: (pageLimit: number) => setPageLimitEvent$.next(pageLimit),
    },
  };
}

We can write anything. It’s a simple TypeScript file. Let’s see a more expressive one.

Here we use discriminated unions to avoid impossible states. Take a look at line 30. We only export a single boolean Observable. Our component doesn’t care about the # of selected rows. Just the bare minimum. Keeping our UI flexible.

type RowSelection =
  | {type: 'ADD'; id: number}
  | {type: 'REMOVE'; id: number}
  | {type: 'CLEAR_ALL'};

export function createExampleStore() {
  const setSelectedRowEvent$ = new Subject<RowSelection>();

  const selectedRows$ = setSelectedRowEvent$.pipe(
    scan((rows: Array<number>, event) => {
      switch (event.type) {
        case 'ADD':
          return [...rows, event.id];
        case 'REMOVE': {
          return rows.filter((rowId) => rowId !== event.id);
        }
        case 'CLEAR_ALL': {
          return [];
        }
        default: {
          return rows;
        }
      }
    }, []),
    startWith([]),
    shareReplay(1)
  );

  const exportSelectedRowsEvent$ = new Subject<void>();
  const isExportAvailable$ = selectedRows$.pipe(
    map((rows) => rows.length > 0),
    shareReplay(1)
  );
  const exportRequest$ = combineLatest([
    exportSelectedRowsEvent$,
    isExportAvailable$,
  ]).pipe(
    filter(([, isExportAvailable]) => isExportAvailable),
    map(([selectedRows]) => ({payload: {selectedIds: selectedRows}}))
    // do a network request
  );

  return {
    data: {
      exportRequest$: withInitialValue(exportRequest$, {status: 'IDLE'}),
    },
    state: {
      selectedRows: withInitialValue(selectedRows$, [] as Array<number>),
      isExportAvailable: withInitialValue(isExportAvailable$, false),
    },
    actions: {
      selectRow: (id: number) => setSelectedRowEvent$.next({type: 'ADD', id}),
      unselectRow: (id: number) =>
        setSelectedRowEvent$.next({type: 'REMOVE', id}),
      clearAllRows: () => setSelectedRowEvent$.next({type: 'CLEAR_ALL'}),
      //
      exportSelectedRows: () => exportSelectedRowsEvent$.next(),
    },
  };
}

And finally, we can handle network requests with confidence.

1. Not bothering with useEffect
2. Not looking for which useQuery initialized that request
3. Canceling, throttling, debouncing, etc, with ease

Connecting to the React world

Again, we have a simple TypeScript file. Nothing React-specific yet. Let’s wire it with our view. We will use Context to pass it around.

React context is a form of Dependency Injection. It’s not a state-management solution. Its combination with useState/useReducer makes it one. There’s no contradiction here.

Here’s how we're going to implement it.

1. We're rendering a route with React-Router
2. This entry component will create our store, and re-use its instance until it’s unmounted
3. It will wrap its children with a context provider, passing down the store
4. Every consumer can fetch that store, and subscribe to the stream it needs.

We won’t have extra rerenders. If any other observable than the one we’re subscribing to changes, nothing will happen. We’re good.

Let’s write our one-off boilerplate. Creating a context, typecasting it, and writing our hook for the consumer. The same thing you would do for a useReducer

import {createContext, useContext, useRef} from 'react';

export type ExampleStore = ReturnType<typeof createExampleStore>;

export const ExampleStoreContext = createContext({} as ExampleStore);

export function useExampleStore() {
  return useContext(ExampleStoreContext);
}

And finally, some React silliness to ensure that we won’t override our store. Note that we can pass props to our store initialization. It could be the id of the project we’re working on since we normally get that info from the URL.

import {createContext, useContext, useRef} from 'react';

// This imports any of the previous snippets, where a store is created
import {createExampleStore} from './ExampleStore';

export type ExampleStore = ReturnType<typeof createExampleStore>;

export const ExampleStoreContext = createContext({} as ExampleStore);

export function useExampleStore() {
  return useContext(ExampleStoreContext);
}

// can pass optional props
export function useCreateExampleStore() {
  const storeRef = useRef<ExampleStore>();
  if (storeRef.current === undefined) {
    // can pass optional props
    storeRef.current = createExampleStore();
  }
  const store = storeRef.current;
  return store;
}

And here’s what our page component would look like. A single store that can react to anything.

export function ExamplePage() {
  const store = useCreateExampleStore();

  return (
    <ExampleStoreContext.Provider value={store}>
      <Layout>
        <OrderBySelector />
        <PageIndexSelector />
        <PageLimitSelector />
        <ExportTrigger />
      </Layout>
      <MyModal />
      <MySidebar />
      <LiterallyAnything />
    </ExampleStoreContext.Provider>
  );
}

Now let’s see what a component would look like. It’s not different than the Redux equivalent.

export function OrderBySelector() {
  const {state, actions} = useExampleStore();
  const orderBy = useObservable(state.orderBy$);

  return (
    <Select value={orderBy} onChange={actions.setOrderBy}>
      <Select.Option value="NAME_ASC">Name ASC</Select.Option>
      <Select.Option value="NAME_DESC">Name DESC</Select.Option>
    </Select>
  );
}

You can also build some Facades. Something like useSortBy and export orderBy and its setter, so that the component won’t have full access to the store. I don’t like to optimize that much early on, but it’s a valid call.

And let’s take closer to the useObservable hook, the glue that keeps everything together. Just plain React. Listen to the subscription, grab the value, bring it as state and move on.

import {Observable} from 'rxjs';
import {useState, useEffect} from 'react';

type ObservableWrapper<T> = {
  observable: Observable<T>;
  initialValue: T;
};

export function withInitialValue<T>(
  observable: Observable<T>,
  initialValue: T
) {
  return Object.freeze({observable, initialValue});
}

export function useObservable<T>({
  observable,
  initialValue,
}: ObservableWrapper<T>) {
  const [state, setState] = useState<T>(() => initialValue);

  useEffect(() => {
    const sub = observable.subscribe(setState);
    return () => sub.unsubscribe();
  }, [observable]);

  return state;
}

There are various 3rd-party implementations like the one from Observable Hooks. That said, I prefer to "hide" the initial value that React needs for that first render. You're free to use a simpler implementation and provide the initial value directly from the component.

Without React-context

With the addition of useSyncExternalSyncStore it’s "doable" to omit context. Here’s how the updated useObservable would look:

function useObservable<T>(observable: BehaviorSubject<T>): T {
  let observableRef = useRef<BehaviorSubject<T>>(observable);

  if (observableRef.current !== observable) {
    observableRef.current = observable;
  }

  const subscribe = useCallback((handleStoreChange: VoidFunction) => {
    const subscription = observableRef.current.subscribe(handleStoreChange);
    return () => subscription.unsubscribe();
  }, []);

  const getSnapshot = useCallback(() => {
    return observableRef.current.getValue();
  }, []);
  return useSyncExternalStore(subscribe, getSnapshot);
}

There’s an obvious "caveat" that we have to use BehaviorSubject instead, as we need access to the "current" value in getSnapshot.

I like my current approach, but if React Suspense requires it, I might revisit it in the future.

Final thoughts

So there’s that. I find this approach gives me all the tools I need to tackle anything. No matter how simple any project starts, it has a solid foundation that will tackle any complexity.

By moving my business logic outside React's lifecycle, I can write expressive code without feeling limited.

I wonder how many people realize that React Hooks is really just disconnected, less declarative reactive programming.

— Ben Lesh, RxJS Team Lead

If you don’t like RxJS, that’s fine! Use Redux Toolkit and its new RTK Query package. xState? Be my guest, love it.

My only suggestion is that you move away from the useState/useReducer approach. It doesn’t scale. Especially for start-up environments where there are a lot of moving pieces in the UI. Use your time building features, and not optimizing re-renders.

Resources:

• How to write performant React apps with Context
• [React Docs] Fetching data with Effects (check the purple section)
• Hooks Considered Harmful
• Meet the new hook useSyncExternalStore, introduced in React 18 for external stores
• The Facade pattern and applying it to React Hooks
• Do I have to put all my state into Redux? Should I ever use React's setState()?

The problem

Let’s examine a common scenario.

We get the backend response, an array of objects.

const data = await fetch('/api/books').then((res) => res.json());!

We map over this array in order to render a table

<Table.Container>
  <Table.Header>
    <Table.HeaderCell>...</Table.HeaderCell>
    <Table.HeaderCell>...</Table.HeaderCell>
    <Table.HeaderCell>...</Table.HeaderCell>
  </Table.Header>
  {data.map((book) => (
    <Table.Row key={book.uuid}>
      <Table.Cell>
        <ComponentA propA={...book.propertyA} propB={...book.propertyB} />
      </Table.Cell>
      <Table.Cell>
        <ComponentB propC={...book.propertyC} />
      </Table.Cell>
      <Table.Cell>
        <ComponentC propA={...book.propertyA} propB={...book.propertyB} />
      </Table.Cell>
    </Table.Row>
  ))}
</Table.Container>

Each row of the table is a component that holds multiple sub-components

<Table.Cell>
  <ComponentA {...book.propertyA} />
</Table.Cell>

There shouldn’t be an issue, right? Our content changes only by applying filters, pagination, or sorting. All will trigger a fresh batch of data, so there won’t be a noticeable change.

But, what if we implement a functionality where we can select a range of items? For example, we can pick the first ten items, the last ten items, or the whole page. Here’s where things get tricky.

<Table.Container>
  <Table.Header>
    <Table.HeaderCell>
      <Checkbox
        state={tableSelectionState} // 'ALL' | 'SOME' | 'NONE'
        onChange={handleAllSelection}
      />
    </Table.HeaderCell>
    <Table.HeaderCell>...</Table.HeaderCell>
    <Table.HeaderCell>...</Table.HeaderCell>
    <Table.HeaderCell>...</Table.HeaderCell>
  </Table.Header>
  {data.map((book) => (
    <Table.Row key={book.uuid}>
      <Table.Cell>
        <Checkbox
          isChecked={selectedBooks.includes(book.uuid)}
          onChange={handleCheckboxSelect}
        />
      </Table.Cell>
      <Table.Cell>
        <ComponentA propA={...book.propertyA} propB={...book.propertyB} />
      </Table.Cell>
      <Table.Cell>
        <ComponentB propC={...book.propertyC} />
      </Table.Cell>
      <Table.Cell>
        <ComponentC propA={...book.propertyA} propB={...book.propertyB} />
      </Table.Cell>
    </Table.Row>
  ))}
</Table.Container>

By clicking the 'select-all' checkbox in the header row, all the components will re-render. This is a very expensive operation.

The same applies for selecting a single row. The parent that holds the state will update and the rest of the components will re-render.

Oh no, it’s slow. It has always been.

No point thinking about these pesky re-renders. Our components were slow from the start.

Extracting expensive computations

We should dig deep into our components and look for the expensive computations.

Commonly the culprits are:

1. Date parsing/formatting
2. Nested loops

By formatting our data the moment we get them from the backend, (adding an adapter if you may), we guarantee two things:

• All the expensive computations are done on the get go, are co-located, easier tested and probably cached.
• Future incompatibilities with the backend will be fixed in a single place

Final thoughts

Before going crazy about multiple rerenders, memoizing everything, we should take a step back and figure out if our components are doing too much.

For more digging on composition, re-renders and et al, I suggest following up on this great read: The mystery of React Element, children, parents and re-renders

Resources:

• "Fix the slow render before you fix the re-render"
• "How to Detect Slow Renders in React?"
• "You can use React Query for slow computation, not just API"

1. Is the candidate a good fit for the team?
2. Can the candidate challenge the ways we do things, propose ideas, and improve the team?

I've been on the other side too, and in that case my questions to answer are the following:

1. Does this job align with my preferred working conditions?
2. Can I get ownership? How much?
3. What's the pace like?
4. What's their engineering culture?
5. Do they care about their craft? How do they comb their code debt?
6. Will I grow? If I stay for 4 years, will I feel I repeated the same year four times?
7. Are they remote-first or remote-out-of-necessity?
8. Is it a step up money-wise?
9. How are promotions handled? Is being an IC viable?

Starting with an honest intro

I preface the interview with an introduction about me. I let them know about my role, its responsibilities, and how long I’ve been doing it. Then, I move on and tell them a bit about my previous job and any other one before that. Lastly, I tell them about how I got into the industry and how I experienced the JavaScript popularity explosion. It shouldn’t take more than a minute.

Then, I let the candidate share their experience.

I might be a spoke person for my company, but to have an honest conversation with the candidate, I have to open up. Let them know, that I’m too a developer who has a career, who has changed jobs, and will do it again. We are pretty much in the same position, and we're having a call to see if we can collaborate.

Expanding on company, team, and role specifics

Next up, I will share more about the company, the position, and how we work. I don’t expect the candidate to know much about the company, but I want to make sure they know what we do.

Succinctly, I’ll cover

• The company product, the clients, and which problem it solves for them
• The company size, its growth projection, and funding status
• How the company is structured
• How the team operates
• The stack, the development process, and practices we follow.
• The responsibilities of the role
• Continuous learning and growth
• Remote policies, if applicable

And finally answer any questions.

It’s important for the candidate to feel confident to ask questions they care about. It should be clear that it’s for their benefit and they won’t be evaluated for them. Asking about the number of meetings, employee retention, and such, is not a taboo. I’m also an employee, who had my fair share of bad experiences because I didn’t ask enough questions beforehand.

It’s best to be transparent, even if it means losing the candidate. For example, if they want to work in a small company, and the plan is to hire 100 more people, they have to know it now. No surprises.

Evaluating working experience

Moving on, the goal is to discuss their relevant working experience. Since I’m interviewing for front-end positions, I’ll probably lead with React. I’ll point out problems I've faced when building apps, and ask the candidate to join me and share their thoughts, based on their experience.

Just having a normal discussion as if we're discussing a ticket. I want to understand what challenges they've faced, their takeaways, things they care about, and all these nice stuff you don’t get from code-golfing.

Aligning

So far the candidate should have a good idea if they like what they hear. Maybe it’s not clear, so let’s align.

Here, I’m asking the candidate what are they hoping to find in our team (money aside). Essentially what is it that they value. It might sound tacky, I know, but different teams have different cultures. Better clear any misunderstandings now.

Recap

One final call for questions, and we wrap this up. I’ll inform them of the next steps, and ask them if they would like to proceed.

Final thoughts

If you’re interviewing someone, try to have an honest conversation. That's pretty much what I've learnt. Maybe there are social engineering tricks I'm not aware of, but I don't care. I know that I might be on the other side of the table soon.

This month I took some time to check what good things have been added to the language that I was unaware of. To be honest, things are looking great.

The list below is not exhaustive, I only reference what I’ll be using, or find notable.

Contents:

• Array destructuring (v7.1)
• Spread operator within arrays (v7.4) & (v8.1)
• Match expressions (v8.0)
• Enumerations (enums) (v8.1)
• Arrow functions (v7.4)
• Named parameters (v8.0)
• Null coalescing operator (v7.0)
• Null coalescing assignment operator (v7.4)
• Null-safe operator (v8.0)
• Spaceship operator (v7.0)
• Multi catch exception handling (v7.1)
• str_starts_with, str_ends_with, str_contains (v8.0)
• Return Types (v7.0)
• Union types (v8.0)
• Null and Void return types (v7.1)
• Never return type (v8.1)
• Grouped imports (v7.0)
• Constructor property promotion (v8.0)
• WeakMaps (v8.0)

Array destructuring

Added in v7.1

// arrays
$posts = [[1, 2, 3, 4], [5, 6, 7]];
[$publishedPosts, $draftPosts] = $posts;
// or skip
[, $draftPosts] = $posts;

// associative arrays
$post = [
  'title' => 'Modern PHP',
  'description' => '...',
  'status' => 'Published'
];

['title' => $title, 'description' => $description] = $post;

Spread operator within arrays

• Initial support for arrays in v7.4
• Support for string-keyed (associative) arrays in v8.1

// arrays
$userPosts = [1, 2, 3, 4, 5];
$userPosts = [...$userPosts, 6];

// associative arrays
$userPosts = [
  'id-a' => 'Published',
  'id-b' => 'Draft',
];
$userPosts = [...$userPosts, 'id-c' => 'Draft'];

Match expressions

Added in v8.1

The one thing I’m most jealous it’s missing in JavaScript

// using a switch statement
switch ($status) {
 case 'Published':
  $message = 'The post has been published';
  break;
 case 'Draft':
  $message = 'The post is in draft state';
  break;
}

// as a match expression
$message = match($status) {
  'Published' => 'The post has been published',
  'Draft' => 'The post is in draft state',
};

Enumerations (enums)

Added in v8.1

// previously using a class
class Status {
  const DRAFT = 'Draft';
  const PUBLISHED = 'Published';
  const ARCHIVED = 'Archived';
}

// using an enum
enum PostStatus {
  case Draft;
  case Published;
  case Archived;
}

$status = PostStatus::Draft;

Arrow functions

Added in v7.4

fn (args) => expression

(!) Arrow functions can’t be multi-line

$publishedPosts = array_filter($posts,
  fn($post) => $post->status === 'Published'
)

Named parameters

Added in v8.0

function enableThisConfig($optionA, $optionB, $somethingElse, $anotherOne) {
 //
}

// 6 months later reading this.. ??
enableThisConfig(true, true, false, 'DEV');

// using named params
enableThisConfig(
  optionA: true,
  optionB: true,
  somethingElse: false,
  anotherOne: 'DEV',
);

Null coalescing operator

Added in v7.0

// this annoying thing
$data['name'] = isset($data['name']) ? $data['name'] : 'Guest';
// to
$data['name'] = $data['name'] ?? 'Guest';

Null coalescing assignment operator

Added in v7.4

// our previous example
$data['name'] = $data['name'] ?? 'Guest';
// to
$data['name'] ??= 'Guest';

Null-safe operator

Added in v8.0

class User {
  public function getPreferences() {}
}
class Preferences {
  public function getColorScheme() {}
}

$user = new User;

// ❌ preferences could be null
$colorScheme = $user->getPreferences()->getColorScheme();

// alternative
$preferences = $user->getPreferences();
$colorScheme = $preferences ? $preferences->getColorScheme() : null;

// using null-safe operator
$colorScheme = $user->getPreferences()?->getColorScheme();

Spaceship operator

Added in v7.0

$result = 1 <=> 1 // 0
$result = 1 <=> 2 // -1
$result = 2 <=> 1 // 1

$array = [1, 4, 5, 6, 7, 8 ,9 ,2];
usort($array, fn($a, $b) => $a <=> $b);

Multi-catch exception handling

Added in v7.1

try {
 // ...
} catch(ErrorA | ErrorB $e) {
 //
} catch(Exception $e) {
 // general case
}

New string utils

Added in v8.0

Previously we would use strpos or some other creative solution.

$string = 'Modern PHP';

if (str_starts_with($string, 'Modern')) {}
if (str_ends_with($string, 'PHP')) {}
if (str_contains($string, 'Modern')) {}

Return types

Added in v7.0

function getPost(int $postId): Post {
 //
}

Union types

Added in v8.0

function updateTotal(int|float $cost) {
 //
}

Null and Void return types

Added in v7.1

// Notice the `?` before the type
function getPost(int $postId): ?Post {
 // can return null
}

function setPostTitle(int $postId, string $title): void {
  persistInDB($postId, $postTitle);
 // won't return anything, or optionally can do:
 // `return;`
}

Never return type

Added in v8.1

function notImplemented(): never {
  throw new Exception('Not implemented');
}

Import grouping

Added in v7.0

A small but welcome addition

// all in separate lines
use App\Entity\Task;
use App\Entity\Reminder;
use App\Entity\Todo;

// now
use App\Entity\{Task, Reminder, Todo};

Constructor property promotion

Added in v8.0

// from this
class User {
  public string $name;
  public Address $address;

  public function __construct(string $name, Address $address) {
    $this->name = $name;
    $this->address = $address;
 }
}

// to this
class User {
  public function __construct(protected string $name, protected Address $address) {
  // nothing else needed
  }
}

Weakmaps

Not really using Weakmaps, not even in JavaScript, but I find it a great addition

// code taken from https://php.watch/versions/8.0/weakmap
class CommentRepository {
  private WeakMap $comments_cache;
  public function getCommentsByPost(Post $post): ?array {
    if (!isset($this->comments_cache[$post])) {
      $this->comments_cache[$post] = $this->loadComments($post);
    }

    return $this->comments_cache[$post]
  }
}

I have to say I’m very happy to see these features, and I look forward to the next PHP releases with great excitement. Although I’ll be mostly working with Laravel and its extensive library (collections & helpers) watching the language grow is lovely.

🐘

type PostId = string;
type UserId = string;

function publishPost(userId: UserId, postId: PostId) {
  //
}

const postId: PostId = 'post-xyz-123';
const userId: UserId = 'user-xyz-123';

publishPost(userId, postId); // correct
publishPost(postId, userId); // would love to error, but passes

Playground Link

We would believe that TypeScript would prevent us pass a value of type PostId when UserId is expected.

Unfortunately, both userId & postId can be used interchangeably. For the compiler, the names are irrelevant, as they are an alias to the same string type.

TypeScript doesn’t care how we name our values, only if the shape they describe (e.g string) can satisfy the constraints.

Structural typing

If you want a thorough explanation, feel free to read the entry from the official docs and skip this section.

TypeScript uses structural typing. Which is a bit different from what you might have used in Java.

In our case TypeScript doesn’t care if a type has an explicit inheritance from another. If its contents are equal (or a superset) it’s fine. Here’s another example:

type Student = {name: string};
type Teacher = {name: string};

const student: Student = {name: 'Benjamin'};
const teacher: Teacher = student; // no issue

For TypeScript both Student & Teacher are equivalent. As long as the contents are the same, any implementation that uses a Studentvalue, can be also satisfied with a Teacher one. In languages like Java, this is a no-go.

class Student {
 public String name;
}
class Teacher {
 public String name;
}

// error: incompatible types: Teacher cannot be converted to Student
Student student = new Teacher();

Of course, in our TypeScript snippet, if we add another property to the Teacher, we will be notified of it.

// Property 'classes' is missing in type 'Student' but required in type 'Teacher'.(2741)
type Teacher = {name: string; classes: Array<string>};

We might feel a false sense of security when using TypeScript, expecting the compiler to save us. But, in reality, we might be introducing similar bugs in our code if we're not careful.

How can we fix this?

We need a way to differentiate between the two types.

First, we create a symbol that we can use to identify our nominal types. It’s worth noting that it won’t exist after compilation.

declare const __nominal__type: unique symbol;

Then we enrich our base type (e.g. string) with a symbol that we can use to identify our nominal types. Two types are considered equivalent if they have the same symbol, in addition to their contents.

declare const __nominal__type: unique symbol;

export type Nominal<Type, Identifier> = Type & {
  readonly [__nominal__type]: Identifier;
};

Some examples, where we might need a distinction:

type UserId = Nominal<string, 'UserId'>;
type PostId = Nominal<string, 'PostId'>;
type OrgId = Nominal<string, 'OrgId'>;
type ProjectId = Nominal<string, 'ProjectId'>;

type CustomerId = Nominal<string, 'CustomerId'>;
type ClientId = Nominal<string, 'ClientId'>;

type projectInvitationToken = Nominal<string, 'projectInvitationToken'>;
type passwordResetToken = Nominal<string, 'passwordResetToken'>;

type EUR = Nominal<number, 'EUR'>;
type USD = Nominal<number, 'USD'>;

type Miles = Nominal<number, 'Miles'>;
type Kilometers = Nominal<number, 'Kilometers'>;

There you have it

type UserId = Nominal<string, 'UserId'>;
type PostId = Nominal<string, 'PostId'>;

let userId = 'xyz' as UserId;
let postId = 'xyz' as PostId;

/*
Type 'PostId' is not assignable to type 'UserId'.
 Type 'PostId' is not assignable to type '{ readonly [__nominal__type]: "UserId"; }'.
 Types of property '[__nominal__type]' are incompatible.
 Type '"PostId"' is not assignable to type '"UserId"'.
*/
userId = postId;

The elephant in the room

Yes, we have to use as. We can’t assign the xyz string directly.

// fails
/*
Type 'string' is not assignable to type 'UserId'.
 Type 'string' is not assignable to type '{ readonly [__nominal__type]: "UserId"; }'.
*/
let userId: UserId = 'xyz';
/*
Type 'string' is not assignable to type 'PostId'.
 Type 'string' is not assignable to type '{ readonly [__nominal__type]: "PostId"; }'.
*/
let postId: PostId = 'xyz';

// works
let userId = 'xyz' as UserId;
let postId = 'xyz' as PostId;

You might consider it cheating, but TypeScript has sharp knives in its feature set. It’s up to us to know when to use them.

That said, we can improve it. Let’s concentrate the as type-casting in one place.

function UserId(id: string): UserId {
  // validation can go here
  return id as UserId;
}

function PostId(id: string): PostId {
  // validation can go here
  return id as PostId;
}

let userId = UserId('id');
let postId = PostId('id');

Playground Link

It will also allow us to take it a step further and introduce validation, using a library like Zod.

Resources:

• Opaque Types
• [GitHub] Support some non-structural (nominal) type matching #202
• Structural Typing in TypeScript
• newtype-ts: Implementation of newtypes in TypeScript

Working remotely is a whole different world. I world that I've been living since 2017.

For some people cutting out the social interactions of the office, while having to work from the very same place they sleep is a nightmare. I get it. It sounds horrible if you put it that way. Here's the benefits I see:

• Avoiding commuting

  I wouldn’t lie if this isn’t the biggest factor. Getting back these ~6 hours per week of contemplating life in the subway is pretty sweet. Believe me, when there are strikes or heavy rain, my morning coffee tastes a bit better.

• Avoiding a noisy office

  Sometimes you just want to do some work and call it a day. No water-cooler conversations, no forced banter, just some good honest work.

• Having a healthier diet

  Being able to cook a rich breakfast and having quality snacks around are awesome perks I’ve come to value highly. Eating in a rush with everyone or resorting to takeaway food isn’t something sustainable. Taking a break to cook mindfully really helps me get back to work refreshed.

• Better workout routine

  Morning workouts are more chill. Knowing I just have to go back home, take a shower and start my work without rush or preparation helps me immensely. It’s also a task completed before work even starts. Previously I would have to find the courage, after a tiring day, to hit the gym during peak hours.

• Having greater flexibility

  Taking my break to go for groceries mid-day, having lunch with my SO wife, or being there to receive a package, are small wins that matter.

• Working with a distributed team

  Nowadays my teammates are scattered throughout the world. If you want to build a diverse, and skilled team you have to recruit from everywhere. This makes Zoom meetings an unavoidable reality. Why go from point A to B, have a couple of calls, and return?

• Using my own bathroom

  I don’t think I have to expand on this.

Working as a remote team

I like remote work because I work asynchronously. Working from distance demands that your team transforms the way it works. Progress only happens when there is clear communication, proper documentation, and respect for other people's time.

Something not unique to remote companies. Everyone benefits from them, but it’s easier to suppress when working in person. Working remotely forces your hand to tackle these inefficiencies if you want to make it.

Issues

Of course, there are issues, I’ll only highlight some I've experienced.

• Difficulties in communication

  Over-communicating isn’t a bad thing. If anything it’s expected and welcomed so everyone knows what’s going on. I’ve written a piece for this called All company chat should be in public.

• Feeling that someone hates your guts

  Unless you've come to know your fellow coworkers in person, it’s hard to have a complete idea of everyone’s personality. Assuming positive intent is critical. Not everyone likes to use exclamation marks and emojis but they are probably awesome to hang out in person though.

• Loneliness

  This is a hard topic. Some of the most meaningful friendships I've made are with former coworkers. But on the flip side, some of the most transformative experiences I've had, were because I made time due to not working in the office.

Not just your home

A big misconception is that you have to work from home. For some people, that's just not possible. When the home is too much, you can always rent a co-working space for a day or two.

This is the ideal arrangement for me. I want to feel the energy of productive people, motivating me to work, without knowing me.

Remote work isn’t for everyone. Unfortunately, Covid19 made this a reality for many people who don’t prefer it. I feel for everyone who has to cope it this situation, and most specifically all of you who have to cope and smug pricks like me who enjoy it.

I’m just glad that working remotely is now mainstream, and people who were previously trapped can finally find more options.

It probably sounds pretty aggressive but honestly, it’s not. People can still talk about their lives, worries, causes, etc, in their direct messages but not about anything related to the product.

Why?

You're leaving information locked behind

1-1 & group chats are not indexed. You can’t reference any such discussion by a link in the future, and if the people leave the company, it’s gone forever.

By posting every little discussion in the open:

• You invite anyone to contribute to the discussion. They probably had context you didn’t know, and you wouldn’t have them invited otherwise
• You are helping others understand why a decision was being made, even if you’re not around
• You are sharing product knowledge
• You are transparent about the work you’re doing

Discussing in the open keeps everyone in the loop. For now and the future.

You're not helping cultivate a culture of communication

If the majority of the communication is hidden in group chats & private channels, you’re creating silos.

People will not feel confident discussing and raising questions in the open. If none is doing it, why would anyone risk making a "stupid" question for everyone to see? Better send a direct message, or just not ask it at all.

This right here is why managers think remote work isn’t working for their team. People are making mistakes due to lack of context, are out-of-sync and generally, chaos ensues.

Foster a collaborative environment, where people are expected to communicate in the open and you will be surprised.

You might not need daily stand-ups anymore

By creating a culture of communicating, we don’t have to waste everyone’s time to see if anything is blocking their progress. What's the point to schedule a slot to announce that? Just write about it, and leave it for everyone to read.

Over-communicate. Ask questions, post findings, share progress in the open.

Boom, you saved 5 meetings per week.

Other improvements

1. Enforce the same usernames across all applications. Reduce cognitive load, make it easier for people to ping you across Slack, Jira, GitHub, etc. Are you relaying messages from every service to your Slack? Enjoy the free cross-service ping integration
2. Pay your services to allow indexing
3. Use threads. Each discussion should be separate and self-contained. Be very strict about this
4. Suppress notifications except direct mentions and threads. Periodically check your channels of interest, but only be notified of what matters

Final thoughts

Communication is already hard, let’s not add more roadblocks to it. Inefficiency makes people disinterested. Disinterested people make mistakes. Mistakes cause tension.

• "Nobody cares, why should I?"
• "Why didn’t we think about this before doing X"
• "We suck at communicating, let’s schedule a zoom"

By putting discussions in the open, you document decisions and provide context for everyone to see. But that's only the start.

You cultivate a culture where people are eager to help each other, are proactive, and share.

Why not try this approach for a week?

1. Update the version
2. Update the changelog
3. Create a new release
4. Publish to NPM

Enter Changesets. This handy package solves all of our problems in a very elegant way.

TL;DR

OK, here’s how it works in a CI environment, like GitHub Actions.

1. If your changes should update the package version, you have to include a small markdown file (changeset). No worries about the format, it’s auto-generated by the Changeset CLI. Just run npx/yarn changeset, follow the prompt and you’re good.
2. Push the changes or merge the PR - essentially just get the updates to the base branch.
3. A GitHub action will check for any number of these specific markdown files, calculate the final semver and finally open a PR with the proposed version & the generated changelog. Here’s an example from the emotion repository. You read that right. If Alice made a patch change and Bob a minor & a patch one, the final version will be just a minor bump.
4. When you’re ready, merging this PR will add the changelog and will trigger another GitHub action that will publish the package in the background.

Installation & configuration

For simplicity's sake, I will use npm. Replace npx install with yarn add & npx with yarn depending on your favorite package manager.

Let’s start by adding the CLI package that helps us with the version bumping, and another one to enrich our changelog with more metadata.

npm install @changesets/cli @changesets/changelog-github

Initialize the configuration..

 npx changeset init

and you will be greeted by the following message:

🦋  Thanks for choosing changesets to help manage your versioning and publishing
🦋
🦋  You should be set up to start using changesets now!
🦋
🦋  info We have added a `.changeset` folder, and a couple of files to help you out:
🦋  info - .changeset/README.md contains information about using changesets
🦋  info - .changeset/config.json is our default config

All good. If you navigate inside .changeset/, you'll find the configuration file

{
  "$schema": "https://unpkg.com/@changesets/config@1.6.1/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "linked": [],
  "access": "restricted",
  "baseBranch": "master",
  "updateInternalDependencies": "patch",
  "ignore": []
}

I would suggest updating only this rule for now, which will include the PR & author links next to each commit entry.

- "changelog": "@changesets/cli/changelog",
+ "changelog": ["@changesets/changelog-github", {"repo": "your-name/your-repository"}],

If you’re into tweaking it, here you can find detailed explanations for all the rules. Finally, let’s update the npm scripts, and let Changeset take over the release.

"scripts": {
  "changeset": "changeset",
  "prerelease": "npm run build && npm run test", // optional
  "release": "changeset publish"
},

Setting up Workflows

Before we proceed we need two tokens:

1. A GitHub token with repo, write:packages permissions
2. An NPM token with write permission

After you obtain them, make sure to add them under GitHub Secrets, so that GitHub Actions can access them.

Let’s create a release.yml under .github/workflows/

Code taken from changesets/action

name: Release
on:
  push:
    branches:
      - master # or main
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
        with:
          # This makes action fetch all Git history so that Changesets can generate changelogs with the correct commits
          fetch-depth: 0
      - name: Use Node.js 14.x
        uses: actions/setup-node@v1
        with:
          version: 14.x
      - name: Install Dependencies
        run: yarn
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # Ensure to have this set up under GitHub secrets
      - name: Create Release Pull Request or Publish to npm
        uses: changesets/action@master
        with:
          publish: yarn release
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Ensure to have this set up under GitHub secrets
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }} # Ensure to have this set up under GitHub secrets

This action will create (or update) a PR every time a new changeset is added to the main branch. It will calculate the final version for the next release and prepare the changelog. When the said PR is merged, these changes will be pushed to the main branch while triggering a background job to push the package to NPM. A couple of moments later you might notice that there is a new package version if you’re using the GitHub registry. That's it!

You might also want to add the changeset-bot that will notify you in PRs if there are any changesets. I find this very useful as I’m introducing new components in a design-system I’m working on, and keep forgetting to add changelog entries.

Adding a changeset

Enough of the configuration, let’s do some work, and call npx changeset to version the changes. Remember, not every commit or feature needs a changeset. Updating docs or improving the test suite doesn’t justify creating a new release for your end-users.

Anyway back to the terminal, let’s pick our change type..

$ npx changeset
🦋  What kind of change is this for change? (current version is 1.0.0)
❯ patch
  minor
  major

Fill with the appropriate summary for the changelog..

🦋  What kind of change is this for change? (current version is 1.0.0) · patch
🦋  Please enter a summary for this change (this will be in the changelogs). Submit empty line to open external editor
🦋  Summary › config: introduce changesets

And call it a day. Under .changeset/ you will notice a new markdown file (its name is randomly generated), with the change-type and summary.

---
'change': patch
---

config: introduce changesets

Push the file along with the rest of the changes, and let the GitHub actions do the heavy-lifting for you. As for the markdown file, it will be deleted by our GitHub action when the entry that's referencing is added to the changelog.

Final thoughts

Changeset is godsend. Recently I had to set up a library and getting versioning/automatic publishing out of the way early was very high on my list. Thanks to Changesets the bulk of the work is invisible to me, and I only have to make the decision when to version my changes.

Previously I was using Semantic release, but I prefer keeping my commit format separate from the versioning process.

Many great libraries like MobX, XState & Formik are using it, so feel free to include it in your projects.

Resources:

• Docs
• Changeset action
• Changeset bot

In my website I use two typefaces Inter & Fira Code. The first font-family covers everything on this website except the code blocks.

My main pet peeve is that before Inter loads, the visitor will briefly notice a fallback font. This is pretty much inevitable unless:

1. You use a loader (suboptimal)
2. Your website transmits everything during the first connection roundtrip (~14K, sometimes impossible)
3. You want to stick to the fallback font

But we'll work with what to have.

Other options

Using Google fonts

• Putting an external dependency on Google is not my cup of tea, privacy-wise
• You're not in control of the updates
• Since Chrome v86, cross-site resources like fonts can’t be shared on the same CDN. No performance boost using Google Fonts anymore

Using fonts from NPM

Like typefaces or fontsource.

• The fonts will be parsed by Webpack, will have a hash assigned to them breaking cache. There are workarounds but the alternatives are simpler
• You can’t preload the fonts easily

How to do it

1. Self-host the fonts

I like to manually fetch the desired fonts from the fountsource repo. By selecting the specific language subsets you need, you can trim a ~150kb font down to ~40kb, which is bonkers.

To avoid pulling multiple fonts, and since I don’t care for old browsers, I use the variable version of Inter & Fira Code (support), served as woff2.

/static
  /fonts
    - fira-code-var-latin.woff2
    - inter-var-latin.woff2

2. Write the font declarations

And import the file from gatsby-browser.js

@font-face {
  font-family: 'Fira Code';
  font-style: normal;
  font-display: swap;
  font-weight: 300 700;
  src: url('./fonts/fira-code-var-latin.woff2') format('woff2');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
    U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215,
    U+FEFF, U+FFFD;
}
@font-face {
  font-family: 'Inter';
  font-style: normal;
  font-weight: 100 900;
  font-display: swap;
  src: url('/fonts/inter-var-latin.woff2') format('woff2');
  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA,
    U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215,
    U+FEFF, U+FFFD;
}

3. Preload the fonts

If you don’t have html.js, check the process here. I prefer to only use react-helmet for properties that differ from page to page, so anything else lives in html.js for me.

You'll notice that I don’t include Fira Code here, as it’s not a critical resource.

<link
  rel="preload"
  href="/fonts/inter-var-latin.woff2"
  as="font"
  crossorigin="anonymous"
  type="font/woff2"
/>

4. Cache them hard

I deploy my website in Netlify, and I use gatsby-plugin-netlify to handle any configuration.

Here’s how I cache my fonts, forever.

{
  resolve: 'gatsby-plugin-netlify',
  options: {
    headers: {
      '/fonts/*': [
        'Cache-Control: public',
        'Cache-Control: max-age=365000000',
        'Cache-Control: immutable',
      ],
    },
  },
},

Otherwise, without the said plugin, a simple _headers file in the public folder will suffice.

/fonts/*
  Cache-Control: public
  Cache-Control: max-age=365000000
  Cache-Control: immutable

Final thoughts

Before trying to install a font-related Gatsby plugin, why not consider this approach?

👋

This is a very outdated post. I don't use Gatsby anymore. Feel free to check something else instead.

Working with images is boring. If you were to include an image on a website, you have to assure:

• That the images are properly resized for each screen
• That we serve the right image based on the device pixel density
• That we serve modern image formats when possible
• That the images are compressed

But also..

• That we don’t load all the page at once, consuming bandwidth, when the visitor might not even scroll to see most of the pages
• That we don’t cause layout movements, as the images abruptly load

Thankfully, Gatsby offers some nice utilities, bundling all the steps required into a single tool-chain, letting us focus on other things.

To use GraphQL or not?

Up to recently, if you didn’t want to go the GraphQL route, you were all out of luck. Thankfully, now it’s possible with the help of the StaticImage component. But let’s take a step back for a moment.

Gatsby is a fantastic framework if you want to consume data from various remote sources. Fetch the data (instagram, wordpress, etc), push them into the GraphQL layer, and populate your pages based on that data. To help with the images that these sources include, the Gatsby team & collaborators added a set of utilities to optimize them. But for everything outside the GraphQL layer, there wasn’t anything.

That resulted in an unnecessary boilerplate. If you had a simple local image but wanted a cool blur effect, you had to go through GraphQL. That said, with the latest gatsby-plugin-image we have the solution, and we can safely go one way or the other depending on the use case.

1. If the image comes from a remote source, you’re already using GraphQL
2. If the image is part of a collection, like the cover of a blog post, you will have an easier time with GraphQL
3. If the image is the 404 illustration, the image of a section, or something ephemeral, inlining is the best way to go.

Inlining images

If your images don’t go through the Gatsby GraphQL layer, you can use StaticImage

import {StaticImage} from 'gatsby-plugin-image';

// my actual 404
return (
  <StaticImage
    alt="Man looking on the map"
    className="border-b-4 border-gray-200"
    layout="constrained"
    width={400}
    src="../images/four-oh-four.png"
  />
);

The same configuration object that we declare in the GraphQL schema, can be passed as props. Rejoice.

GraphQL Configuration

Dependencies

First of all, we need to ensure we have all the dependencies in place.

We need 4 plugins before we start:

• gatsby-source-filesystem, to make the images known the GraphQL data layer. You probably already have this installed.
• gatsby-plugin-image, which exposes the StaticImage & GatsbyImage components
• gatsby-plugin-sharp, to bridge the gap between Sharp and the rest of the plugins
• gatsby-transformer-sharp, to manipulate the images using GraphQL queries

{
  resolve: `gatsby-source-filesystem`,
  options: {
    path: `${__dirname}/src/images`,
    name: 'images',
  },
  `gatsby-plugin-sharp`,
  `gatsby-transformer-sharp`,
  `gatsby-plugin-image`,
},

Types of images

Now, this is where it gets interesting - we can have three types of responsive images.

1. Images with fixed width. When knowing exactly how big the images should be. (FIXED)
2. Images that stretch across their fluid parent container. Completely dependent on their parent, who can take many shapes and forms between screen sizes. (FULL_WIDTH)
3. Images that stretch across their container but limited to a maximum width (CONSTRAINED)

Ok, this might be confusing. The difference between FULL_WIDTH & CONSTRAINED can be seen in the following table. The FULL_WIDTH image will expand to fill its container, even if it looks blurred.

So assuming we want a CONSTRAINED image and we don’t want image copies bigger than 200px, here’s our query.

query {
  image: file(relativePath: { eq: "image.jpg" }) {
    childImageSharp {
        gatsbyImageData(
          quality: 90
          width: 200
          layout: CONSTRAINED
        )
      }
    }
  }

This setting will make sure to include copies for both jpg and webp, even if we don’t specifically request for the latter.

Placeholders

Everything is in order, but we probably want a smooth fallback. Here are our options:

• BLURRED: (default) a blurred, low-resolution image, encoded as a base64 data URI
• TRACED_SVG: a low-resolution traced SVG of the image
• DOMINANT_COLOR: a solid color, calculated from the dominant color of the image.
• NONE: no placeholder. Looks better with the background prop set.

Here are the first three options side to side. I tend to prefer the first two.

Blurred	Dominant	Traced

Transforms

Gatsby allows us to do some transforms too:

• grayscale
• duotone
• rotate
• trim
• cropFocus
• fit

Frankly, Gatsby is a bit notorious for its build times, so I would advise to do a pre-processing to avoid transforming the same images again and again. If that's not possible, this option is for you.

Consuming the images

Contrary to the StaticImage example, GatsbyImage accepts an image prop.

import {StaticImage} from 'gatsby-plugin-image';

return (
  <GatsbyImage
    alt={album.title}
    image={album.cover.childImageSharp.gatsbyImageData}
    className="shadow-sm"
  />
);

Now writing album.cover.childImageSharp.gatsbyImageData is a bit tedious, so we can import getImage from the very same package, and refactor it as follows:

import {StaticImage, getImage} from 'gatsby-plugin-image';

return (
  <GatsbyImage
    alt={album.title}
    image={getImage(album.cover)} // much better
    className="shadow-sm"
  />
);

Referencing images

You probably want to fetch the images dynamically, as part of another entity. The best way for that is to link the images with the rest of the metadata. Here’s an example from my blog.

  {
    "artist": "Joy Division",
    "title": "Unknown Pleasures",
    "releasedDate": 1979,
    "rating": 5,
    "cover": "./images/unknown-pleasures.jpg",
    "spotify": "https://open.spotify.com/album/0cbpcdI4UySacPh5RCpDfo"
  },
  {
    "artist": "King Crimson",
    "title": "In the Court of the Crimson King",
    "releasedDate": 1969,
    "rating": 5,
    "cover": "./images/in-the-court.jpg",
    "spotify": "https://open.spotify.com/album/5wec5BciMpDMzlEFpYeHse"
  },
  {
    "artist": "Radiohead",
    "title": "OK Computer",
    "releasedDate": 1997,
    "rating": 5,
    "cover": "./images/ok-computer.jpg",
    "spotify": "https://open.spotify.com/album/7dxKtc08dYeRVHt3p9CZJn"
  },

And the call with the rest of the metadata

export const query = GraphQL`
  {
    albums: allAlbumsJson(
      sort: {
        fields: [rating, badge, title, artist, releasedDate]
        order: DESC
      }
    ) {
      edges {
        node {
          id
          releasedDate
          title
          artist
          rating
          badge
          spotify
          cover {
            childImageSharp {
              gatsbyImageData(
                height: 200
                width: 200
                quality: 100
                layout: CONSTRAINED
                placeholder: DOMINANT_COLOR
              )
            }
          }
        }
      }
    }
  }
`;

Images in markdown files

Unfortunately, gatsby-plugin-image doesn’t help with markdown files. We can optimize any images we query along with our data, but the images which are referenced inside the markdown file, won’t be touched.

In order to do this, we have to include a separate plugin gatsby-remark-images. Now to keep things tidy, I like to keep my blog images near the markdown file, and copy them over with gatsby-remark-copy-linked-files.

Here’s how it looks

And here how it’s written

Here’s how it looks.

![blog-files](./blog-files.jpg)

Now having installed the plugins, we add some basic options and we're ready to go.

{
  resolve: `gatsby-transformer-remark`,
  options: {
    plugins: [
      // .. rest of the plugins
      'gatsby-remark-copy-linked-files',
      {
        resolve: `gatsby-remark-images`,
        options: {
          maxWidth: 900,
          quality: 90,
          withWebp: true,
        },
      },
    ],
  },
},

Not as polished as the gatsby-plugin-image, but it does the trick.

Final thoughts

At the time of writing gatsby-plugin-image is still in beta. That said, I’m using it because life is too short to not live on the edge.

If you want to follow the official documentation, you can find it here

👋

A front-end developer utilizing a stack of React, TailwindCSS, Next.js, and Prisma can ship an pretty good MVP quite fast. The JavaScript tools we have available are just too good. And they are getting better! That's a fantastic time to be a developer.

During my career, I was expected to build apps with React, Redux, Express, Webpack, and then go build websites with responsive typography and smooth animations. Release React Native apps, and then spin off landing pages with accessible and semantic markup.

I struggled a lot, feeling that I can’t keep up. The more I focused on the “back-end” of the front-end, the more I felt out of touch with CSS. The more I wanted to master performance optimization, the more I distanced myself from creating kick-ass animations.

I felt that I was the one at fault until I realized that it’s impossible to cover everything. We are shoe-horning many aspects of web development into a single job title, that's it’s impossible to ever feel that you master front-end.

The confusion

Client-side !== Front-end

We mistakenly label anything that runs in the browser (client-side) as "Front-end". Some years ago, that would be true, as the code in the browser would only:

1. Account for how the page looks & feels
2. Handle the user interactions

But technology evolves and we rightly demand more from our applications. Eventually, we delegated part of our business logic that would traditionally live in the "Back-end" (server-side), to browser-code.

We started introducing state-management libraries (Redux, MobX, Zustand), solutions to optimize the data flow (Apollo Client, React-Query), and got creative with our CSS (Styled components, Fela). Add TypeScript, RxJS, Webpack, Docker to the mix too. The front-end tool-chain got quite big.

This meant that the modern front-end developer should also be skilled in data structures, algorithms, and scalable architecture. Oh and functional programming.

This created a huge confusion for people who didn’t have a solid programming background, and only care about HTML, CSS, design & animations. They got side-lined by essentially back-end developers whose primary programming language was JavaScript.

The problem

The modern Front-end Developer title is a jack of all trades, or even better a JavaScript Engineer. I feel blessed working across the stack, being part of an ecosystem that is always looking to disrupt. But this has some shortcomings:

• Junior developers have no idea where to start
• Accessibility becomes an afterthought
• Excellent professionals feel impostor syndrome due to the overwhelming context
• Subpar front-end experiences. Consider serving a website holding critical info during emergencies with a 2MB JavaScript bundle

With JavaScript taking over, we, unfortunately, have succumbed to mediocrity. We miss proper craftsmanship. For the modern front-end developer writing CSS & HTML is a necessary evil. Something easy.

This became more apparent to me while reviewing candidate assignments. People know React and can reason about the state management options, but fail hard in CSS. Algorithmic skills matter more than proper templating.

And eventually:

1. Those who don’t like JavaScript, are forced to adapt and follow along producing poor code.
2. While those who love JavaScript, assume what they know in the HTML/CSS-sphere is good enough, producing yet again poor code.

Two “front-end web developers” can be standing right next to each other and have little, if any, skill sets in common. That’s downright bizarre to me for a job title so specific and ubiquitous. I’m sure that’s already the case with a job title like designer, but front-end web developer is a niche within a niche already.

The Great Divide

Should we keep calling ourselves Front-end Developers?

I believe no. Having UX Developers & JavaScript Engineers rings more true to my ears. Companies that operate on a large scale, have already some sort of distinction like that. Medium-sized start-ups not so much, they won’t hire a specialist.

But again this isn’t about what title to slap on your LinkedIn profile. We need to understand that just because JavaScript can be written everywhere now, that doesn’t make someone a front-end developer.

That "good enough" is almost always bad. Before no-code takes all of our jobs, let’s stop the gatekeeping, and accept that the mythical Front-end developer ninja died a long time ago.

The Problem

There was a period where we included everything into our Redux stores. Maybe not all of you, but teams I worked with used to do it. That's what we knew, and what Medium authors were preaching as good practice.

We had plenty of presentational components that displayed information we got from our server. The info we wanted to present would be duplicated across the application, so it made sense to centralize the data fetching implementation and update them all accordingly.

There is nothing wrong with the way I present it now. But ultimately, it gets overwhelming doing it for ever-growing applications. What was supposed to be an excellent solution for state-management, was now responsible for handling loading states and making remote calls.

We introduced redux-thunk, some of you might have even tried redux-saga and its approach with generators. So much more complexity.

And it’s not that we only had trouble keeping up with the remote data flow. The actual information that presents how UI state would be suppressed & refactoring would be painful.

What we needed

There is no need to store what the server responds. If the time-to-live of the response is a couple of seconds, we don’t want that anywhere near our stores. The moment we get the response, we transform it accordingly and we feed it to the components.

And this is where React Query comes into play.

In short:

1. If the component wants remote data, React Query fetches them
2. It exposes the status progress so that the component can give proper feedback
3. Refetches the data or serves them from the cache, when needed again

Let’s see it in action.

function Matches() {
  const {status, data, error} = useQuery('matches', getMatches);

  if (status === 'loading') {
    return <Skeleton />;
  }

  if (status === 'error') {
    // Depends on your implementation
    return <ErrorState error={error} />;
  }

  // something like this
  return (
    <List>
      {data.map((match) => (
        <MatchesRow match={match} key={match.id} />
      ))}
    </List>
  );
}

In the highlighted line, we use the useQuery hook. We tell React Query that we want to call the getMatches function, and associate the response with the key matches.

We don’t store the loading states or the response. Somehow, React Query handles all that and feeds the component just the right amount of data it needs. We don’t care if the data are new or cached, or what happened. Only that we should prepare some view for the state of the remote call.

Any other component asking the same query/function combination will get the cached response. Isn’t this what we want? It’s ok, we can configure it.

What matters is that we have a solution that caches the ephemeral data from the server, and lets us know of the progress. We don’t include isXLoading flags in our stores, and we can be happy again.

What about passing params?

They are part of the key of course! Every little variation will get a cached entry of its own.

function Match({matchId}) {
  const {status, data, error} = useQuery(['matches', matchId], getMatch);

  if (status === 'loading') {
    return <Skeleton />;
  }

  if (status === 'error') {
    // Depends on your implementation
    return <ErrorState error={error} />;
  }

  // something like this
  return <Match match={match} />;
}

And here’s how the fetcher accepts them.

export const getMatch = ({
  queryKey,
}: QueryFunctionContext<[string, string]>) => {
  const [_key, matchId] = queryKey;
  return axios.get(MATCH_ENDPOINT, {id: matchId}).then((data) => data.match);
};

I don’t want to dive deep into the syntax accept of the library. It has excellent documentation & vibrant community. Take a look. There are plenty of goodies I’m not covering here.

Extract to a custom hook

In this example we want the query to re-run when we change our state variables matchStatus, enabledLeagues, orderBy. There is no need to duplicate the code in every components, so abstracting to a custom hook is an excellent option.

Here’s an example:

import React from 'react';
import {useQuery} from 'react-query';
import {pick} from 'lodash-es';

import {useMatchContext} from '../state';
import {getMatches} from '../api/queries';

export const useMatchesQuery = ({queryProps = {}} = {}) => {
  const {state} = useAppContext();

  const {matchStatus, enabledLeagues, orderBy} = state;
  const queryVariables = {matchStatus, enabledLeagues, orderBy};

  // We're using the alternative Object API here.
  // For more expressive calls, I find that it helps with readability
  const results = useQuery({
    queryFn: getMatches,
    queryKey: ['matches', queryVariables],
    staleTime: Infinity,
    onError: (error) => {
      // some reporting if needed
    },
    // override default configuration if needed
    ...queryProps,
  });

  const {status, error} = results;
  const data = results?.matches || [];

  return {status, data, error};
};

So we can re-use the same query, without having to account for the key or the fetcher function.

function Matches() {
  const {status, data, error} = useMatchesQuery();

  /// ...
}

Canceling requests

Although we don’t need to cancel requests to avoid outdated content (different params, result in different queries), it is good practice to do, so that our server won’t have to take the extra load.

Here’s an example. By clicking "Next page" 5 times on a paginated table, we’ll run 5 queries. Thankfully we won’t have conflicts since all of them have distinct keys (due to the page number). Our loyal server will respond 5 times though.

So here’s the question. Do we value more having these 4 previous pages cached for the future, or minimizing the load for our server?

It depends. I prefer to cancel the requests as a general rule.

How caching works

Let’s take a closer look at the caching decision-making.

• A new instance of useQuery('matches', getMatches) mounts.
  • Since no other queries have been made with this query + variable combination, this query will show a hard loading state and make a network request to fetch the data.
  • It will then cache the data using 'matches' and getMatches as the unique identifiers for that cache.
  • A stale invalidation is scheduled using the staleTime option as a delay (defaults to 0, or immediately).
• A second instance of useQuery('matches', getMatches) mounts elsewhere.
  • Because this exact data exist in the cache from the first instance of this query, that data is immediately returned from the cache.
• Both instances of the useQuery('matches', getMatches) query are unmounted and no longer in use.
  • Since there are no more active instances to this query, a cache timeout is set using cacheTime to delete and garbage collect the query (defaults to 5 minutes).
• No more instances of useQuery('matches', getMatches) appear within 5 minutes.
  • This query and its data are deleted and garbage collected.

So Stale queries are automatically refetched:

• Whenever their query keys change (this includes variables used in query key tuples),
• When they are freshly mounted from not having any instances on the page,
• Or when they are refetched via the query cache manually.

I like to set the stateTime to a certain amount when I’m confident that the data won’t change soon.

Afterthoughts

After using React Query in an application that is primary using GET requests, I can say that it has helped immensely. Orchestrating remote data fetching can cause a lot of boilerplate, and it makes sense to outsource it. This way we can focus more on writing features.

But what I never considered first, was how much it helps with refactoring. Migrating over to GraphQL endpoints is such a painless task. React-query doesn’t care what protocol or client you’re using.

Finally, you get to see your UI stores for what they are. I have heard testaments of people dropping their dedicated state management library in favor of simple Context. And it makes sense. Not it every case, but it’s a viable path.

I like React Query because it promotes less complexity and more confidence in the code.

Give it a spin 🙇‍♂️

Resources:

• React Query Documentation (is crazy good)
• Why You Should Be Storing Remote Data in a Cache (and Not in State)

Updating the UI optimistically is a pattern of persisting a new UI state, before getting the go-ahead approval of the server.

This pattern makes more sense for non-destructive parts of our interfaces. Things like liking a post, marking a tweet as favorite, or as seen below, starring a repository.

In the above scenario, the GitHub UI will mark the repository as 'starred', even if the backend hasn’t approved of the operation.

But it’s fine really! Operations like that are meant to be fast. To properly capture the sequence, I had to drop down to GPRS speed.

The other options would be:

• Display a loader and then persist the new state
• Don’t display a loader, but cling on the previous state and update when the server responds.

Both of these are suboptimal for such cases.

The first one can be very UX-unfriendly. Seeing small spinners for every single micro-interaction can be very tiring for the user.

The second one, makes the user second-guess if they clicked or not. But most importantly it gives the idea that the application is sluggish, buggy or both.

Sometimes the user expects a delay.

Think of toggling an article from private to public. By slowing things down, we're letting the user know that the operation has been processed and the article is now live.

Even if the interaction is a simple switch, it’s an important action that the user knows to expect a delay.

They are not moving to other actions, but instead, they are waiting for a confirmation, and any immediate feedback will put them in disbelief.

Choose wisely

Optimistic updates are meant for complementary actions.

Here are some rules of thumb:

• The actions should be binary-like. ("Liked", "Starred" or "In saved searches")
• The actions shouldn’t be tied to other parts of the interface.
• The API response times should be extremely fast.
• The API success ratio should be near 100%.

We're optimistic, but not stupid for a reason.

Feedback

Eventually, something will go wrong.

Reverting the original state should suffice. Remember we're doing this because we know that the API will respond in less than a second, and it will almost always succeed. The user will notice the change.

Of course, we can also silently-retry or provide feedback. It depends on the context.

Be optimistic 🤞

So the question is, when should one adopt a new piece of technology?

Here's a list of things to consider:

• Is it creating a better user experience?
• Is it trimming down the bill?
• Is it simplifying the code, and making it easier to maintain?

If the answer to all is no, then you should probably not adopt it.

I had my fair share of technology FOMO. I've introduced libraries like Redux, and other to places where they didn't belong. I regret it.

It's very easy as a beginner to get excited about shiny stuff and fancy landing pages. As you start to learn more about the field, you realize that there are tradeoffs you didn't consider. And in a lot of cases, the tradeoffs are not worth it.

To sum up, it's good to be a later adopter. Let others face the Next.js warts and bugs. Give this new library a few months to mature. See if the community is still excited about it. Take your time, don't rush into it anything.

Ship, ship, ship. That's the most important thing.

'Props drilling' is the process of passing down data to your components level after level.

You start simple with two child components. Then you have to add more features and inevitably the two original components have children of their own. You start moving your callbacks further and further down the component hierarchy, but ultimately the code works.

It doesn’t feel nice though since we have components that don’t care about most of their props, they just act as middlemen. To add more insult to injury:

• Refactoring is painful
• Needs more work to avoid unnecessary re-renderings
• There is a lot of code smell

Here’s an example. We have an ItemsList component that semantically groups everything related to the list of our items.

// ...
const ItemsList = memo(
  ({items, selectedItems, handleSelect, handleDelete, handleSort}) => (
    <div>
      <ItemsControl
        total={items.length}
        selectedTotal={selectedItems.length}
        handleDelete={handleDelete}
        handleSort={handleSort}
      />
      <ItemsTable
        items={items}
        handleDelete={handleDelete}
        handleSelect={handleSelect}
      />
    </div>
  )
);

Now the ItemsTable can be broken down in more components. And the ItemRow could be broken down in even more if the table cell contents are editable.

// ...
const ItemsTable = memo(({items, handleDelete, handleSelect}) => {
  return (
    <table>
      <thead>
        <tr>
          <th>Name</th>
          <th>Quantity</th>
          <th>Actions</th>
        </tr>
      </thead>
      <tbody>
        {items.map((item) => (
          <ItemRow
            key={item.id}
            handleDelete={handleDelete}
            handleSelect={handleSelect}
          />
        ))}
      </tbody>
    </table>
  );
});

In medium to large applications, with an overload of information people resort to state management solutions like Redux or MobX.

While we can use one of either, in our use case we don’t need a state-management library, as we are only about to use a small subset of their features.

Thankfully the React team in 16.3.0 updated their context API that these libraries rely on.

What is a game-changer for me now, it’s the combination with the newly released React Hooks. It offers a greatly streamlined development experience, let’s dive in!

Note: You can also Composition. Here’s a tweet demonstrating this approach https://twitter.com/mjackson/status/1195495535483817984 - To be frank, I believe it’s easy to get out of hand, but works wonders for few levels of nesting.

Context + Hooks

Alright, in this case, I’ll omit using the usual state pattern and take a page out of Redux’s book. Hooks introduced the useReducer hook, and that works wonders since we can use the same dispatch callback all over our codebase.

The “store” declaration is in the same file purely for demonstration purposes

Let’s try to redo the previous snippet.

const initialState = {items: {}, selectedItems: {}};

const reducer = (state, action) => {
  switch (action.type) {
    case 'DELETE_ITEMS':
      return {...state, items: _.omit(state.items, action.payload.ids)};
    // ...
    default:
      return state;
  }
};

const AppContext = createContext(null);

export const useAppContext = () => useContext(AppContext); // expose the custom Hook

const App = () => {
  const [state, dispatch] = useReducer(reducer, initialState);

  // The Provider HOC is mandatory so  that the useAppContext can function
  return (
    <AppContext.Provider value={[state, dispatch]}>
      <Component1 />
      <Component2 />
      <Component3 />
    </AppContext.Provider>
  );
};

Now these ComponentX components, can be totally agnostic of the data that their children need.

Let’s move on to our nested ItemRow component. We only care about the dispatch handler for now so let’s just introduce this handleDelete. In this naive example, the moment we trigger the button, the component will be unmounted so we don’t care about extra memoization in the handleDelete callback.

The reason why DELETE_ITEMS expects an array of ids, is so that it can be reused when we have multi-row controls.

// ...
// Even better if you can use Webpack alias here
import {useAppContext} from '../../App';

const ItemRow = memo(({id, name, description, quantity, dateAdded}) => {
  const [state, dispatch] = useAppContext();

  const handleDelete = () =>
    dispatch({
      type: 'DELETE_ITEMS',
      payload: {ids: [id]},
    });

  return (
    <tr>
      <td>{name}</td>
      <td>{description}</td>
      <td>{quantity}</td>
      <td>{dateAdded}</td>
      <td>
        <button onClick={handleDelete}>Remove</button>
      </td>
    </tr>
  );
});

Now if we wanted to add more functionality in the above component, that wouldn’t be that hard! Let’s add the row selection functionality. Previously, we could have to include the handleSelection callback in every component between App & ItemRow. Now, we'll stick to using dispatch with a different type.

Since we use hash-map instead of an array in our state, we can add this to our reducer

case "TOGGLE_ITEM":
  const { id, value } = action.payload;
  return { ...state, selectedItems: { ...selectedItems, [id]: value } }

Adding the extra table column, as well as the onClick handler and we're good!

// ...
const ItemRow = useMemo(({ id, name, description, quantity, dateAdded }) => {
  const [state, dispatch] = useAppContext();

  // The handleSelection function will cause rerenders, so let’s memoize this function
  const handleDelete = useCallback(
    () =>
      dispatch({
        type: 'DELETE_ITEMS',
        payload: { ids: [id] },
      }),
    [id]
  );

  const isSelected = !!state.selectedItems[id]

  const handleSelection = useCallback(() =>
    dispatch({
      type: 'TOGGLE_ITEM',
      payload: {
        id,
        value: !isSelected,
      },
    }), [id, isSelected]
  );

  return (
    <tr>
      <td><input type='checkbox' checked={isSelected} onChange={handleSelection} />
      <td>{name}</td>
      <td>{description}</td>
      <td>{quantity}</td>
      <td>{dateAdded}</td>
      <td>
        <button onClick={handleDelete}>Remove</button>
      </td>
    </tr>
  );
});

In case you wondered why we include dispatch in the useCallback dependencies, that's straight from the docs:

React guarantees that dispatch function identity is stable and won’t change on re-renders. This is why it’s safe to omit from the useEffect or useCallback dependency list.

Final thoughts

That is all.

React hooks are a breath of fresh air and I really enjoy utilizing them more and more. That being said, as we move on to functions rather than classes, it’s good to be extra precautious about caching all your expensive computations and callbacks.

The official documentation is probably the best resource out there, so that's all you need. I would strongly recommend using the accompanying eslint plugin, which helps immensely.

As for the Context API, let’s keep in mind that it’s a simple way to tunnel data to components further down the component tree. It’s not a replacement for Redux, even if they tend to accomplish the same goals in small scale projects.

Redux might be using Context internally, but also enables great features like the DevTools plugin, 'time-travel' and more. I would point out you to You Might Not Need Redux by Dan Abramov, because who better to reason about it, that him?

Pi-hole has been on my radar for quite some time. After being overwhelmed by the ads on my mobile, I decided to give it a go. Pi-hole in short, blocks all ads on the DNS level.

For our computers, it’s easy to set up an adblocker.

What about a smart-TV though? How can one ensure that their purchase is ad-free? The fact that this is even reality is audacious, but let it be for now. We want to verify that our TVs are full of corny sitcoms and nothing else. In the case of mobiles, even if we can run adblocker (for example Firefox mobile) we can’t take the performance hit.

Reading from their website...

The Pi-hole® is a DNS sinkhole that protects your devices from unwanted content, without installing any client-side software.

• Easy-to-install: our versatile installer walks you through the process, and takes less than ten minutes
• Resolute: content is blocked in non-browser locations, such as ad-laden mobile apps and smart TVs
• Responsive: seamlessly speeds up the feel of everyday browsing by caching DNS queries
• Lightweight: runs smoothly with minimal hardware and software requirements
• Robust: a command line interface that is quality assured for interoperability
• Insightful: a beautiful responsive Web Interface dashboard to view and control your Pi-hole
• Versatile: can optionally function as a DHCP server, ensuring all your devices are protected automatically
• Scalable: capable of handling hundreds of millions of queries when installed on server-grade hardware
• Modern: blocks ads over both IPv4 and IPv6
• Free: open source software which helps ensure you are the sole person in control of your privacy

Setup

My colleague Chris has written a great tutorial using balena. In my version, I’ll use Rasbian instead.

• Raspberry Pi ('B' in my case)

• SD card (I use a leftover SanDisk extreme 64GB)

• Ethernet cable

• Raspberry power adaptor

• Etcher (In order to flash the Rasbian image)

• Raspbian Stretch Lite

• Your favorite SSH client (I’ll use macOS terminal)

Preparing the Raspberry Pi

First, let’s get the Raspbian Lite image, and then Etcher in order to flash it.

If you’re an owner of a MacBook Pro with two USB-C ports like me, get your dongles ready.

When the flashing is complete, we have to enable SSH on the device. That's very simple, as we only have to create an 'shh' file in the root directory.

# 'cd' in /Volumes/{name-of-the-media}

touch ssh

Great, now let’s get these two lovebirds together, and plug the Pi in the router I decided to use Ethernet for steady connection.

Nothing out of order here

Preparing the installation

Cool beans. Now we need to get the IP address of the Pi. Simply log in to your router's admin panel and check the connected devices.

Alright, let’s SSH into our Rasbian image pi@{ip-of-the-device}. The password is raspberry (use passwd to change it).

Before we continue, let’s bring our image up to date

sudo apt-get update
sudo apt-get dist-upgrade

and then run the install command

curl -sSL https://install.pi-hole.net | bash

and you will see this lovely image. The pink screen of progress.

Really now it’s up to you. Follow along with the wizard, and pick whatever suits your use case. When everything is said and done, we can go check the dashboard!

Remember to change the password before quitting the terminal session with pihole -a -p

Dashboard

I love this already. I’m a sucker for graphs, even if I don’t understand a thing.

Let’s get some extra lists from blocklist

https://blocklist.site/app/dl/crypto
https://blocklist.site/app/dl/drugs
https://blocklist.site/app/dl/fraud
https://blocklist.site/app/dl/fakenews
https://blocklist.site/app/dl/gambling
https://blocklist.site/app/dl/malware
https://blocklist.site/app/dl/phishing
https://blocklist.site/app/dl/porn
https://blocklist.site/app/dl/proxy
https://blocklist.site/app/dl/ransomware
https://blocklist.site/app/dl/redirect
https://blocklist.site/app/dl/scam
https://blocklist.site/app/dl/spam
https://blocklist.site/app/dl/torrent
https://blocklist.site/app/dl/tracking
https://blocklist.site/app/dl/facebook
https://blocklist.site/app/dl/youtube

and place them in Settings/Blocklists.

I've also scanned through Reddit and played around with various others like:

https://v.firebog.net/hosts/Easyprivacy.txt
https://v.firebog.net/hosts/Prigent-Ads.txt
https://gitlab.com/quidsup/notrack-blocklists/raw/master/notrack-blocklist.txt
https://raw.githubusercontent.com/StevenBlack/hosts/master/data/add.2o7Net/hosts

Caveats

• Make sure you have a static IP for the Raspberry Pi. Modern routers are smart enough to assign the same IP, but let’s be extra careful.
• We have to be up-to-date with the block lists. For smart TVs with 0 protection that’s good enough. But for your other devices, if you can add another level of protection like Little Snitch that would be great.

Moving on

Well now, it’s up to both of us to use it more. I’m sure there must be some false positives, so with everyday use, these issues should be ironed out.

I’ll keep the Pi as my DNS server for my own laptop & mobile, but let my work-related one talk with the router directly. Better not mess with meetings for such an experiment :)

Resources

I’m not a clever man, I used this guide and the dedicated subreddit for help.

How much TypeScript should I have written over the past months to consider it an 'active' skill? Do side projects count?

Am I good because I can get those daily tasks done? - what's the definition of a good developer? Would I be rubbish for Amazon?

For a part of my career, I was a coding monkey for Greek startups with zero guidance. None of my colleagues had more than 2 years worth of solid experience in the field. My deadlines were the evenings and testing was something the client did on production.

Under these circumstances, it’s very hard to pick up good practices along the way. You either work your ass off on your own time, or you’re stuck. It was very hard to change my mindset from "adding this quick fix, and maybe one day...", to "let’s tackle the root cause, and make sure it won't happen again".

And yet here I am. I’m working with brilliant people all across the globe, having learned a ton and still feel like a fraud.

It happens, I'm not a fraud. I worked for it.

Impostor syndrome (also known as impostor phenomenon, impostorism, fraud syndrome or the impostor experience) is a psychological pattern in which an individual doubts their accomplishments and has a persistent internalized fear of being exposed as a "fraud".

Despite external evidence of their competence, those experiencing this phenomenon remain convinced that they are frauds, and do not deserve all they have achieved.

Individuals with impostorism incorrectly attribute their success to luck, or as a result of deceiving others into thinking they are more intelligent than they perceive themselves to be.

Wikipedia

The first approach is to pull master and merge it into the working branch:

git pull origin master

Unfortunately, this way we're creating a new commit. What we really want is the following:

1. Isolate our changes
2. Get the latest upstream updates
3. Apply the changes on top
4. Resolve any conflicts

So we don’t want to merge our branch in the updated upstream but rebase on top of it.

First, let’s fast-forward the local master branch.

git checkout master
git pull

Now let’s head back to our working branch and do a rebase. All of our commits will be applied on top of the updated master

git checkout working_branch
git rebase origin master

You can completely ignore updating your local master branch and simply run git rebase origin/master. I like having my local master up to date so I opt for the first case.

At this point, we might have a few conflicts. We have a few options to deal with them:

1. git rebase --abort will completely stop the rebase. The branch's initial state will be restored and we can start over. Nothing changed.
2. git rebase --skip will ignore the local commit that causes the problem. This is useful if the commit is not relevant anymore or if it’s a mistake.
3. or fix the conflicts, stage them and keep the rebase going with git rebase --continue

Merging the branch

Having finished the work, it’s always a nice idea to 'squash' commits that that are not relevant in isolation. For example, if you have a few commits that are just fixing typos or minor CSS tweaks, it’s better to merge them into a single commit.

For this reason, doing an 'Interactive' rebase is really helpful

```txt title="Terminal"
git rebase -i master

Here’s an example of an interactive rebase prompt:

pick 07c6add Include password strength indicator in registration formm
pick d29b1fb Fix the regex
pick 317tt36 Minor typo
pick fa2fff3 CSS tweaks

# Rebase 44a7ee6..fa2fff3 onto 44a7ee6
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit’s log message
#  x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#

Now you can do any of the following

1. Pick - Keep the commit and move on to the next one
2. Reword - Keep the commit, and get a prompt to update the message
3. Edit - Keep the commit, but wait for you to update files and include them before moving on
4. Squash - Merge into the commit above, and get a prompt to update the message
5. Fixup - Same as Squash but it won’t prompt for a new message
6. Exec - Allows running shell commands against a commit

You can reorder these commits around if needed.

For this case, we'll:

1. Reword and keep the first commit
2. Squash the rest and discard the commit message by doing a Fixup

r 07c6add Include password strength indicator in registration formm
f d29b1fb Fix the regex
f 317tt36 Minor typo
f fa2fff3 CSS tweaks

As a result our branch will contain a single meaningful commit on top of all the latest upstream changes.

Finally, we can push the branch to the remote repository and enjoy an up to date branch.

git push origin working_branch

Demo

I don't enjoy writing the error handling in JavaScript. I find it really annoying to have to wrap everything in a try-catch block. Especially for async calls. Let's see if we can make it a bit easier.

Let’s start by using a call that may fail.

const requestUsers = () => fetch('https://jsonplaceholder.typicode.com/users');

Normally we would add a try-catch block around the call to handle any error.

const doTheCall = async () => {
  try {
    const users = await requestUsers();
  } catch (e) {
    // something with the error
  }
};

Instead, let's create a wrapper function that will handle the error for us.

export const wrapRequest =
  (fn) =>
  (...params) =>
    fn(...params)
      .then((response) => {
        if (!response.ok) {
          throw response;
        }
        return response.json();
      })
      .catch((error) => handleError(error));

For this example let's write a simple function that will return the error message.

import store from './store';

const handleError = (error) => {
  const errorStatus = error ? error.status : error;
  const errorMessage = prepareErrorMessage(errorStatus);
  store.dispatch('populateErrors', errorMessage);
};

Vuex Setup

Let's set up a Vuex store..

import Vue from 'vue';
import Vuex from 'vuex';

import errors from './_errors.js';
import users from './_users.js';
import loader from './_loader.js';

Vue.use(Vuex);

export default new Vuex.Store({
  modules: {
    errors,
    users,
    loader,
  },
});

And a Users module to handle the users list.

import {wrappedRequestUsers} from '../requests';

const state = {
  usersList: [],
};
const getters = {
  usersList: (state) => state.usersList.length,
};
const mutations = {
  usersListSet: (state, list) => (state.usersList = list),
  updateLoader: (state, status) => (state.loading = status),
};
const actions = {
  requestUsers: async ({commit}) => {
    const data = await wrappedRequestUsers();
    if (data) commit('usersListSet', data);
  },
  clearUsersList: ({commit}) => {
    commit('usersListSet', []);
  },
};

export default {
  state,
  getters,
  mutations,
  actions,
};

As for the error handling actions, we will push the new error message in the state

const state = {
  errors: [],
};

const getters = {
  errors: (state) => state.errors,
};

const mutations = {
  addError: (state, error) => state.errors.unshift(error),
  popError: (state) => state.errors.pop(),
};

const actions = {
  populateErrors: ({commit}, error) => {
    commit('addError', error);
    setTimeout(() => commit('popError'), 3000);
  },
};

export default {
  state,
  getters,
  mutations,
  actions,
};

And the custom toast component will simply loop through every error message

<template>
  <div class="error-wrapper">
    <transition-group name="fade" tag="div">
      <div class="error" v-for="(error, index) in errors" :key="index">
        {{ error }}
      </div>
    </transition-group>
  </div>
</template>

<script>
import {mapGetters} from 'vuex';

export default {
  name: 'errorToast',
  computed: {
    ...mapGetters(['errors']),
  },
};
</script>

<style>
.fade-enter-active,
.fade-leave-active {
  transition: opacity 0.5s;
}
.fade-enter,
.fade-leave-to {
  opacity: 0;
}
.error-wrapper {
  position: absolute;
  top: 0;
  right: 0;
  .error {
    background: #cc0000;
    border-radius: 8px;
    color: #fff;
    margin-top: 1em;
    padding: 0.5em 2em;
  }
}
</style>

Use a spinner

Sometimes, we have to display a spinner. For this case, I’ve made a separate module for the loading instance. When a loader is needed, we won’t call the action directly, but instead we’ll dispatch executeWithLoader with the action name as a param.

const state = {
  loading: 0,
};
const getters = {
  loading: (state) => state.loading > 0,
  loadingStatus: (state) => (state.loading > 0 ? 'Fetching stuff' : 'Ready'),
};
const mutations = {
  updateLoader: (state, loading) =>
    (state.loading = loading ? state.loading++ : state.loading--),
};
const actions = {
  executeWithLoader: async ({commit, dispatch}, fn) => {
    commit('updateLoader', true);
    await dispatch(fn, {root: true});
    commit('updateLoader', false);
  },
};

export default {
  state,
  getters,
  mutations,
  actions,
};

<button
  @click='executeWithLoader("requestUsers")'
  :disabled="loading"
  class="button button--success"
>
  Fetch users
</button>

There you have it. We have a simple way to handle errors in our Vue app.

When I showed my father the app I built, he was excited for me and he wanted to try it. Unfortunately, he uses an old Dell 620. He really likes the computer's form factor and it works fine for him. Why would he upgrade?

Then I saw him trying to use the app. He was confused, and he didn't know how to navigate through the app. The performance was also horrible. I blocked the DOM multiple times, and overworked his CPU while parsing the entire food catalog twice. That's the result of inexperience.

Now when implementing a feature I like to put a face on the average customer, the face of my father. It puts things into perspective and throws out of the window every half-ass implementation I would normally feel alright with.

This was my first attempt to write a post.
I haven't updated it out of respect to the struggling new developer trying to find his voice.

These past few weeks I’ve been messing around with PostCSS. Everything about the said ecosystem is astounding and rightly so. Before we go any further, think of PostCSS as a preprocessor like your favourite one. Technically it’s not, but let’s take one step at a time.

First of all, what is it that makes the PostCSS’ approach much more attractive? Saving you some time, the answer is it’s modular approach, allowing the user to tweak the dependencies as he/she sees fit. PostCSS standalone, does nothing. It’s up to you to include everything that benefits your development process. It’s essentially a tool, waiting to feed your awesome css to a number of javascript plugins.

SASS and LESS are monolithic. You get everything, batteries included, and with that thousands of lines of code you might not need. While it’s great to have a black box that just works, as a developer I prefer an ecosystem where I can use -among others- my own, tailor-made plugins. And this folks, is the biggest sell of PostCSS. You can build ground up your CSS development process, exactly like you want.

Another distinct difference is that every pre-processor has it’s own idiomatic syntax, limited to it’s own use. Essentially you write code inside css. Why not just write CSS separately and have JavaScript do it’s ES6 magic afterwards? JavaScript isn’t going anywhere, can LESS say the same?

How it Works

Alright, let’s take the example of Autoprefixer, the most famous PostCSS plugin. Minding your own business, you decide to align side by side these cat facts paragraphs. Something seems off and you notice that they don’t have the same height. It’s expected, but it would be nice to arrange them in a way that shadows or borders wouldn’t seem silly.

One dirty but effective approach is the following:

.column-wrapper {
  overflow: hidden;
}

.column-wrapper .column {
  margin-bottom: -9999px;
  padding-bottom: 9999px;
  /* and whatever grid css rules you want */
}

I shiver just by looking at it. But thanks to Flexbox we have a great tool in our hands to solve such problems. As expected though, in order for a Flexbox solution to work in all modern browsers, we have to use some prefixes,

.element {
  box-shadow: 0 0 2px 1px #797979;
  display: flex;
}

Now, what we should do is include the whole -moz and -webkit spam. While it might be alright for a small app, in more ambitious ones we should search for alternatives.

In SASS you would create a mixin and have it add include the prefixes. A simple include doesn’t seem much, but it’s still suboptimal. What if in the following months, a prefix or two is no longer needed? Consider the box shadow case. Firefox & Chrome don’t need prefixes for shadows, but SASS would add them anyway.

The ideal case is to omit any prefix. Autoprefixer will parse the css code and add itself only the necessary ones. The sole thing you have to do is to point out which browser versions you support. Consulting the caniuse database, Autoprefixer will take care of the rest.

How is that possible? Earlier I said that PostCSS does nothing without plugins. I lied. It does one thing, which is to tranform your css code to Abstract Syntax Tree (AST). A JSON like data presentation, that every plugin will parse and modify. When everything is said and done, the output is stringified and ready for production.

Play around this example to get a better grasp of the whole AST transformation.

Notable Plugins

There are 200+ plugins out there, so it’s hard to list the 'best' ones. What I can do though, is to post my postcss configuration for this very site.

const rucksack = require('rucksack-css');
const lost = require('lost');
const cssnext = require('postcss-cssnext');
const atImport = require('postcss-import');
const autocorrect = require('postcss-autocorrect');
const magician = require('postcss-font-magician');

exports.modifyWebpackConfig = function (config) {
  config.merge({
    postcss: [
      atImport(),
      magician({
        variants: {
          Raleway: {
            200: [],
            400: [],
            500: [],
          },
        },
      }),
      autocorrect(),
      rucksack(),
      cssnext({
        browsers: ['>1%', 'last 2 versions'],
      }),
      lost(),
    ],
  });

  return config;
};

CSSnext allows me to write CSS specifications not quite supported yet by any browser. Variables, Nesting, etc, will be available sooner or later. So why not use them today?

Font Magician is my favourite. When it came to decide which font to use, i wrote the following code:

body {
  /*font-family: 'Montserrat';*/
  /*font-family: 'Josefin Sans';*/
  /*font-family: 'Inconsolata';*/
  /*font-family: 'Fira Mono';*/
  /*font-family: 'Roboto';*/
  font-family: 'Raleway';
}

Hot reloading allowed me to change the font-family without any effort and check 6 fonts under 30 seconds. It’s amazing. The site is extremely lightweight, so I can get away with Google fonts. If you'd rather use self-hosted fonts, Font Magician can help you out in this case too.

Rucksack is a collection of very handy plugins. It’s responsive font-size plugin is pure awesomeness. I used to do the following in order to get responsive typography:

body {
  font-size: calc(0.5em + 1vw);
}

But with rucksack, I can just throw the following lines of code and be done with it

body {
    /* cssnext & font magician lines */
    background-color: var(--secondary-color);
    color: var(--primary-color);
    font-family: "Raleway"
    /* rucksack */
    font-size: responsive 14px 18px;
}

Of course you can set some breakpoints for the upper and lower limits. I like it because you can have global responsive typography but also target other elements in a nicer manner. I don’t really like calc too much, and em units can be tricky from time to time. If you want to have some specific rules about a call-to-action section for example, just do this and avoid pixels and breakpoints.

& .call-to-action {
  font-size: responsive 18px 22px;
}

Lost is a nice to have plugin when you don’t want to include some css grid framework. I don’t use any in my side projects, so it saves some lines of code.

Finally postcss-autocorrect is a plugin I made.

There are moments when I make a typo and i wonder why nothing changed. In this plugin, I correct these typos, the flow continues and there is a warning in the console for the user. That's all.

Making a plugin

Boilerplates are great, so clone this repo to quickstart the project.

Every bit of logic will be placed in index.js. Nothing fancy, we get the options, if any, and parse the AST. Business as usual.

var postcss = require('postcss');

module.exports = postcss.plugin('PLUGIN_NAME', function (opts) {
  opts = opts || {};

  // Work with options here

  return function (root, result) {
    // Transform CSS AST here
  };
});

For our showcase, let’s do something simple. Say we have the following code:

.link {
  text-decoration: none;
  color: red;
  @disable #efefef;
}

We will transform the @disable #efefef to:

.link {
  text-decoration: none;
  color: red;
  & .disabled {
    color: #efefef;
  }
}

Note that the & syntax is the way CSSnext works with nesting. Read more about the specification here.

Alright, lets get our hands dirty. Follow each step here. Developing in this platform is much more easy, since you can check AST any time. Babel is also included, so we can modify our code a bit like this:

import * as postcss from 'postcss';

export default postcss.plugin('postcss-disable-annotation', (options = {}) => {
  return (root) => {
    root.walkRules((rule) => {});
  };
});

In the above snippet, we can parse every single css rule. Throw a console.log and see for yourself. As for our example we are only interested in declarations with an annotation. So let’s filter the rest out.

import * as postcss from 'postcss';

export default postcss.plugin('postcss-disable-annotation', (options = {}) => {
  return (root) => {
    root.walkRules((rule) => {
      const disable = rule.nodes.filter((x) => {
        return x.type === 'atrule' && x.name === 'disable';
      });

      if (disable.length === 1) {
        const color = disable[0].params;
        rule.removeChild(disable[0]);
      }
    });
  };
});

We've kept only the annotated declarations and the ones named 'disable'. We expect to have only one in each selector. If that's the case we're free to delete the @disable #efefef entry and start building the output.

var postcss = require('postcss');

module.exports = postcss.plugin('postcss-disable-annotation', function (opts) {
  opts = opts || {};

  return (root) => {
    root.walkRules((rule) => {
      const disable = rule.nodes.filter((x) => {
        return x.type === 'atrule' && x.name === 'disable';
      });

      if (disable.length === 1) {
        const color = disable[0].params;
        rule.removeChild(disable[0]);

        const new_rule = postcss.rule({
          selector: '&.disabled',
        });
        const decl = postcss.decl({
          prop: 'color',
          value: color,
        });
        new_rule.append(decl);
        rule.append(new_rule);
      }
    });
  };
});

Creating a new rule, we pick the selector's name, and append the color declaration. To wrap things up, place the new rule inside the rule where the annotated declaration used to be. Removing the ES6 features that require Babel, we're free to paste the code in index.js. The output is correct and the crowd goes wild.

.link {
  text-decoration: none;
  color: red;
  &.disabled {
    color: #efefef;
  }
}

Well that's it. The PostCSS API docs are must read for any follow up ideas.

PostCSS opens infinite possibilities. I strongly believe that any developer willing to invest some time in this ecosystem, will be rewarded.

Might want to check out my presentation too.

Cheers!