
### tldr;

For some reason, I have a particular disdain for writing blog titles and meta descriptions. So I thought "maybe AI could do it for me..."

Turns out, it can. And it's pretty easy.

### Why Use AI for Blog Titles?

Because writing them feels like busy work. And they are usually words that I would struggle to come up with myself. And I hate it. ⛈

### The OG Blog Post Script

On this blog, all of my MDX files are stored in `/src/content/articles`. I have a simple script that let's
me run

```shell
$ yarn article:new some-article-slug-i-like
```

When I run that, it generates a numbered MDX file
in that directory with the appropriate slug. Here's what that script looked like originally:

```js:/scripts/add-article.js
const fs = require('fs')
const path = require('path')

// helper that gets the number of the file from a string like 0001-my-first-post.mdx
function getFileNameIndex(fileName) {
  if (!fileName) return 0
  const match = fileName.match(/^[0-9]+\-/)
  if (!match) return 0
  return parseInt(match[0].slice(0, -1), 10)
}

async function addArticle() {
  // grab the title from the command line arguments
  const title = process.argv[2]
  const directory = process.argv[3] || 'articles'
  const directoryPath = `src/content/${directory}`

  // read the src/content/articles directory and get the last numbered file (e.g. 0035-hello-world.mdx)
  const files = await fs.readdirSync(
    path.join(process.cwd(), directoryPath),
    {
      withFileTypes: true,
    }
  )

  // sort by index and grab the last file
  const lastFile = files
    .filter((file) => file.name.endsWith('.mdx'))
    .sort((a, b) => {
      const aIndex = getFileNameIndex(a?.name) || 0
      const bIndex = getFileNameIndex(b?.name) || 0
      return bIndex - aIndex
    })[0]

  // get the index of the last file
  const index = getFileNameIndex(lastFile?.name) || 0

  // ensure the new index is a string with 4 digits
  const indexString = `${index + 1}`.padStart(4, '0')

  // get the current date in the format YYYY-MM-DD
  const date = new Date().toISOString().split('T')[0];

  // create a new file name with the next index
  const newFileName = `${indexString}-${title.toLowerCase().replace(/ /g, '-')}.mdx`

  // create the new file
  await fs.writeFileSync(
    path.join(process.cwd(), directoryPath, newFileName),
    `---
author: Ty Barho
date: '${date}'
title: ${title}
description:
tags:
---

`
  );
}

async function run() {
  await addArticle()
}

run()
```

And the correspoding `package.json` entry:

```json:/package.json {8}
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "postbuild": "next-sitemap",
    "article:new": "node ./scripts/add-article.js"
  },
}
```

This was a nice setup. If I ran the command
```shell
$ yarn article:new how-to-build-an-mdx-blog-in-next
```

the script would automatically generate a file named `/src/articles/0123-how-to-build-an-mdx-blog-in-next.mdx` with
frontmatter content like this:

```text
---
author: Ty Barho
date: '08/24/2023'
title: "how-to-build-an-mdx-blog-in-next"
description:
tags:
---


```

The bad part? I still have to go write those dang SEO `title`, and `description` attributes. What a pain. 😡

### Setting Up the AI Model

I've been messing with LLM's for the past couple of weeks, and I thought: "Man, I really hate writing blog titles
and meta descriptions. I wonder if ChatGPT could do that for me."

Turns out, it can.

Here's how I edited the script...

```js:/scripts/add-article.js {3-16,58-95}
const fs = require('fs')
const path = require('path')
const OpenAI = require('openai')

require('dotenv').config({
  path: path.join(process.cwd(), '.env.development.local'),
})

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const defaultModelOptions = {
  model: 'gpt-3.5-turbo',
  stream: false,
}

function getFileNameIndex(fileName) {
  if (!fileName) return 0
  const match = fileName.match(/^[0-9]+\-/)
  if (!match) return 0
  return parseInt(match[0].slice(0, -1), 10)
}

async function addArticle() {
  // grab the title from the command line arguments
  const title = process.argv[2]
  const directory = process.argv[3] || 'articles'
  const directoryPath = `src/content/${directory}`

  // read the src/content/articles directory and get the last numbered file (e.g. 0035-hello-world.mdx)
  const files = await fs.readdirSync(path.join(process.cwd(), directoryPath), {
    withFileTypes: true,
  })

  const lastFile = files
    .filter((file) => file.name.endsWith('.mdx'))
    .sort((a, b) => {
      const aIndex = getFileNameIndex(a?.name) || 0
      const bIndex = getFileNameIndex(b?.name) || 0
      return bIndex - aIndex
    })[0]

  // get the index of the last file
  const index = getFileNameIndex(lastFile?.name) || 0

  // ensure the index is a string with 4 digits
  const indexString = `${index + 1}`.padStart(4, '0')

  // get the current date in the format YYYY-MM-DD
  const date = new Date().toISOString().split('T')[0]

  // create a new file name with the next index
  const newFileName = `${indexString}-${title
    .toLowerCase()
    .replace(/ /g, '-')}.mdx`

  try {
    const training = [
      { role: 'system', content: '[your base training here]' },
      { role: 'user', content: '0001-sample-post-1' },
      { role: 'assistant', content: '[example response 1]' },
      { role: 'user', content: '0002-sample-post-1' },
      { role: 'assistant', content: '[example response 2]' },
    ]

    const response = await openai.chat.completions.create({
      ...defaultModelOptions,
      messages: [
        ...training
      ],
    })

    const res = response.choices[0].message.content
    const ai = JSON.parse(res)

    const content = `---
author: Ty Barho
date: '${date}'
title: "${ai.title}"
description: "${ai.description}"
tags: ${ai.tags}
---

  `

    // create the new file
    await fs.writeFileSync(
      path.join(process.cwd(), directoryPath, newFileName),
      content
    )
  } catch (e) {
    console.error(e)
    process.exit(1)
  }
}

async function run() {
  await addArticle()
}

run()
```

After a litle prompt engineering, it worked like a charm! For example, if I run it with this command:

```bash
$ yarn article:new writing-an-automated-keyword-finder-with-puppeteer-and-ai
```

Here's the frontmatter I get:

```text
---
author: Ty Barho
date: '2023-10-18'
title: "Automated Keyword Finder using Puppeteer and AI"
description: "Learn how to build an automated keyword finder using Puppeteer to scrape search engine results and AI algorithms for keyword analysis."
tags: automation,puppeteer,ai,keyword-analysis,web-scraping
---

```

Now, instead of writing all that from my already addled brain, I can do some quick edits, and I'm done.

Pretty neat, huh? 😎🤖

### Prompt Engineering Example

For simplicity, I didn't include my training data above, just so you could read the code more clearly. But, for those
who don't yet have a lot of experience with engineering these prompts, here they are for you to tweak to your
use case.

#### The System Prompt

We start with the system prompt, which gives the LLM some basic parameters to operate by.

> yellow:"Woe" I'm still working through getting System prompts to "obey" me well. Often, some of my instructions are ignored.
> I've found using language like "You may NEVER" or the Question/Answer format work most of the time, though I still get errors.

```js
{
  role: 'system',
  content: `
You are a bot that cleans blog post titles and generates tags and descriptions.
Titles must be grammatically correct.
Descriptions must be between 50 and 160 characters.
Here is an example:
<input>0014-adding-a-copy-button-mdx-code-snippets.mdx</input>
<output>
{
  "title": "Add a Copy Button to Your Rehype (NextJS / MDX) Code Snippets",
  "description": "In this article I'll show you how to add a convenient copy button to Rehype code snippets in your NextJS MDX blog.",
  "tags": "nextjs,mdx"
}
</output>

Please note that tags should be short abbreviations.
Example: artificial-intelligence = ai
Example: natural-language-processing = nlp
`,
}
```

#### The User / Assistant Prompts

These are where you give examples of expected output. This is called "multi-shot" prompt engineering,
and IMO, this is where the meat of completion goodness happens. Make sure these are solid.

```js
;[
  { role: 'user', content: `0016-nextjs-convertkit-blog-subscriber-form.mdx` },
  {
    role: 'assistant',
    content: `{
  "title": "Newsletter Subscriptions with NextJS & ConvertKit",
  "description": "In this article, I'll teach you how to create a newsletter subscription form in NextJS, and connect to ConvertKit using NextJS api routes.",
  "tags": "nextjs,convertkit,react-hook-form,yup,api"
}`,
  },
]
```

I'm only using one-shot prompting here.  You probably want to use 2 or 3 of these "shots".

> indigo:"JSON Output" Notice that in both my `system` and `assistant` prompts, I am responding in JSON. This has proven
> effective in ensuring that I only get responses in JSON that I can parse.

### Next Steps

So far, this has been a super useful time-saver. If I were looking at where to take this next, I might
extend this by chaining another trained model to revise the description for specific SEO keywords & density,
or possibly ensure that titles are more directly related to posts that I've already created, from a content
perspective.

In the meantime, I'm just really happy that I don't have to write blog titles or meta descriptions by hand
anymore 😅.

Hope this helps someone, and happy coding! 🦄


Learn how to use AI to generate catchy and engaging blog titles for your MDX blog, and attract more readers to your content.

Generating AI-Powered Blog Titles for Your MDX Blog


I've recently jumped into prompt engineering with both feet, but found myself rewriting a lot of the same
boilerplate code when engineering new prompts. If you take a look at 2 of the tools I've added to this site:

1. [TailwindCSS + React Hook Form Generator](/tools/tailwindcss-forms-ai-generator)
2. [AI Spec Generator](/tools/ai-spec-generator)

They are pretty close to the same UI, but the API code for them was almost identical. So? DRY.

# tldr;

Vercel AI + Open AI makes building new AI experiences fast. Adding a little abstraction makes it even faster. 💥

### The Original Vercel AI API Route

To get started with Vercel AI, I basically just ripped their code from the docs [here](https://sdk.vercel.ai/docs/concepts/caching). No biggie. I added a little
training data, and some code examples, so that my first attempt at a streaming AI API route looked like this:

```js:/api/ai/code/index.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const modelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

const training = [
  { role: 'system', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
];

export default async function handler(req) {
  const { messages } = await req.json()
  const key = `${prefix}-${JSON.stringify(messages)}`

  // Check if we have a cached response in production
  const cached = DEV ? null : await kv.get(key)

  if (cached) {
    const chunks = cached.split(' ')
    // Emulate the "stream" interface, even if we're cached
    const stream = new ReadableStream({
      async start(controller) {
        for (const chunk of chunks) {
          const bytes = new TextEncoder().encode(chunk + ' ')
          controller.enqueue(bytes)
          await new Promise((r) =>
            setTimeout(
              r,
              // get a random number between 10ms and 50ms to simulate a random delay
              Math.floor(Math.random() * 40) + 10
            )
          )
        }
        controller.close()
      },
    })
    return new StreamingTextResponse(stream)
  }

  const response = await openai.chat.completions.create({
    ...modelOptions,
    messages: [...training, ...messages],
  })

  const stream = OpenAIStream(response, {
    async onCompletion(completion) {
      // Cache the response. Note that this will also cache function calls.
      if (DEV) {
        return;
      }

      await kv.set(key, completion)
      await kv.expire(key, 60 * 60)
    },
  })

  return new StreamingTextResponse(stream)
}

```

Not bad, considering it even implements caching for cost savings on responses.  But then,
when I went to build the second AI API route (the one for my [spec tool](/tools/ai-spec-generator)), I realized I was
basically identically copying all the meat of this handler, with the exception of the training
data.

There are a couple of ways you could handle this:

1.  Add the training data in an api request to a single ChatGPT completion endpoint
2.  Abstract the creation of AI api handlers into a function that accepts additional training data

Ultimately, I opted for #2, simply because having all that training data in React components
seemed like a weird place for it to live, and I like the flexibility of different API endpoints per bot 🤖.

Maybe I want to extend them, or chain them... who knows.  This is all new to me.

Anyway, here's the simple abstraction, and a sample implementation, for your reusing pleasure.

```js:/lib/createAIHandler.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const defaultModelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

export default function createAIHandler({
  prefix,
  training = [],
  modelOptions = defaultModelOptions,
}) {
  // Return a function, that is the handler
  return async function (req) {
    const { messages } = await req.json()
    const key = `${prefix}-${JSON.stringify(messages)}`
    // Check if we have a cached response
    const cached = DEV ? null : await kv.get(key)

    if (cached) {
      const chunks = cached.split(' ')
      const stream = new ReadableStream({
        async start(controller) {
          for (const chunk of chunks) {
            const bytes = new TextEncoder().encode(chunk + ' ')
            controller.enqueue(bytes)
            await new Promise((r) =>
              setTimeout(
                r,
                // get a random number between 10ms and 50ms to simulate a random delay
                Math.floor(Math.random() * 40) + 10
              )
            )
          }
          controller.close()
        },
      })
      return new StreamingTextResponse(stream)
    }

    const response = await openai.chat.completions.create({
      ...modelOptions,
      messages: [...training, ...messages],
    })

    const stream = OpenAIStream(response, {
      async onCompletion(completion) {
        // Cache the response. Note that this will also cache function calls.
        if (DEV) {
          return;
        }
        
        await kv.set(key, completion)
        await kv.expire(key, 60 * 60)
      },
    })

    return new StreamingTextResponse(stream)
  }
}
```

Pretty simple wrapper, eh?

Now, here's how you use it in a sample AI route for generating animal names:

```js:/api/ai/animal-names/index.js
import createAIHandler from '@/lib/createAIHandler'

export const runtime = 'edge'

const training = [
  { role: 'system', content: `
You are a bot that can ONLY respond with made up animal names.
Include a person's name, an adjective, a color, and an animal name.

<example>
Bart, the Slippery Green Walrus.
</example>
` },
  { role: 'user', content: 'Give me an animal name'  },
  { role: 'assistant', content: 'Sue, the Hilarious Yellow Antelope.' },
  { role: 'user', content: 'How are you?'  },
  { role: 'assistant', content: 'Jeff, the Angry Red Hare.' },
]

export default createAIHandler({
  prefix: 'animal-bot',
  training,
})
```

Lastly, wire it up in your component:

```jsx:/pages/animal-name-generator.jsx
import { useChat } from 'ai/react'

export default function Page() {
  
  const { messages, handleSubmit, input, handleInputChange } = useChat({
    api: '/api/ai/animal-names',
  });

  return (
    <>
      // Your chat UX
    </>
  )
}
```

I'm not gonna go into building forms and chat UX here, but good starting places are:

- [TailwindUI Feeds](https://tailwindui.com/components/application-ui/lists/feeds)
- [How I build forms](/articles/react-fast-performant-forms)
- [My AI Tailwind Form Generator](/tools/tailwindcss-forms-ai-generator)

Hope this helps you ramp up on your AI skillz, and happy coding! 😎

Learn how to abstract a Vercel OpenAI handler to quickly build and deploy AI-powered tools and applications.

Abstracting a Vercel OpenAI Handler for Quick AI Tools


So you have a complete set of product mocks... How do you get this thing over the finish line in record time?

In this guide, I'll teach you the 4 step process I use with my teams.

- [Step 1 - Reduction](#reduction)
- [Step 2 - Inversion](#inversion)
- [Step 3 - Velocity](#velocity)
- [Step 4 - Build!](#build)

<div id="reduction"></div>

# Step 1 - Reduction

Reduction is the process of understanding the whole of what you've drawn (that's right, product mocks are just drawings) as the sum of its parts.

#### Why Reduce?

If you're wondering what the point of this reduction exercise is, you're not alone.  Let's look at this in terms we can all understand and identify with.

#### A Tiny Project

Let's say you have a 4 screen app, like a TODO app.  You could pretty easily just open up your editor (vscode), get cracking, and knock a nice little app out with little or no effort toward organizing your work.

And you're probably not going to notice any speed loss, because the project is so small.  If you do it fast, it takes a day.  If you do it slow, it takes 1.5.  Not a huge hit in clock time.

#### A Large, Team-Driven Project

Large projects are another animal.  We have all likely worked on teams of 4+ people where it's difficult to know who's doing what, and we eventually blow a deadline set by executive OKR.  We know that we need every little speed lift we can get.

Common lines I hear from engineering groups (even teams that I run) when these deadlines are missed are:
- "Well, it takes as long as it takes." 
- "You can't put time deadlines on on-demand invention."

But I beg to differ.  I believe that with some smart organizational effort (i.e. Reduction), you can

1. Dramatically improve your teams pace
2. Quickly understand what your team can accomplish within a time frame

## How to Reduce a Project

So we now understand WHY the process of reduction is important:  It gains us speed & clarity in large, team-oriented projects.

Now, we'll understand HOW to reduce a set of Mocks into a consumable task list that engineering can jump on.

You're going to start with 3-4 major buckets, and IN ORDER, go through each of these buckets, creating a list of items.

Here are your buckets:

<Table
  headings={['SCREENS', 'COMPONENTS', 'INFRASTRUCTURE', 'API']}
  rows={[
    ['', '', '', '']
  ]}
/>

**Remember that ORDER IS IMPORTANT**

<div id="screens"></div>

## Screens

This is where you will start.  At this point, SCREENS are the easiest thing for you list off, because you're literally looking at the list of them in your Mocks.

> zinc:"Tip: Choose a good issue tracker" Your issue tracker is an important decision, as you'll be working it in daily.  I love Pivotal Tracker for it's speed, velocity tracking, fast imports and visualization of staged Epics.
> <br /><br />
> I hate JIRA.  I won't hate you if you choose JIRA, just know that every time a product organization chooses JIRA, a fairy and her puppy both die.

For each screen in your list of Mocks, just list them out.  You could do this in a spreadsheet, like this:

<Table
  headings={['EPIC: SCREENS', 'Mock', 'Points']}
  rows={[
    ['SignIn',<a>link</a>,'3'],
    ['SignUp',<a>link</a>,'3'],
    ['ForgotPassword',<a>link</a>,'3'],
    ['Dashboard',<a>link</a>,'3'],
    ['Posts',<a>link</a>,'3'],
    ['Post',<a>link</a>,'3'],
    ['PostNew',<a>link</a>,'3'],
    ['PostEdit',<a>link</a>,'3'],
    ['...','',''],
  ]}
/>


But I prefer to just duplicate lines in VSCode, so I would have an import .csv string going that looked like this:

```csv
Id,Type,Title,Labels,Estimate,Description
,Feature,SignIn,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,SignUp,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,ForgotPassword,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,Dashboard,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,Posts,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,Post,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,PostNew,"MYAPP - SCREENS",3,link-to-mock-screen
,Feature,PostEdit,"MYAPP - SCREENS",3,link-to-mock-screen
...
```

> yellow:"TIP" For now put a point value of 3 for each your screens.  We'll come back to this later, when we rapidly apply velocity tracking

This is ready to highlight and paste into Pivotal Tracker's .csv importer.

> indigo:"SPEED" This is extremely fast to build in vsCode using CMD+SHIFT+D to duplicate lines for each screen, then CMD+D to select the Title and change it.  You can reduce 100 screen application in just a few minutes.  It's even faster if you pattern your screen links.



Now, you've defined (reduced) your screens, and everything is accounted for.  Feel free to import your .csv to Pivotal Tracker.  The result would look something like this:

![image](https://user-images.githubusercontent.com/863020/69681645-5108bf80-1074-11ea-9ef9-c644279a31ea.png)


## Components

The next piece we'll reduce is our components.  We did [Screens](#screens) first because it was the fastest and easiest.  The same is now true for Components.

#### What is a Component?

Any piece of functionality commonly reused.  A component could be as simple as a `Button`, or as complex as a `SqueezePageDownloadForm`.  As long as it's used in more than one screen, it's a component.

> zinc:"TIP" There is one exception that I'll occasionally make to this rule, and that is for extremely complex components that need to be built in isolation.  It may not be technically used in more than one place, but if you need to build it in isolation to keep firm separation of concerns, I would classify it as a component.

To reduce your components, **for each screen**:
1. Open the mock for that screen
2. Make a list of components used on that screen

Keep doing this for all of your screens, until you have one big long list of components, that looks something like (ignore the comments):

```bash
TextInput    # SignIn - Email Input
TextInput    # SignIn - Password Input
Button       # SignIn - Sign In Button
Link         # SignIn - Create Account Link
Link         # SignIn - Forgot Password Link
TextInput    # SignUp - Email Input         
TextInput    # SignUp - Password Input
TextInput    # SignUp - Confirm Input      
Button       # SignUp - Create Account Button
Link         # SignUp - Sign In Link
...
```

It's fine to have duplicates, but...

#### Why duplicate?

1. Being systematic helps you be more thorough and deliberate about each screen
2. It's really easy to dedupe them

To dedupe your list, you can use this <a href="/tools/deduplication-software" target="_blank">simple deduper</a>.

Once you have your deduped list, you can now add them to Pivotal Tracker, or your tool of choice.

## Infrastructure

The next, and often final, section of reduction is Infrastructure.  The items in this list or epic will be any and all architectural decisions about how your application is to be developed.

A typical Infrastructure list would look something like:

<Table
  headings={['Epic - INFRASTRUCTURE', 'Points']}
  rows={[
    ['Create repo','3'],
    ['Setup CI','3'],
    ['Conventional Commits','3'],
    ['Framework Setup','3'],
    ['Storybook','3'],
    ['Webpack Config','3'],
    ['Linter Setup','3'],
    ['Prettier Setup','3'],
    ['App Booting & Loading','3'],
    ['MaterialUI // Semantic Setup','3'],
    ['Theming','3'],
    ['Routing','3'],
    ['Assets & Image Loading','3'],
    ['Apollo Setup','3'],
    ['Firebase Setup','3'],
    ['Authentication','3'],
    ['withPermissions() - HOC','3'],
  ]}
/>


or, in Pivotal .csv...

```
Id,Type,Title,Labels,Estimate,Description
,Feature,Create repo,"MYAPP - INFRASTRUCTURE",3,
,Feature,Setup CI,"MYAPP - INFRASTRUCTURE",3,
,Feature,Conventional Commits,"MYAPP - INFRASTRUCTURE",3,
,Feature,Framework Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,Storybook,"MYAPP - INFRASTRUCTURE",3,
,Feature,Webpack Config,"MYAPP - INFRASTRUCTURE",3,
,Feature,Linter Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,Prettier Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,App Booting & Loading,"MYAPP - INFRASTRUCTURE",3,
,Feature,MaterialUI // Semantic Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,Theming,"MYAPP - INFRASTRUCTURE",3,
,Feature,Routing,"MYAPP - INFRASTRUCTURE",3,
,Feature,Assets & Image Loading,"MYAPP - INFRASTRUCTURE",3,
,Feature,Apollo Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,Firebase Setup,"MYAPP - INFRASTRUCTURE",3,
,Feature,Authentication,"MYAPP - INFRASTRUCTURE",3,
,Feature,withPermissions() - HOC,"MYAPP - INFRASTRUCTURE",3,
```

> yellow:"TIP" Be thorough.  Get the leadership team together and make these decisions together.  The list will be more accurate, and you'll have more buy-in on decisions from day 1.

## API

Occasionally, your app will require either some API functionality be changed or added, or an entirely new API being built.

That's beyond the scope of this post (I hope to build write on how I build API's in the near term), but for lighter changes
 (a couple of endpoints changed or added), I would just do a small reduction of the required changes in an API epic.  For example:

<Table
  headings={['Epic - API', 'Points']}
  rows={[
    ['endpoint - /posts','3'],
    ['endpoint - /post/:id','3'],
    ['endpoint - /post/new','3'],
    ['endpoint - /post/:id/edit','3'],
  ]}
/>

or...

```
Id,Type,Title,Labels,Estimate,Description
,Feature,endpoint - /posts,"MYAPP - API",3,
,Feature,endpoint - /post/:id,"MYAPP - API",3,
,Feature,endpoint - /post/new,"MYAPP - API",3,
,Feature,endpoint - /post/:id/edit,"MYAPP - API",3,
```

... respectively.

Import to your tracker, and you're ready for the next step.

At this point, your board should look something like this:

![image](https://user-images.githubusercontent.com/863020/69679394-9d043600-106d-11ea-952c-cf280a50403f.png)

<div id="inversion"></div>
# Step 2 - Inversion

So far, we have effectively [Reduced](#reduction) our application mocks into actionable items, and imported them to our board.

We used the order of `SCREENS > COMPONENTS > INFRASTRUCTURE > API` to achieve this as quickly as possible.

Now, we need to **build** it as quickly as possible.  How do we do this?

## Reversing the Epics

Take a look at what happens if you reverse the order of how we reduced:

`API > INFRASTRUCTURE > COMPONENTS > SCREENS`

Looks like a pretty sensible way to build our app, right?

Let's dig a little deeper to make it sticky:

#### #1 - API
We build this first.  This ensure's that our client has everything it needs to persist data, authenticate, etc.

#### #2 - INFRASTRUCTURE
Next, we strap up all of the infrastructure and patterns we need for our application to work, scale, and have good developer stories.

#### #3 - COMPONENTS
Third, we build out our list of components.  These will be the building blocks of our screens, and make screen develop incredibly fast.

#### #4 - SCREENS
Lastly, we build out our final screens.  Because we have routing, data fetching, permissions, and components all built up, this is as quick and painless as possible.

Inversion of our epic order gives us a succint build path, optimized for speed.  We now know what we're going to build, and exactly how we're going to build it.

There's one final step for project success, and that is setting up our [Velocity](#velocity).

Once you have inverted your board, it should look something like this:

![image](https://user-images.githubusercontent.com/863020/69679551-05ebae00-106e-11ea-9fe0-4cdd995688e9.png)

<div id="velocity"></div>

# Step 3 - Velocity

So far we've answered:

- What we're going to build - [Reduction](#reduction)
- How we're going to build it - [Inversion](#inversion)

Now we need have a base understanding of **How fast can we build it** by setting up and tracking our Velocity.

#### Guiding the Ship

The purpose of tracking our Velocity is two-fold:

1.  To know how fast we did a thing
2.  So that we can more accurately guess how fast we'll do another thing

If we can achieve #2, it will help us understand, as an organization, the body of work that we can get through in a week / month / year, so that we can better plan our product roadmap.

#### Point Values

To begin tracking your Velocity, you need to add point estimates to each item in the Epics from your [Inversion](#step-2---inversion).

I typically use an adjusted Fibonacci scale for tracking:

```
0,1,2,3,5,8,13,25
```

> yellow:"Don't Decide" The point values are aribitrary at this point.  Eventually, they will have a rough time meaning, but for now, try to avoid associating point values with time (e.g. saying 3 points means 1 developer day is BAD)

> blue:"Bugs & Chores" I typically use 0 points for chores and bugs <br />
> I typically use 25 points for placeholding Epics that need to be broken down later

<div id="points"></div>

#### Deciding on Point Values

There are many ways to decide on point values, but I typically prefer a variation on Planning Poker using at least 2, but no more than 4 team members.  The basics are:

1. Start with the first item in an Epic
2. Each member picks a point value for the item **(10 seconds)**
3. If all members agree, set the point value and move to the next item
4. If not all members agree, discuss why, and come to a consensus. **(2 minutes)**

> blue:"Majority vs. Unanimous" Another effective variation on this is to use a simple majority vote, and only enact #4 if there is no majority.

#### Setting Up Velocity

With the fundamentals in place, you're now ready to set point values for your `API > INFRASTRUCTURE > COMPONENTS > SCREENS` epics.

For each of these Epics, use the [Deciding Point Values](#points) methodology (or your own), and assign point values to all items.

If you haven't imported to Pivotal yet, do this in your .csv import file.  Otherwise, use the Pivotal UI to set the values.

![image](https://user-images.githubusercontent.com/863020/69679610-23207c80-106e-11ea-9915-b1500e5c6e3b.png)

#### Predicting the Future

After your first full week of development, Pivotal will automatically adjust your default velocity, based on the points you achieved that week.

You can then open the Current/Backlog panel and see how many weeks your build will likely take, based on that point value.

![image](https://user-images.githubusercontent.com/863020/69679746-87dbd700-106e-11ea-8798-48e8d4b3e684.png)

<div id="build"></div>
# Step 4 - Build & Adjustments

Congratulations!  You have effectively boarded out a major project!  You:

✅ Know what you're going to build<br />
✅ Know how you're going to build it<br />
✅ Can make more educated guesses at how long it will take<br />

#### Scope Changes

Now that you're building, your biggest worry is going to be feature and scope changes.  Don't fret, though, because you have better assets than you used to.

#### When a mock changes...

Simply audit the mock the way you did, following `SCREENS > COMPONENTS > INFRASTRUCTURE > API` order, and update or add new items as needed.

If the work is already in flight, coordinate directly with the developer when you update the items, so the developer understands and can provide input on the impact of the change.

#### When new mocks are added...

Again, same deal.  Just follow `SCREENS > COMPONENTS > INFRASTRUCTURE > API`, and new items as needed.

## Other Tips for building fast

Here are some additional tips for building quickly:

-  **Lock spec & mocks.**<br />  Designers be designing.  Once boarded, lock the mocks, and inform designers that no new creep will be allowed in this cycle.  All changes will be viewed as new work, in a new cycle.<br /><br />
-  **Keep it tight.** <br /> Make sure your engineers aren't constantly tied up in meetings, etc.  Let them work.  Have a 15 minute / day board review, at most.<br /><br />
-  **Use Storybook.** <br /> Personally, I would set a hard requirement that all components be built with Storybook.  You get better components, faster.<br /><br />
-  **Take Time with Patterns.** <br /> Don't rush your application patterns, like routing, theming, etc.  Spend time coming up with patterns that are fast and flexible, and provide a clean developer story.<br /><br />


### **Now go build!** 🏎 



This guide shows you how I go from wireframes to a fully-baked software estimate and product board in minutes, not days.

Spec in hours.  Not weeks.

Better. Software. Faster. - Part I:  Mocks → Board.


Newsletter subscriptions are a mixed bag for me.  On the one hand, from a marketing perspective, your subscriber
list (that you own, and not FB or [X](https://www.twitter.com/hostmonk)) is probably your most valuable asset.

On the other hand, writing newsletters is a pain.

My goal here, I think, is to put in place something EXTREMELY automated... something along the lines of:

- Write an MDX blog post
- Commit to Git
- Vercel auto-deploys (already happens)
- Git hook fires to an API route
- A newsletter is drafted and sent to my contacts

That would be nice.  We'll see if I can get there eventually.  But for today, I just need a way to
let subscribers register from the site.

> zinc:"Email Platforms" **Full disclosure:** This is the first time I'm trying [ConvertKit]().
> I'm not an email marketing expert, but I have tried quite a few different platforms.
> In the past I have used [SendGrid](), [MailChimp](), [Brevo](), [PostMark](), and a handful of others.
> So far I haven't yet found a platform that fits 100% of my specific needs, which are:
> <br /><br />
> - Good API (bonus points for SDK)
> - Can send plain text emails
> - Easy, robust sequences
> - Cost effective at low volume
> - Paid & Free newsletter options
> <br />
> [ConvertKit]() seems to get close, which is why I'm trying it out.  If you have a recommendation, please share it on [Twitter]()

So with that out of the way, let's get started! ⚡️

### Create a ConvertKit Account

First things first, head over and [create an account at ConvertKit](https://convertkit.com/).

### Set up a contact group

Once you've created an account, you're going to want to create a tag to bucket users that register from your site.

So go to **Grow > Subscribers** from the nav bar...

![convertkit-shot-1](/images/convertkit-shot-1.png)

Then at the bottom right, click **+ Create a Tag** (it's small and hard to find... ahem 😳).

![convertkit-shot-2](/images/convertkit-shot-2.png)


### Add a NextJS /api route

Now, we want to create a NextJS /api route that adds a subscriber to our list, with the new tag
we have created.

Head over to the [ConvertKit api docs](https://developers.convertkit.com/#add-subscriber-to-a-form).

You can see from the API docs that the call we want looks like this:

```shell
# Include a tag during subscribing
curl -X POST https://api.convertkit.com/v3/forms/<form_id>/subscribe\
     -H "Content-Type: application/json; charset=utf-8"\
     -d '{ \
           "api_key": "<your_public_api_key>",\
           "email": "jonsnow@example.com",\
           "tags": [1234, 5678]\
         }'
```

So we'll need a few things to get this going:

```
1.  <form_id>
2.  <your_public_api_key>
3.  [1234,5678]  # our tag ids
```

First, let's find the Form ID...

<Loom src="https://www.loom.com/embed/23ebd3d1f7b24c95ab0d4de70a0206ba?sid=3d14cc4f-e5ee-4542-8672-b03f711ec0d6" />

Now, to get your **public_api_key**, just head over to [your ConvertKit account settings](https://app.convertkit.com/account_settings/advanced_settings).

In the Advanced section, you'll find your API key.

Lastly, we need to find our Tag IDs, which is similar to finding out our form id.

<Loom src="https://www.loom.com/embed/5763f1a5acd4410886816865cf1dd8db?sid=703bd64b-3d97-49cd-a9e2-253ccb407683" />

We are going to want to set both of these as [environment variables](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables) in our NextJS app.  So let's create a file called `.env.local` and paste in the following:

```shell
CONVERTKIT_PUBLIC_API_KEY=your_public_api_key   # Be sure and make these the actual values you got above
CONVERTKIT_SUBSCRIBE_FORM_ID=form_id            # Be sure and make these the actual values you got above
```

> indigo:"Note" You'll need to restart your dev server for these changes to take effect.

Now, we're ready to make our API route.

Create a new file at `/api/newsletter-subscribe`, and add the following code:

```js:/api/newsletter-subscribe.js
// Next.js API route support: https://nextjs.org/docs/api-routes/introduction
export default async function handler(req, res) {
  const { email } = req.body

  if (!email) {
    // Tell developers when they are missing params
    res.status(400).json({ message: 'No email address provided.' });
    return;
  }

  const api_key = process.env.CONVERTKIT_PUBLIC_API_KEY;
  const formId = process.env.CONVERTKIT_SUBSCRIBE_FORM_ID;

  if (!api_key || !formId) {
    // Don't tell people about internal server errors
    res.status(500);
    return;
  }

  const url = `https://api.convertkit.com/v3/forms/${formId}/subscribe`;
  const tags = [4062331];

  try {
    const body = JSON.stringify({ api_key, email, tags })

    // POST a request to the ConvertKit endpoint
    await fetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json; charset=utf-8'
      },
      body,
      redirect: 'follow'
    });

    // Send a non-descriptive success response
    res.status(200).json({ success: true });
  } catch(e) {
    // Don't tell people about internal server errors
    res.status(500);
  }
}

```

Now, let's see if our API route works using a cURL request from our command line.

```shell
curl --location --request POST 'http://localhost:3000/api/newsletter-subscribe' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[youremail]+newsletter@gmail.com"
}'
```

> indigo:"Real Email" ConvertKit sends a confirmation email that you have to click to actually subscribe, so be sure to send to
a real email address.<br /><br />
> I tend to just at a `+newsletter` to my normal Gmail account, like **ty+newsletter@[yourdomain].com**.

If everything works, you should get a line back like this:

```shell
{"success":true}
```

Once you've confirmed your subscription, go back to your [ConvertKit Subscribers](https://app.convertkit.com/subscribers), and you should see **test@example.com** in your 
subscribers list!

> zinc:"On security..." From the NextJS docs...<br /><br />
> ```API Routes do not specify CORS headers, meaning they are same-origin only by default. You can customize such behavior by wrapping the request handler with the CORS request helpers.```
> <br /><br />
> So where we would typically need to add some sort of security, Next takes care of this for us.

Now, alls we need is a form. 🛠

### Create the Subscribe Form

I'm gonna burn through this with a couple of big code blocks, so if you're new to forms be sure to check out my post
on [quickly building forms with NextJS, React Hook Form, and TailwindCSS](/articles/react-fast-performant-forms).

Create a new file at `/components/Newsletter.jsx` and paste the following code:

```jsx:/components/Newsletter.jsx
import { useState } from 'react'
import { useForm } from 'react-hook-form'
import * as yup from 'yup'
import { yupResolver } from '@hookform/resolvers/yup'

import { Button } from '@/components/Button'

const schema = yup.object().shape({
  email: yup
    .string()
    .email('Please enter a valid email.')
    .required('Email address is required.'),
})

function MailIcon(props) {
  return (
    <svg
      viewBox="0 0 24 24"
      fill="none"
      strokeWidth="1.5"
      strokeLinecap="round"
      strokeLinejoin="round"
      aria-hidden="true"
      {...props}
    >
      <path
        d="M2.75 7.75a3 3 0 0 1 3-3h12.5a3 3 0 0 1 3 3v8.5a3 3 0 0 1-3 3H5.75a3 3 0 0 1-3-3v-8.5Z"
        className="fill-zinc-100 stroke-zinc-400 dark:fill-zinc-100/10 dark:stroke-zinc-500"
      />
      <path
        d="m4 6 6.024 5.479a2.915 2.915 0 0 0 3.952 0L20 6"
        className="stroke-zinc-400 dark:stroke-zinc-500"
      />
    </svg>
  )
}

export function Newsletter() {
  const [success, setSuccess] = useState(false)
  const [serverError, setServerError] = useState(null)

  const {
    register,
    handleSubmit,
    reset,
    formState: { errors, isSubmitting },
  } = useForm({
    resolver: yupResolver(schema),
  })

  async function onSubmit(values) {
    // We'll wire this up next...
    console.log(values);
  }

  return (
    <form
      onSubmit={handleSubmit(onSubmit)}
      className="rounded-2xl border border-zinc-100 p-6 dark:border-zinc-700/40"
    >
      <h2 className="flex text-sm font-semibold text-zinc-900 dark:text-zinc-100">
        <MailIcon className="h-6 w-6 flex-none" />
        <span className="ml-3">Stay up to date</span>
      </h2>
      <p className="mt-2 text-sm text-zinc-600 dark:text-zinc-400">
        Get notified when I publish something new, and unsubscribe at any time.
      </p>
      <div className="mt-6 flex">
        <input
          {...register('email')}
          type="email"
          placeholder="Email address"
          aria-label="Email address"
          className="min-w-0 flex-auto appearance-none rounded-md border border-zinc-900/10 bg-white px-3 py-[calc(theme(spacing.2)-1px)] shadow-md shadow-zinc-800/5 placeholder:text-zinc-400 focus:border-indigo-500 focus:outline-none focus:ring-4 focus:ring-indigo-500/10 dark:border-zinc-700 dark:bg-zinc-700/[0.15] dark:text-zinc-200 dark:placeholder:text-zinc-500 dark:focus:border-indigo-400 dark:focus:ring-indigo-400/10 sm:text-sm"
        />

        <Button type="submit" className="ml-4 flex-none">
          {isSubmitting ? 'Joining' : 'Join'}
        </Button>
      </div>
      {errors?.email || serverError ? (
        <div className="ml-3 mt-2 text-xs font-light text-red-600">
          {errors?.email?.message || serverError}
        </div>
      ) : null}
      {success ? (
        <div className="ml-3 mt-3 text-xs font-light leading-5 text-green-700">
          Thanks for joining! Check your email for a confirmation.
        </div>
      ) : null}
    </form>
  )
}

```

This should give you a presentable looking Tailwind newsletter subscribe form, complete with
schema-based validation, and ready for server errors & success messages.

### Wire the Form up to the /api route

Now we need to connect our form up to our API route.

We will handle this in our `onSubmit()` handler that we provided to the form.

```jsx:/components/Newsletter.jsx showLineNumbers

//... rest of file

export function Newsletter() {
  const [success, setSuccess] = useState(false)
  const [serverError, setServerError] = useState(null)

  const {
    register,
    handleSubmit,
    reset,
    formState: { errors, isSubmitting },
  } = useForm({
    resolver: yupResolver(schema),
  })

  async function onSubmit(values) {
    // Reset the server error (if there is one)
    setServerError(null)

    // Grab the email off of the form values
    const { email } = values

    try {
      // Send the request to our API
      await fetch('/api/newsletter-subscribe', {
        method: 'POST',
        // Be sure and set the content type header if using fetch()
        headers: {
          'Content-Type': 'application/json; charset=utf-8',
        },
        body: JSON.stringify({
          email,
        }),
      })

      // Set success to true to show the success message
      setSuccess(true)
      // Reset the form
      reset()

      // Hide the success message after a while
      setTimeout(() => {
        setSuccess(false)
      }, 3000)
    } catch (e) {
      // Log the error, and set server error message
      console.error(e)
      setServerError('There was an error subscribing.')
    }
  }

  

  return (
    {/* ... our form ...*/}
  )
}

```

And that's it!  With that in place, you should have a nice Newsletter form that looks like this:

<Newsletter />

The last thing we need to do is wire up our environment variables to Vercel deployments.

### Wiring up Vercel

I'm a big fan of using CLI's when possible.  It helps me learn how to save time by staying in the terminal
but is also *critical* to gaining knowledge on CI / CD pipelines.  If you're ignoring devops, don't.  It
can be a game changer.  Don't believe me?  Checkout what the illuminary [Kent C. Dodds has to say about automation](https://kentcdodds.com/blog/automation).

That said, let's be sure we have the Vercel CLI installed:

```shell
yarn global add vercel@latest
```

Now, pretending like we're new to this, let's see what it can do... remember, no browser help here:

```shell
vercel --help
```

This is going to spit out a big list of commands you can run, like this:

```shell
Vercel CLI 31.4.0

  ▲ vercel [options] <command | path>

  For deploy command help, run `vercel deploy --help`

  Commands:

    Basic

      deploy               [path]      Performs a deployment (default)
      dev                              Start a local development server
      env                              Manages the Environment Variables for your current Project
      git                              Manage Git provider repository for your current Project
      help                 [cmd]       Displays complete help for [cmd]
      init                 [example]   Initialize an example project
      inspect              [id]        Displays information related to a deployment
      link                 [path]      Link local directory to a Vercel Project
      ls | list            [app]       Lists deployments
      login                [email]     Logs into your account or creates a new one
      logout                           Logs out of your account
      promote              [url|id]    Promote an existing deployment to current
      pull                 [path]      Pull your Project Settings from the cloud
      redeploy             [url|id]    Rebuild and deploy a previous deployment.
      rollback             [url|id]    Quickly revert back to a previous deployment
      switch               [scope]     Switches between teams and your personal account

    Advanced

      alias                [cmd]       Manages your domain aliases
      bisect                           Use binary search to find the deployment that introduced a bug
      certs                [cmd]       Manages your SSL certificates
      dns                  [name]      Manages your DNS records
      domains              [name]      Manages your domain names
      logs                 [url]       Displays the logs for a deployment
      projects                         Manages your Projects
      rm | remove          [id]        Removes a deployment
      secrets              [name]      Manages your global Secrets, for use in Environment Variables
      teams                            Manages your teams
      whoami                           Shows the username of the currently logged in user

  Global Options:

    -h, --help                     Output usage information
    -v, --version                  Output the version number
    --cwd                          Current working directory
    -A FILE, --local-config=FILE   Path to the local `vercel.json` file
    -Q DIR, --global-config=DIR    Path to the global `.vercel` directory
    -d, --debug                    Debug mode [off]
    --no-color                     No color mode [off]
    -S, --scope                    Set a custom scope
    -t TOKEN, --token=TOKEN        Login token

  Examples:

  - Deploy the current directory

    $ vercel

  - Deploy a custom path

    $ vercel /usr/src/project

  - Deploy with Environment Variables

    $ vercel -e NODE_ENV=production

  - Show the usage information for the sub command `list`

    $ vercel help list
```

It looks like the one we're going to care about is `vercel env`, so let's check the help for that command:

```shell
vercel env --help
```

Which should output something like this:

```shell
Vercel CLI 31.4.0

  ▲ vercel env [options] <command>

  Commands:

    ls      [environment] [gitbranch]         List all variables for the specified Environment
    add     [name] [environment] [gitbranch]  Add an Environment Variable (see examples below)
    rm      [name] [environment] [gitbranch]  Remove an Environment Variable (see examples below)
    pull    [filename]                        Pull all Development Environment Variables from the cloud and write to a file [.env.local]

  Options:

    -h, --help                     Output usage information
    --environment                  Set the Environment (development, preview, production) when pulling Environment Variables
    --git-branch                   Specify the Git branch to pull specific Environment Variables for
    -A FILE, --local-config=FILE   Path to the local `vercel.json` file
    -Q DIR, --global-config=DIR    Path to the global `.vercel` directory
    -d, --debug                    Debug mode [off]
    --no-color                     No color mode [off]
    -t TOKEN, --token=TOKEN        Login token
    -y, --yes                      Skip the confirmation prompt when overwriting env file on pull or removing an env variable

  Examples:

  - Pull all Development Environment Variables down from the cloud

      $ vercel env pull <file>
      $ vercel env pull .env.development.local

  - Add a new variable to multiple Environments

      $ vercel env add <name>
      $ vercel env add API_TOKEN

  - Add a new variable for a specific Environment

      $ vercel env add <name> <production | preview | development>
      $ vercel env add DB_PASS production

  - Add a new variable for a specific Environment and Git Branch

      $ vercel env add <name> <production | preview | development> <gitbranch>
      $ vercel env add DB_PASS preview feat1

  - Add a new Environment Variable from stdin

      $ cat <file> | vercel env add <name> <production | preview | development>
      $ cat ~/.npmrc | vercel env add NPM_RC preview
      $ vercel env add API_URL production < url.txt

  - Remove a variable from multiple Environments

      $ vercel env rm <name>
      $ vercel env rm API_TOKEN

  - Remove a variable from a specific Environment

      $ vercel env rm <name> <production | preview | development>
      $ vercel env rm NPM_RC preview

  - Remove a variable from a specific Environment and Git Branch

      $ vercel env rm <name> <production | preview | development> <gitbranch>
      $ vercel env rm NPM_RC preview feat1
```

One thing I love about the Vercel CLI is all the helpful examples they give you.

Most CLI tools I've used (even good ones like Heroku) don't give you all the great examples
for common use cases.  Nice work there Vercel.  🎉

So to add our environment variables, it looks like we're going to want this command:

```shell
vercel env add <name>
```

We could use the `Add a new variable for a specific Environment` example, and you would definitely
do this if you were adding variables for something like a database, where you had specific environments
or if you wanted to have a "staging" setup for ConvertKit.  I don't, and I'm fine with all of 
my test environments working just like production for newsletter subscriptions (at this point in time).

So I'll just use:

```shell
vercel env add CONVERTKIT_PUBLIC_API_KEY
```

When it prompts you for the value, paste in your key and hit enter.  Then, it will ask what environments
you want to add the variables.  For this circumstance, press **a** (for all), and hit enter.

Then, do the same thing for `CONVERTKIT_SUBSCRIBE_FORM_ID`.


```shell
vercel env add CONVERTKIT_SUBSCRIBE_FORM_ID
```

Now, you should be all set.  You may need to redeploy your app if you don't have a new commit going out
soon.

### Conclusion

And there you have it!  A ConvertKit newsletter subscription form that you can use on your site.

If I were going to take this to the next steps (which I did), I would add this to my MDXComponents
file so that I can just add `<Newsletter />` tags whenever relevant.

Hope this was helpful, and happy coding! 🦄⚡️

In this article, I'll teach you how to create a newsletter subscription form in NextJS, and connect to ConvertKit using NextJS api routes.

I help founders & CEO's build better software... fast.

Generating AI-Powered Blog Titles for Your MDX Blog

Abstracting a Vercel OpenAI Handler for Quick AI Tools

Better. Software. Faster. - Part I: Mocks → Board.

Newsletter Subscriptions with NextJS & ConvertKit

Stay up to date

Work