Black Sheep Code

Conference notes for Web Directions Code 2025 - The behaviour of browsers and their loading of resources.

Links to documentation and open issues.

How to add an experimental feature to your code, without having it in your main version control

You might have a really good idea, but its not practical to get it commited to version control. You can keep the feature around for local use with some shell aliases and git commands.

No, react context is not causing too many renders

A lot of people are under the impression that context shouldn't be used to store state, because it'll cause the entire application tree to re-render. This is a misnomer.

At least write one test.

The value of writing one test isn't in testing the code's correctness - it's in testing its consumability.

I'm going off MDX for blogging

I like standardised formats like markdown. MDX allows markdown, plus sprinkle in some React. However, I'm considering that maybe I'd be better off just using React.

Well designed code is easy to delete

The mark of some well designed code is that the act of replacing it is some what straight forward.

How to prevent further modification commits to a file with a pre-commit hook

Sometimes you want to prevent accidentally modifying sets of test fixtures etc. Use this simple pre-commit hook to prevent it.

Tools I Want: A VSCode plugin that highlights how often an error appears in Sentry, or other monitoring tools

I liberally throw errors defensively, often not expecting the error scenario to ever actually occur - it would be nice if I could see some real metrics about how often a thing is occurring, without having to leave the IDE.

The tool I want to exist - an API mocking tool that generates mock data by observing real world usage.

Mocking API calls, particularly multiple interlinked calls can be cumbersome. I want a tool to do it for me.

If I were building a start up from scratch, these are the things I would include (or have a plan to include).

The easiest time to include something in your application is at the start. On the other hand, you're likely time-poor and there's no point on burning all your runway on a gold-plated hello world! application.

Good idea: Loading screen tips for developers

Video games commonly show helpful hints and tips on loading screens. Developer tools should contain the same.

React testing patterns: When making a change to a leaf component breaks tests further up the tree

A common pain point in testing React applications is when we make a change to a component that exists down the component tree, and this change causes breaks in multiple components that directly or indirectly consume this component. Here we outline some strategies for mitigating this problem.

Module behaviour in browsers - loading waterfalls, module preloading, cache invalidation cascades and import maps.

Browsers now support ESM modules natively - meaning that we no longer need to bundle our modular code. However be aware that naive use of ESM modules may lead to unperformant loading waterfalls. Our options: bundle, use dynamic imports, or preload our modules.

How to create an imperative useConfirmationModal hook

Avoid a bunch of state hooks and handlers in your code for things like confirmation modals by encapsulating that kind of logic away in a hook.

Examples of tooling that do not play nicely with ESM

EcmaScript Modules (ESM) are well established - leading some to argue that we no longer need to provide CJS packages. However, is that really the case?

Two caching strategies

There are generally two strategies for caching, 'cache, but require validation' and 'trust what you've already got without caching'. The latter is well suited for caching static assets.

Assume the next developer will copy paste what they see you do. (That next developer might be you.)

It's not a criticism of developers to suggest that they'll copy paste what they already see in a codebase. Programming is complex and we'll use whatever hueristic we can to reduce what we need to think about.

The behaviour of browsers and loading resources - Scripts

JavaScript scripts can not be evaluated until they have been completely loaded. By default they are parse blocking.

The behaviour of browsers and loading resources - HTML, images, and CSS

Browsers do not need to wait for an entire HTML document to be loaded before it can display it. CSS is render blocking. Images will start streaming as soon as the tag is encountered.

TypeScript - indexing into a mapped type

Indexing into a mapped type a powerful TypeScript technique to allow a collection of all different types, while retaining the type information.

TypeScript types are inferred in a forward direction

TypeScript's type inference is powerful, but it does have constraints. One constraint is that it can't retrospectively narrow types.

Using cookies in React Server Components to avoid a flash the incorrect content.

We make use of NextJS's `cookies` function to access the cookies on the server side.

How to create a responsive React hook to listen for changes to cookies

Your React components may wish to listen for changes to made to cookies, whether they were made by other React code, or HTTP requests or non-React JavaScript. The CookieStore API can help.

The natural state of software is chaos

The perfect codebase is a myth. Abondon the pursuit of it, and instead seek to contain the mess.

Migrating from Remix to NextJS

NextJS appears to well and truely established. These are the steps I followed to migrate from Remix 1.9.3 to Next 14.

An overview of configuring proxy behaviour in NodeJS applications

You may wish to proxy node requests via service like mitmproxy for the purpose of analysing the requests its making or generating test data. Here's a quick reference sheet for setting this behaviour up.

How to publish a React component package, using NextJS as the compiler

Although your component library may not be making use of React Server Components and the like, it can be helpful to see how the component behaves in a NextJS context.

How to configure NextJS to proxy its requests

We may wish to proxy the requests NextJS makes, for example through a tool like mitmproxy in order to analyse traffic or generate test data.

The problem of testability in React

It seems like there are no perfect solutions for testing in React.

git checkout interactive

micro: gci is an interactive CLI utility to select a git branch with arrow keys.

Adding dark mode to a blog - how to avoid flashes of the wrong theme

I've added dark mode to this blog. Here's a few tricks I've learned.

How to configure Remix and mdx-bundler for a serverless platform - barrel files approach, Remix v1

If using Remix on a serverless platform such as Netlify we can use a build time compilation and barrel files to access frontmatter metadata.

How to get started testing a React codebase that has no tests

You've inherited a React codebase that has no tests. You're having trouble with regressions and think that tests might help, but how do you get started?

Run a Docker image on AWS ECS + Postgres using Terraform CDK

CDKTF is a tool that allows us to use fully fledged programming languages to do Terraform deployments, having the advantage of being type safe for one.

Why I've gone off React Testing Library

React Testing Library is perhaps the most popular tool for testing React applications. However its use of JSDOM under-the-hood means we often spend time dealing with browser APIs that JSDOM has not implemented.

How to configure Remix and mdx-bundler (with file system access)

How to use Remix and mdx-bundler to make use of frontmatter headers. This will allow adding publication dates, or grouping posts into series, adding tags, etc. This solution works for a non-serverless solution - it requires file system access.

A comprehensive guide to testing with Easy-Markdown-Editor

Easy Markdown Editor is a handy markdown editor with formatting keyboard shortcuts. This post outlines how to write tests for applications using it, using either Testing Library or Cypress.

Testing strategies for a Single Page Application as it relates to state management

The presence of state management is often what makes testing an Single Page Application difficult. Various approaches such as API mocking, dependency injection, component composition and error boundaries can help.

Today I learned: The Etc/GMT+x timezones actually mean UTC-x

Counter-intuitively Etc/GMT+x timezones means the opposite of how they appear in an ISO 8601 formatted date string.

Black box contract testing - third party API mocking

We have an API that makes calls out to a third party - how do we test it? We can use .HAR files to configure a tool like Mockbin to act as the third party service.

The horseshoe model for software development

I propose that the designer and the QA should be one and the same.

Blackbox contract tests - Performance testing with Jest

We can use a tool called jest-timing-reporter to provide a performance diff in our Github pull request.

OpenAPI and contract tests with Jest

Using good ol' Jest to write some contract tests with our OpenAPI generated client SDK.

Using Postman and an OpenAPI spec for contract/blackbox tests

Syncing Postman with our Github repo, generating queries from our OpenAPI spec.

Postman and OpenAPI - Automating tests

Postman has an automated testing feature, but how well does it work?

The case for blackbox tests

Blackbox tests do not require knowledge of the implementation details - they're a 'how the consumer sees it' style of test.

This blog now features comments

You can very easily add comment functionality to a webpage via the Github-powered Utterances plugin.

Thoughts about JSON API

JSON API is an opinionated REST API structuring spec. I think it has some good ideas about what can be useful in a RESTful API, but ultimately the complexity of using it makes it not worth using.

Generating MSW mocks from an OpenAPI spec.

We're using msw-auto-mock to generate MSW mocks to test our React application.

Why I don't like API mocking as a necessary frontend testing strategy

A lot of state management frameworks recommend doing API mocking as the testing strategy. I think dependency injection is a better approach.

User Experience reflects the underlying data structure

I propose a variation of Conway's Law.

Generating application and client code from an OpenAPI spec

We'll use openapi-generators to generate a Go backend and a React frontend.

I'm playing with Remix

Using Remix to generate a static blog.

Why use OpenAPI?

OpenAPI is a spec for describing HTTP APIs. It has a healthy ecosystem of tooling that supports it.

The case for splitting Cypress tests into multiple it blocks

Cypress recommends long running tests with lots of assertions. I argue that it would be helpful if we had granular visibility of the parts of the test.

A model of extensible changes.

Making changes in an extensible manner avoids having to do significant code rewrites or being disruptive to downstream consumers of your API.

Dependency injection when using redux.

An unconventional strategy to inject the behaviour of your state management in testing contexts

Different Approaches to Form Element State Management in React

Working with lists of data for form inputs such as radio buttons or checkboxes is non-trivial. I outline three approaches.

Agnostic state and service management in React

Avoid make state framework specific calls inside of your React components, and instead access them via hooks. This reduces the cognitive overhead in understanding your components, and likely allows reuse of those data fetching functions elsewhere.

What is the role of QA and how should their tests fit into the development process?

If we're doing shift-left testing, and developers are writing their own tests - then where does that leave QA?

How to effectively hire contractors

Contractors are best utilised to plough through a well defined scope of work.