DEV Community: Colin McDonnell

The ideal tech stack for a personal dev blog in 2020

Colin McDonnell — Sat, 11 Jul 2020 09:41:17 +0000

Originally published at https://vriad.com/essays/devii

Check out the HN ~~roast~~ discussion here! 🤗

I recently set out to build my personal website — the one you're reading now, as it happens!

Surprisingly, it was much harder than expected to put together a "tech stack" that met my criteria. My criteria are pretty straightforward; I would expect most React devs to have a similar list. Yet it was surprisingly hard to put all these pieces together.

Given the lack of a decent out-of-the-box solution, I worry that many developers are settling for static-site generators that place limits on the interactivity and flexibility of your website. We can do better.

tl;dr
Clone the repo here to get started with this setup: https://github.com/vriad/devii.

Let's quickly run through my list of design goals:

React (+ TypeScript)

I want to build the site in React and TypeScript. I love them both wholeheartedly, I use them for my day job, and they're gonna be around for a long time. Plus writing untyped JS makes me feel dirty.

I don't want limitations on what my personal website can be/become. Sure, at present my site consists of two simple, static blog posts. But down the road, I may want to build a page that contains an interactive visualization, a filterable table, or a demo of a React component I'm open-sourcing. Even something simple (like the email newsletter signup form at the bottom of this page) was much more pleasant to implement in React; how did we use to build forms again?

Plus: I want access to the npm ecosystem and all my favorite UI, animation, and styling libraries. I sincerely hope I never write another line of raw CSS ever again; CSS-in-JS 4 lyfe baby. If you want to start a Twitter feud with me about this, by all means at me.

Good authoring experience

If it's obnoxious to write new blog posts, I won't do it. That's a regrettable law of the universe. Even writing blog posts with plain HTML — just a bunch of <p> tags in a div — is just annoying enough to bug me. The answer: Markdown of course!

Static site generators (SSGs) like Hugo and Jekyll provide an undeniably wonderful authoring experience. All you have to do is touch a new .md file in the proper directory and get to writing. Unfortunately all Markdown-based SSGs I know of are too restrictive. Mixing React and Markdown on the same page is either impossible or tricky. If it's possible, it likely requires some plugin/module/extension, config file, blob of boilerplate, or egregious hack. Sorry Hugo, I'm not going to re-write my React code using React.createElement like it's 2015.

Well, that doesn't work for me. I want my website to be React-first, with a sprinkling of Markdown when it makes my life easier.

Static generation

As much as I love the Jamstack, it doesn't cut it from an SEO perspective. Many blogs powered by a "headless CMS" require two round trips before rendering the blog content (one to fetch the static JS bundle and another to fetch the blog content from a CMS). This degrades page load speeds and user experience, which accordingly degrades your rankings on Google.

Instead I want every page of my site to be pre-rendered to a set of fully static assets, so I can deploy them to a CDN and get fast page loads everywhere. You could get the same benefits with server-side rendering, but that requires an actual server and worldwide load balancing to achieve comparable page load speeds. I love overengineering things as much as the next guy, even I have a line. 😅

My solution

I describe my final architecture design below, along with my rationale for each choice. I distilled this setup into a website starter/boilerplate available here: https://github.com/vriad/devii. Below, I allude to certain files/functions I implemented; to see the source code of these, just clone the repo git clone git@github.com:vriad/devii.git

Next.js

I chose to build my site with Next.js. This won't be a surprising decision to anyone who's played with statically-rendered or server-side rendered React in recent years. Next.js is quickly eating everyone else's lunch in this market, especially Gatsby's (sorry Gatsby fans).

Next.js is by far the most elegant way (for now) to do any static generation or server-side rendering with React. They just released their next-generation (pun intended) static site generator in the 9.3 release back in March. So in the spirit of using technologies in the spring of their life, Next.js is a no-brainer.

Here's a quick breakdown of the project structure. No need to understand every piece of it; but it may be useful to refer to throughout the rest of this post.

.
├── README.md
├── public // all static files (images, etc) go here
├── pages // every .tsx component in this dir becomes a page of the final site
|   ├── index.tsx // the home page (which has access to the list of all blog posts)
|   ├── blog
|       ├── [blog].md // a template component that renders the blog posts under `/md/blog`
├── md
|   ├── blog
|       ├── devii.md // this page!
        ├── whatever.md // every MD file in this directory becomes a blog post
├── components
|   ├── Code.tsx
|   ├── Markdown.tsx
|   ├── <various others>
├── loader.ts // contains utility functions for loading/parsing Markdown
├── node_modules
├── tsconfig.json
├── package.json
├── next.config.js
├── next-env.d.ts
├── .gitignore

TypeScript + React

Both React and TypeScript are baked into the DNA of Next.js, so you get these for free when you set up a Next.js project.

Gatsby, on the other hand, has a special plugin for TypeScript support, but it's not officially supported and seems to be low on their priority list. Also, after messing with it for an hour I couldn't get it to play nice with hot reload.

Markdown authoring

Using Next's special getStaticProps hook and glorious dynamic imports, it's trivial to a Markdown file and pass its contents into your React components as a prop. This achieves the holy grail I was searching for: the ability to easily mix React and Markdown.

Frontmatter support

Every Markdown file can include a "frontmatter block" containing metadata. I implemented a simple utility function (loadPost) that loads a Markdown file, parses its contents, and returns a TypeScript object with the following signature:

type PostData = {
  path: string; // the relative URL to this page, can be used as an href
  content: string; // the body of the MD file
  title?: string;
  subtitle?: string;
  date?: number;
  author?: string;
  author_image?: string;
  tags?: string[];
  cover_image?: string;
  thumb_image?: string;
};

I implemented a separate function loadPosts that loads all the Markdown files under /md/blog and returns them as an array (PostData[]). I use loadPosts on this site's home page to render a list of all posts I've written.

Medium-inspired design

I used the wonderful react-markdown package to render Markdown as a React component. My Markdown rendered component (/components/Markdown.tsx) provides some default styles inspired by Medium's design. Just modify the style pros in Markdown.tsx to customize the design to your liking.

GitHub-style code blocks

You can easily drop code blocks into your blog posts using triple-backtick syntax. Specify the programming language with a "language tag", just like GitHub!

To achieve this I implemented a custom code renderer (/components/Code.tsx) for react-markdown that uses react-syntax-highlighter to handle the highlighting. So this:



```ts
// pretty neat huh?
const test = (arg: string) => {
  return arg.length > 5;
};
```

turns into this:

// pretty neat huh?
const test = (arg: string) => {
  return arg.length > 5;
};

RSS feed generation

An RSS feed is auto-generated from your blog post feed. This feed is generated using the rss module (for converting JSON to RSS format) and showdown for converting the markdown files to RSS-compatible HTML. The feed is generated during the build step and written as a static file to /rss.xml in your static assets folder. It's dead simple. That's the joy of being able to easily write custom build scripts on top of Next.js's getStaticProps hooks!

SEO

Every blog post page automatically populated meta tags based on the post metadata. This includes a title tag, meta tags, og: tags, Twitter metadata, and a link tag containing the canonical URL. You can modify/augment this in the PostMeta.ts component.

Static generation

You can generate a fully static version of your site using yarn build && yarn export. This step is entirely powered by Next.js. The static site is exported to the out directory.

After its generated, use your static file hosting service of choice (Firebase Hosting, Vercel, Netlify) to deploy your site.

Insanely customizable

There's nothing "under the hood" here. You can view and modify all the files that provide the functionality described above. Devii just provides a project scaffold, some Markdown-loading loading utilities (in loader.ts), and some sensible styling defaults (especially in Markdown.tsx).

To start customizing, modify index.tsx (the home page), BlogPost.tsx (the blog post template), and Markdown.tsx (the Markdown renderer).

Get started

Head to the GitHub repo to get started: https://github.com/vriad/devii. If you like this project, leave a ⭐️star⭐️ to help more people find Devii! 😎

To jump straight into the code, clone the repo and start the development server like so:

git clone git@github.com:vriad/devii.git mysite
cd mysite
yarn
yarn dev

You probably shouldn't use @emotion/core

Colin McDonnell — Sun, 07 Jun 2020 09:37:38 +0000

A maintainer of Emotion published a very thoughtful response to a version of this post! I encourage you to check that out here. The blog post below has modified to address some of his points.

Emotion is my favorite CSS-in-JS library.

It's easy to define style classes — both inline or in separate files. You can powerfully compose classes in powerful ways with the cx utility (the Emotion equivalent of Jed Watson's classnames). You sprinkle in your styles using the standard className attribute. There's no need to modify your markup/JSX — as it should be! You only need to install a single module (yarn add emotion). And there's no complicated Babel plugin or config file to set up.

import { css, cs } from 'emotion';

const redBorder = css({ border: '1px solid red' });
const blueText = css({ color: 'blue' });

const MyComp = () => {
  return <div className={cx(redBorder, blueText)}>hello</div>;
};

I'm currently building a Tailwind-style CSS-in-JS utility styling library (follow me to hear when it's ready!). Emotion provides the perfect layer of abstraction to build upon.

The "but"

But unfortunately everything I just said only applies to the "vanilla" emotion module (docs), not the confusingly-named @emotion/core module.

@emotion/core is the React-centric Emotion wrapper that gives you some extra goodies, specifically server-side rendering and theming. It's also the official recommendation of the Emotion project for any React project.

So why exactly is Emotion recommending this for React devs?

Minimal upsides

The main three advertised benefits of using @emotion/core are server-side rendering (SSR), theming, and customizability. Let's dig into those.

Out-of-the-box SSR

There's no denying this is a remarkable technical achievement. Getting SSR to "just work" with both Next.js, Gatsby, and the classic ReactDOMServer.renderToString approach is very impressive. I'd be lying if I claimed to understand the complexities involved.

I don't have data on this, but — in my experience — SSR isn't a consideration for a hefty majority of React projects. If you started a project/website in the last 7 years where SEO/SEO/pageload speed/bundle size was an important design consideration, you probably didn't choose React. Website builders, static site generators, and HTML templating still dominate that arena. Take it from someone who got torn apart on HN for advocating the use of React/Next.js for personal developer websites 😘

For the people who do need SSR, the guidance is a little slim.

Next.js

There's no explicit documentation from Next.js on how to set up SSR with vanilla emotion. Next.js provides a sample project here. Notably, this project a) has a very uninformative Readme and b) is built with @emotion/core! So it's not immediately obvious that the approaches on display will even transfer to a vanilla project.

Enough buildup. Here's the internet's first comprehensive guide to setting up SSR with vanilla Emotion and Next.js:

yarn add emotion-server
create _document.tsx in your pages directory and copy this gist into it
ok ur done

Gatsby

For completeness, here's some instructions for Gatsby users, too.

yarn add gatsby-plugin-emotion
add 'gatsby-plugin-emotion' to your plugins list in gatsby-config.js

If you're using @emotion/core to avoid the complexities of SSR configuration, you may want to reconsider.

Theming

In the era of React Context and Hooks, there's no reason for libraries to use prop or high-order components to handle theming. Emotion provides a useTheme hook, but it still requires adding an additional library (emotion-theming).

This isn't a controversial claim; the next version of Emotion will explicitly recommend using a Context/Hook based solution, so I won't belabor this point.

Even Context/Hooks might be overkill for many projects. Just define your theme values as variables and import them into components as needed. If you're using TypeScript here's some code to get you started:

// theme.ts
export const primaryColor = "blue";
export const serif = `"Merriweather", Times New Roman, Times, serif`;

// anydamnfile.ts
import { css } from 'emotion';
import * as theme from './theme.ts';

export const MyComponent = ()=>{
  return <p className={css({ color: theme.primaryColor, fontFamily: theme.serif })}>
}

If you want to import your theme with a useTheme hook, here's a workable implementation that took me several seconds to write:

import * as theme from './theme.ts';
export const useTheme = () => theme;

Customization

Edit: This section was added after the fact to address a concern raised by the maintainer of Emotion in his response to an earlier version of this post.

@emotion/core provides a CacheProvider component that lets you customize low-level aspects of it's behavior. This customization isn't possible with vanilla emotion. I'll let the maintainer of Emotion explain it:

Because [@emotion/core] doesn't give you string class names back, but rather just opaque objects, the rule insertion is lazy. This might not be as interesting on its own, but it allows us to customize injection through a . Use cases for this are not as common - but they exist and once you ever come across one then you might be very thankful for the path we've chosen...Main things that can be customized:

prefixing rules

parser plugins

container element (very important for rendering into iframes)

nonce (very important for CSP)

— Andarist (Github)

If you absolutely need this degree of customizability, then @emotion/core is probably right for you.

For everyone else, let's look at the downsides.

Serious downsides

The `css` prop

Emotion recommends using their non-standard css prop to style your components, instead of React's built-in className. This causes me immeasurable emotional pain.

This approach destroys the portability of your React components. Your components are now unusable in any codebase that isn't configured to use @emotion/core.

The portability and encapsulation of React components is one of the most powerful and wondrous achievements in web development in the last last decade. Don't give that up without a good reason!

Installation woes

Unfortunately to get that non-native css prop to work, Emotion core entirely replaces your project's JSX parser. It substitutes the built-in React.createElement function with Emotion's custom jsx function.

There are a couple ways to set this up.

Option #1: install the @emotion/babel-preset-css-prop Babel plugin and add it to your .babelrc. If you're using Create React App, this isn't impossible. If you're using TypeScript, you probably don't have a .babelrc in your project.

If you're in one of those buckets, there's option #2: copy these two lines at the top of every React component you want to style with Emotion:

/** @jsx jsx */

import { jsx } from '@emotion/core';

If your TypeScript config or linter doesn't allow unused imports, you'll have to disable those rules to get rid of the warning. Check out this issue if you want to see dozens of TypeScript users being sad about this.

Lack of composability

Perhaps the most damning issue with @emotion/core is that it makes the simple things harder. If you want to define a new class or use cx, you have to wrap your component with the ClassNames render prop. But with @emotion/core, these basic functions — found in nearly all CSS-in-JS libraries — requires you to modify your markup. In my humble opinion, requiring markup modifications is a cardinal sin for a styling library.

Here's the example from the top of this post, reimplemented with @emotion/core:

import { ClassNames } from '@emotion/core';

const MyComp = () => {
  return (
    <ClassNames>
      {({ css, cx }) => {
        const redBorder = css({ border: '1px solid red' });
        const blueText = css({ color: 'blue' });

        return <div className={cs(redBorder, blueText)}>hello</div>;
      }}
    </ClassNames>
  );
};

Wrapping up

I understand how this happened. Vanilla emotion was undoubtedly getting flooded with GitHub issues by frustrated developers hitting against subtle limitations of its design. @emotion/core fixes these issues. But because @emotion/core is now the officially recommended approach for all React projects (the vanilla option isn't even mentioned on the Readme anymore), I suspect thousands of developers using it who would be better served by plain ol' emotion.

And finally: a huge thank you to the Emotion team for all their exceptional work and contributions to the open-source community.

Designing the perfect Typescript schema validation library

Colin McDonnell — Sun, 07 Jun 2020 08:05:37 +0000

There are a handful of wildly popular validation libraries in the Javascript ecosystem with thousands of stars on GitHub.

When I started my quest to find the ideal schema declaration/validation library, I assumed the hardest part would be identifying the Most Great option from a sea of excellent ones.

But as I dug deeper into the many beloved tools in the ecosystem, I was surprised that none of them could provide the features and developer experience I was looking for.

tl;dr
I made a new Typescript validation library that has static type inference and the best DX this side of the Mississippi. To jump straight to README, head over to https://github.com/vriad/zod

A pinch of context

I'm building an API for a healthcare application with Typescript. Naturally I want this mission-critical medical software to be rock-solid, so my goal is to build a fully end-to-end typesafe data layer.

All data that passes from the client to the server AND server to client should be validated at runtime. Moreover, both the client and server should have static type definitions of all payloads, so I can catch more errors at compile-time.

I also don't hate myself, so I don't want to keep my static types and runtime type validators in sync by hand as my data model changes. Which means we need a tool that supports 🚀StAtIc TyPe InFeReNcE!!🚀 vuvuzela sounds

Let's look at our options!

The existing options

Joi (14.3k stars)

Doesn't support static type inference. Boo.

Yup (8.6k stars)

Yup is jquense's popular, Joi-inspired validation library that was implemented first in vanilla JS, with Typescript typings added later.

Yup supports static type inference! But with a small caveat: the typings are wrong.

For instance, the yup package treats all object properties as optional by default.

const schema = yup.object({
  asdf: yup.string(),
});
schema.validate({}); // passes

Yet the inferred type indicates that all properties are required. 😕

type SchemaType = yup.InferType<typeof schema>;

// returns { asdf: string }
// should be { asdf?: string }

Yup also mis-infers the type of "required" arrays.

const numList = yup.array().of(yup.string()).required();

// .required() is used to indicate a non-empty list
numList.validateSync([]); // fails

// yet the inferred type doesn't reflect this
type NumList = yup.InferType<typeof numList>;
// returns string[]
// should be [string,...string[]]

Finally, Yup doesn't explicitly support generic union and intersection types. This is a recurring source of frustration for the Yup community.

These may sound like nitpicks. But it's very uncool for the inferred type to not actually reflect the actual type of the validator it came from.

Moreover, there are no plans to fix these issues in Yup's type inference because those changes would be backwards compatible. See more about this here.

io-ts (2.7k stars)

Finally, a library that was designed for Typescript from the ground up!

Look, io-ts is excellent library. It's creator, gcanti, has done more than anyone to bring proper higher-order functional programming to Typescript with his fp-ts library.

But in my situation, and I think many others', io-ts prioritizes functional programming purity at the expense of developer experience. Functional purity is a valid and admirable design goal, but it makes io-ts particularly hard to integrate into an existing codebase with a more procedural or object-oriented bias. It's difficult to progressively integrate io-ts without entirely refactoring your code with a more functional flavor.

For instance, consider how to define an object schema with optional properties in io-ts:

const A = t.type({
  foo: t.string,
});

const B = t.partial({
  bar: t.number,
});

const C = t.intersection([A, B]);

type C = t.TypeOf<typeof C>;
/*
{
  foo: string;
  bar?: number | undefined
}
*/

You must define the required props with a call to t.type({...}), define your optional props with a call to t.partial({...}), and merge them with t.intersection().

Spoiler alert: Here's the equivalent in my new library:

const C = z.object({
  foo: z.string(),
  bar: z.number().optional(),
});

type C = t.TypeOf<typeof C>;
/* {
  foo: string;
  bar?: number | undefined
} */

io-ts also requires the use of gcanti's functional programming library fp-ts to parse results and handle errors. From the io-ts docs, here is the most basic example of how to run a validation:

import * as t from 'io-ts';
import { pipe } from 'fp-ts/lib/pipeable';
import { fold } from 'fp-ts/lib/Either';

// failure handler
const onLeft = (errors: t.Errors): string => `\${errors.length} error(s) found`;

// success handler
const onRight = (s: string) => `No errors: \${s}`;

pipe(t.string.decode('a string'), fold(onLeft, onRight));
// => "No errors: a string"

The functional approach here is alienating for developers who aren't accustomed to it.

Again: fp-ts is fantastic resource for developers looking to keep their codebase strictly functional. But depending on fp-ts necessarily comes with a lot of intellectual overhead; a developer has to be familiar with functional programming concepts, fp-ts's nomenclature, and the Either monad to do a simple schema validation. It's alienating for devs who don't have a functional background, and it drives them to libraries like Yup, which returns incorrect types.

Introducing Zod

So, in the tradition of many a nitpicky programmer, I decided to build my own library from scratch. What could go wrong?

The final result: https://github.com/vriad/zod.

Zod is a validation library designed for optimal developer experience. It's a Typescript-first schema declaration library with rigorous (and correct!) inferred types, incredible developer experience, and a few killer features missing from the existing libraries.

Uses Typescript generic inference to statically infer the types of your schemas
Eliminates the need to keep static types and runtime validators in sync by hand
Has a composable, declarative API that makes it easy to define complex types concisely

Zod was also designed with some core principles designed to make all declarations as non-magical and developer-friendly as possible:

Fields are required unless explicitly marked as optional (just like Typescript!)
Schemas are immutable; methods (i.e. .optional()) return a new instance.
Zod schemas operate on a Parse, don't validate! basis!

To jump straight to README, head over to https://github.com/vriad/zod. If you're feeling frisky, leave a star 🌟👍

Primitives

import * as z from 'zod';

const stringSchema = z.string(); // => ZodType<string>
const numberSchema = z.number(); // => ZodType<number>
const booleanSchema = z.boolean(); // => ZodType<boolean>
const undefinedSchema = z.undefined(); // => ZodType<undefined>
const nullTypeSchema = z.null(); // => ZodType<null>

Parsing

// every ZodType instance has a .parse() method
const stringSchema = z.string();
stringSchema.parse('fish'); // => "fish"
stringSchema.parse(12); // throws Error('Non-string type: number');

Type inference

Like in io-ts, you can extract the Typescript type of any schema with {'z.TypeOf<>'}.

const A = z.string();
type A = z.TypeOf<typeof A>; // string

const u: A = 12; // TypeError
const u: A = 'asdf'; // compiles

We'll include examples of inferred types throughout the rest of the documentation.

Objects

// all properties are required by default
const dogSchema = z.object({
  name: z.string(),
  age: z.number(),
  neutered: z.boolean(),
});

type Dog = z.TypeOf<typeof dogSchema>;
/* equivalent to:
type Dog = {
  name:string;
  age: number;
  neutered: boolean;
} 
*/

const cujo = dogSchema.parse({
  name: 'Cujo',
  age: 4,
  neutered: true,
}); // passes, returns Dog

const fido: Dog = {
  name: 'Fido',
  age: 2,
}; // TypeError: missing required property 'neutered'

Arrays

const dogsList = z.array(dogSchema);

dogsList.parse([{ name: 'Cujo', age: 3, neutered: true }]); // passes
dogsList.parse([]); // passes

Plus you can explicitly define a non-empty array schema, something
io-ts doesn't support.

// Non-empty lists

const nonEmptyDogsList = z.array(dogSchema).nonempty();
nonEmptyDogsList.parse([]); // throws Error("Array cannot be empty")

Unions (including nullable and optional types)

Zod includes a built-in z.union method for composing "OR"
types.

const stringOrNumber = z.union([z.string(), z.number()]);

stringOrNumber.parse('foo'); // passes
stringOrNumber.parse(14); // passes

Unions are the basis for defining nullable and optional values.

/* Optional Types */ // "optional string" === the union of string and undefined
const A = z.union([z.string(), z.undefined()]);
A.parse(undefined); // => passes, returns undefined
type A = z.TypeOf<typeof A>; // string | undefined

There is also a shorthand way to make a schema "optional":

const B = z.string().optional(); // equivalent to A

const C = z.object({
  username: z.string().optional(),
});
type C = z.TypeOf<typeof C>; // { username?: string | undefined };

/* Nullable Types */ const D = z.union([z.string(), z.null()]);

const E = z.string().nullable(); // equivalent to D
type E = z.TypeOf<typeof D>; // string | null

You can create unions of any two schemas.

/* Custom Union Types */
const F = z.union([z.string(), z.number()]).optional().nullable();
F.parse('tuna'); // => tuna
F.parse(42); // => 42
F.parse(undefined); // => undefined
F.parse(null); // => null
F.parse({}); // => throws Error!

type F = z.TypeOf<typeof F>; // string | number | undefined | null;

Intersections

Intersections are useful for creating "logical AND" types.

const a = z.union([z.number(), z.string()]);
const b = z.union([z.number(), z.boolean()]);

const c = z.intersection(a, b);
type c = z.TypeOf<typeof C>; // => number

const neverType = z.intersection(z.string(), z.number());
type Never = z.TypeOf<typeof stringAndNumber>; // => never

This is particularly useful for defining "schema mixins" that you can apply to multiple schemas.

const HasId = z.object({
  id: z.string(),
});

const BaseTeacher = z.object({
  name: z.string(),
});

const Teacher = z.intersection(BaseTeacher, HasId);

type Teacher = z.TypeOf<typeof Teacher>;
// { id:string; name:string };

Object merging

In the examples above, the return value of z.intersection is an instance of ZodIntersection, a generic class that wraps the two schemas passed in as arguments.

But if you're trying to combine two object schemas, there is a shorthand:

const Teacher = BaseTeacher.merge(HasId);

The benefit of using this shorthand is that the returned value is a new object schema (ZodObject), instead of a generic ZodIntersection instance. This way, you're able to fluently chain together many .merge calls:

// chaining mixins
const Teacher = BaseTeacher.merge(HasId).merge(HasName).merge(HasAddress);

Tuples

These differ from arrays in that they have a fixed number of elements, and each element can have a different type.

const athleteSchema = z.tuple([
  // takes an array of schemas
  z.string(), // name
  z.number(), // jersey number
  z.object({
    pointsScored: z.number(),
  }), // statistics
]);

type Athlete = z.TypeOf<typeof athleteSchema>;
// type Athlete = [string, number, { pointsScored: number }]

Recursive types

You can define a recursive schema in Zod, but because of a limitation of Typescript, their type can't be statically inferred. If you need a recursive Zod schema you'll need to define the type definition manually, and provide it to Zod as a "type hint".

interface Category {
  name: string;
  subcategories: Category[];
}

const Category: z.ZodType<Category> = z.lazy(() => {
  return z.object({
    name: z.string(),
    subcategories: z.array(Category),
  });
});

Category.parse({
  name: 'People',
  subcategories: [
    {
      name: 'Politicians',
      subcategories: [{ name: 'Presidents', subcategories: [] }],
    },
  ],
}); // passes

Function schemas

Zod also lets you define "function schemas". This makes it easy to validate the inputs and outputs of a function without intermixing your validation code and "business logic".

You can create a function schema with z.function(args, returnType) which accepts these arguments.

args: ZodTuple The first argument is a tuple (created with z.tuple(\[...\]) and defines the schema of the arguments to your function. If the function doesn't accept arguments, you can pass an empty tuple (z.tuple([])).
returnType: ZodType The second argument is the function's return type. This can be any Zod schema.

const args = z.tuple([
  z.object({ nameStartsWith: z.string() }),
  z.object({ skip: z.number(), limit: z.number() }),
]);

const returnType = z.array(
  z.object({
    id: string(),
    name: string(),
  })
);

const FetcherFactory = z.function(args, returnType);

z.function returns a higher-order "function factory". Every "factory" has .validate() method which accepts a function as input and returns a new function. The returned function automatically validates both its inputs and return value against the schemas provided to z.function. If either is invalid, the function throws.
This lets you confidently execute business logic in a "validated function" without worrying about invalid inputs or return types, mixing your validation and business logic, or writing duplicative types for your functions.
Here's an example.

const validatedQueryUser = FetchFunction.validate((filters, pagination) => {
  // the arguments automatically have the appropriate types
  // as defined by the args tuple passed to `z.function()`
  // without needing to provide types in the function declaration

  filters.nameStartsWith; // autocompletes
  filters.ageLessThan; // TypeError

  // Typescript statically verifies that value returned by
  // this function is of type { id: string; name: string; }[]

  return 'salmon'; // TypeError
});

const users = validatedQueryUser(
  {
    nameStartsWith: 'John',
  },
  {
    skip: 0,
    limit: 20,
  }
); // => returns { id: string; name: string; }[]

This is particularly useful for defining HTTP or RPC endpoints that accept complex payloads that require validation. Moreover, you can define your endpoints once with Zod and share the code with both your client and server code to achieve end-to-end type safety.

Onwards and upwards

I think there's a LOT of room for improvement in how we handle the complexity of data modeling, validation, and transport as developers. Typescript, GraphQL, and Prisma are huge steps towards a future where our tooling can provide guarantees of data integrity. But there's still a long way to go.

If you like what you see, head over to https://github.com/vriad/zod and leave a star.

DEV Community: Colin McDonnell

The ideal tech stack for a personal dev blog in 2020

React (+ TypeScript)

Good authoring experience

Static generation

My solution

Next.js

TypeScript + React

Markdown authoring

Frontmatter support

Medium-inspired design

GitHub-style code blocks

RSS feed generation

SEO

Static generation

Insanely customizable

Get started

You probably shouldn't use @emotion/core

The "but"

Minimal upsides

Out-of-the-box SSR

Next.js

Gatsby

Theming

Customization

Serious downsides

The css prop

Installation woes

Lack of composability

Wrapping up

Designing the perfect Typescript schema validation library

A pinch of context

The existing options

Joi (14.3k stars)

Yup (8.6k stars)

io-ts (2.7k stars)

Introducing Zod

Primitives

Parsing

Type inference

Objects

Arrays

Unions (including nullable and optional types)

Intersections

Object merging

Tuples

Recursive types

Function schemas

Onwards and upwards

The `css` prop