Forem: Anvil Engineering

Converting your vanilla Javascript app to TypeScript

Anvil Engineering — Mon, 09 May 2022 21:18:12 +0000

The Javascript language has gone through many updates throughout its long (in internet terms) history. Along with its
rapidly changing ecosystem and maturing developer base came attempts to ease some of Javascript’s shortcomings. Of note,
one of the more significant attempts was CoffeeScript (initial release in 2009) which adds
syntactic sugar and features that make programming easier.

In late 2012, TypeScript was publicly released at version
0.8 ¹. Similar to CoffeeScript, TypeScript attempted to
add more features onto Javascript. The biggest feature TypeScript brought to the table, as its name implies, was types.
Types, and all other features that build on top of types such as generics, were already enjoyed by developers on other
languages like Java and C#, but this felt like the start of something big for Javascript.

Fast-forward to 2016 – the first time TypeScript is mentioned
on Stack Overflow’s Developer Survey. In 2016, a whopping 0.47% of
survey respondents have used TypeScript. Skipping ahead two more years
to the 2018 survey and TypeScript jumps to 17.4% of
respondents using TypeScript. You probably get where this is heading now. In
the most recent survey (2021) TypeScript jumped to 30.19%, even moving
past languages like C# and PHP. This is definitely a sign that TypeScript is something to pay attention to and maybe
your vanilla Javascript app could use a little makeover.

This post will go through an example TODO app repo we’ve set up
here: https://github.com/anvilco/anvil-ts-upgrade-example. This repo is in plain vanilla Javascript and runs on Node.js
and uses Express. There are some basic tests included, but it’s as simple as can be. We will go through a few strategies
that one can take when attempting to migrate to using TypeScript from Javascript.

This post will not go through TypeScript programming concepts in depth and will only gloss over them briefly since those
are huge chunks of information themselves. The
official TypeScript Handbook is a great resource if you want
to learn more.

Step 0

Before starting, it’s important to know our starting point with our app’s functionality. We need tests. If you don’t
have any, it’s worth it to at least create a few tests for happy path tests: that is, tests that do the simplest “good”
thing.

Also worth mentioning before you start: have your code on a versioning system (i.e. git). A lot of files are likely to
change and you’ll want an easy way to undo everything.

Install TypeScript

Simple enough. Let’s get started:

$ npm install --save-dev typescript
# or 
$ yarn add --dev typescript

TypeScript is a superset of Javascript, so any valid Javascript program is also a valid TypeScript
program ². Essentially, if we run our code through the TypeScript
compiler tsc (which is provided when you install typescript above) without any major problems, we should be good to
go!

tsconfig.json

After installing, we also need to set up a basic tsconfig.json file for how we want tsc to behave with our app. We
will use one of the recommended tsconfig files
here: https://github.com/tsconfig/bases#centralized-recommendations-for-tsconfig-bases. This contains a list of
community recommended configs depending on your app type. We’re using Node 16 and want to be extremely strict on the
first pass to clean up any bad code habits and enforce some consistency. We’ll use the one
located: https://github.com/tsconfig/bases/blob/main/bases/node16-strictest.combined.json.

{
  "display": "Node 16 + Strictest",
  "compilerOptions": {
    "lib": [
      "es2021"
    ],
    "module": "commonjs",
    "target": "es2021",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "importsNotUsedAsValues": "error",
    "checkJs": true,
    // Everything below are custom changes for this app
    "allowJs": true,
    "outDir": "dist"
  },
  "include": [
    "./src/**/*",
    "./__tests__/**/*"
  ]
}

Compile and fix errors

Now let’s run tsc:

$ yarn tsc
# or 
$ npx tsc
Found 68 errors in 5 files.

Errors  Files
    13  __tests__/app.test.js:1
    28  __tests__/store.test.js:3
    14  src/app.js:1
     1  src/models/Todo.js:4
    12  src/store.js:13
error Command failed with exit code 2.

68 errors. Not too bad especially with extremely strict rules on. Many of the errors are “implicitly has an 'any' type”
and should have easy fixes.

Aside from those, there are a few interesting errors:

src/app.js:1:25 - error TS7016: Could not find a declaration file for module 'express'. 'anvil-ts-upgrade-example/node_modules/express/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/express` if it exists or add a new declaration (.d.ts) file containing `declare module 'express';`

1 const express = require('express')
                          ~~~~~~~~~

src/app.js:2:28 - error TS7016: Could not find a declaration file for module 'body-parser'. 'anvil-ts-upgrade-example/node_modules/body-parser/index.js' implicitly has an 'any' type.
  Try `npm i --save-dev @types/body-parser` if it exists or add a new declaration (.d.ts) file containing `declare module 'body-parser';`

2 const bodyParser = require('body-parser')
                             ~~~~~~~~~~~~~

These error messages tell us how to fix the errors and also point to how parts of the typing system works in TypeScript.
Packages can provide typing declarations (with the *.d.ts file extension). These are generated automatically through
the tsc compiler. If you have a publicly accessible TypeScript app, you can also provide official typing declarations
by submitting a pull request to the DefinitelyTyped repo: https://github.com/DefinitelyTyped/DefinitelyTyped.

The two packages in the snippet are very popular modules, so they’ll definitely have type declarations:

# We’re also adding in type declarations for modules used in testing: supertest, jest
npm i --save-dev @types/body-parser @types/express @types/supertest @types/jest
# or
$ yarn add -D @types/body-parser @types/express @types/supertest @types/jest

Let’s check on tsc:

Found 15 errors in 3 files.

Errors  Files
     2  src/app.js:13
     1  src/models/Todo.js:4
    12  src/store.js:13
error Command failed with exit code 2.

From 68 errors to 15. That’s much more manageable. The rest of the errors should now be actually related to our own
code. Let’s take the one that repeats the most:

src/store.js:28:16 - error TS7053: Element implicitly has an 'any' type because expression of type 'any' can't be used to index type '{}'.

28     let item = localStore?.[id]
                  ~~~~~~~~~~~~~~~~

What does this mean? Our localStore variable is an Object, but its key type is any. In strict TypeScript, we need to
be clear what our indexes can be. In this case we use numbers as indexes.

Before we fix this, let’s change our file’s extension to the *.ts: store.js -> store.ts. This will let tsc know
this is a TypeScript file, as well as our IDE. Now we start actually writing TypeScript.

interface LocalAppStore {
  [key: number]: typeof TodoModel
}

const localStore: LocalAppStore = {}

We’ve created our first interface. It tells the TypeScript compiler what a LocalAppStore object looks like with its
keys as numbers and its values as a TodoModel.

We also need to create a new interface TodoData which defines the object we pass to create and update Todo
instances.

// src/models/Todo.ts  (renamed from Todo.js)
export interface TodoData {
  id?: number,
  title?: string,
  description?: string,
}

We can then import that interface and use it as type annotations throughout the app.

Without getting too verbose and explaining all the other smaller errors, you can take a look at the branch we have here
to see what changed: https://github.com/anvilco/anvil-ts-upgrade-example/tree/ts-convert.

In summary, after installing TypeScript and creating its config file we:
Get tsc to run without failing – not including errors it finds in our code Look for any missing type declarations. In
this case we were missing types from jest, express, body-parser, and supertest. Rename files from .js to .ts
Fix errors by creating type aliases or interfaces, adding type annotations, etc. This can potentially take the most time
as you’ll need to take a look at how functions are used, how and what kind of data is passed.

One thing to keep in mind is that the migration process to TypeScript can be done at your own pace. Since valid
Javascript is also valid TypeScript, you don’t have to rename all files to .ts. You don’t have to create type
interfaces for all objects until you’re ready. Using a less-strict tsconfig.json
file (https://github.com/tsconfig/bases/blob/main/bases/node16.json), together with // @ts-ignore comments to ignore
errors you don’t agree with or maybe aren’t ready for yet.

After compiling

After tsc finally compiles your project, you may need to adjust your package.json file. In our package.json we
have:

  "main": "src/server.js",

which now points to a file that doesn’t exist. Since this should point to a Javascript file, we need to update this to
point to the compiled version:

  "main": "dist/server.js",

Note that you will need to compile your app code every time your entry point needs to be updated. This can be done
automatically as you develop with packages such as tsc-watch
and nodemon.

You can also see if the compiled version of the app runs manually through a command like node dist/server.js.

IDE Support

One of the major side effects from migrating to TypeScript, if you use a supported IDE such as Visual Studio Code or one
of the JetBrains IDEs, is better integration with the IDE. This includes, but isn’t limited to, better autocomplete and
better popup hints for function types (see image below). This brings the language much closer to typed, compiled
languages like C# and Java.

(./ide-support.png)

Other tooling

This post has only covered a very narrow migration case involving a basic Node.js app and a few unit tests. Real
applications are much more complex than this and would involve other transpilers and builders such as webpack, rollup,
and babel. Adding TypeScript to those build processes would be separate blog posts themselves, but I believe the general
advice here is still 100% applicable in complex situations.

Conclusion

Migrating an app to another platform or language is never easy. Fortunately, if you want to migrate your vanilla
Javascript app to TypeScript, it can be done progressively, as fast or as slow as you want. Additionally, the TypeScript
compiler can be configured to provide as much feedback as we need throughout the process to ensure your code runs.
Hopefully this post has inspired you to at least think about the possibility of migrating your Javascript app.

At Anvil, we’ve begun migrating some of our public projects to TypeScript as well. So far it’s been painless and fairly
straightforward. If you're developing something cool with our libraries or paperwork automation, let us know at
developers@useanvil.com. We'd love to hear from you.

Measuring React styled-components performance & best practices

Anvil Engineering — Thu, 05 May 2022 21:56:46 +0000

Nothing feels worse to a new user than having to navigate across a slow-performing webapp. Nine out of ten times, I hit 'back' on a webpage once I realize a page is rendering excruciatingly slow. Webapp performance is one of the most important components of user experience, and that is why search engines take into account website metrics such as 'first contentful paint' or 'time to interactive' when ranking.

Lighthouse metrics for an example webpage

I'll assume you already have some working knowledge on what styled-components is and how it works. But just in case, styled-components is one of the most popular open-source styling libraries, especially in the React ecosystem. Instead of applying styles to an entire webpage or specific HTML elements using the class/id system, you can apply styles onto individual React components. One of my favorite aspects of the styled-components approach is it neatly blends together logic & styling – JS, HTML, and CSS – so everything is accessible from just one file.

const StyledButton = styled.button`
  font-size: 14px;
  color: #525252;
  background-color: #7AEFB2;
  border-color: transparent;
`

const ButtonComponent = ({ isLoading, onClick, children }) => {
  return (
    <StyledButton className=”example-btn” onClick={onClick}>
      {children}
      {isLoading ? <LoadingSpinner /> : null}
    </StyledButton>
  )
}

export default ButtonComponent

Example styled component button in React

Now that we've covered the background, let's ask the important questions. How can we gauge how well our styled-components are performing? What metrics should we look out for? And what are some best practices we can implement to keep our code efficient?

Measuring performance

We'll be using Chrome DevTools' Performance Monitor to gauge a page's performance in real time. It will appear like this:

Chome DevTools performance monitor

Navigate to the page containing your code, open up the performance monitor, press record, perform an action, and stop recording. You'll see something like this:

Performance timeline & summary

Looking at the summary, we can see scripting takes up the majority of the recording time – 1904ms out of 2880ms. It appears we can make the most significant improvements in this department. Let's dive further by clicking into the 'Bottom-up' tab.

Performance Bottom-up tab

The 'insertBefore' scripting activity takes 364.4ms – the longest of any process. Let's figure out where this code comes from.

insertBefore subfolders

The code with the greatest 'Self time' comes from styled-components. Now that we've identified where the problem lies, let's fix it by making our code more efficient.

To learn more about using the DevTools performance monitor, check out this blog post about optimizing render performance!

Best practices

The first step in code optimization is to examine the way our code is structured. Let's take a look at some of those best practices for styled-components.

Dynamic styling

Oftentimes we want the styling of a UI component to be dependent upon some logic or state in the application. For example, we may want the background of a div to be gray when being hovered over. We can achieve this by applying dynamic styling.

const Field = styled.div`
  background: ${props => props.isHover ? '#E2EEF0' : '#FFFFFF'};
`

Example of dynamic styling - div with light cyan background upon hover

What if we want multiple dynamic styles to be applied? It could look quite repetitive.

const Field = styled.div`
  color: ${props => props.isSelected ? '#2D2D2D' : '#7A7A7A'};
  border-radius: ${props => props.isSelected ? '4px' : '0px'};
  background: ${props => props.isHover ? '#E2EEF0' : '#FFFFFF'};
`

Multiple dynamic styles - the 'meh' way

Let's clean up our code by importing the props once for each prop instead of doing it on a per-line basis.

const Field = styled.div`
  color: #7A7A7A;
  border-radius: 0px;
  background: #FFFFFF;

  ${({ isSelected }) => isSelected && `
    color: #2D2D2D;
    border-radius: 4px;
  `}

  ${({ isHover }) => isHover && `
    background: #E2EEF0;
  `}
`

Multiple dynamic styles - the okay way

Having a bunch of dynamic styles can quickly get complicated. Let's imagine we have a styled-component that takes a 'displayStyle' prop that applies various combinations of CSS. Like so:

const StyledInput = styled.input`
  font-size: 14px;
  border-radius: 2px;

  ${({  displayStyle }) => displayStyle === 'compact' && `
    border-top: none;
    border-left: none;
    border-right: none;
    padding-top: 0;
    padding-left: 0;
    padding-right: 0;
    margin-left: 0;
    margin-right: 0;
    font-size: 12px;
    box-shadow: none;
  `}

  ${({ displayStyle }) => displayStyle === 'internal' && `
    border: none;
    margin-left: 0;
    margin-right: 0;
    font-weight: bold;
  `}

  ${({ displayStyle }) => displayStyle === 'large' && `
    border: 2px;
    margin-left: 10px;
    margin-right: 10px;
    font-size: 22px;
  `}
  …
`

Another example of multiple dynamic styles - the okay way

It can get quite confusing to track all the CSS rules when there are a bunch of different display styles. We can compartmentalize everything by creating distinct styled-components for each display style.

const StyledInput = styled.input`
  font-size: 14px;
  border-radius: 2px;
`

const CompactInput = styled(StyledInput)`
  border-top: none;
  border-left: none;
  border-right: none;
  padding-top: 0;
  padding-left: 0;
  padding-right: 0;
  margin-left: 0;
  margin-right: 0;
  font-size: 12px;
  box-shadow: none;
`

const InternalInput = styled(StyledInput)`
  border: none;
  margin-left: 0;
  margin-right: 0;
  font-weight: bold;
`

const LargeInput = styled(StyledInput)`
  border: 2px;
  margin-left: 10px;
  margin-right: 10px;
  font-size: 22px;
`

export default function Input ({ displayStyle, …props }) {
  let InputComponent = StyledInput
  if (displayStyle === 'compact') InputComponent = CompactInput
  else if (displayStyle === 'internal') InputComponent = InternalInput
  else if (displayStyle === 'large') InputComponent = LargeInput

  return (
    <InputComponent {...props} />
  )
}

Multiple dynamic styles - the cleanest way

By adopting this improved format of structuring your styled-components, I hope you'll see some improvement in performance.

Global styles

Styled-components has a helper function named createGlobalStyle which generates a special component that handles global styles. The function works by creating a HTML style tag. Whenever a React component with createGlobalStyle is mounted, createGlobalStyle is called and a new style tag is generated. Using the helper function with a React component that is mounted & unmounted frequently will lead to redundant style tags in the DOM, so it is best to minimize the number of times the function is used.

const DropdownGlobalStyle = createGlobalStyle`
  .selected-option {
    background-color: #3E3E57;
  }
`

function Dropdown (props) {
  return (
    <>
      …
      <DropdownGlobalStyle />
    </>
  )
}

const InputGlobalStyle = createGlobalStyle`
  .error-container {
    color: #FB7578;
  }
`

function Input (props) {
  return (
    <>
      …
      <InputGlobalStyle />
    </>
  )
}

Using createGlobalStyle for multiple components - the bad way

Let's create global styles once only in the App component.

const AppGlobalStyle = createGlobalStyle`
  .selected-option {
    background-color: #3E3E57;
  }

  .error-container {
    color: #FB7578;
  }
`

function App () {
  return (
    <>
      …
      <AppGlobalStyle />
    </>
  )
}

Using createGlobalStyle once in the root component - the better way

Summary

We've covered how to measure the performance of your styled-components and best practices on structuring your code. By implementing these techniques into your development process, you can worry less about having a slow-performing web app!

We've applied these practices to our code at Anvil, and believe sharing our experience helps everyone in creating awesome products. If you're developing something cool with PDFs or paperwork automation, let us know at developers@useanvil.com. We'd love to hear from you.

Introducing SpectaQL 1.0 - an even better way to autogenerate GraphQL API documentation

Anvil Engineering — Tue, 03 May 2022 22:42:38 +0000

Back in March 2021, Anvil released SpectaQL to the open source community with the goal of becoming the de-facto, go-to library to use for auto-generating static HTML documentation for any GraphQL API. So far we're very pleased with the progress we've made:

It gets downloaded thousands of times per week on NPM
It has over 500 stars on Github
It has a healthy amount of user support and Github issue activity
There have been several articles written about it, like this one and this one

Despite the success of SpectaQL over the last year or so, it was still in a "pre 1.0" stage as we learned more and more about what worked well, heard from users about what they wanted, and of course fixed a whole bunch of bugs. After all that time, feedback, and thought we decided that it was time to devote some resources to make a major internal overhaul, improve some existing features and APIs, and create or expose some new features and APIs that prepare SpectaQL for the future. We are happy to announce the culmination of all that work with the release of SpectaQL 1.0!

In the rest of this article, I'm going to outline some of the major changes, enhancements, and new features, as well as the decision process around some of the things we've done. I hope you find it informative and interesting.

Why did we decide to do it? And why now?

In order to increase their reliability and usefulness, most open source projects, and especially libraries and packages, follow the Semantic Versioning (aka Semver) specification. Perhaps the most important takeaway from Semver is that if you make any "breaking changes" to your library, you should release those changes as a new Major version—e.g. go from 1.x.x => 2.0.0. While the possibility of breaking changes without a major version change was something I warned users about while SpectaQL was on version 0.x.x, I was still hesitant to cause any breaking changes due to the amount of usage the package was getting.

As a developer who uses open source packages myself, I know that upgrading package dependencies by a "patch" or "minor" amount is usually no big deal, but that upgrading a package by a "major" amount is something that requires careful consideration and oftentimes some (major) code changes and real work. For this reason, I wanted to be careful about introducing breaking changes too often, so I waited for more understanding.

After what felt like enough experience, feedback, discussion, thought, and research there ended up being many things that I wanted to change about SpectaQL that would be considered "breaking changes." That time and perspective also allowed me to be more confident that the APIs and ergonomics of the changes I wanted to make would prove to be smart and complete enough to avoid having to make any breaking changes for some time. And so I began developing SpectaQL 1.0. Here is a somewhat exhaustive list of the "breaking changes" intended to help users migration from 0.x.x to 1.0.0. I'll focus the rest of this article on some of the major and more interesting parts of this work.

Internal DNA based on JSON Schema and Swagger/OpenAPI

SpectaQL was originally forked from a project called DociQL to add some enhancements there. And DociQL was originally forked from a project called Spectacle to make it work with GraphQL. And (finally) Spectacle was designed to work with Swagger/OpenAPI. Swagger/OpenAPI is a specification designed to help standardize the description of REST APIs with many routes, and uses JSON Schema as the way to define Data Types/Models. This means that SpectaQL had to wrestle with several layers of history and transformations; making SpectaQL's enhancements fit into the DociQL world, which in turn had to make things fit into the Spectacle/Swagger/OpenAPI world.

This presented many challenges, but there were a few in particular that made things feel like they were really trying to fit a round peg into a square hole:

Unlike REST APIs, GraphQL does not have many different endpoints or paths to represent. It usually has just 1 which accepts any valid Queries or Mutations.
GraphQL already has a Schema definition and strict Typing built into the language, so conversion to JSON Schema felt unnecessary.
GraphQL already had a number of tools to work with and interact with schemas in useful and interesting ways.

These are just a few of the big ones, but there were other reasons as well, and eventually it became clear that all signs pointed to re-writing SpectaQL's internals to use pure GraphQL tools—no more Swagger/OpenAPI, and no more JSON Schema. The responses and comments on this issue I opened up confirmed my feelings.

This re-writing of the internals took up the bulk of the time to get SpectaQL 1.0 ready, and in the end, provided little-to-no immediate User-facing changes. However, it was well worth the trouble as it dramatically simplified the codebase, making it much easier to make other changes and enhancements. Things that used to take a great deal of experience in and understanding of the codebase can now be easily understood and figured out by a much more casual observer of the code. This has already been proven by receiving pull requests from users wanting to fix bugs or add new features with just a few intuitive lines of code.

Simpler schema manipulation, and the creation of Microfiber

One major feature of SpectaQL is its ability to filter (or "hide") things in your GraphQL schema that you don't want documented. Most schemas have at least a few Types, Queries, or Mutations that are for administrators only, or that are sensitive for various reasons. We put a lot of effort into making this possible for the original launch of SpectaQL, but as time went on it became increasingly challenging to implement complex logic. For example, if you tell SpectaQL to hide your custom type Foo, you probably also want to hide all references to Foo: Queries or Mutations that return Foo, fields that return Foo, arguments of type Foo, etc. This was very tricky to do in the old system.

After starting from scratch with a purely GraphQL mindset and landscape, these sorts of advanced manipulations became much easier to reason about and implement. Since there was no existing tool for it, we ended up creating a standalone package just for querying and manipulating the GraphQL schema in the ways that we needed. We then decided that others might find this tool useful, so we recently open sourced it as Microfiber. You can read my blog post about its release here.

Increase customizabilty and reduce forking via "themes"

By far the biggest user-facing changes that were made for SpectaQL 1.0 were around allowing for customization. In the pre-1.0 world, there was a limited, difficult, disjointed set of ways to customize the CSS, JavaScript, and output. Even worse, there was no real way to customize the data arrangement / grouping or to really control the HTML structure. All of these shortcomings would either leave some users frustrated, or perhaps looking elsewhere for another solution for them. Even worse than a user deciding not to use SpectaQL would be having a user need to fork the project in order to make the changes they need. Forking, we reasoned, was a sign that we'd not given enough flexibility and power to the users. With all of this in mind, we decided that the goal of our customization system in SpectaQL would be to reduce the need to fork the project in order to get any sort of reasonable customization that a user might want.

We accomplished this through the creation of a "theme" system that gives users the following:

Complete control of the HTML templates (SpectaQL uses Handlebars) to render any DOM structure you like.
Complete control over the SCSS/CSS supplied along with your HTML.
Complete control over the JavaScript files that are loaded with your HTML.
Complete control over the GraphQL data that gets passed to the HTML template engines, allowing you to group, order, and arrange the data however you like.

Some other cool things to note about themes:

SpectaQL comes with 3 built-in themes to choose from.
User-created theme files and structure will be overlaid on top of the default theme files and structure so that the theme only needs to contain files that are supplemental or that should be overwritten in the default theme. This makes it easy for the user to provide minor tweaks to the default theme without a lot of code and without missing out on any future updates and bug fixes made to the original/underlying theme.

If you're interested in learning more about SpectaQL's theming system, please check out the docs.

Summary

While SpectaQL owes a great deal to its original DNA, over time some of that legacy code became a hindrance. Converting GraphQL to Swagger/OpenAPI was tough to reason about and follow. Converting GraphQL to JSON Schema also provided challenges. A "feel good" way to support customizing all aspects of the output was also just not there. Over time, it became clear that some old patterns were not necessary, and that things would be a lot better off after a major refactoring. Time, feedback, and research were also necessary before being able to design and implement a robust customization system via "themes."

The big takeaway? While you don't want to be hasty and end up rolling out major breaking changes too frequently, you should also not be afraid to act once you feel you've gathered enough understanding and a critical mass of things that need to change for the project to succeed. For SpectaQL, this was a major investment of time and effort but already it has borne much fruit. We feel confident that we made the right decisions and have set up SpectaQL for long-term success. Happy coding!

PurgeCSS & styled-components: Does It Work?

Anvil Engineering — Fri, 29 Apr 2022 22:53:56 +0000

While CSS itself is ubiquitous, the way each project uses it is certainly not. Before preprocessors like Sass and Less, there were entire methodologies, like BEM, for writing and maintaining your CSS. Even with methodologies and preprocessors to help our style writing, there is still an abundance of CSS bloat in all projects.

Enter PurgeCSS: a tool used to eliminate unused CSS from your codebase. PurgeCSS helps projects with performance and UX by reducing overall bundle size. Preprocessors, methodologies, and all of the actions we take before building our projects are wonderful, but it's unrealistic to expect them to completely solve maintainability & performance issues. Despite our best efforts as developers to keep a lean codebase, unnecessary CSS will inevitably come up during development. PurgeCSS is our fail-safe to ensure we ship the least amount of CSS that's needed.

Here at Anvil, we use styled-components. PurgeCSS functionality is essentially baked into styled-components, with a few caveats. If PurgeCSS is already included in styled-components, can you still use both? And if you can, is there any benefit to doing so?

This blog post will answer these questions, as well as:

How PurgeCSS works
The benefits of using styled-components
The caveats with styled-components' 'PurgeCSS' functionality
Discuss some competitors to PurgeCSS & why PurgeCSS is the de facto solution
Show you how to include PurgeCSS on a Gatsby site

What is PurgeCSS and why should I care?

PurgeCSS is a build/bundle time tool to transform your CSS into the bare minimum it should be. It aims to reduce your overall bundle size by sending only the critical CSS you need, instead of all the CSS you have written and imported. You can use it with any flavor of CSS you use: Sass, Less, Tailwind, Bootstrap, Material UI, Bulma, the list goes on.

The core reason to use PurgeCSS is to improve your site's performance. I also like using it to see a 'diff' of what CSS isn't being used. It's hard to track down what CSS is or isn't being used, so after building your site with PurgeCSS it's much easier to see what classes don't belong. After finding those classes, you can safely delete them from your codebase.

How PurgeCSS works

PurgeCSS analyzes your HTML and internally keeps track of which selectors are being used or not. PurgeCSS actually analyzes other types of files besides HTML for selectors, such as template files and JavaScript. This feature is what makes PurgeCSS different from a similar solution, UnCSS, and related to a 'predecessor' solution called PurifyCSS. More on both of those later on.

After finding which selectors are actually being used, PurgeCSS analyzes your CSS files and deletes the ones that aren't used. The CSS files with only the used selectors are included in the bundle. It's important to note that this only works by comparing selectors across your HTML and CSS; it's entirely possible that you have an unnecessary CSS property and value within a rule and that is entirely up to you to find and delete. Unfortunately, it's impossible (for now) for a program to determine if a CSS property is necessary or not.

There might be cases where you want to keep CSS selectors/rules in the bundle no matter what. PurgeCSS comes with a 'safelist' option so you can configure what selectors you want to keep, even if they aren't used. You can also toggle the safelist directly in your CSS with comments, similar to ESLint's configuration comments.

Styled-components

On the other side of our titular question is styled-components. While I'm talking about styled-components specifically, the topics and concepts here apply to any CSS-in-JS provider (e.g. emotion). There is a smaller CSS-in-JS library called astroturf that aims to give the developer the best of all worlds, so the limitations I'll discuss later on don't apply there. But be careful with smaller projects/ones that claim you can have it all! You are wading through uncharted territory :)

Writing styles with styled-components, simply put, is amazing. The primary motivation to use it is to improve DX (developer experience) and through that, increase development speed. React revolutionized web development by introducing component-based development to JS, and styled-components took that a step further by tying styles directly to components. It's a natural fit, as CSS classes are meant to be reused throughout the site, much like how a component is reused in many places in your application.

Another benefit of using CSS within JS: built-in processing. Using preprocessors, leveraging dynamic props, trimming whitespace from your CSS, and even purging your CSS of unneeded selectors all take time to configure; styled-components comes with all of that 'out of the box' since it's embedded into JavaScript.

While using styled-components is certainly more powerful than CSS by itself (or its preprocessor derivatives), it comes with its own caveats and considerations:

Do you even need JavaScript? If your project is small, you should stick to HTML & CSS. Keep It Simple, Stupid!
Are you introducing styled-components into a legacy codebase? You should probably clean up the cruft first before introducing more complexity.
Does styled-components really include all the functionality of PurgeCSS? Let's find out!

What's the diff between styled-components and PurgeCSS?

From the documentation for styled-components, you get 'Automatic critical CSS' out of the box:

Automatic critical CSS: styled-components keeps track of which components are rendered on a page and injects their styles and nothing else, fully automatically. Combined with code splitting, this means your users load the least amount of code necessary.

This boils down to: if a component is unused, the CSS isn't included in the bundle. Effectively, that is what PurgeCSS does. But let's understand how each technique works.

Styled-components is 100% JavaScript-based, which is how it manages to keep track of what components are rendered on the client. This makes styled-components a run-time optimization. PurgeCSS works by analyzing your content files and, based off what selectors it finds, removes rules from your CSS files before including them in the final bundle. This makes PurgeCSS a build-time optimization.

You need to consider your project's unique constraints and concerns, but in general build-time optimizations are better than run-time optimizations.

Quick note on PurgeCSS' comparison logic

Before we go any further, I want to make sure you understand how PurgeCSS does its 'magic'. While an incredible tool, PurgeCSS doesn't do anything fancy. None of the tools for removing CSS are intelligent by nature; they all remove CSS by pretty simple comparison.

In PurgeCSS' case, it builds up a list of selectors from your HTML/JS/template files. You have the power to control what selectors make it into this list via extractors, but that is considered advanced and is out of scope for this post. After building up a list of selectors, PurgeCSS compares the selectors from CSS to that list. If a CSS selector is found that doesn't exist in the generated list, remove it! That's about it.

Feature comparison: what about nested selectors?

Effectively styled-components and PurgeCSS do the same thing. Let's see if we can poke a hole in that. Consider nested/combined selectors. Let's say you have a styled component like Parent below:

const Parent = styled.div`
  width: 300px;
  height: 300px;
  background: yellow;

  .child {
    width: 100px;
    height: 100px;
    background: black;
  }
`

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <Parent />
      </header>
    </div>
  )
}

styled-components nested selector

The class names of App and App-header are from create-react-app, and are irrelevant for the whole blog post. We are only focusing on parent and child styles.

But looking at what React is going to render, we don't have any element with the class name 'child' as it is nested within the Parent component. So ideally, the .child CSS rule would not be included in our bundle, which for styled-components is injected CSS into the head of our document. Here's what was sent:

.child rule is sent to the browser in the head tag of our document

Bummer, so styled-components doesn't handle nested selectors. PurgeCSS should be able to remove the selector from the equivalent CSS project right? Here's that same project, using React + CSS:

import './styles/App.css'

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <div className="parent" />
      </header>
    </div>
  )
}

export default App

React component using CSS directly from App.css

.parent {
  width: 300px;
  height: 300px;
  background: yellow;
}

.parent .child {
  width: 100px;
  height: 100px;
  background: black;
}

CSS for our React + CSS project

And here's the resulting CSS file after running PurgeCSS:

.parent {
  width: 300px;
  height: 300px;
  background: yellow;
}

.parent .child {
  width: 100px;
  height: 100px;
  background: black;
}

PurgeCSS output file

Wait, we still have that selector with .child... what's going on here? As it turns out, PurgeCSS doesn't handle descendant selectors/combinators like these well, just like styled-components. If we go back to the quick note on PurgeCSS' comparison logic, this actually makes sense. PurgeCSS isn't yet smart enough to build up nested selectors; so even though the HTML does represent .parent .child in this case, the list of selectors are only the smallest possible, e.g.

const listOfSelectors = ['parent', 'child', '', …]

And in our CSS, does this rule have a selector from the list?

.parent .child {
  width: 100px;
  height: 100px;
  background: black;
}

Yep, clearly we have .parent in our selector. PurgeCSS thinks this rule is used, even though it's not because of the increased specificity with .child.

While this is hugely disappointing, this is a known issue the PurgeCSS team is developing towards. The goal of styled-components is to provide great developer experience while styling, which has many subgoals. PurgeCSS, on the other hand, has only one goal of eliminating unused CSS to increase performance. I bet PurgeCSS will get this functionality before styled-components does.

Alternatives to PurgeCSS

As mentioned before, there are 2 alternatives to PurgeCSS: UnCSS & PurifyCSS.

PurifyCSS

PurifyCSS works much the same way as PurgeCSS: build up a list of selectors from your content and delete the CSS rules with those selectors. The downside of this project is that it scopes out all the content from your project, so if you have a CSS class called 'arrow' and you happen to have the word 'arrow' in a paragraph, PurifyCSS will consider that selector used and keep it in the outputted CSS.

This problem was one of the main goals of PurgeCSS and it solves this quite well.

UnCSS

This project is very interesting. It actually solves the problem of excess CSS the best; it does so by loading your HTML into jsdom, and then querySelector-ing all of the selectors found in your CSS against the emulated DOM. If a selector isn't found in the emulated DOM, UnCSS will not include the CSS rule in its output.

Because UnCSS compares in the 'other direction' (CSS → content, instead of content → CSS like PurgeCSS), it removes CSS much more accurately, including our edge case of nested selectors! In the example above, document.querySelector('.parent .child') would return null, and that CSS rule wouldn't be included.

If UnCSS is so accurate, why do we use PurgeCSS?

What do you think is quicker, statically analyzing content for text (CSS selectors) and doing simple string comparison against CSS files or emulating the entire DOM in JavaScript, loading your HTML/CSS into it, and then running document.querySelector on the emulated DOM for each CSS rule?

UnCSS is splendid, but very costly to run. Imagine a huge project and doing all that work, just to get a few more KB of savings! PurgeCSS is the de facto standard because out of all the solutions, it's the most bang for your buck: remove most of the unused CSS in your project, but keep your build times low.

How to use both PurgeCSS & styled-components

As of writing this, there is no way to integrate both technologies for a couple of reasons:

Styled-components works by injecting critical CSS directly into the head of your HTML; the CSS files needed for PurgeCSS never exist.
PurgeCSS is primarily run with PostCSS, which is not supported with styled-components.

The second of those two reasons is very disappointing, as PostCSS is a rich ecosystem of plugins to extend your CSS' functionality and build process. PostCSS is what Babel is for JavaScript, and unfortunately styled-components is missing out on an entire suite of new functionality.

I have some good news for you though: there is a very common case where you can use both!

CSS Frameworks

I'm not sure what the stats are, but I'm willing to bet that over 50% of websites and webapps started off using a CSS framework. I'm talking about frameworks like Bootstrap, Bulma, Ant, Material UI, Skeleton, and many more.

Using a CSS framework lets developers get up and running much faster than building custom HTML/CSS for components that already exist. And including a framework in your website alongside styled-components is a breeze - add in the classic <link rel="stylesheet" href="styles.css"> with your framework's stylesheets, and those classes will be available to you globally.

But this is exactly what PurgeCSS was written for. You only need a few components from the CSS framework, not thousands of classes you'll never use. So even though we can't integrate PurgeCSS and styled-components directly, they still mesh well together to bring your bundle size to the lowest possible.

Set up PurgeCSS with Gatsby

To help you get up and running with PurgeCSS, I'll show you how to set up PurgeCSS with Gatsby. The options used here can be applied to any other PurgeCSS setup as well.

Install gatsby-plugin-purgecss: yarn add gatsby-plugin-purgecss
Configure the plugin in gatsby-config.js, ensuring you place this plugin AFTER all your other style plugins:

{
      resolve: `gatsby-plugin-purgecss`,
      options: {
        printRejected: true,
        purgeCSSOptions: {},
    },
}

Default configuration for gatsby-plugin-purgecss; be sure to add LAST after all CSS plugins

If you import your styles directly (e.g. import './styles.css' instead of import styles from './styles.css'), this is all you have to do. During your gatsby build command you'll see something like this:

The savings we got from plugging and playing the PurgeCSS plugin

And will feel much better about shipping your CSS to the browser :)

There are two edge cases I'll cover here. The first: if you don't import your styles directly. If you set class names like the following:

import styles from './styles.css'

<div className={style.mySelector} />

You have a couple of options. You can safelist the selector so it never gets purged:

purgeCSSOptions: {
  safelist: ['my-selector'], // Don't remove this selector
}

Using PurgeCSS' native safelist configuration as part of the Gatsby plugin

Or you can use a comment above your component with the correct format of the selector so it gets purged, which is the method I prefer. That way, it's easier to manage if you end up never using the selector and it can be purged safely; the safelist option is a good fail-safe, but it's a bit aggressive in keeping styles. Here's an example with the comment:

import styles from './styles.css'

// my-selector
<div className={style.mySelector} />

PurgeCSS comment to ensure the correctly formatted selector gets purged

Ant Design

The other edge case to consider is if, like us at Anvil, you use Ant Design. PurgeCSS has a hard time with Ant Design to keep the correct styles, and PurgeCSS is aware of this. Here's the solution straight from the docs, but it isn't adapted for the Gatsby plugin.

Below is how I adapted the solution for Gatsby. The gist: use the LESS/CSS files as content. Using your style files as content is a bit confusing, but this makes it so we are getting the selectors in our list of 'used' styles, so when PurgeCSS compares against the same exact files, we are guaranteed to keep those styles we need.

For any components we need all of the styles for, we use the Gatsby plugin's ignore field to ensure nothing from those directories gets purged.

{
  resolve: `gatsby-plugin-purgecss`,
  options: {
    // set this to true for debugging purposes; see what was removed
    printRejected: false,
    // ignore the antd styles you want to completely keep
    ignore: [
      'node_modules/antd/lib/select',
      'node_modules/antd/lib/checkbox',
    ],
    purgeCSSOptions: {
      content: [
        path.join(process.cwd(), 'src/**/!(*.d).{ts,js,jsx,tsx}'),
        // antd doesn't mesh well w purgecss, so keep the files we use
        // by listing them as content files.
        // reference: https://purgecss.com/ant_design.html
        path.join(
          process.cwd(),
          'node_modules/antd/lib/{tooltip,modal,radio}/**/*.{css,less}'
        ),
        // utility styles from ant, let's keep it
        path.join(
          process.cwd(),
          'node_modules/antd/lib/style/**/*.{css,less}'
        ),
      ],
      extractors: [
        {
          // on top of listing antd files as content, we need an extractor to work
          // with css/less to get the selectors
          extractor: (content) =>
            content.match(/([a-zA-Z-0-9-@&:{}]+)(?= {)/g) || [],
          extensions: ['css', 'less'],
        },
      ],
    },
  },
}

gatsby-plugin-purgecss configured to keep select antd styles

Our final CSS savings isn't as much as I wanted, but over 50% is still pretty good:

Putting it all together

Both PurgeCSS and styled-components are popular for a reason. Web development has no one 'correct' way to implement a solution, but both technologies are great additions to any project. And when the two are combined in the case of using a CSS framework, you're guaranteed to get production-ready UX, DX, stylability, and performance. Have any other CSS optimization tips? We'd love to hear from you at developers@useanvil.com. Happy coding!

Manipulate and query GraphQL Schemas with ease using Microfiber

Anvil Engineering — Wed, 13 Apr 2022 16:55:51 +0000

A while back we introduced SpectaQL to the open source community and it's been a big success. It gets thousands of weekly downloads, has a healthy amount of user support and interest via github, and has had a number of articles written about it like this one and this one. Our goal for SpectaQL has always been to be the de-facto go-to library to use for auto-generating static HTML documentation for any GraphQL API. A very important feature of SpectaQL is its ability to "hide" any parts of your API that you don't want to expose in your documentation. This sounds like a simple task, but in practice it's actually a bit tricky. In order to make interacting and manipulating a GraphQL schema easy, we developed a tool designed specifically for this purpose. Eventually we realized that while this tool was super integral to SpectaQL, it would also be useful for other applications so we decided to break it out into its own library and open source it! In this post, I'll introduce Microfiber and give an overview of its most interesting features and capabilities.

The Problem

Unless you're an expert, GraphQL schemas can be a bit tricky to wrap your head around and understand their structure. For example, not everyone understands that your queries are actually defined as Fields on a type that you have specified as a special "Query" type (either by convention or by configuration, depending on the implementation you're using). Also, it can be tricky to understand what you need to know about the Type of certain Fields, Arguments or query/mutation results: are they nullable? Are they a single item or a list? If it's a list, can any of the items be null? Furthermore, if you want to "hide" a Type from your schema, how do you go about finding all the references to that Type in Fields, Arguments, or query/mutation results and remove those things as well? Enter Microfiber!

Why "Microfiber"?

Before we dive in further, you may be wondering: why is it called "microfiber"? You know that little fibrous thing that comes with your glasses and is used to clean the lenses? That's a microfiber. Since a microfiber is used for cleaning up things, and our microfiber is used for "cleaning up" your GraphQL schema, we thought the name made sense. Also, since a microfiber is often used to clean glasses, and our microfiber is used heavily by SpectaQL (a reference to glasses) we thought the name fit doubly as well.

Getting started

In order to keep Microfiber lightweight in terms of dependencies, it requires you to provide it your schema in the form of an Introspection Query result. This result is just a simple JSON object. You can set a number of interesting options when creating your Microfiber instance, however the defaults are all pretty "sane" for must use cases. You can see all the options that are supported in the documentation.

import { Microfiber } from 'microfiber'

const introspectionQueryResults = {...}

const microfiber = new Microfiber(introspectionQueryResults)

// ...do some things to your schema with `microfiber`

const cleanedIntrospectonQueryResults = microfiber.getResponse()

// ...do something with your cleaned Introspection Query Results.

Querying Your Schema

It's not always easy to traverse a schema to find what you're looking for, or to check if it exists. Microfiber provides a number of "get" functions that can do this for you with ease. Here are a few examples:

// Get a specific Query from your schema.
const query = microfiber.getQuery({ name: 'users' })

// Get a specific Mutation from your schema.
const mutation = microfiber.getMutation({ name: 'createUser' })

// Get a specific Field from your schema.
const field = microfiber.getField({ typeKind: 'OBJECT', typeName: 'User', fieldName: 'email' })

// Get a specific Arg from your schema.
const arg = microfiber.getArg({ typeKind: 'OBJECT', typeName: 'User', fieldName: 'addresses', argName: 'countryFilter' })

Modifying Your Schema

While querying with your schema is useful, the real power of Microfiber comes with the manipulations that it can perform. For example, you may want to hide a specific Field on a Type:

microfiber.removeField({
  typeKind: 'OBJECT',
  typeName: 'User',
  fieldName: 'email',
})

Or you may want to hide a mutation that you don't want anyone to know exists:

microfiber.removeMutation({
  name: 'deleteUser',
})

Or, perhaps the most useful feature of Microfiber, you may want to remove a Type completely from your schema. That is, not only remove the Type, but also remove any Fields, InputFields, Union Type options, Args, Queries, or Mutations of that Type. This can be tricky to do on your own but is easy with Microfiber:

microfiber.removeType({
  kind: 'OBJECT',
  name: 'SecretType',
})

Additionally, Microfiber can automatically clean things up by—for example—removing all Types from your schema that are not actually used anywhere. This can sometimes occur when you've hidden certain Fields, etc, that reference a Type, but did not explicitly remove that Type yourself.

microfiber.cleanSchema()

You can retrieve your modified schema with ease, and pass it along where you need it to go:

const cleanedResponse = microfiber.getResponse()

Summary

If you're looking for an easy way to query your GraphQL schema—especially in the form of an Introspection Query result—then Microfiber is a great option instead of trying to write your own helpers. However, if you are trying to clean up or modify your schema by hiding things, then Microfiber can really make your life easier. We'll continue to add more features as we identify them, and if you find microfiber helpful (or have questions) please reach out to us at developers@useanvil.com, or swing on by the repo and leave a message. Happy developing!

Techniques to optimize React render performance: part 2

Anvil Engineering — Fri, 11 Mar 2022 21:11:05 +0000

This is the final part in a two part series on optimizing React component render performance in your UI. In part one of optimizing React performance, we covered tooling, profiling, and generally tracking down exactly where your UI is slow. If you haven't read it yet, check it out. Part 1 was trying to answer Where is it slow? and Why is it slow? Like debugging, knowing exactly where you need to spend your time will make the solution come a lot easier.

By now you should have some UI profiling under your belt and have a good idea of which components are slow. It is high time to fix them. In this post, we will focus on just that: techniques and pitfalls to improve your slow React components.

Render less

The central tenet of improving performance in general is effectively: "do less work." In React land, that usually translates into rendering less often. One of the initial promises of React and the virtual DOM was that you didn't need to think very hard about rendering performance: slowness is caused by updates to the Real DOM, and React abstracts the Real DOM from you in a smart way. Diffing of the virtual DOM and only updating the necessary elements in the Real DOM will save you.

In UIs with a lot of components, the reality is that you still need to be concerned with how often your components are rendering. The less DOM diffing React needs to do, the faster your UI will be. Do less work, render less often. This will be the focus of our initial performance efforts.

Example: list of fields

We'll be applying several different optimization techniques to the same example: a list of webform fields. We'll pretend that we've identified this part of the UI as something to optimize. This same example was used in our first React performance post and we identified a couple issues:

When the list re-renders with a lot of fields, it feels slow.
Each field in the list renders too often; we only want fields that have changed to re-render.

A simplified version of the code and a basis for our optimization work:

// Each individual field
const Field = ({ id, label, isActive, onClick }) => (
  <div onClick={onClick} className={isActive ? 'active' : null}>
    {label}
  </div>
)

// Renders all fields
const ListOfFields = ({ fields }) => {
  // Keep track of the active field based on which one
  // was clicked last
  const [activeField, setActiveField] = useState(null)

  return (
    <div>
      {fields.map(({ id, label }) => (
        <Field
          id={id}
          label={label}
          isActive={id === activeField}
          onClick={() => setActiveField(id)}
        />
      ))}
    </div>
  )
}

Our example for techniques in this post

Note that we are keeping track of an active field in ListOfFields. Each time a Field is clicked, it will store the last-clicked Field's id in the ListOfFields state. The state change will trigger ListOfFields to re-render.

By default, when ListOfFields re-renders, all of the child Field components will re-render as well. For example, clicking one Field will set activeField state in ListOfFields which will cause a ListOfFields re-render. The parent re-render will cause all of the child Field components to re-render. Every one of them! Every time!

Solutions

Our potential solutions will center around two main goals:

Render child Field components less often
Compute expensive operations in the render function less often

After this post, you should be able to apply all these techniques to your own codebase while avoiding the pitfalls. Here's what we'll be covering:

Pure components
shouldComponentUpdate
Caching computed values
Consider your architecture
Other solutions

Let's dig in!

Pure components

The first potential solution to selective component re-rendering is converting our Field component into a pure component. A pure component will only re-render if the component's props change. There are caveats, of course, but we'll get to those in a minute.

In our example above, when a Field is clicked and the activeField state is set, all Field components are re-rendered. Not good! The ideal scenario is that only two Field components are re-rendered: the previously-active and the newly-active Fields. It should skip rendering all of the other Fields that did not change.

Pure components are extremely easy to use. Either:

Wrap a functional component with React.memo
Or define your class component with React.PureComponent instead of React.Component

import React from 'react'

// These components will only re-render
// when their props change!

// Pure functional component
const Field = React.memo(({ id, label, isActive, onClick }) => (
  <div onClick={onClick}>
    {label}
  </div>
))

// Pure class component
class Field extends React.PureComponent {
  render () {
    const { id, label, isActive, onClick } = this.props
    return (
      <div onClick={onClick}>
        {label}
      </div>
    )
  }
}

Using pure components can be an easy win, but it is also very easy to shoot yourself in the foot and unknowingly break re-render prevention.

The big caveat is that a pure component's props are shallow-compared by default. Basically, if (newProps.label !== oldProps.label) reRender(). This is fine if all of your props are primitives: strings, numbers, booleans. But things get more complicated if you are passing anything else as props: objects, arrays, or functions.

Pure component pitfall: callback functions

Here is our original example with Field as a pure component. Turns out even in our new example using pure components, the re-rendering issue has not improved—all Field components are still being rendered on each ListOfFields render. Why?

// Still re-renders all of the fields :(
const Field = React.memo(({ id, label, isActive, onClick }) => (
  <div onClick={onClick}>
    {label}
  </div>
))

const ListOfFields = ({ fields }) => {
  const [activeField, setActiveField] = useState(null)
  return (
    <div>
      {fields.map(({ id, label }) => (
        <Field
          id={id}
          label={label}
          isActive={id === activeField}
          onClick={() => setActiveField(id)} // Problem!!!
        />
      ))}
    </div>
  )
}

The issue is that the onClick callback function is being created in the render function. Remember that pure components do a shallow props comparison; they test equality by reference, but two onClick functions are not equal between renders: (() => {}) === (() => {}) is false.

How can we fix this? By passing the same function to onClick in each re-render. You have a couple options here:

Pass in setActiveField directly
Wrap your callback in the useCallback hook
Use bound member functions when using class components

Here the issue is fixed with the first two options in a functional component:

const ListOfFields = ({ fields }) => {
  // The useState hook will keep setActiveField the same
  // shallow-equal function between renders
  const [activeField, setActiveField] = useState(null)
  return (
    <div>
      {fields.map(({ id, label }) => (
        <Field
          id={id}
          label={label}
          isActive={id === activeField}

          // Option 1: setActiveField does not change between renders,
          // you can pass it directly without breaking React.memo
          onClick={setActiveField}

          // Option 2: memoize the callback with useCallback
          onClick={useCallback(() => setActiveField(id), [id])}
        />
      ))}
    </div>
  )
}

// An anonymous function in the render method here will not
// trigger additional re-renders
const Field = React.memo(({ id, label, isActive, onClick }) => (
  <div
    // Option 1: Since setActiveField is passed in directly,
    // we need to give it an id. An inline function here is ok
    // and will not trigger re-renders
    onClick={() => onClick(id)}

    // Option 2: Since the id is passed to the setActiveField
    // in the parent component, you can use the callback directly
    onClick={onClick}
  >
    {label}
  </div>
))

And a fix using class components:

class Field extends React.PureComponent {
  handleClick = () => {
    const { id, onClick } = this.props
    onClick(id)
  }

  render () {
    const { label, isActive } = this.props
    return (
      <div onClick={this.handleClick}>
        {label}
      </div>
    )
  }
}

class ListOfFields extends React.Component {
  state = { activeField: null }

  // Use a bound function
  handleClick = (activeField) => {
    this.setState({ activeField })
  }

  render () {
    const { fields } = this.props
    return (
      <div>
        {fields.map(({ id, label }) => (
          <Field
            id={id}
            label={label}
            isActive={id === this.state.activeField}

            // Solved! The bound function does not change between renders
            onClick={this.handleClick}
          />
        ))}
      </div>
    )
  }
}

Pure component pitfall: dynamic data in the render function

The function callback pitfall described above is really a subset of a larger issue: passing props dynamically created in the render function. For example, because { color: 'blue' } is defined in the render function here, it will be different on each render, which will force a re-render on every Field component.

// Pure component for each individual field
const Field = React.memo(({ label, style }) => (
  <div style={style}>{label}</div>
))

const ListOfFields = ({ fields }) => {
  const style = { color: 'blue' } // Problem!
  return fields.map(({ label }) => (
    <Field
      label={label}
      style={style}
    />
  ))
}

The ideal solution is to create the style prop's object somewhere outside of the render function. If you must dynamically create an object or array in the render function, the created object can be wrapped in the useMemo hook. The useMemo hook is covered in the caching computed values section below.

shouldComponentUpdate

By default, pure components shallow-compare props. If you have props that need to be compared in a more complex way, there is a shouldComponentUpdate lifecycle function for class components and a functional / hooks equivalent in React.memo.

For the functional implementation, React.memo takes a second param: a function to do the props comparison. It's still beneficial to shoot for props that do not change between renders unless a re-render is necessary, but the real world is messy and these functions provide an escape hatch.

const Field = React.memo(({ label, style }) => (
  <div style={style}>{label}</div>
), (props, nextProps) => (
  // Return true to NOT re-render
  // We can shallow-compare the label
  props.label === nextProps.label &&
    // But we deep compare the `style` prop
    _.isEqual(props.style, nextProps.style)
))

Then implemented as a class component

class Field extends React.Component {
  shouldComponentUpdate () {
    // Return false to NOT re-render
    return props.label !== nextProps.label ||
      // Here we deep compare style
      !_.isEqual(props.style, nextProps.style)
  }

  render () {
    const { label, style } = this.props
    return (
      <div style={style}>{label}</div>
    )
  }
}

Caching computed values

Let's say that while profiling your app you've identified an expensive operation happening on each render of ListOfFields:

const ListOfFields = ({ fields, filterCriteria }) => {
  const [activeField, setActiveField] = useState(null)

  // This is slow!
  const filteredFields = verySlowFunctionToFilterFields(fields, filterCriteria)

  return filteredFields.map(({ id, label }) => (
    <Field
      id={id}
      label={label}
      isActive={id === activeField}
      onClick={setActiveField}
    />
  ))
}

In this example, every time a Field is clicked, it will re-run verySlowFunctionToFilterFields. But it doesn't need to! The filteredFields only need to be computed each time either the fields or filterCriteria are changed. You can wrap your slow function in the useMemo() hook to memoize filteredFields. Once it's memoized, verySlowFunctionToFilterFields will only re-run when fields or filterCriteria changes.

import React, { useMemo } from 'react'

const ListOfFields = ({ fields, filterCriteria }) => {
  const [activeField, setActiveField] = useState(null)

  // Better, yay
  const filteredFields = useMemo(() => (
    verySlowFunctionToFilterFields(fields, filterCriteria)
  ), [fields, filterCriteria])

  return filteredFields.map(({ id, label }) => (
    <Field
      id={id}
      label={label}
      isActive={id === activeField}
      onClick={setActiveField}
    />
  ))
}

Like pure components, you need to be careful that you do not break the comparison. useMemo suffers from the same pitfalls as pure components: it performs a shallow-comparison of arguments. That means if fields or filterCriteria are re-created between renders, it will still re-compute your expensive operation on each render.

Unfortunately useMemo does not accept a second comparison argument like React.memo. If you want to do a deep comparison there are several code samples and libraries out there you can use.

Using `useMemo` to limit re-renders

In our pure component pitfalls above, we noted that passing objects created in the render function can break a pure component's benefits. Note here that the style object is being created on each render of ListOfFields, forcing all Fields to render all the time.

// Pure component for each individual field
const Field = React.memo(({ label, style }) => (
  <div style={style}>{label}</div>
))

const ListOfFields = ({ fields }) => {
  const style = { color: 'blue' } // Problem! Forces Field to always re-render
  return fields.map(({ label }) => (
    <Field
      label={label}
      style={style}
    />
  ))
}

While the ideal scenario is to move creation of the style object out of the render function, sometimes creating an object in the render function is necessary. In those instances, useMemo can be helpful:

const ListOfFields = ({ color, fields }) => {
  // This will be cached until the `color` prop changes
  const style = useMemo(() => ({ color }), [color])
  return fields.map(({ label }) => (
    <Field
      label={label}
      style={style}
    />
  ))
}

Caching computed values in class components

Caching computed values in class components is a bit clunkier, especially if you are trying to avoid the UNSAFE_componentWillReceiveProps() lifecycle function. The React maintainers recommend using the memoize-one library:

import React from 'react'
import memoize from "memoize-one"

class ListOfFields extends React.Component {
  state = { activeField: null }

  handleClick = (id) => this.setState({activeField: id})

  getFilteredFields = memoize(
    (fields, filterCriteria) => (
      verySlowFunctionToFilterFields(fields, filterCriteria)
    )
  )

  render () {
    const { fields, filterCriteria } = this.props
    const filteredFields = this.getFilteredFields(fields, filterCriteria)
    return filteredFields.map(({ id, label }) => (
      <Field
        id={id}
        label={label}
        isActive={id === activeField}
        onClick={this.handleClick}
      />
    ))
  }
}

Consider your architecture

So far, we've focused on pretty tactical solutions: e.g. use this library function in this way. A much broader tool in your toolbox is adjusting your application's architecture to re-render fewer components when things change. At the very least, it is helpful to understand how your app's data flow and data locality affects performance.

A couple questions to answer: at what level are you storing application state? When something changes deep in the component tree, where is the new data stored? Which components are being rendered when state changes?

In the spirit of our webform example, consider the following component tree:

<Application>
  <Navbar />
  <AnExpensiveComponent>
    <ExpensiveChild />
  </AnExpensiveComponent>
  <Webform>
    <ListOfFields>
      <Field />
      <Field />
      <Field />
    </ListOfFields>
  </Webform>
<Application>

For the webform editor, we need an array of fields stored somewhere in this tree. When a field is clicked or label is updated, the array of fields needs to be updated, and some components need to be re-rendered.

Let's say at first we keep the fields state in the <Application /> Component. When a field changes, the newly changed field will bubble up all the way to the Application component's state.

const Application = () => {
  const [fields, setFields] = useState([{ id: 'one'}])
  return (
    <>
      <Navbar />
      <AnExpensiveComponent />
      <Webform fields={fields} onChangeFields={setFields} />
    </>
  )
}

With this architecture, every field change will cause a re-render of Application, which will rightly re-render Webform and all the child Field components. The downside is that each Field change will also trigger a re-render of Navbar and AnExpensiveComponent. Not ideal! AnExpensiveComponent sounds slow! These components do not even care about fields, why are they being unnecessarily re-rendered here?

A more performant alternative would be to store the state closer to the components that care about the fields array.

const Application = () => (
  <>
    <Navbar />
    <AnExpensiveComponent />
    <Webform />
  </>
)

const Webform = () => {
  const [fields, setFields] = useState([{ id: 'one'}])
  return (
    <ListOfFields fields={fields} onChangeFields={setFields} />
  )
}

With this new setup, Application, Navbar, and AnExpensiveComponent are all blissfully unaware of fields. Don't render, ain't care.

In practice: Redux

While I am not a Redux advocate, it really shines in this scenario. The Redux docs even outline this as the number one reason to use Redux:

You have large amounts of application state that are needed in many places in the app.

"Many places in the app" is the key for us here. Redux allows you to connect() any component to the Redux store at any level. That way, only the components that need to will re-render when the requisite piece of state changes.

// Application does not need to know about fields
const Application = () => (
  <>
    <Navbar />
    <AnExpensiveComponent />
    <ListOfFields />
  </>
)


// ListOfFieldsComponent does need to know about
// fields and how to update them
const ListOfFieldsComponent = ({ fields, onChangeFields }) => (
  fields.map(({ label, onChangeFields }) => (
    <Field
      label={label}
      style={style}
      onChange={eventuallyCallOnChangeFields}
    />
  ))
)

// This will connect the Redux store only to the component
// where we need the state: ListOfFields
const ListOfFields = connect(
  (state) => ({ fields: state.fields }),
  (dispatch) => {
    onChangeFields: (fields) => dispatch({
      type: 'CHANGE_FIELDS',
      payload: fields
    }),
  }
)(ListOfFieldsComponent)

If you're using Redux, it's worth checking which components are being connected to which parts of the store.

App state best practices?

Deciding where to put your application state, or pieces of your application state is tricky. It depends heavily on what data you are storing, how it needs to be updated, and libraries you're using. In my opinion, there are no hard / fast rules here due to the many tradeoffs.

My philosophy is to initially optimize for consistency and developer reasonability. On many pages, it doesn't matter where the state is, so it makes the most sense to keep the ugly bits in one place. State is where the bugs are, premature optimization is the root of all evil, so for the sake of our own sanity let's not scatter state around if we can help it.

For example, your company's about page can have all data come into the top-level component. It's fine, and is likely more ideal for developer UX. If performance is an issue for some component, then it's time to think deeper about the performance of your app's state flow and maybe break the paradigm for performance reasons.

At Anvil, we use Apollo to store app state from the API, and mostly adhere to the Container pattern: there is a "Container" component at a high level doing the fetching + updating via the API, then "Presentational" component children that consume the data as props. To be a little more concrete:

Our app's pages all start out with all data for a page being fetched and stored at the Route level.
For complex components with a lot of changes to state, we store state at the deepest level that makes sense.
We store ephemeral UI state like hover, 'active' elements, modal visibility, etc., as deep as possible.

This is how we approach things, but your organization is likely different. While your approach and philosophical leanings may be different, it's helpful to understand that the higher the state is in the component tree, the more components React will try to re-render. Is that an issue? If so, what are the tools to fix it? Those are hard questions. Hopefully the sections above can help give you a bit of direction.

You made it!

Performance optimization is tricky work; it is filled with tradeoffs and could always be better. Hopefully this post helped add tools to your performance optimization toolbox.

Before we depart, I want to stress the importance of profiling your UI before applying any of these techniques. You should have a really good idea of which components need to be optimized before digging in. Performance optimization often comes at the expense of readability and almost always adds complexity.

In some cases, blindly adding performance optimizations could actually make your UI slower. For example, it may be tempting to make everything a pure component. Unfortunately that would add overhead. If everything is a pure component, React will be doing unnecessary work comparing props on components that do not need it. Performance work is best applied only to the problem areas. Profile first!

Do you have any feedback? Are you developing something cool with PDFs or paperwork automation? Let us know at developers@useanvil.com. We’d love to hear from you!

Understanding SEO and ways to improve it

Anvil Engineering — Fri, 11 Feb 2022 20:57:55 +0000

With the abundance of digital content and distractions today, it has become increasingly tricky navigating the path to publishing content online and making sure it gets seen. Search engines have adopted complex and evolving algorithms factoring in a number of metrics to determine a site's ranking on their results page. How do you make sure your content gets seen? To answer this, we look to SEO (search engine optimization).

SEO is the process of improving the metrics search engines look at to increase the ranking of a website in search results. In this post, we'll be diving into how search engines work, the foundations of SEO, and the specific changes you can make on your web app to ensure your content consistently shows up on the front page. We'll be covering the many small but incremental changes you can make that build into a noticeable impact in user experience on your site. The extra steps you take in doing so will naturally translate into search engines prioritizing your content.

Search engines: how do they work?

When you type 'cats' into Google images, the search engine returns a never-ending gallery of lovely cat images. Every one of these images are known to the search engine because they have been discovered prior by one of Google's web crawlers. This step of discovering webpages by search engines is called crawling. Web crawlers work by visiting links found in online content, and are crawling the internet nonstop to discover newly published websites.

Next comes indexing. Upon discovering a webpage, web crawlers must parse the data to make sense of what the page is about. Indexing involves analyzing the text, metadata, images, and video files embedded into webpages. The results are stored into a gigantic database belonging to the search engine called the index.

The last step is serving. Based on the input given by the user, which in our case is 'cats', search engines query, filter, and return the most relevant webpages from its index. Serving also takes into account the user's information such as location, language, and search history.

When thinking about SEO, we must consider all of these steps: crawling, indexing, and serving. We need to make it easy for search engines to do their job every step of the way. So, our web app needs to be discoverable, easy to understand, and descriptive. Once search engines find it easily, humans will too.

Increase crawl accessibility

Crawl accessibility is important for the discoverability of your website to web crawlers, and the best way of improving that metric is providing sitemaps. Crawlers automatically traverse through webpages regardless of whether sitemaps are provided, but including them provides a number of advantages. First, pages listed in sitemaps are prioritized by crawlers, giving your webpages earlier exposure and more frequent indexing by search engines. This is especially important if your content is rapidly evolving or not close in proximity to sites with heavy traffic. Second, sitemaps enable the communication of additional information to crawlers, such as update frequency and image or video metadata. Providing crawlers with more data is especially helpful for pages with lots of non-textual content, as crawlers typically rely on text for context.

There are several formats for sitemaps: XML, RSS, and text. Different search engines may accept different formats.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>http://www.example.com/foo.html</loc>
    <lastmod>2020-12-04</lastmod>
    <changefreq>monthly</changefreq>
    <priority>0.9</priority>
  </url>
</urlset>

An example of a sitemap in XML format.

As you can see, the code snippet shown communicates to crawlers about the date the webpage was last modified, the likely frequency of changes to the page, and priority of the webpage's URL relative to other pages on the domain.

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
  <url>
    <loc>http://example.org/page1.html</loc>
    <image:image>
      <image:loc>http://example.org/image1.jpg</image:loc>
    </image:image>
  </url>
  <url>
    <loc>http://example.org/page2.html</loc>
    <image:image>
      <image:loc>http://example.org/image2.jpg</image:loc>
      <image:caption>Cats in a pet-friendly office</image:caption>
      <image:geo_location>San Francisco, CA</image:geo_location>
      <image:title>Office cats</image:title>
      <image:license>http://example.org/image-license</image:license>
    </image:image>
  </url>
</urlset>

An example sitemap for two webpages with images in XML format.

Visit this page to learn more about sitemaps and its documentation.

Prevent crawling on irrelevant data

In contrast to encouraging crawling, we need rules to disable crawlers from accessing sensitive, duplicate, or unimportant content. There are numerous scenarios where we want content hidden. There may be pages with private data on your domain you want hidden from search results. In addition, it's good practice to prevent crawlers from seeing repeated content in your web app, as it can be mistaken for spam thus lowering your ranking in search results. Your webpage may have also embedded content from third party sites which can be irrelevant to your topic.

Multiple approaches are available for hiding content from search engines, such as removing the content directly, requiring passwords for certain webpages, or using the noindex directive. Adding a robots.txt file to your web app is the most flexible approach.

User-agent: Googlebot
Disallow: /private/media/

User-agent: *
Allow: /

Sitemap: http://useanvil.com/sitemap.xml

An example robots.txt file

The above example prevents Google search's web crawler from accessing routes under /private/media/, but all other visitors are given full site access. It's important to allow crawlers access to JavaScript, CSS, and image files with the exception of sensitive data to avoid negative impacts on indexing. And finally, the last line tells the crawler where the sitemap can be found.

The file must be named robots.txt and placed at the root of the website host for crawlers to find. robots.txt works by specifying rules, with each rule involving a group specified using User-agent and their permissions specified using Allow or Disallow. Only one rule may apply to a group at a time.

For more information regarding robots.txt files, refer to these docs.

`noindex` directive

Besides the robots.txt approach, using the noindex directive is just as effective. noindex can be placed within a meta tag in HTML or an HTTP response header, telling web crawlers indexing the webpage to prevent the page from being shown in search results.

<head>
  <title>404 Page not found</title>
  <meta name="robots" content="noindex">
</head>
<body>
  …
</body>

404 page should not be shown in search results

HTTP/2 200 OK
…
X-Robots-Tag: noindex

Response body will not be shown in search results. Body can include HTML, image, video, PDF files.

Refer to this page for more information.

Return helpful HTTP status codes

Web crawlers rely on status codes to determine whether a page should be crawled and if it contains meaningful content. Make use of '301' (moved permanently), '401' (unauthorized), or '404' (not found) statuses so crawlers know how to update the index. Google's web crawler, for example, doesn't save webpages that respond with 4xx or 5xx into the index.

Make indexing easy

Once web crawlers have found your website, you want your webpages to be easy to understand. This involves using concise and unique page titles and descriptions. Each webpage should have a title that is focused on what the content is about and is distinguishable. It's also a good idea to include the business name or location if applicable.

Make use of title and meta tags. Titles should include seven to eight words at most, to avoid any text cut off when shown in search results. Descriptions should include a hook to grab users' attention and get clicks. Having a one to three sentence description is optimal.

<head>
  <title>Minimizing webpack bundle size - Anvil</title>
  <meta name="description" content="Learn how to minimize your Webpack bundle size by following these best practices, ensuring an optimal user experience.">
</head>

First page on Google results

Performance

Besides the basics such as title and description, user experience plays a huge role. Factors such as performance and web accessibility belong under that category. Metrics such as 'first contentful paint' and 'time to interactive' factor into whether users will remain on the site. You can gather these metrics for your web app using Lighthouse made available by Google.

Performance metrics for Anvil's main page

You can improve your performance metrics by compressing images, decluttering your files, code splitting, using lighter dependencies, and so on. If you use Webpack to compile your web app, I highly recommend taking a look at my post about Minimizing webpack bundle size, which covers the subject comprehensively with solutions.

Web accessibility

Enabling your content to be accessible to everyone, including those with impairments, can provide a considerable boost to your ranking. Best practices to adopt include using header tags (i.e. <h1>, <h2>), setting alt attributes to images, and providing labels to control elements (e.g. <button>, <checkbox>).

<h1>Yellow Cab Inc.</h1>
<img src="https://yellowcab.com/assets/logo" alt="Yellow Cab Inc. logo">
<h2>Contact us</h2>

<label for="fullName">Full name:</label>
<input type="text" name="fullName">

<button type="submit">Submit</button>

Make use of header tags, the alt attribute, and labels.

Accessibility metrics

Mobile-friendly

Users expect websites to be usable on mobile, and having a web app that is responsive to that format is crucial for online presence. The most common mobile strategy is responsive web design. With this approach, telling the browser how to adjust content on the viewport is necessary.

<meta name="viewport" content="width=device-width, initial-scale=1.0">

The browser is instructed to handle the viewport's dimensions. The width of the webpage is set to the device's width, and with a zoom ratio of 1.0.

A good way to check whether your web app is ready for use on mobile devices is the Mobile-Friendly Test.

Optimize images

Always use the <img> tag to display pictures instead of alternate methods such as CSS. Crawlers respond positively to images having alt attributes in case the image cannot be found. Compress your images so they don't take forever to load and lazy load images that have a high file size. Image filenames also matter, as it gives crawlers context on what the image is. Also, avoid using images as links.

Ex: use 'dog-in-office.png' instead of 'dog1.png'.

Use simple and clear URLs

It may not be apparent, but users do pay attention to the format of URLs. Structure your routes so that they are organized, concise, and clear. Having unstructured URLs can prevent users from clicking and sharing.

Ex: use https://useanvil.com/docs/api/getting-started, not https://useanvil.com/folder-1/file-2.

While on the topic of URLs, I recommend creating a 404 not found page for your web app. It's almost guaranteed that someone will hit a broken link sooner or later.

Provide useful content

I've suggested all the changes you can make to your code to boost your SEO ranking, but the central factor is providing good content. Make sure your blog, service, newsletter, or whatever it is provides information valuable to users. Using keywords, encouraging sharing, adding links to other pieces of useful information, and understanding your audience are all factors to consider.

Summary

We've covered the concept of SEO, the steps involved in displaying a webpage on search results, increasing web app crawl accessibility, optimizing code in handling indexing, and providing a better user experience. We also looked into SEO tools and general web development best practices. With these concepts introduced into your code, you can worry less about whether your content will be discovered.

Introduction to the Twelve-Factor App Part 3

Anvil Engineering — Fri, 11 Feb 2022 20:53:19 +0000

12 Factor App Blog Post Part 3

Summary: Make your toy web apps more robust and manageable by following the Twelve-Factor App methodology.

This is the third and last part in a series of posts detailing the 12 Factor App. In the last
post we looked at:

Build, release, and run stages and how segmenting your development processes can open up possibilities in terms of automation
Explored the benefits of running your app as a stateless process

If you need a refresher or would like to take a look at the previous posts:

As with the last post, most of the remaining factors come about as downstream results from implementing the previous
factors. If you’ve been following along, many of these will be on the easier side of implementing – or it may even be
done already if you’re using certain services.

VII. Port binding

Export services via port binding - https://12factor.net/port-binding

Once your application becomes more or less
stateless (Factors II, III, IV, you’re now
able to think of your application itself as a backing service. One of the last steps would be to export HTTP as a
service by binding to a port.

For example, when developing a frontend application, you may be familiar with a development server listening on your
local port 3000 (i.e. http://localhost:3000). Exporting your app as a service would work the same. Some frameworks may
have it built-in already and can be deployed with a simple node app.js. You may have to look into adding additional
dependencies such as uWSGI/Gunicorn in the Python world.

VIII. Concurrency

Scale out via the process model - https://12factor.net/concurrency

The obvious first thought when attempting to scale your app is “Can we just run more instances of the app?” If you’ve
been following along so far and implemented all the previous factors, the answer should be “Yes!*”

* But you should still look at the remaining factors :)

Some of the main hurdles at this point will be to:

Assess your infrastructure and see if this can be done automatically, like with Kubernetes. Scaling up and down automatically, depending on usage, can save your site when unexpected traffic hits.
Assess your code and backing services. If a bunch of users hit an endpoint at the same time on multiple app instances, will something catch on fire? Can your database support all the new connections/queries from the new instance?
Start thinking about any additional costs when new instances are created. How much additional resources your entire application plus infrastructure will start to consume?
Think about how data and user flow will work when a new instance is created and destroyed (covered in IX. Disposability).

IX. Disposability

Maximize robustness with fast startup and graceful shutdown - https://12factor.net/disposability

Since your app is stateless, you won’t have to worry about any stored data in your app instance as anything important is
stored in the cloud and/or in a database. Going hand-in-hand with concurrency above, this gives you the freedom of
creating and destroying instances at any time. You can create new instances to handle more load on your application and
also destroy any excess to avoid incurring extra infrastructure costs.

When thinking about disposability, your app should be resilient against interruptions at any point in its lifecycle.

What will your app do when a long-running request gets cancelled?
Will your database be left with incomplete data?
Will your job queue be left with stale jobs that never finished?

Addressing these sorts of potential problems may lead to a lot of work, but will definitely be worth it since the work
you do here will also help mitigate any problems when more catastrophic app failures happen.

Again, if using a Kubernetes cluster, a lot of this is handled automatically, however, you will still need to think
about your codebase and backing services and how they will react to sudden interruptions.

X. Dev/prod parity

Keep development, staging, and production as similar as possible - https://12factor.net/dev-prod-parity

In a modern development environment, this is much less of an issue because of the popularity of Docker and automation.
Nevertheless, it’s still important to try to keep development and production environments as similar as possible. Of
course, this does not mean you should be developing on the live production database, but if your app in production uses
PostgreSQL, you should also be using PostgreSQL in development, and so on.

The most common way of achieving this is to use Docker. Docker makes this easy by making development environments
extremely reproducible which leads to less ramp up time for new team members and more time working on your app’s
features. Docker also makes it easy to have the same (or nearly the same) backing services available for your app in
development with docker-compose.

Keeping development and production as identical as possible should:

Decrease backing service issues during deployment.
Give more confidence to developers that their code will work the way it does in their own development environment.
Allow higher chance of reproducibility for any issues seen on production.

XI. Logs

Treat logs as event streams - https://12factor.net/logs

With smaller, earlier stage apps, logging is most likely an afterthought, or not as robust, so this may not seem that
important. In a 12 factor app, logs are treated as event streams. This can be done through external services such as
Papertrail, or possibly already handled by your app’s deployment platform such as Heroku or Google Cloud Platform.

Essentially 12 factor apps should only be concerned with sending log output to the system’s stdout. This allows for
other backing services or apps to manage log data and whether or not to store it. Again, this keeps the app stateless as
it decouples log storage and it also centralizes all log data, which is especially useful when there’s more than one app
instance up.

Logging itself, as well as best practices, what to log, etc. is a whole different beast, but good logging should allow
for:

Finding specific events in the past.
Large-scale graphing of trends (such as requests per minute).
Active alerting according to user-defined heuristics (such as an alert when the quantity of errors per minute exceeds a certain threshold). https://12factor.net/logs

XII. Admin processes

Run admin/management tasks as one-off processes - https://12factor.net/admin-processes

More likely than not, your application will have to run admin processes every now and then. An example of this includes
database migrations to change table structures and/or data. In a 12 factor app, these admin processes should be stored
in the same codebase as the app, and it should also run in the same environment as the app.

This prevents extra dependencies and unexpected issues from things such as one-off shell scripts. Being in the same
codebase, and in the same environment, we’re able to control the one-off processes’s execution to ensure it runs as
expected.

As examples: In the node world, you could have npm or yarn scripts that would bootstrap part of your application to
run these one-off tasks. Also in the Python world, Django has its own REPL and framework to create your own custom
commands which run via python manage.py <YOUR_COMMAND>.

A caveat: while doing research for this, some articles mention that having an REPL available in production (which is
what 12factor.net recommends) is a potential security concern as it gives almost complete access to your entire
application. Depending on how your infrastructure is designed, you may also want to incorporate more security for
one-off admin processes.

Conclusion

According to Wikipedia the Twelve-Factor app is over 10
years old(!) at the time of writing this post. As this post was written, it’s incredible how many of these concepts are
still absolutely valuable and used in practice in the modern development world we’re in today. We here at Anvil follow
nearly all of the 12 factors and our development team performs like a well oiled machine because of it.

Are you developing your apps with the 12 Factor methodology in mind? Are you using or want to use Anvil as a backing
service? If you’re developing something cool with PDFs or paperwork automation, let us know at developers@useanvil.com.
We’d love to hear from you.

Image Processing in Gatsby

Anvil Engineering — Fri, 14 Jan 2022 20:26:55 +0000

According to The HTTP Archive, 90% of the pages on the web contain about 7MB of data, with 5.2MB being unoptimized images. That means no matter what you do to your site, if your images aren't optimized then your site is falling behind in terms of performance alone. Add in accessibility concerns and responsive design, and you have a recipe for disaster.

Luckily, Gatsby handles most image optimization problems for us. Out of the box, Gatsby compresses your images, converts them to modern formats (e.g. webp), and adds cache-control headers to them. With Gatsby's newest image plugin, you can also set up responsive images for your entire site. The topic of this blog post is not to discuss these optimizations themselves (look out for a future blog post on that), but rather how Gatsby does all that ‘magic' for you and how you can get the most out of Gatsby's image processing.

Ready to dive in?

The Basics

First and foremost, make sure you understand image formats.

Image formats

The old school, raster image formats are PNG and JPEG (or JPG). These image formats are best suited for actual photographs and pictures because the pixels in these images are explicitly defined.

We also have vector images, such as SVG. These image formats are for everything else that isn't a photograph. Icons and designed graphics come to mind here. SVGs should make up most of your site's images and be used whenever possible. They have huge benefits over raster image formats, such as:

Smaller file sizes. SVGs define shapes, lines, etc. and let the browser fill those in. Since the images don't need to explicitly define each pixel, file sizes are much smaller.
Inherently responsive. Again because of not explicitly defining pixels, SVGs will look nice and clean on any screen size. You can dynamically resize them too!
Can be written inline. SVGs don't actually have to be assets. You can write them inline in your HTML (or React).

Lastly, we have the new school raster image formats, WebP and AVIF. These follow the same usage guidelines as PNG and JPEG: only use them for photographs/images. The difference with these image formats is they are better for compression and quality.

Importing assets in Gatsby

Gatsby leverages a widely-used module bundler called webpack. Through webpack, you as a developer can import assets directly in your JavaScript files, like the example below:

import React from 'react'
// path can be absolute (like below) or relative to the current file
import heroAsset from '~/dev/super-sophisticated-site/hero-asset.png'

export default class MyComponent extends React.Component {
    render () {
        return (
            <img src={heroAsset} alt="Super Sophisticated's Hero Asset" />
        )
    }
}

Webpack is what enables line 3, where we import an image directly into JS

This import syntax, enabled by webpack, automatically minifies and bundles your assets, pushes any errors to build time instead of run time, and sets up caching on your assets.

What's also important to note here for image optimization is that these imports are where Gatsby applies a conversion for images to data URIs if the image is less than 10,000 bytes. It's more cost effective to embed the data directly in HTML in this case - the less network requests, the better!

The `static` folder

The last piece of the basics of images in Gatsby, is the static folder. It sits at the top-level directory of your project, and serves as an escape hatch for everything I talked about in the previous section on importing assets.

We do not use the static folder here at Anvil, and neither should you. All the optimizations above improve your site's performance, usability, and maintainability drastically, so only use this folder if you really need to. Gatsby has a good list on when you should use the static folder, but in general it's used for when you want to keep the name of an asset the same at run time or if you want to serve a custom script.

Under the hood

With the basics out of the way, let's get into what powers Gatsby's system to perform actions like data sourcing, dynamic image processing, and generating responsive images.

Data layer

At the core of Gatsby is the data layer. This is built into Gatsby and provides a uniform interface to access any data you need for your site.

Most static sites are article-based. But how do you host your content? Do you opt for a CMS like WordPress, Sanity, or Contentful? Or what if you want something simple, like keeping your content in markdown alongside your code? There are many places for your content to live, and the questions above are only for static content. Many more questions arise when user-specific, dynamic content is involved, likely requiring a database.

Designing the right solution for your content and site is complex, but the data layer Gatsby provides is a way to simplify accessing your data regardless of its source. Gatsby also has ways to transform your data nodes after sourcing it into the data layer, so by the time you access the data on your site, it is exactly in the format we want: optimized for production.

The diagram above uses 'source plugins' to gather data. We'll take a deeper look at plugins later on, but for now let's start an example of sourcing data using the gatsby-source-filesystem plugin.

Let's say we are starting a blog website that will feature technical writers. Since the blog authors will be technical, we aren't going to need a CMS; we are comfortable with the authors writing in markdown and potentially even having access to the entire codebase. With this in mind, all we need is markdown articles served right from the same repository as our code. This will be our directory structure:

super-sophisticated-technical-website
    | - src
        | - components
        | - pages
    | - markdown-articles
        | - blog-posts
    | - gatsby-config.js
    | - gatsby-node.js
    | - package.json

Super Sophisticated™'s directory structure

With this directory structure, the configuration for our technical blog will be as follows:

const path = require('path')

export default {
    siteMetadata: {
        siteName: 'Super Sophisticated',
    title: 'The most sophisticated business',
    description:
      'Reduce costs and unlock growth by transitioning from paper and PDF-based processes to simple and flexible online workflows.',
    keywords: 'website,sophisticated,super,gatsby',
    },
    plugins: [
        {
        resolve: 'gatsby-source-filesystem',
      options: {
        path: path.resolve('src/markdown-articles/blog-posts'),
        name: 'blog-posts',
      },
    },
    ]
}

The plugins section uses gatsby-source-filesystem to load our markdown blog posts into Gatsby's data layer.

While not the topic of this blog post, the data in your gatsby-config.js's siteMetadata field gets automatically loaded into the data layer. So siteName, title, description, and keywords are all accessible throughout your site - this is useful for setting HTML meta tags for all pages.

Accessing your data

GraphQL is how you access your data from Gatsby's data layer. There are two ways to query for data:

Page queries
"Building block" components' static query

If you are unfamiliar with GraphQL, I highly recommend you take the time to learn it. GraphQL makes data querying much more efficient than REST endpoints, and maps to any data you need within your data model. If you're coming from REST and need a place to start, we have a blog post on consuming GraphQL APIs just for you. GraphQL uses REST under the hood, after all :)

Back to Gatsby and its GraphQL API. To start accessing your data, you will need to use the named import graphql from gatsby for both page queries and static queries. To start, let's look at a page query for a blog post template:

import React from 'react'
import { graphql } from 'gatsby'
import RehypeReact from 'rehype-react'

const MyGatsbyPage = ({ data }) => {

    /* AST renderer we use at Anvil: https://github.com/rehypejs/rehype-react */
    const renderAst = new RehypeReact({
      createElement: React.createElement,
    }).Compiler

    return (
        <div>
            <h1>{data.frontmatter.title}</h1>
            <h2>{data.frontmatter.date}</h2>
            <h3>By ${data.frontmatter.author}</h3>
            <p>{data.frontmatter.summary}</p>
            <div id="blog-content">
                {renderAst(data.htmlAst)}
            </div>
        </div>
    )
}

export default MyGatsbyPage

export const pageQuery = graphql`
    query BlogPostByPath($slug: String!) {
        site {
            siteMetadata {
                siteName
                title
                description
                keywords
            }
        }
        markdownRemark(frontmatter: { path: { eq: $slug } }) {
            htmlAst
            frontmatter {
                date
                title
                summary
                author
                image {
                    publicURL
                    childImageSharp {
                        gatsbyImageData
                    }
                }
            }
        }
    }
`

Accessing data via a Gatsby page query, using GraphQL

Page queries, like the one above, are exported in the page component. Gatsby recognizes the exported const pageQuery and at build time will execute your query. The resulting data from the query is then passed into your page component (in our case, MyGatsbyPage) as a prop called data. You can now access any data from your query directly in your component!

The above example is supposed to be simple to show how page queries work... so for understanding this section, just focus on the export const pageQuery part and how we are able to use the prop data with data directly from the data layer. The other parts (markdownRemark, frontmatter, htmlAst, and childImageSharp) are from Gatsby plugins to make blog posts from markdown work and to enable responsive images. We'll talk about plugins in a bit!

As a note, the syntax I used in getting the variable data is called destructuring. The equivalent example without destructuring would be:

const MyGatsbyPage = (props) => {

    const data = props.data

    /* AST renderer we use at Anvil: https://github.com/rehypejs/rehype-react */
    const renderAst = new RehypeReact({
      createElement: React.createElement,
    }).Compiler

    return (
        <div>
            <h1>{data.frontmatter.title}</h1>
            <h2>{data.frontmatter.date}</h2>
            <h3>By ${data.frontmatter.author}</h3>
            <p>{data.frontmatter.summary}</p>
            <div id="blog-content">
                {renderAst(data.htmlAst)}
            </div>
        </div>
    )
}

Accessing the data prop without destructuring

The other way to access data is in what Gatsby calls 'building block' components. These components aren't anything special; they just aren't page components… which makes them components you reuse anywhere and everywhere possible. Since they aren't page components, Gatsby has provided the StaticQuery component (old school way, made for class components) and the useStaticQuery hook (new school way, made for function components). The useStaticQuery is much cleaner and simpler to use, so let's do an example with it.

import React from 'react'
import { useStaticQuery, graphql } from 'gatsby'

const Header = () => {
  const data = useStaticQuery(graphql`
    query {
      site {
        siteMetadata {
          title
                    description
        }
      }
    }
  `)
  return (
    <header>
      <h1>{data.site.siteMetadata.title}</h1>
            <h3>{data.site.siteMetadata.description}</h3>
    </header>
  )
}
export default Header

Accessing data in a non-page component, using the useStaticQuery hook

Using this hook isn't much different than the page query, the only difference is the data is retrieved as part of the component itself.

Now that you know the difference between the two types of queries, which should you use? Page queries are easier to spot. But 'building block' components are a bit trickier. When you create a new component that needs data and is not just presentational, ask yourself where the data is coming from.

Page queries actually cover most cases because you can pass down the queried data to your reusable components. The only time you should use a static query is if the component should always use your site's data independently of any page. A good example is your site's title or any site-wide configuration you set. Using static queries this way helps isolate data querying to the spot it's actually needed (in that building block component) and modularize your site (consumers of the component don't need to know data querying is happening).

Take the Header component above for example; the header of our site will never change - it will always have the title and description of our site. It's page independent! As such, we use useStaticQuery to get the data, and now all consumers of the Header component don't care about its internals; developers just use the component and it works.

Plugins

In the data layer section we configured the gatsby-source-filesystem plugin. But what are Gatsby plugins even for? There are two core reasons for the plugin system:

Modularity. Even though our example sources data from the filesystem, many other Gatsby-powered sites don't need that functionality. They either source from a CMS, a database, or don't source data at all.
Unified interface. Gatsby is an open source web framework made of many other technologies, like React, webpack, and babel. Customizing and optimizing your site yourself is a long process and oftentimes is cognitive overload; plugins provide enhancements to the underlying technology for us and provide an easier interface to customize each plugin via gatsby-config.js.

Gatsby provides official plugins, like gatsby-source-filesystem, and also has community plugins written by open source developers in the Gatsby community. The rest of this blog post will be covering the plugins you need for optimal image processing.

One note on plugins, you'll notice I highlighted the data layer's sourcing and transforming of data in the data layer section. That is because those terms are directly related to certain plugins in the Gatsby ecosystem: plugins used to source data into the data layer are named gatsby-source-<whatever_source_here> and plugins used to transform data while in the data layer are named gatsby-transformer-<whatever_file_format_here>.

Examples of source plugins:

gatsby-source-filesystem - source data from the filesystem
gatsby-source-contentful - source data from the Contentful CMS
gatsby-source-pg - source data from your PostgreSQL database
gatsby-source-graphql - source data from other GraphQL APIs

Examples of transformer plugins:

gatsby-transformer-json - transforms .json files into JavaScript objects
gatsby-transformer-csv - transforms .csv files into JavaScript arrays
gatsby-transformer-remark - parses and transforms .md files
gatsby-transformer-sharp - transforms ImageSharp nodes into optimized image objects. More on this soon!

Sharp

Now that we know about Gatsby's data layer and plugin system, let's add image processing to our Super Sophisticated™ site. Sharp is a Node.js image processing library that Gatsby uses for its plugins. It resizes and compresses images, as well as converts them to web-optimal formats (WebP and AVIF).

Since we are sourcing data from the filesystem, we don't need to worry about getting our images into the data layer. We do need to add Sharp image processing, so let's add and configure two new plugins:

export default {
    ...
    plugins: [
        {
      resolve: 'gatsby-plugin-sharp',
      options: {
        defaults: {
          placeholder: `blurred`,
        },
      },
    },
    'gatsby-transformer-sharp',
        // any other plugins
    ]
}

Adding the Sharp plugins in to our gatsby-config.js

gatsby-plugin-sharp adds the low-level Sharp capabilities to our system. You can think of it like adding the sharp NPM package to our project, but we haven't actually used it yet. This plugin is where you will configure the actual image processing options to your liking; you'll notice that I configured the default placeholder to be blurred. I'll touch on that in the next section more when we talk about responsive images.

The gatsby-transformer-sharp plugin is the Gatsby transformer to allow the images to be usable in Gatsby. After the data is sourced into the data layer, this plugin will leverage Sharp image processing to provide you with optimized images. This is where we actually use the capabilities from gatsby-plugin-sharp (making gatsby-plugin-sharp a pseudo peer dependency in NPM terms).

Gatsby Image Plugin

The last piece of the Gatsby image processing puzzle is the relatively new gatsby-plugin-image. After installing and configuring the plugin, it leverages the two Sharp plugins we installed in the previous section and gives us responsive images. Responsive images solve two problems with image loading on the web: the art direction problem and the resolution switching problem.

If you're curious about these topics, look out for the future blog post on web optimized images. In the meantime, let's see how Gatsby makes including responsive images as easy as importing and using a React component.

StaticImage

gatsby-plugin-image gives us two core components to use in our site: StaticImage and GatsbyImage.

The StaticImage component has two required props. Both are standard props on HTML img tags: src and alt. Using StaticImage is for images that never change and are known before build time. This is strictly enforced by this component, as you can only pass an absolute path, a relative path, or a local variable that resolves to a path to the src parameter. You cannot pass props from other components into src. Actually, you can't pass any props from other components into any props on this component at all! This is a static image, so absolutely no dynamic data is allowed.

A good example of an image to be used for StaticImage is your hero asset, or any design assets throughout your site. They are never going to change (unless you redesign your site), so referencing them directly by path for StaticImage makes sense over importing them as JavaScript modules.

import React from 'react'
import { StaticImage } from 'gatsby-plugin-image'

export default function MyStaticImage () {
    return (
        <StaticImage
            src="../static/img/hero90em.png"
            alt="Hero Giant"
        />
    )
}

StaticImage usage. Both src and alt are required

GatsbyImage

Tying everything we've covered in this blog post gives us the GatsbyImage component. This is the component you will use for dynamic images that are determined at build time. The order for the images used by this component are as follows:

Sourced into Gatsby's data layer (by gatsby-source-filesystem, in our example)
Transformed and optimized (by gatsby-transformer-sharp and gatsby-plugin-sharp)
Accessed via a GraphQL query (either as a page query or a static query)
Converted to responsive images (by gatsby-plugin-image and this component)
Used in your JSX & generated HTML

Because GatsbyImages use dynamic data from the data layer, we are able to pass in any props we want. This is desirable for setting up a blog because we can create a template for a blog post and then pass in the appropriate content to the template at build time and create as many blog posts as we want.

There are several helper functions to use as well, but the main one you will use is getImage. Since the returned data from the data layer is from gatsby-transformer-sharp, it will be in a childSharp object and in sharp format. The getImage helper will take that object, and return to us the data correctly to be used in GatsbyImage.

Let's see this in action, using an image file named dynamic-test.png:

import React from 'react'
import { useStaticQuery, graphql } from 'gatsby'
import { GatsbyImage, getImage } from 'gatsby-plugin-image'

export default function MyGatsbyImage () {
    const data = useStaticQuery(graphql`
          query ImageQuery {
            file(
                    ext: { eq: "png" },
                    name: { eq: "dynamic-test"}
                ) {
                    childImageSharp {
                        gatsbyImageData
                    }
                }
          }
        `)

    return (
        <GatsbyImage
      image={getImage(data.image.childImageSharp.gatsbyImageData)}
      alt="Dynamic Test Image"
    />
    )
}

We need to query for data to use GatsbyImage. Using the helper getImage, we are able to pass the correct data to the component after our GraphQL query against the data layer.

Shared props & options

StaticImage and GatsbyImage have different props for setting the image (src for StaticImage, and image for GatsbyImage), but most of their props are shared. The props for these components are mainly about styling the images, especially as they are loaded.

Easily confused with props, there are also options for these components. All the options are shared between the two components, but there are two differences in how the options get applied to StaticImage and GatsbyImage. Remember the core difference between the two components (one is completely static, one is dynamic) and those differences will make a lot of sense.

One option I want to highlight is the placeholder option. This option controls the initial placeholder for the image when the page is first loaded, until the image fully loads. The user should see this for only a second at most (hopefully), and then the full image will replace the placeholder.

In the Sharp section, I explicitly set this option to blurred. The default for this option is dominantColor, which I think is the worst value besides none. dominantColor analyzes the image to figure out which color is most prevalent, and then the entire image dimensions are filled with this color. To me, seeing a giant block of black, red, green, or whatever color is determined is very noticeable. It's even more noticeable when the block disappears and your image is put in - it's jarring, to say the least. This is why I'm a fan of blurred. Instead, a low-resolution, blurred out version of the real image is used. When the real image is loaded, it feels like a much more natural transition.

Summary

By now, you should have a great understanding of Gatsby's image processing, and more importantly, the data layer and plugin system that underpins the entire Gatsby ecosystem. Even if you don't understand the optimizations applied to your images, you are able to get the most out of them through your knowledge of Gatsby and this incredible framework. If you have any comments, questions, or image optimization tips you'd like to share, we'd love to hear from you at developers@useanvil.com.

Lastly, if you'd like to see the gatsby-config.js all together for our Super Sophisticated™ example, check it out below. It includes plugins we did not explicitly go over, but are needed to build our technical blog website.

Let's continue to build the web fast for all ⚡️

const path = require('path')

export default {
    siteMetadata: {
        siteName: 'Super Sophisticated',
    title: 'The most sophisticated business',
    description:
      'Reduce costs and unlock growth by transitioning from paper and PDF-based processes to simple and flexible online workflows.',
    keywords: 'website,sophisticated,super,gatsby',
    },
    plugins: [
        'gatsby-plugin-resolve-src',
        {
        resolve: 'gatsby-source-filesystem',
      options: {
        path: path.resolve('src/markdown-articles/blog-posts'),
        name: 'blog-posts',
      },
    },
        {
      resolve: 'gatsby-plugin-sharp',
      options: {
        defaults: {
          placeholder: `blurred`,
        },
      },
    },
    'gatsby-transformer-sharp',
        'gatsby-plugin-image',
        {
      resolve: 'gatsby-transformer-remark',
      options: {
        plugins: [
          'gatsby-remark-autolink-headers',
          'gatsby-remark-images',
          'gatsby-remark-copy-linked-files',
                    'gatsby-remark-prismjs'
        ],
      },
    },
    ]
}

Final gatsby-config.js for our technical blog site

Consuming GraphQL APIs for REST-minded Developers

Anvil Engineering — Fri, 14 Jan 2022 20:11:00 +0000

If you've been developing against APIs for more than just a few years, I'm willing to bet that you've encountered and used RESTful-style APIs. Why am I so confident? Because REST has become the de-facto standard, most commonly used style of API on the web today. Even though REST is great and has become ubiquitous, it's not without a few challenges and shortcomings:

Under-fetching data you need
Over-fetching data you don't need
Many endpoints - usually 1 for each resource type
Related data requires multiple calls
Difficult discovery and auto-tooling
...and more

To solve these and other issues, GraphQL was developed by Facebook starting in 2012. It was originally internal-only, but was open-sourced in 2015 and since then it has gained immense popularity. A recent study indicated that it is used in nearly 20% of all organizations with an API. This may not sound like a lot—especially when compared to REST's roughly 82% usage rate—but another study shows that developers' experience with GraphQL grew from around 5% in 2016 to nearly 40% in 2019. That's some solid growth, and Anvil has contributed to those statistics. While we have some RESTful APIs, we rely heavily on GraphQL for the majority of our exposed capabilities.

Yet despite the significant and rapidly growing share of GraphQL APIs out there, some developers who are used to RESTful APIs have yet to use it, and some are reluctant to try and learn it. I'm here to show you that consuming a GraphQL API is really nothing to be afraid of, and it’s something that any developer can figure out the basics of.

GraphQL Background / Primer

First off, if you have no idea what GraphQL is about and what it feels like, I'd like to suggest a few things:

Read this article to help gain a reasonable background on what GraphQL is all about.
Try playing around with some live queries in this online demo to get the feel for how things actually work. Take note of how you can traverse the relationship graph of objects from the root object, retrieving nested/related objects of your choice. Also notice how you can request as much or as little information as you want from each of those objects.

Hopefully after familiarizing yourself with some basics of interacting with a GraphQL API, you realize that for simple queries it's very straightforward. Here's a quick cheat sheet on what you need to know:

Instead of multiple "endpoints" that you might have in a REST API, a GraphQL API has just a single endpoint, but additionally defines and exposes any number of Queries (for read operations) and Mutations (for insert/update operations). These operations are hopefully given helpful, descriptive names like invoices or updateUser, etc.
GraphQL is all about Types, and each operation will normally return an object of a specific Type. These Types include some basic Scalars like Int, String, Boolean, but custom Types built from scalars or even other custom Types can also be defined - think User, Organization, Invoice, etc. These custom Types typically are objects that contain 1 or more Fields, each of which has a Type.
Field definitions not only require a Type specifier, but they also can have a few modifiers:
- !: A non-nullable (i.e. "required") value can be indicated with a !. E.g. name: String!.
- [<Type>]: An array of values can be indicated by surrounding a Type in brackets. E.g. names: [String].
- These 2 modifiers can be combined arbitrarily, for example to indicate "an array of non-nullable Strings" (e.g. names: [String!]). Or to indicate "an array of non-nullable Strings, which itself cannot be null" (e.g. names: [String!]!).
The last big thing to mention is that GraphQL supports Arguments for Queries (e.g. the invoice query expects an invoiceId argument), Mutations (e.g. the createUser mutation expects name and email arguments) and also Fields (e.g. the addresses field on a User type may accept a country argument for filtering).

And with that, while there are definitely more advanced things one can learn about GraphQL, you should be armed with enough knowledge about the GraphQL spec to understand how to use and consume most GraphQL APIs.

Request Shape

Hopefully by now you're no longer mystified by interacting with a GraphQL API, and are starting to see some of the advantages of it. All that's left to do now is actually write some code that consumes one! GraphQL is so popular that there are client packages available in every popular language like Node, Python, Ruby, Java, Go, and more. Chances are that whatever language you're using to consume REST APIs has a library to make it easy to consume GraphQL APIs.

If you're unable (or unwilling) to add more dependencies to your code base, or you'd just like to "roll your own" client for whatever reason, I'll show you some examples of how easy it is a bit later on. What I hope you'll realize is that at the end of the day, a GraphQL API call is just a POST request to the server's GraphQL endpoint with a JSON payload consisting of a few key/values:

query: A string containing the query or mutation you'd like to execute.
variables: A JSON object whose keys match the name of any variables used in your query, and whose values are the values for the server to use for those variables.

Most servers will even let you send those key/values as query params to a GET request if you really want to for some reason.

The response should come with a 200/OK status (even when there are errors), with a content-type of application/json and have the following JSON structure:

errors: An array that should be present and populated only if there were errors encountered. The elements in the array should provide details about what thing or things went wrong. As noted above, the server response will still be 200/OK even if there are errors.
data: A JSON object containing the result of your query or mutation operation.

Sample Code

Hopefully this sounds easy so far, but let's see how it looks in code. Let's say we have a relatively simple User query that looks like this:

query User($id: Int!) {
  user(id: $id) {
    id
    email
  }
}

And let's say that the $id variable will be the integer 42.

The expected response would look like this:

{
  "data": {
    "user": {
      "id": 123,
      "email": "foo@bar.com"
    }
  }
}

Here are some examples of how to execute this query in different languages - I've left out the authorization header for simplicity:

curl

curl -X POST 'https://example.com/graphql' \
-H 'Content-Type: application/json' \
-d '{"query":"query User(id: Int!) { user(id: $id) {id email} }", "variables": {"id": 42}}'

python

# Every project will have a dependency like this if it's making HTTP requests
import requests
import json

data = {
  'query': 'query User(id: Int!) { user(id: $id) {id email} }',
  'variables': { 'id': 42 }
}

headers = { 'Content-Type': 'application/json' }

body = requests.post(
  'https://example.com/graphql',
  data=json.dumps(data),
  headers=headers
).json()

Node/JavaScript

// Every project will have a dependency like this if it's making HTTP requests
import fetch from 'isomorphic-fetch'

const res = await fetch('https://example.com/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: '{"query":"query User(id: Int!) { user(id: $id) {id email} }", "variables": {"id": 42}}'
})

const body = await res.json()

Ruby

require 'uri'
require 'net/http'
require 'json'

uri = URI('http://localhost:3000/graphql')
res = Net::HTTP.post_form(uri, 'query' => 'query {currentUser{id email}}', 'variables' => { 'id' => 42 }.to_json)
body = res.body

PHP

$url = 'http://localhost:3000/graphql';
$data = array('query' => 'query {currentUser{id email}}', 'variables' => array('id' => 42));

$options = array(
  'http' => array(
    'header' => "Content-Type: application/json",
    'method' => 'POST',
    'content' => json_encode($data)
  )
);

$context = stream_context_create($options);
$result = file_get_contents($url, FALSE, $context);

Summary

So there you have it! In my opinion, there's nothing mystical or particularly challenging to using GraphQL APIs - they're easy, efficient, and pretty fun/awesome. Admittedly, I kept the examples rather simple, and there are far more complex things that can be done with GraphQL (for example, trying to upload binary files can be a bit tricky), but for many APIs this is more or less all you need to know. So don't be afraid when you hear that an API is GraphQL - it's only some basic REST-like calls under the covers. Happy coding!

Techniques to optimize react render performance: part 1

Anvil Engineering — Wed, 15 Dec 2021 20:43:58 +0000

Improving performance is an art. To me, chasing performance issues feels like it flexes the same muscles as debugging. You're wading into the unknown with only a sliver of information. But instead of understanding why it does that one weird thing, you're asking adjacent questions: Where is it slow? Why is it slow? Then of course, How can it be improved?

This post will be the first in a series outlining how I approach improving performance, specifically for laggy UIs built with React. Even though this will mention tools and techniques specific to React, a fair amount of this would transfer to general-purpose optimization work. No matter the environment or tools, I'm trying to answer the same questions.

So, you have a UI that feels slow. Where do you start? This post will cover two big chunks of the process of optimizing React performance:

Tools
Where is it slow?

In a future post, we'll cover the other half of optimization: React pitfalls and techniques to actually improve performance of your UI.

I'm starting with tooling and the "where" because, like debugging, the hard part is in really understanding what’s going on and what should be improved. I often find that the actual solution to speed up a UI is a couple of small changes. I can't tell you how many times an ill-placed splat or anonymous function passed as a prop has made a UI unusable. Fixing these issues was only possible by understanding which parts of the code needed optimization.

Tools

There are a few browser tools you can use to help you understand where to optimize. Specialized tools aren't the end-all, though. In my experience, they almost never straight-up point out a performance issue. But they can give you a general direction to answer "What is slow?" and tell you how much time something takes.

DevTools profiler

Chrome has a profiler in the dev tools' Performance tab. The profiler can help point out that obvious case where you have a super slow function, or when you are calling a function too many times. Usually it'll show the lowest hanging fruit.

First, start up a profile by opening up the dev tools and clicking record.

Do your slow action, then click stop. It will show you a summary like this.

To me, the most useful tab is "Bottom-Up". It will show you which functions took the most time. Since we are focused on JavaScript performance in this post, I'll drag my mouse over the yellow chunks of the timeline, which show JavaScript performance concerns, then select the "Bottom-Up" tab:

Select the Bottom-Up tab in the 2nd level tabs

Oh hey, a slow function. Lucky us!

Self Time will tell you how much time was actually spent in this function. You can see that slowFunc() shows the most "Self Time", so it likely does a bunch of additional processing within its function boundary. That is, it's not calling some other slow function, it is slow itself.
Total Time tells you how much time was spent, including time calling slow child functions. Basically, if this is high and "Self Time" is low, this function is calling a slow function somewhere down its call tree. You can see the 4th line, render(), has a high "Total Time", but a low "Self Time". It does very little itself, but calls something slow: slowFunc().

You can also dig into the call tree with the carets. By opening slowFunc(), you can see that it is called by render(). If multiple functions are calling slowFunc(), there will be more than one line here.

For reference, our contrived slowFunc() example is the following: render() calls slowFunc() directly.

function slowFunc () {
  for (let i = 0; i < 100; i++) {
    console.log('Hello', Math.random())
  }
}

const SlowComponent = () => {
  slowFunc()
  return "I'm slow :("
}

const App = () => (
  <>
    <SlowComponent />
    <SlowComponent />
    // 100 more SlowComponent renders
  </>
)

This is an extremely simplified case. The obvious solution is to not call slowFunc() here. But what if it is doing necessary work? The real world is often much messier.

JavaScript profiler

Instead of opening the Performance tab and clicking Record, you can programmatically generate performance profiles for later viewing. This is useful if you want to capture a very specific part of the code. For example:

console.profile('The slow thing')
doTheSlowThing()
console.profileEnd('The slow thing')

It works similarly to the "Performance" tab, but In Chrome these show up in a different part of the dev tools: ... -> More tools -> JavaScript Profiler

How to access the JavaScript profiler

And it shows your generated profiles:

Our slowFunc profile in the JavaScript profiler

React profiler

There is yet another profiler, one specifically for React. React developer tools is a Chrome browser extension written by Facebook.

Once it's installed, you will get a new tab. Just like the JavaScript profiler, you can record profiles.

React developer tools profiler in chrome

Click record, do your slow action, click stop, and you'll get a breakdown of which components rendered and how much time they took.

React developer tools flame graph

The profiler breaks down your profile into "commits"; see the chart in the top right of your profile. A "commit" is when React actually applies your rendered components to the DOM. Note that a commit may contain multiple render calls for a given component! In the above screenshot, it's possible Container has been re-rendered 10 times.

Click on the tallest peak in the commit chart and you will see the slowest renders.

This profiler has its own concept of Self Time and Total Time shown in each horizontal bar. For example, in 1ms of 100ms, 1ms is the self time; the time that was spent rendering this component, and 100ms is the total time; the time spent rendering itself and all its children.

You can see I have a lot of components rendering each time I do my slow action. Each one of them takes only a few milliseconds, but it adds up!

console.log()

Let's be honest, logging is probably the most widely used (and dare I say, useful) debugging tool ever invented. It might feel low-tech, but well-placed logging can play a central role in performance optimization. It can be a super fast way to check parts of the code, which we'll get into later in this post. For example:

const start = performance.now()
doSlowOperation()
console.log('Time to do slow operation', performance.now() - start)

This example is a little basic, but it becomes more useful when your start and stop points are asynchronous. For example:

class MyComponent extends React.Component {
  handleStartSlowOperation = () => {
    this.startPerf = performance.now()
    kickOffSlow()
  }

  handleSlowOperationDone = () => {
    console.log('Time to do slow operation', performance.now() - this.startPerf)
  }

  render () {
    // ...
  }
}

Where is it slow?

Let's dig into how to actually find where a laggy UI is slow. I spend a fair amount of time trying to understand where it is slow, as it makes the fixing part significantly easier.

I start by picking an operation that represents the slow condition. Say load up your UI with a lot of data, then type into that slow input box, or click that slow button. The more quickly repeatable the scenario, the better. Can you repeatedly type into the slow input box and have it feel slow? That's the best scenario.

My examples will be based on an optimization in Anvil's webform builder. For context, our webform builder is a piece of our Workflows product. Clients create custom sharable webforms in the builder by adding and modifying input fields. Clients can use the webforms they build to collect data from their users. Once the user has filled out the webform, our clients can use the data from the webform to fill PDFs and gather signatures.

We recently optimized rendering when there were a lot of fields on a webform page. e.g. our client creates a webform page with 100 input fields.

Anvil's webform builder

In our example case, it will be typing a single character into the label field in the left panel. When you change this label value, it will change the selected input field's label in the right panel. There was a noticeable lag when changing a field's label on a webform with many fields.

Changing an input field's label can feel laggy

With my slow operation chosen, I get to tracking down the slowest parts of the code within that operation. You might be thinking, "I mean, it's slow when I type into the slow input box". But where where is it slow? That one keystroke might trigger hundreds of components to re-render or several expensive operations to run, maybe even a number of times.

The first goal is to isolate what is slow, down to some function(s) or part of the DOM tree.

Profiling

The profiling tools mentioned above will be the most help in this "Where" stage of optimization. I follow mostly the same process each time I am tracking down inefficiencies in a slow UI.

First, I use the DevTools profiler mentioned above. Usually it can help point out any obvious slowdowns.

1. If a function in your codebase shows a high "Self Time", that is a good candidate for optimization. It's possible it's getting called a ton, or it's just plain inefficient.

Note that the Self Time is high here

2. If a non-React 3rd party library function shows a high "Self Time", likely something is calling it too often. For example, I added this snippet to the our webform Field component's render function:

for (let i = 0; i < 10; i++) {
  _.uniq(_.times(10000))
}

You can see lodash functions at the top of the list:

Something is calling a library function too often

The trick here is to drill down into the call tree for each of these items and figure out exactly where in your code base this is being called, how often, etc. It's easy to blame a library function for being slow itself, but in my experience the issue is almost always with how it's being used in our own codebase.

3. If the profiler shows mostly React library functions at the top of the "Bottom-Up" list, then some component is slow to render, or is being rendered too many times.

All react all the way down

If you see this, it's time to dig into the React profiler. Here is the same action in the react profiler:

Dig into the React profiler

You can see the slow render is made up of a ton of other component renders. Each of these renders takes up only a few milliseconds, but it adds up to a lag.

The above React profile is from the webform editor example; it looks like every keystroke is causing a re-render of all fields, even for fields whose label isn't being updated.

In my example case, I now have a basic direction: look into the component that is rendering all those fields.

Establish a baseline

The next thing I like to do after having some direction from the profiling tools is to figure out how much time my specific action is taking now.

I've found relying on the profiles for this info isn't so precise. Profiling can also impact the performance of the action you're taking. I want to see a number that is pretty consistent run-to-run and keep the action's real world feel. Instead of profiling, I like to add logging around the slow action. Having a consistent number run to run can show you how much it improves as you change code.

It can be challenging to exactly wrap your action in React. When dealing with rendering performance, it often involves using the componentDidUpdate func. In my case, it will look something like:

class Editor extends React.Component {
  handleKeystroke = (event) => {
    this.startTime = performance.now()
    this.lastChange = {
      label: event.target.value,
      index: event.target.index,
    }
    this.props.onChangeLabel(event)
  }

  componentDidUpdate = () => {
    const lastChange = this.lastChange
    if (this.props.fields[lastChange.index].label === lastChange.label) {
      console.log('Keystroke millis', performance.now() - this.startTime)
    }
  }

  render () {
    // ...
  }
}

This doesn't need to be pretty code, it's temporary

Pressing a keystroke in my example, I can now see how much time is being spent between pressing the key and rendering.

This is my baseline: around 1000ms. You can see here that it's actually being rendered twice on a change, not ideal.

My baseline for my slow keystroke operation

Delete

At this point, after profiling and creating a baseline, it's possible you have a really good idea of exactly what is slow. If so, that is awesome, and you can probably stop to improve the slow parts.

In complex code bases, however, things might not be very straightforward. It may not be clear which part of the render function is slow, what is causing all the re-renders, or which components shouldn't re-render. If you're looking at, say, a slow data-transformation function, it helps to know exactly which loop or operation is causing the pain.

A lot of times, once I have a baseline, I employ another extremely high-tech technique to narrow the path further: deleting code. I'm trying to answer: How fast could it be? Where exactly will make the biggest impact?

In the case of my example, the react profiler shows a lot of renders for each field.

Each input field is being re-rendered on a change to one field

Here, rendering could possibly be improved by either re-rendering fewer Field components, or optimizing the render method in each Field component. Intuitively, it feels like the best option is just to render fewer components here, but we won't really know until we try and note the change in performance.

The process is very much the scientific method: have hypotheses, then quickly test them. The UI doesn't even need to be totally functional during this process; this just gives you an idea of where you should spend your time.

For our example: how long does the action take when we do basically nothing in each Field component's render func? We still render all field components, but each does the absolute minimum: only render an empty div in the Field render function. How much does that impact the total time?

const Field = () => <div />

The parent renders 100 Fields that are just divs

An order of magnitude improvement, great!

Now, is the issue the rendering of the children itself, or building the props? We can test this by still rendering all fields, building the props to render children, but only rendering the div.

const Field = () => {
  // Is props setup slow?
  const fieldInfo = buildFieldInfo()
  return (<div />)
}

The parent renders 100 Fields that build props, then render divs

Back close to 1000ms, not great. It seems the actual rendering is less of an issue and now we know building the props could be a place to dig in.

Let's look into only rendering a single component on change. We can first return false from shouldComponentUpdate. shouldComponentUpdate is a React lifecycle function that allows you to control when something re-renders. Returning false from it will tell React to render the component only once (initially), then never again. This will tell us how much it takes to render the parent on a label change.

I'll dig more into shouldComponentUpdate in the next post in this series.

class Field extends React.Component {
  shouldComponentUpdate (nextProps) {
    return false
  }

  render() {
    const fieldInfo = buildFieldInfo()
    return (<TheFieldComponents {...fieldInfo} />)
  }
}

None of the 100 Fields re-render on a label change

Ok, it's reasonably fast.

Next, I can add a dirty check to shouldComponentUpdate. This check might not be totally correct, but we can simulate what it looks like to only render the changed field. Note that we are doing a full render in the Field component's render func, instead of just rendering a div like in other examples.

class Field extends React.Component {
  shouldComponentUpdate (nextProps) {
    return this.props.field.label !== nextProps.field.label
  }

  render() {
    const fieldInfo = buildFieldInfo()
    return (<TheFieldComponents {...fieldInfo} />)
  }
}

Only the changed Field re-renders on a label change

Fully rendering only the changed field, even though it is less-than-efficient when building props, is about 105ms.

In the React profiler, we can see my change only renders the affected fields. Note all the greyed out components under styled.div:

The greyed out components did not render

Analysis

After profiling and strategically deleting code in my example, I have direction as to where I should spend my time.

Remember, we were typing a single keystroke to change the label for a single field in a large list of fields.

Our example: type a character into the label field here

The experimentation has given me a pretty good idea of the shape of performance behavior:

On changing a label with a single keystroke, it's rendering all input Field components in the webform twice. Does it need to?
It's rendering all input Field components on changes that do not necessarily affect all fields.
It is possible to be fast rendering all fields, but building the props to render a single Field component is a bottleneck. This doesn't seem to be a huge problem when only one field changes, but it could be a big deal for changes that do affect all fields, or initial render.

Since typing a single keystroke was the initial problem, my approach would be to first get excessive re-rendering under control. Clean up the double renders, and only render the changed Field component. Then if there was time, I would dig into fixing props-building for each Field render.

Going through the exercise of understanding what is slow has also given me some ballpark numbers.

I now know I can reasonably shoot for ~80-100ms for a change that renders a single field; the parent component takes up about 70ms.
Rendering all fields in ~100ms isn't out of the question. If I can make building props for a single field more efficient, I can likely get close.
Typically when typing, animating an element on a user action, or other things that run 'in band' of user input, you need to finish all work within a ~16ms window (60 frames per second) to avoid the user feeling a lag. It appears that fitting into this 16ms is out of reach for our example keystroke.
- The work we are doing in the example doesn't necessarily need to happen on every keystroke. There are techniques like debouncing, which will keep user input feeling fast, then does the work once the user is finished typing. I will dig into debouncing and other techniques that can help us solve this in the next post.

Next up: improving performance

Now you have some tooling and approaches for tracking down the slow parts of your code. In the next post, we'll cover React pitfalls, understanding React re-renders, then techniques to actually fix performance issues in your UIs.

Have feedback on this post? Or are you developing something cool with PDFs or paperwork automation? Let us know at developers@useanvil.com. We’d love to hear from you!

Introduction to the Twelve-Factor App Part 2

Anvil Engineering — Wed, 08 Dec 2021 21:14:25 +0000

12 Factor App Blog Post Part 2

Summary: Make your toy web apps more robust and manageable by following the Twelve-Factor App methodology.

This is the second part in a series of posts detailing the 12 Factor App. In the last post we looked at:

Your codebase and made it deployable across different environments
Dependencies and why they’re important in reproducibility
Configuration files and how to make them useful across different environments
Backing services, what they are and how decoupling gives your app more flexibility

If you need a refresher or aren’t familiar with the above already, take a look at the last post. Many of the earlier concepts are used as building blocks for the concepts in this post.

V. Build, release, run

Strictly separate build and run stages - https://12factor.net/build-release-run

Many of the previous sections finally start coming together here. This may be one of the more time consuming sections or steps, but also the one that will improve your development and release cycles tremendously. These steps are also what people usually refer to as Continuous Integration/Continuous Deployment, or CI/CD. Let’s step through from the start.

Build:

In the build step, the goal is to get all code and assets into a usable state at the run step. The end product can differ depending on whether you’re building for development or for production. In a development environment, for example, we could skip optimizations such as compressing files and compiling frontend assets (HTML/CSS/JS) into bundles that would normally live in a CDN.

In general, the build step can look like the following:

Pin your release on a specific commit or tag, if using git (Factor I). This keeps everything at a known starting point.
Start compiling your code. This depends on the codebase, but in general, this would be:
- Gather all the app’s dependencies (Factor II) via npm, PyPI, git clones, etc.
- Compile code where needed. This could mean using a bundler like webpack, or compiling binaries and libraries like Java .jar files.
Log all build processes running.
Build process should have a mechanism to keep track of attempted builds -- whether or not they were successful.
If any of the above fails to complete, stop the entire build-release-run process and send notifications or some sort of message to the developer about the failure.

Release:

In the release step, the main product of the release step is to have your compiled and built code ready to run, publish, or use for the end-user in some way.

The release process can look like the following:

Apply config specific to this build’s environment (Factor III).
For example, a development environment can point to a database running on a cheap server instance, while a production version would point to a much more robust version on Amazon RDS with backups enabled.
Run your tests! This would include unit, integration, and end-to-end tests. These tests would run against the compiled build and with the proper config applied. If any tests fail, we could immediately cancel any further actions and send out notifications/messages about the failure.
Any other preparations you need before getting to the run phase.
If using Docker, this is when you would create an image of all the parts of your application that you want deployed. This image is a snapshot of the application code where you know all tests have passed and the build process ran successfully.

Run:

At this point, all the previous steps should have given us high confidence that your application will work as expected. We’ve compiled and prepared all code and assets, ensuring that the application is set up correctly and does not have any build-time problems. We’ve tested the application itself with run-time tests, and maybe even end-to-end tests. Now all we have to do is just deploy the thing.

The Run step should be fairly straightforward. We’ll be assuming you’re using Docker, or some other containerization tool:

Upload your Docker image(s) from the release step to your code’s final running destination.
Run your application.
Notify/message any other external services that your application is up and running.
If scaling to multiple instances, there are infrastructure considerations that need to be made. You would need a load balancer like nginx or HAProxy. Some cloud services also handle this automatically like Amazon ECS, so double check with your provider docs as well. At the higher end of complexity, much of this can also be handled with Kubernetes, but that in itself would require more than a few blog posts to introduce.

The build-release-run workflow is very well-supported on platforms like GitHub and GitLab with GitHub Actions and GitLab CI/CD, respectively. You can also customize your own build process with tools like Jenkins and CircleCI. When using those services, the build and release steps are covered, but the run step will require a container hosting service such as Amazon ECS. There are also services that encompass all the steps such as Heroku (which developed this 12 Factor methodology).

At this point, we actually have a running app. We could stop here, but we have millions of users to take care of and the application needs to scale easily!

VI. Processes

Execute the app as one or more stateless processes

This section is mainly how to think about your application processes in the context of scaling. At its simplest case, we can think of a single-purpose application that resizes images. This application would get image data, resize it, and finally upload it to a cloud storage service like Amazon S3.

For this application, we have no shared state from other processes. We can even imagine 10s or 100s of instances of these running independently in parallel. They all don’t require any additional context data nor do they need to share data. They only need an input (image data) and they return an output (successful upload to S3).

What’s the key aspect to processes?

Processes are stateless

That is, they don't expect data in memory or on disk will exist permanently. The easiest way to think about this is to ask: If the app were to be completely torn down and redeployed from a Docker image, would it be a catastrophic failure?

In a twelve-factor app, all the states that we need to persist (database, cloud storage, session data, etc.) are saved in backing services (Factor IV) that our app uses. These backing services are defined in our app’s config (Factor III) which has been applied in the release step of our build-release-run process (Factor V). The app itself should be highly recoverable if it goes down, and at the opposite end, the app should easily scale up to more instances.

This architecture will play a key role in a few of the next sections.

To be continued

This post covered sections V-VI of the Twelve-Factor App methodology. Hopefully, this has shown the interconnectedness of all the factors and how smaller efforts in your application architecture can build up to something that can scale and have more resilience.
Here at Anvil we follow many of these concepts in our development process and we believe that sharing our experiences helps everyone create awesome products. If you’re developing something cool with PDFs or paperwork automation, let us know at developers@useanvil.com. We’d love to hear from you.

Forem: Anvil Engineering

Converting your vanilla Javascript app to TypeScript

Step 0

Install TypeScript

tsconfig.json

Compile and fix errors

After compiling

IDE Support

Other tooling

Conclusion

Measuring React styled-components performance & best practices

Measuring performance

Best practices

Dynamic styling

Global styles

Summary

Introducing SpectaQL 1.0 - an even better way to autogenerate GraphQL API documentation

Why did we decide to do it? And why now?

Internal DNA based on JSON Schema and Swagger/OpenAPI

Simpler schema manipulation, and the creation of Microfiber

Increase customizabilty and reduce forking via "themes"

Summary

PurgeCSS & styled-components: Does It Work?

What is PurgeCSS and why should I care?

How PurgeCSS works

Styled-components

What's the diff between styled-components and PurgeCSS?

Quick note on PurgeCSS' comparison logic

Feature comparison: what about nested selectors?

Alternatives to PurgeCSS

PurifyCSS

UnCSS

If UnCSS is so accurate, why do we use PurgeCSS?

How to use both PurgeCSS & styled-components

CSS Frameworks

Set up PurgeCSS with Gatsby

Ant Design

Putting it all together

Manipulate and query GraphQL Schemas with ease using Microfiber

The Problem

Why "Microfiber"?

Getting started

Querying Your Schema

Modifying Your Schema

Summary

Techniques to optimize React render performance: part 2

Render less

Example: list of fields

Solutions

Pure components

Pure component pitfall: callback functions

Pure component pitfall: dynamic data in the render function

shouldComponentUpdate

Caching computed values

Using useMemo to limit re-renders

Caching computed values in class components

Consider your architecture

In practice: Redux

App state best practices?

Other potential solutions

Debouncing

Rendering very large lists of elements

You made it!

Understanding SEO and ways to improve it

Search engines: how do they work?

Increase crawl accessibility

Prevent crawling on irrelevant data

noindex directive

Return helpful HTTP status codes

Make indexing easy

Performance

Web accessibility

Mobile-friendly

Optimize images

Use simple and clear URLs

Provide useful content

Summary

Introduction to the Twelve-Factor App Part 3

12 Factor App Blog Post Part 3

VII. Port binding

Using `useMemo` to limit re-renders

`noindex` directive

The `static` folder