---
title: "GraphQL Code vs Schema First Development"
date: "2021-02-27T22:12:03.284Z"
description: "Comparison of using code-first and schema-first development for a GraphQL server in TypeScript"
image: "/code-first-vs-schema-first.jpg"
imageAlt: "Light and Water"
photographer: "Joshua Sortino"
photographerHref: "https://unsplash.com/@sortino"
---

Two main approaches exist for writing a GraphQL server: code-first and schema-first. This post will compare these two approaches and explain why I typically prefer the code-first approach.

## Schema-first Approach

With a schema-first approach, you start with the GraphQL SDL. For instance, you start in a `.graphql` file writing something like

```GraphQL
type Query {
  hero(episode: Episode): Character
}

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

type Character {
  name: String!
  appearsIn: [Episode!]!
}
```

Once you've settled on the data types and operation definitions, you need to write resolvers to tell the GraphQL server how to resolve the data declared in the schema. In order to achieve type safety in accordance with the schema, you would typically use GraphQL Code Generator's [Typescript Resolvers plugin](https://graphql-code-generator.com/docs/plugins/typescript-resolvers). Finally, you can implement the logic necessary to resolve the data and use the generated types to annotate the resolvers ensuring type safety.

## Code-first Approach

[Nexus](https://github.com/graphql-nexus/nexus) is what would typically be used for a code-first approach in TypeScript. Rather than specifying the schema in a separate `.graphql` file first, the source of truth for data types and operations lives in `.ts` files right alongside the resolver implementation. The same schema from the schema-first approach in Nexus would be

```ts
import { objectType, inputObjectType } from "nexus";

export const Episode = enumType({
  name: "Episode",
  members: ["NEWHOPE", "EMPIRE", "JEDI"],
});

export const Character = objectType({
  name: "Character",
  definition(t) {
    t.nonNull.string("name");
    t.field("appearsIn", { type: nonNull(list(nonNull(Episode))) });
  },
});

export const heroQuery = queryField("hero", {
  type: Character,
  args: {
    episode: arg({ type: nullable(Episode) }),
  },
  async resolve(root, args, ctx) {
    ...
  },
});
```

Similar to the schema-first approach, you still start by declaring the data types and operations and then filling in how to resolve them. You still do end up with an SDL file that you can feed to a GraphQL server implementation like Apollo, but it is a build artifact and not the original source of truth.

## Schema-first Advantages

Nothing in the above examples is particularly compelling for the code-first approach. Indeed, the first time I looked at Nexus, I thought it was a step backwards to something like vanilla graphql-js compared to the approach popularized by Apollo where you get to write the nice SDL. I still think the biggest benefit of the schema-first approach is that writing and reading the SDL is easier than the Nexus API. `appearsIn: [Episode!]!` is a lot easier to parse than `t.field("appearsIn", { type: nonNull(list(nonNull(Episode))) })`. As I've used nexus more, however, this disparity has decreased.

## Code-first Advantages

The biggest advantage of a code-first approach is that it allows for more dynamic schema creation. GraphQL's type system doesn't include generics, so you oftentimes end up with a lot of similar types when following conventions. Relay-styled pagination is the most common example in my experience. So many `*Connection` and `*Edge` types that only differ by what the `node` type is and the queries all have the same `first/after/before/last` arguments.

By moving our schema definition into the TypeScript realm instead of the GraphQL SDL realm, we gain the ability to use TypeScript to generate our schema. That means functions to abstract common patterns. Nexus actually includes a [connection plugin](https://nexusjs.org/docs/plugins/connection) that nicely implements relay-style pagination.

Instead of having to write SDL like this over and over

```GraphQL
type CharacterConnection {
  edges: [CharacterEdge!]!
  pageInfo: PageInfo!
}

type CharacterEdge {
  cursor: String!
  node: Character!
}

type Query {
  heros(
    after: String
    before: String
    first: Int
    last: Int
  ): CharacterConnection!
}
```

you get to write

```ts
export const herosQuery = queryField((t) => {
  t.connectionField("heros", {
    type: Character,
    async nodes(root, args, ctx) {
      // Return an array of Characters
      return [];
    },
  });
});
```

It is these types of common situations where the code-first approach really shines.

The other advantages are a simplified dev/tooling setup and colocation of types/implementation. While your server runs, Nexus automatically regenerates TypeScript types based on what is defined. So if I add an argument and save the file, it is quickly available in the `resolve` arguments. This developer experience is similar to what you can get with GraphQL Code Generator in watch mode, but you don't need another tool to do it. Moreover, the colocation of the type definitions and the resolve implementation prevents having to jump back and forth between files.

## Wrapping Up

Both schema-first and code-first approaches are viable for developing a GraphQL server. My preference at this point is to use Nexus and a code-first approach.


Comparison of using code-first and schema-first development for a GraphQL server in TypeScript

GraphQL Code vs Schema First Development

---
title: "Preact in the Shadow DOM"
date: "2020-11-22T22:12:03.284Z"
description: "Why and how to render Preact components into the shadow DOM"
image: "/preact-shadow-dom.jpg"
imageAlt: "Tables and Chairs in Shadows"
photographer: "Jonny Clow"
photographerHref: "https://unsplash.com/@jonnyclow?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText"
---

The [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) is typically associated with [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components), but its style encapsulation properties can also be useful on its own. Up until recently, React's event system presented problems in the Shadow DOM, but those issues have been [resolved in React 17](https://github.com/facebook/react/issues/10422#issuecomment-674928774). So while this post focuses on Preact since its small size is a good fit for the cases that style encapsulation is also useful, the same process will also work with React.

## Benefits of Shadow DOM

The main reason to use the shadow DOM is for style encapsulation. CSS rules do not cross the shadow DOM in either direction, although inherited properties are still inherited as usual (for instance, font-family, color, etc).

<iframe
  height="425"
  style={{ width: "100%" }}
  scrolling="no"
  title="Shadow DOM Example"
  src="https://codepen.io/TLadd/embed/preview/PoGoQeV?height=425&theme-id=dark&default-tab=js,result"
  frameBorder="no"
  loading="lazy"
  allowTransparency="true"
  allowFullScreen="true"
>
  See the Pen{" "}
  <a href="https://codepen.io/TLadd/pen/PoGoQeV">Shadow DOM Example</a> by
  Thomas Ladd (<a href="https://codepen.io/TLadd">@TLadd</a>) on{" "}
  <a href="https://codepen.io">CodePen</a>.
</iframe>

The above example demonstrates the style encapsulating properties of the shadow DOM.
The red box is in the normal light DOM and the purple box contents are in a shadow
DOM. Even though there is a style rule in the `index.html` file to set the background-color
of all buttons to red, it does not affect the button that is in the shadow DOM. Conversely,
the style set in the shadow DOM to set the color of all `p` tags to purple and `font-weight`
to bold does not affect the paragraph in the light DOM

For most apps, this sort of encapsulation is not necessary. Assuming you are in full control of all app styles, you can ensure the styles do not interfere. Style encapsulation can be incredibly useful, however, if you are building something that gets embedded onto host pages that you do not control. For instance the [Grow.me](https://www.grow.me/), [OneSignal](https://onesignal.com/) or [Intercom](https://www.intercom.com/) widgets (note that not all of them use shadow DOM). In these cases, the style encapsulation behavior the shadow DOM provides is very useful.

## Shadow DOM with Preact

Rendering Preact or React into the shadow DOM is pretty simple. The target element that the initial Preact render call attaches to just needs to be within a shadow DOM.

<iframe
  height="450"
  style={{ width: "100%" }}
  scrolling="no"
  title="xxExYJX"
  src="https://codepen.io/TLadd/embed/preview/xxExYJX?height=450&theme-id=dark&default-tab=js,result"
  frameBorder="no"
  loading="lazy"
  allowTransparency="true"
  allowFullScreen="true"
>
  See the Pen <a href="https://codepen.io/TLadd/pen/xxExYJX">xxExYJX</a> by
  Thomas Ladd (<a href="https://codepen.io/TLadd">@TLadd</a>) on{" "}
  <a href="https://codepen.io">CodePen</a>.
</iframe>

That's all there is to it.

## Caveats

For the most part, everything works normally. I have, however, come across a few cases that required extra consideration.

#### styled-components

By default, styled-components injects styles into the head node. When rendering components into the shadow DOM, this doesn't work since those styles can't cross the shadow DOM barrier. Luckily, styled-components provides a [StyleSheetManager component](https://styled-components.com/docs/api#stylesheetmanager) that allows customizing the target node that the styles are injected into. Setting the target to the root element inside the shadow DOM works.

#### Global Click Listeners

Click events still bubble out of the shadow DOM, but the events are [retargeted](https://polymer-library.polymer-project.org/2.0/docs/devguide/shadow-dom#event-retargeting) when observed outside of the originating shadow DOM. One case where this is particularly problematic is menu libaries that setup click listeners on `window` to determine if you click outside of the menu and automatically close it. The target ends up being the shadow DOM root when observed from the window event listener and that logic likely no longer functions properly.

## Comparison to iframe

For building apps that get embedded onto others' sites, iframes have long been the most common means of ensuring encapsulation. Typically a very thin script is loaded onto the page that is primarily responsible for initializing an iframe loads the app. One thing iframes get you that the shadow DOM does not is javascript encapsulation in addition to the style encapsulation. The hosting site could do any number of heinous to the global Javascript namespace and your app would continue to work fine unaffected.

The cost of that full encapsulation is a lot of overhead when it comes to interacting with the host site or perhaps other iframes if your embedded app requires multiple widgets. The [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) is great for cross-frame communication, but not having to communicate across frames at all is a whole lot less hassle. If your application doesn't demand the guarantees Iframe's provide, I think using the shadow DOM is preferrable.


Why and how to render Preact components into the shadow DOM

Preact in the Shadow DOM

---
title: "User-Defined Type Guards in TypeScript"
date: "2020-08-12T22:12:03.284Z"
description: "Explain what user-defined type guards in TypeScript are and provide examples of commonly needed ones"
image: "/type-guards.jpg"
imageAlt: "Red glove on a sign post"
photographer: "Gary Bendig"
photographerHref: "https://unsplash.com/@kris_ricepees?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText"
---

The [TypeScript documentation](https://www.typescriptlang.org/docs/handbook/advanced-types.html#user-defined-type-guards) defines a Type Guard as

> some expression that performs a runtime check that guarantees the type in some scope.

In practical terms, I think of a type guard as a function that tells TypeScript it is safe to assign a certain type to a value based on whether that function returns true of false. Type guards can help in situations you would otherwise have to resort to a type cast. Type guards are similar to a cast in the sense that the programmer is asserting they know something TypeScript can't deduce on its own, but they are safer since they come with a runtime check that should validate that the type assignment is safe.

## An Example

Let's say we have two interfaces

```typescript
interface A {
  a: string;
  b: number;
}

interface C {
  c: boolean;
  d: string;
}
```

and for some reason, we have a place in our code where the type of a value is unknown and we want to validate the data meets our expectation before passing the data along to the rest of our program. I find this situation often arises when I'm operating on data I don't have full control over, perhaps extracting data from a url or web storage, and I want to be really careful with it. Our goal is to verify that `value` below is of type A or type C and then pass it to the appropriate function.

```typescript
let value: unknown;

function callWithA(a: A) {}
function callWithC(c: C) {}

// Goal
if (isA(value)) {
  callWithA(value);
} else if (isC(value)) {
  callWithC(value);
}
```

`isA` and `isC` are the type guards that make this possible:

```typescript
function isA(value: unknown): value is A {
  if (typeof value !== "object" || !value) {
    return false;
  }
  return (
    typeof (value as Record<string, unknown>).a === "string" &&
    typeof (value as Record<string, unknown>).b === "number"
  );
}

function isC(value: unknown): value is C {
  if (typeof value !== "object" || !value) {
    return false;
  }
  return (
    typeof (value as Record<string, unknown>).c === "boolean" &&
    typeof (value as Record<string, unknown>).d === "string"
  );
}
```

Notice the `value is A` and `value is C` as the return type annotation of these functions. This syntax is what tells TypeScript to assign the type to `value` in blocks where `isA`/`isC` return true.

Another note, we are using a cast to `Record<string, unknown>` in these type guards because the `typeof value !== "object" || !value` refines `value` from `unknown` to `object`. `object` doesn't allow arbitrary property access, so the cast allows us to access fields a, b, c, and d. This cast isn't particularly unsafe, since we're just calling typeof on the property. I find it pretty typical to need to perform similar casts in type guards, since you are telling TypeScript something it otherwise could not figure out.

## Filtering Arrays with Type Guards

Another place type guards can oftentimes come in handy is as the argument to the array filter function. Taking our interfaces and type guards from the above example,

```typescript
const mixedArray: (A | C)[] = [];

// A[]
const arrayA = mixedArray.filter(isA);
// C[]
const arrayC = mixedArray.filter(isC);
```

One of the first places most people will probably encounter type guards is when trying to filter out `null`/`undefined` out of an array. Passing `Boolean` or `!!x` to the filter function is a very common pattern in JavaScript.

```typescript
let arr: (A | null)[];
// (A | null)[]
let filteredArr1 = arr.filter(Boolean);
// (A | null)[]
let filteredArr2 = arr.filter((x) => !!x);
```

Unfortunately, this [doesn't quite work](https://github.com/microsoft/TypeScript/issues/16655) in TypeScript, at least for now. The resulting array still is typed as having null values. Instead, a type guard can be used for this case.

```typescript
export function isPresent<T>(t: T | undefined | null | void): t is T {
  return t !== undefined && t !== null;
}

// A[]
let filteredArr3 = arr.filter(isPresent);
```


Explain what user-defined type guards in TypeScript are and provide examples of commonly needed ones

Blog

GraphQL Code vs Schema First Development

Preact in the Shadow DOM

User-Defined Type Guards in TypeScript