```yaml
---
slug: tailwind-css-for-email
published: 2022-10-11T15:00:00-07:00
description: While this won't remove your dependency on table tags, at least you can reuse your Tailwind colors and spacing rules in email templates
changelog: ~
---
```

I can no longer count the hours [Tailwind](https://tailwindcss.com) saves me. I don't really _hate_ the state of CSS-in-JS. I just find it gets in the way of quickly saying "make this blue, put it in a flex box oriented by row, with the items centered." It's a preference thing, and my preference is towards utility class names at this point, letting React components do any reusable composition for me. It's been great, save for one quibble; email is awful. It's not really tailwind's fault, but emails are still table-based, inline styles, and generally everything awful we definitely thought we got rid of in 2002.

What follows isn't complex enough to justify an NPM module, but it is a pattern generally usable for getting Tailwind into your HTML emails. The short version is:

1. A very minimal `tailwind.email.css` is generated using the tailwind CLI. It contains `@tailwind utilities;` and any resets I'd like to do. Be sure you add your email templates to tailwind's config file, otherwise your styles won't be included.
2. We put the generated `tailwind.email.css` through a conversion of `rem` to `px` because it's 2022 and [outlook still does not support the `rem` unit](https://www.caniemail.com/features/css-unit-rem/)
3. [juice](https://github.com/Automattic/juice) inlines the tailwind styles for us where possible, keeping the media queries in the head for email clients that support it
4. A [rehype](https://github.com/rehypejs/rehype) pipeline replaces Tailwind `--tw-` variables with their resolved values

## On Generating the HTML
For what I'm currently doing, emails are built using everyday React and a renderer that calls `ReactDOMServer.renderToStaticMarkup(element)`. The complexities of `tr` and `td` nesting is easily hidden behind some common components, which I chose to name `Row` and `Column` respectively. They're nothing fancy and based on the reality we'll probably never get flexbox in HTML emails in my lifetime.

```tsx
const tableAttributes = {
  role: "presentation",
  cellPadding: 0,
  cellSpacing: 0,
};

interface EmailComponentProps {
  className?: string;
}

export const Row: React.FC<PropsWithChildren<EmailComponentProps>> = ({
  children,
  className,
}) => {
  return (
    <table
      {...tableAttributes}
      {...({ border: "0" } as Record<string, string>)}
      className={cx(className, "w-full")}
    >
      <tr>{children}</tr>
    </table>
  );
};

export const Column: React.FC<PropsWithChildren<EmailComponentProps>> = ({
  children,
  className,
}) => {
  return <td className={className}>{children}</td>;
};
```

Ultimately though, how you generate the HTML is up to you, as long as you have it as a string.

## Tailwind Configuration
To make Tailwind email friendly, we need to disable a bunch of core plugins that don't work well across email clients. A huge shoutout goes to [Can I Email](https://www.caniemail.com). Disabling these plugins is straightforward: add them to your theme's definition, and Tailwind will make sure not to generate CSS for them. Trying to use these CSS classes will just result in useless CSS classes with no style information & can be stripped later.

```js
module.exports = {
  content: [
    // put your email paths here
  ],
  theme: {
    corePlugins: {
      preflight: false,
      backgroundOpacity: false,
      borderOpacity: false,
      boxShadow: false,
      divideOpacity: false,
      placeholderOpacity: false,
      textOpacity: false,
    },
  },
  plugins: [],
};

```

## Converting `rem` to `px`

I wasn't keen on building a completely custom `tailwind.config.js` file, and the `rem` unit is easy enough to convert from as long as you specify a base value in pixels. Tailwind [uses a default base](https://tailwindcss.com/docs/customizing-spacing#default-spacing-scale) of `16px`, so we can convert all of our units via a regular expression.

```ts
const css = originalCSS.replace(
  /([\d.-]+rem)/gi,
  (_, value) => `${parseFloat(value.replace(/rem$/, "")) * 16}px`
);
```

## Applying juice

Our stylesheet is now email friendly, and it's time for [juice](https://github.com/Automattic/juice).

> Given HTML, juice will inline your CSS properties into the style attribute.

Cool. That sounds exactly what we're looking to do. We'll take our HTML plus our px-friendly CSS and ask juice to merge the two together into a final output.

```ts
const juiced = juice(html, { extraCss: css });
```

That's mostly it. Juice takes care of the inline style tags for us where it can, defaulting to a `<style>` tag in the head where it can't (ie media queries), and just generally does the right thing all the time. About the only thing it can't do is fix custom CSS variables, but [there's an issue for CSS variable support](https://github.com/Automattic/juice/issues/312) with a workaround. We'll use code similar to the workaround, but with a tool that's a bit faster than cheerio.

## Resolving CSS Variables

Resolving our CSS variables requires us to make a few assumptions about how email clients behave. First, if a client supports advanced CSS such as `@media` queries, they also support CSS variables. That means the only CSS variables we'll need to care about are those located inline and in the body. Second, we can assume that Tailwind isn't going to generate any weird syntax. CSS variables will be in the form of `--declaration: value`, and usage will be in the form of `var(--declaration)` with an optional fallback.

Replacing the variables will require two passes. On the first pass, we'll capture all our CSS variables assigned to the inline style, and on the second, we'll replace our `var()` statements with the resolved values. Using [`rehype`](https://github.com/rehypejs/rehype) and [`rehype-rewrite`](https://github.com/jaywcjlove/rehype-rewrite) makes this a straightforward task.

```ts
const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;
const hyped = rehype()
  .use(rehypeRewrite, {
    rewrite: (node) => {
      if (node.type !== "element") {
        return node;
      }
      const resolveVariables = (s: string): string => {

        // pass 1: pull definitions
        const defs = new Map<string, string>();
        let withoutDefs = s.replace(
          variableDefRegex,
          (_, def: string, value: string) => {
            defs.set(def.trim(), value.trim());
            return "";
          }
        );

        // pass 2: replace variables (maxCycles prevents Terrible Things from happening)
        let maxCycles = 1000;
        while (withoutDefs.match(variableUsageRegex)) {
          maxCycles--;
          if (maxCycles <= 0) {
            throw new Error("Max Cycles for replacement exceeded");
          }
          withoutDefs = withoutDefs.replace(
            variableUsageRegex,
            (_, def: string, fallback: string) => {
              const d = def.trim();
              if (defs.has(d)) {
                return defs.get(d) ?? "";
              }
              return (fallback ?? "").trim();
            }
          );
        }

        // return clean result
        return withoutDefs;
      };
      node.properties = {
        ...node.properties,
        style: resolveVariables(`${node.properties?.style ?? ""}`),
      };
    },
  })
  .use(stringify)
  .processSync(juiced)
  .toString();
```

## Wrapping Up

At this point, I'm pretty happy with where the code is. The generated tailwind output from the email.css is easy to understand and manage since it's just vanilla tailwind. Juice is doing what it does best, and the only manual adjustments in the code are converting the `rem` to `px` and fixing of inline CSS variables. That's a really small amount of maintained code relative to an email specific library and build system in exchange for the full power of Tailwind. Emails still suck, but hopefully they'll suck a little less. With the Libraries in place, we put together the Taskless Usage in about 20 minutes.

![image](https://user-images.githubusercontent.com/1795/193527500-a0ada56c-272b-4809-b886-8f112312ef5e.png)

And the associated code:

```ts
/* mailwindCss.ts */
import { readFile } from "node:fs/promises";
import juice from "juice";
import { rehype } from "rehype";
import rehypeRewrite from "rehype-rewrite";
import stringify from "rehype-stringify";

/** Cache of compiled tailwind files */
const twcCache = new Map<string, Promise<string>>();

/**
 * Originally based on The MailChimp Reset from Fabio Carneiro, MailChimp User Experience Design
 * More info and templates on Github: https://github.com/mailchimp/Email-Blueprints
 * http://www.mailchimp.com &amp; http://www.fabio-carneiro.com
 * These styles are non-inline; they impact UI added by email clients
 * By line:
 * (1) Force Outlook to provide a "view in browser" message
 * (2) Force Hotmail to display emails at full width
 * (3) Force Hotmail to display normal line spacing
 * (4) Prevent WebKit and Windows mobile changing default text sizes
 * (5) Remove spacing between tables in Outlook 2007 and up
 * (6) Remove table borders on MSO 07+ http://www.campaignmonitor.com/blog/post/3392/1px-borders-padding-on-table-cells-in-outlook-07/
 * (7) Specify bicubic resampling for MSO on img objects
 * (8) Media Query block - Pretty phone numbers in email: http://www.campaignmonitor.com/blog/post/3571/using-phone-numbers-in-html-email
 * (9) Media Query block - same as above, but for tablet sized devices
 */
const universalStyles = /*css*/ `
  #outlook a{ padding:0; }
  .ReadMsgBody{ width:100%; } .ExternalClass{ width:100%; }
  .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div { line-height: 100%; }
  body, table, td, p, a, li, blockquote{ -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
  table, td{ mso-table-lspace:0pt; mso-table-rspace:0pt; }
  table td {border-collapse: collapse;}
  img{-ms-interpolation-mode: bicubic;}
  @media only screen and (max-device-width: 480px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
  @media only screen and (min-device-width: 768px) and (max-device-width: 1024px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
`;

/**
 * Inline reset styles
 * These set common defaults for a consistent UI. Their comments will be automatically stripped by juice
 */
const resetStyles = /*css*/ `
  /* default margin/padding, box sizing*/
  * { margin: 0; padding: 0; box-sizing: border-box; }
  /* height 100% all the way down */
  table, tr, td {height: 100%;}
  /* img behavior - bicubic ms resizing, no border, fix space gap on gmail/hotmail */
  img { outline: none; text-decoration: none; -ms-interpolation-mode: bicubic; display: block; }
  a img { border: none; }
  /* mso 07, 10 table spacing fix http://www.campaignmonitor.com/blog/post/3694/removing-spacing-from-around-tables-in-outlook-2007-and-2010 */
  table { border-collapse: collapse; mso-table-lspace: 0pt; mso-table-rspace: 0pt;}
  /* tel/sms links are unstyled by default */
  a[href^="tel"], a[href^="sms"] { text-decoration: none; pointer-events: none; cursor: default; }
`;

const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;

/** Juices the styles, and then resolves CSS variables and additional HTML adjustements via rehype */
const inlineStyles = (html: string, css?: string) => {
  const juiced = juice(html, { extraCss: css });
  const hyped = rehype()
    .use(rehypeRewrite, {
      rewrite: (node) => {
        if (node.type !== "element") {
          return node;
        }

        // inline styles into the <head>
        if (node.tagName === "head") {
          node.children = [
            ...node.children,
            {
              type: "element",
              tagName: "style",
              children: [{ type: "text", value: universalStyles }],
            },
          ];
        }

        const resolveVariables = (s: string): string => {
          // pass 1: pull definitions
          const defs = new Map<string, string>();
          let withoutDefs = s.replace(
            variableDefRegex,
            (_, def: string, value: string) => {
              defs.set(def.trim(), value.trim());
              return "";
            }
          );

          // pass 2: replace variables
          let maxCycles = 1000;
          while (withoutDefs.match(variableUsageRegex)) {
            maxCycles--;
            if (maxCycles <= 0) {
              throw new Error("Max Cycles for replacement exceeded");
            }
            withoutDefs = withoutDefs.replace(
              variableUsageRegex,
              (_, def: string, fallback: string) => {
                const d = def.trim();
                if (defs.has(d)) {
                  return defs.get(d) ?? "";
                }
                return (fallback ?? "").trim();
              }
            );
          }

          // return clean result
          return withoutDefs;
        };
        node.properties = {
          ...node.properties,
          style: resolveVariables(`${node.properties?.style ?? ""}`),
        };
      },
    })
    .use(stringify)
    .processSync(juiced)
    .toString();
  return hyped;
};

interface MailwindOptions {
  /** A path to your tailwind.css file, optimized for email */
  tailwindCss: string;
  /** The base px value for 1rem, defaults to 16px */
  basePx?: number;
  /** Set to `false` to disable extended resets */
  reset?: boolean;
}

const mailwindCss = async (email: string, options: MailwindOptions) => {
  const basePx = options?.basePx ?? 16;

  // cache promise for performance in serverless environments
  if (
    !twcCache.has(options.tailwindCss) ||
    process.env.NODE_ENV === "development"
  ) {
    // console.log("loading styles");
    const p = new Promise<string>((resolve, reject) => {
      readFile(options.tailwindCss)
        .then((buf) => {
          const s = buf.toString();
          // rem to px
          const pxed = s.replace(
            /([\d.-]+rem)/gi,
            (_, value) => `${parseFloat(value.replace(/rem$/, "")) * basePx}px`
          );
          resolve(pxed);
        })
        .catch((reason) => reject(reason));
    });
    twcCache.set(options.tailwindCss, p);
  }

  const s = await twcCache.get(options.tailwindCss);
  if (typeof s === "undefined") {
    throw new Error(`Could not load tailwind css from ${options.tailwindCss}`);
  }

  return inlineStyles(
    email,
    options.reset === false ? s : [resetStyles, s].join("\n")
  );
};

export default mailwindCss;
```


While this won't remove your dependency on table tags, at least you can reuse your Tailwind colors and spacing rules in email templates

Link

code

Fence

module.exports = {
  content: [
    // put your email paths here
  ],
  theme: {
    corePlugins: {
      preflight: false,
      backgroundOpacity: false,
      borderOpacity: false,
      boxShadow: false,
      divideOpacity: false,
      placeholderOpacity: false,
      textOpacity: false,
    },
  },
  plugins: [],
};



const css = originalCSS.replace(
  /([\d.-]+rem)/gi,
  (_, value) => `${parseFloat(value.replace(/rem$/, "")) * 16}px`
);


blockquote

const juiced = juice(html, { extraCss: css });


/* mailwindCss.ts */
import { readFile } from "node:fs/promises";
import juice from "juice";
import { rehype } from "rehype";
import rehypeRewrite from "rehype-rewrite";
import stringify from "rehype-stringify";

/** Cache of compiled tailwind files */
const twcCache = new Map<string, Promise<string>>();

/**
 * Originally based on The MailChimp Reset from Fabio Carneiro, MailChimp User Experience Design
 * More info and templates on Github: https://github.com/mailchimp/Email-Blueprints
 * http://www.mailchimp.com &amp; http://www.fabio-carneiro.com
 * These styles are non-inline; they impact UI added by email clients
 * By line:
 * (1) Force Outlook to provide a "view in browser" message
 * (2) Force Hotmail to display emails at full width
 * (3) Force Hotmail to display normal line spacing
 * (4) Prevent WebKit and Windows mobile changing default text sizes
 * (5) Remove spacing between tables in Outlook 2007 and up
 * (6) Remove table borders on MSO 07+ http://www.campaignmonitor.com/blog/post/3392/1px-borders-padding-on-table-cells-in-outlook-07/
 * (7) Specify bicubic resampling for MSO on img objects
 * (8) Media Query block - Pretty phone numbers in email: http://www.campaignmonitor.com/blog/post/3571/using-phone-numbers-in-html-email
 * (9) Media Query block - same as above, but for tablet sized devices
 */
const universalStyles = /*css*/ `
  #outlook a{ padding:0; }
  .ReadMsgBody{ width:100%; } .ExternalClass{ width:100%; }
  .ExternalClass, .ExternalClass p, .ExternalClass span, .ExternalClass font, .ExternalClass td, .ExternalClass div { line-height: 100%; }
  body, table, td, p, a, li, blockquote{ -webkit-text-size-adjust:100%; -ms-text-size-adjust:100%; }
  table, td{ mso-table-lspace:0pt; mso-table-rspace:0pt; }
  table td {border-collapse: collapse;}
  img{-ms-interpolation-mode: bicubic;}
  @media only screen and (max-device-width: 480px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
  @media only screen and (min-device-width: 768px) and (max-device-width: 1024px) {
    a[href^="tel"],
    a[href^="sms"] {
      text-decoration: default !important;
      pointer-events: auto !important;
      cursor: default !important;
    }
  }
`;

/**
 * Inline reset styles
 * These set common defaults for a consistent UI. Their comments will be automatically stripped by juice
 */
const resetStyles = /*css*/ `
  /* default margin/padding, box sizing*/
  * { margin: 0; padding: 0; box-sizing: border-box; }
  /* height 100% all the way down */
  table, tr, td {height: 100%;}
  /* img behavior - bicubic ms resizing, no border, fix space gap on gmail/hotmail */
  img { outline: none; text-decoration: none; -ms-interpolation-mode: bicubic; display: block; }
  a img { border: none; }
  /* mso 07, 10 table spacing fix http://www.campaignmonitor.com/blog/post/3694/removing-spacing-from-around-tables-in-outlook-2007-and-2010 */
  table { border-collapse: collapse; mso-table-lspace: 0pt; mso-table-rspace: 0pt;}
  /* tel/sms links are unstyled by default */
  a[href^="tel"], a[href^="sms"] { text-decoration: none; pointer-events: none; cursor: default; }
`;

const variableDefRegex = /(--[a-zA-Z0-9-_]+)\s*:\s(.+?);/g;
const variableUsageRegex = /var$(\s*--[a-zA-Z0-9-_]+\s*)(?:$|,\s*(.*)\))/;

/** Juices the styles, and then resolves CSS variables and additional HTML adjustements via rehype */
const inlineStyles = (html: string, css?: string) => {
  const juiced = juice(html, { extraCss: css });
  const hyped = rehype()
    .use(rehypeRewrite, {
      rewrite: (node) => {
        if (node.type !== "element") {
          return node;
        }

        // inline styles into the <head>
        if (node.tagName === "head") {
          node.children = [
            ...node.children,
            {
              type: "element",
              tagName: "style",
              children: [{ type: "text", value: universalStyles }],
            },
          ];
        }

        const resolveVariables = (s: string): string => {
          // pass 1: pull definitions
          const defs = new Map<string, string>();
          let withoutDefs = s.replace(
            variableDefRegex,
            (_, def: string, value: string) => {
              defs.set(def.trim(), value.trim());
              return "";
            }
          );

          // pass 2: replace variables
          let maxCycles = 1000;
          while (withoutDefs.match(variableUsageRegex)) {
            maxCycles--;
            if (maxCycles <= 0) {
              throw new Error("Max Cycles for replacement exceeded");
            }
            withoutDefs = withoutDefs.replace(
              variableUsageRegex,
              (_, def: string, fallback: string) => {
                const d = def.trim();
                if (defs.has(d)) {
                  return defs.get(d) ?? "";
                }
                return (fallback ?? "").trim();
              }
            );
          }

          // return clean result
          return withoutDefs;
        };
        node.properties = {
          ...node.properties,
          style: resolveVariables(`${node.properties?.style ?? ""}`),
        };
      },
    })
    .use(stringify)
    .processSync(juiced)
    .toString();
  return hyped;
};

interface MailwindOptions {
  /** A path to your tailwind.css file, optimized for email */
  tailwindCss: string;
  /** The base px value for 1rem, defaults to 16px */
  basePx?: number;
  /** Set to `false` to disable extended resets */
  reset?: boolean;
}

const mailwindCss = async (email: string, options: MailwindOptions) => {
  const basePx = options?.basePx ?? 16;

  // cache promise for performance in serverless environments
  if (
    !twcCache.has(options.tailwindCss) ||
    process.env.NODE_ENV === "development"
  ) {
    // console.log("loading styles");
    const p = new Promise<string>((resolve, reject) => {
      readFile(options.tailwindCss)
        .then((buf) => {
          const s = buf.toString();
          // rem to px
          const pxed = s.replace(
            /([\d.-]+rem)/gi,
            (_, value) => `${parseFloat(value.replace(/rem$/, "")) * basePx}px`
          );
          resolve(pxed);
        })
        .catch((reason) => reject(reason));
    });
    twcCache.set(options.tailwindCss, p);
  }

  const s = await twcCache.get(options.tailwindCss);
  if (typeof s === "undefined") {
    throw new Error(`Could not load tailwind css from ${options.tailwindCss}`);
  }

  return inlineStyles(
    email,
    options.reset === false ? s : [resetStyles, s].join("\n")
  );
};

export default mailwindCss;


Document

Tailwind CSS for Email

```yaml
---
slug: use-github-as-a-cms
published: 2022-01-11T11:40:00-08:00
description: GitHub's rich GraphQL API gives you a built-in headless CMS
changelog: ~
---
```

First thing's first. I really love [Ghost](https://ghost.org/). It's got an excellent content and admin API and I'd honestly consider it better than many other Headless CMS options. Second, this isn't a post about Ghost. There were two major shortcomings in Ghost that ultimately I couldn't find good workarounds for.

1. Custom structured data. As it stands I was jamming everything into `codeinjection_foot` as YAML and hoping I didn't ever need that field. I also needed to comment my code explaining all my additional metadata resided in the field not called `metadata`. Yikes.
2. Something that isn't Mobiledoc. I understand why it's used. I don't like that my parsing process on Codedrift requires that I start from the final HTML and then throw it all in [rehype](https://github.com/jakobo/codedrift/blob/9d0bd286355f5b80d1ba71561d78603a9a388ed0/src/components/markup/rehype.js#L25) to [fix URL links, remove widowed text, and more](https://github.com/jakobo/codedrift/blob/0f5991456f576dd031f2e95888af5878a63f16c3/src/graphql/util.js).

HTML to AST back to HTML is not a good feeling and the pipeline was brittle. When I realized I didn’t want to re-add tags on my posts to Codedrift because of the complexity, I looked for alternatives.

I saw [Casual JavaScript](https://github.com/casualjavascript/blog) which was running the entire site off of [GitHub Issues](https://github.com/casualjavascript/blog/blob/gh-pages/index.html). It wasn't perfect, but GitHub Issues are in Markdown, and Markdown _does_ support frontmatter, and frontmatter _is literally designed for metadata_.

The missing piece was something that wasn't issue based. [Discussions](https://github.blog/changelog/2021-02-23-github-discussions-graphql-api-public-beta/). Sold.

## Core Tools
The original Codedrift had a GraphQL micro server that ran everything. It was overengineered (like all good personal projects should be), but in the rewrite I wanted to remove as much of my code as possible. The entire GraphQL infrastructure became a simple [http proxy](https://github.com/jakobo/codedrift/blob/9d5b0349dc204cd1076b54fd5e475dffe449c84d/src/pages/api/proxy/api.github.com/graphql.ts) using [http-proxy-middleware](https://www.npmjs.com/package/http-proxy-middleware). This way I wouldn't need to expose a personal access token in the browser.

The next step was to use [graphql-code-generator](https://www.graphql-code-generator.com/) for Typescript typed Urql hooks. I'm still a fan of Urql, and their [docs for next.js integration](https://formidable.com/open-source/urql/docs/advanced/server-side-rendering/#nextjs) are easy to follow and set up.

Because scope creep is a thing, the site's now also in Typescript. 🥳 

So now I've got typed GraphQL queries to GitHub's API without exposing the access token. All that's left is to get our Discussions, turn them into blog posts, and solve for weird cases like [tag-based searches](https://github.com/jakobo/codedrift/blob/main/src/pages/thunked/tag/%5Bname%5D.tsx#L19) which need to go through the `search` endpoint instead of the `repository` endpoint. Consistency (and sanity) between queries came from the Post fragment.

## The Post Fragment
Fragments are [better explained by graphql.org](https://graphql.org/learn/queries/#fragments), but in context they are the reusable unit of documents. In this case, a fragment on `Discussions` will let me get the same fields every time for our discussion, regardless if I arrived at the Discussion via the `search` endpoint or a `repository` endpoint. Even though it might overfetch a little for its use case, a fragment pushed through graphql-code-generator will give you a typed object representing the returned data structure.

In other words, having this GraphQL fragment
```gql
fragment PostDetails on Discussion {
  id
  title
  lastEditedAt
  url
  labels(first: 100) {
    nodes {
      id
      name
      description
    }
  }
  author {
    avatarUrl(size: 10)
    ... on User {
      id
      name
    }
  }
  body
}
```

Will give us this type in our generated file:
```ts
export type PostDetailsFragment = {
  __typename?: "Discussion";
  id: string;
  title: string;
  lastEditedAt?: any | null | undefined;
  url: any;
  body: string;
  labels?:
    | {
        __typename?: "LabelConnection";
        nodes?:
          | Array<
              | {
                  __typename?: "Label";
                  id: string;
                  name: string;
                  description?: string | null | undefined;
                }
              | null
              | undefined
            >
          | null
          | undefined;
      }
    | null
    | undefined;
  author?:
    | { __typename?: "Bot"; avatarUrl: any }
    | { __typename?: "EnterpriseUserAccount"; avatarUrl: any }
    | { __typename?: "Mannequin"; avatarUrl: any }
    | { __typename?: "Organization"; avatarUrl: any }
    | {
        __typename?: "User";
        id: string;
        name?: string | null | undefined;
        avatarUrl: any;
      }
    | null
    | undefined;
};
```

Even a `Partial<PostDetailsFragment>` adds excellent safeguards to a function when I expect to receive data shaped like the GraphQL response for a Discussion.

## Slugs and Search
Fetching the most recent posts is [a straightforward process](https://github.com/jakobo/codedrift/blob/cbcc0f4beac26e611c14cb789a7adc5b3ba7c55a/src/graphql/posts.graphql#L27) since the API can go from a repository to its discussions and limit those to a single category. For accessing a single post by anything other than its ID, there's only the `search` endpoint.

A generic search on GitHub takes a search query as a string. It's the same string used in [GitHub's Advanced Search](https://github.com/search/advanced?r=jakobo%2Fcodedrift) which at least means it's easy to test and iterate on, even if there is no official query builder. The result is a very generic GraphQL query for searching, which can be used for both slugs and tags. It could probably also be used for the recently created posts, but I'd prefer less magic strings where possible.

```gql
query SelectPostsWithSearch($search: String!, $first: Int = 1, $after: String) {
  search(first: $first, after: $after, type: DISCUSSION, query: $search) {
    nodes {
      ... on Discussion {
        ...PostDetails
      }
    }
    discussionCount
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}
```

The first of two major downside to this approach is I need to constantly cast the node collection to `Discussion`, but I feel that's more my inexperience with Typescript than the language itself. The other is that because when running a search, there's always a risk of returning two records for a search. I briefly thought about changing the URLs to be `slug/post_id` but that felt like it was binding me too closely to GitHub's ID system.

## The New Post Workflow
Posts on Codedrift start in [my public notes](https://codedrift.com/notes), but eventually they’re well-formed enough to get ideas and opinions. At that point, there’s discussion on the draft, which used to exist exclusively over email and Twitter DMs. These processes also worked, but it always felt like I was missing an opportunity for more open discourse about a topic.

So now, when a post grows out of Codedrift, it’ll become an [issue](https://github.com/jakobo/codedrift/issues?q=is%3Aopen+is%3Aissue+label%3A%22%E2%9C%92+Draft%22), When it’s ready to be published, it can be moved to a Discussion, and GitHub saves all of the relevant comments and edits in the transfer. This has the added benefit of matching my mental model. Unposted content is an issue which certainly needs resolution. Posted content deserves a discussion.

The code for all of this is in the [Codedrift repository](https://github.com/jakobo/codedrift), though now that I'm just calling a GitHub API with no interference, the code feels very vanilla. And that feels pretty good.

GitHub's rich GraphQL API gives you a built-in headless CMS

fragment PostDetails on Discussion {
  id
  title
  lastEditedAt
  url
  labels(first: 100) {
    nodes {
      id
      name
      description
    }
  }
  author {
    avatarUrl(size: 10)
    ... on User {
      id
      name
    }
  }
  body
}


export type PostDetailsFragment = {
  __typename?: "Discussion";
  id: string;
  title: string;
  lastEditedAt?: any | null | undefined;
  url: any;
  body: string;
  labels?:
    | {
        __typename?: "LabelConnection";
        nodes?:
          | Array<
              | {
                  __typename?: "Label";
                  id: string;
                  name: string;
                  description?: string | null | undefined;
                }
              | null
              | undefined
            >
          | null
          | undefined;
      }
    | null
    | undefined;
  author?:
    | { __typename?: "Bot"; avatarUrl: any }
    | { __typename?: "EnterpriseUserAccount"; avatarUrl: any }
    | { __typename?: "Mannequin"; avatarUrl: any }
    | { __typename?: "Organization"; avatarUrl: any }
    | {
        __typename?: "User";
        id: string;
        name?: string | null | undefined;
        avatarUrl: any;
      }
    | null
    | undefined;
};


query SelectPostsWithSearch($search: String!, $first: Int = 1, $after: String) {
  search(first: $first, after: $after, type: DISCUSSION, query: $search) {
    nodes {
      ... on Discussion {
        ...PostDetails
      }
    }
    discussionCount
    pageInfo {
      endCursor
      hasNextPage
      hasPreviousPage
      startCursor
    }
  }
}


TypeScript

2022

Tailwind CSS for Email

GitHub as a CMS