
## Why LLMs don't know the current date

Your favorite LLM doesn't have any way of knowing what time it is. It has no access to the current date, and it doesn't know what day of the week it is. It also doesn't know what year it is, or even what decade it is.

It's one of those things that _sounds_ obvious once you've heard it - but you need to _tell_ your model the date and time in order for it to be able to make tool calls that are date-aware.

Every major chat product - ChatGPT, Claude, Gemini - injects the current date into the model's context before your message ever reaches it.

I ran into this while building an agent into our internal tools at [Craftwork](https://craftwork.com). **If you're the one integrating the model, injecting the date is your job.** If you skip it, you get some very strange behavior.

## Hallucinated date ranges fail silently

Here's the scenario: at Craftwork, we have a variety of LLM tools for use internally - our sales and support teams will often ask our Assistant to search through previous conversations with customers, to provide better service. Things like "Which rooms are we painting ceilings in?" or "What colors is Joe Smith using on their project?" are pretty straightforward.

Another example of a common question might be: "Last weekend I got a call from a customer asking about Limewash. Can you tell me what their name was?"

**Without telling the model the date, it has no idea what "last weekend" means.** It doesn't know that it doesn't know, either - so it doesn't stop and ask. It picks something arbitrary, formats it into a perfectly valid ISO date range, and hands that to your tool with total confidence.

That's the part that should worry you. This isn't a crash, and it isn't an error you can catch. In old-timey programming lingo, this is called a "logical error" - everything appears to be working, but it is producing the wrong result... confidently.

Your tool receives a well-formed request, runs a real query, and returns an honest, empty result set. Then your assistant says:

```plaintext
🤖 I couldn't find any conversations about Limewash.
```

To the salesperson reading that, this looks like a data problem. Maybe the call never got logged. Maybe the customer used different words. What it does _not_ look like is a bug, so until someone notices, nobody files anything.

You might ship this, and never hear about it.

**A confidently wrong answer is worse than no answer.** In our case, the downside could be a support rep chasing a ghost for ten minutes, telling customers something wrong, or worse. If you're building something where dates carry real weight - scheduling, billing cycles, medication reminders, flight changes - a hallucinated date range stops being an annoyance and starts being a genuine hazard.

So, let's fix it.

## Give your model a clock: put the date in your system prompt

The fix starts in your system prompt. Before any tool ever gets called, the model needs to know what "now" means:

```ts
const system = `You are Craftwork's internal assistant.

Current date and time: 2026-08-04T09:14:00-06:00
Day of week: Tuesday
Time zone: America/Denver (MDT)`;
```

That's the whole idea. It really is that simple, and it's the single highest-leverage thing you can do.

But there are a few details that will bite you, and they're the reason this post is longer than four lines.

## A date alone isn't enough: time zone, day of week, and locale

Handing the model `2026-08-04` and calling it done will get you most of the way there and then quietly fail on the interesting cases. Three things travel with the date:

**Time zone.** This is important to get right. Our sales team is spread across the US, and datestamps are expressed in UTC. When a rep in Denver asks about "last weekend" at 9pm on a Sunday, UTC has already rolled over to Monday. Your model needs the user's [IANA time zone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (`America/Denver`), not your server's idea of the time.

**Day of week.** "Last weekend" means the most recently _completed_ weekend - and which two dates that is depends entirely on the day you're asking. Ask on a Monday and it's the previous two days. Ask on a Sunday and it's seven to eight days back, because the weekend you're standing in isn't "last weekend," it's today and yesterday. Same two words, ranges a week apart, and the only thing separating them is a fact the model doesn't have.

The model can't reason about any of this unless it knows which day it is, and asking it to derive Tuesday from `2026-08-04` is asking for trouble.

**Locale.** This one surprised me. "Last week" depends on when the week starts, and that isn't universal: the week starts on Sunday in the US, Monday across most of Europe, and Saturday in much of the Middle East. If you're only shipping to one country you can safely ignore this. If you're not, a US-centric assumption baked into your date helpers will silently shift every "this week" query by a day for a chunk of your users.

## Don't make the model do calendar math

Here's where I'll finish the thought I started earlier: if you've been building software for a long time, you'll be relieved to hear the answer is at least partly deterministic. And honestly, we should push it further than "partly."

Models are genuinely bad at calendar arithmetic. Ask one to work out the date range for "the weekend before last" and it will produce something that _looks_ right, with abysmal accuracy for edge cases, like month boundaries, daylight saving transitions, and leap years. This is exactly the kind of work computers have been reliably good at since the 1970s. Don't outsource it to a language model.

So rather than giving the model a timestamp and hoping, give it the answers already worked out. We use [date-fns](https://date-fns.org/) at Craftwork, paired with [`@date-fns/tz`](https://github.com/date-fns/tz) for time zone support:

```ts
import { TZDate } from '@date-fns/tz';
import {
  addDays,
  endOfMonth,
  format,
  getDay,
  startOfDay,
  startOfHour,
  startOfMonth,
  startOfWeek,
  subDays,
  subMonths,
  subWeeks,
  type Locale,
} from 'date-fns';
import { enUS } from 'date-fns/locale';

const iso = (d: Date) => format(d, 'yyyy-MM-dd');

// 'MDT' rather than 'GMT-6' - friendlier for the model, and for anyone
// reading your prompt logs later
const tzAbbreviation = (d: Date, timeZone: string) =>
  new Intl.DateTimeFormat('en-US', { timeZone, timeZoneName: 'short' })
    .formatToParts(d)
    .find((part) => part.type === 'timeZoneName')?.value;

export type NamedRange =
  | 'today'
  | 'yesterday'
  | 'last_weekend'
  | 'this_week'
  | 'last_week'
  | 'this_month'
  | 'last_month';

export type DateRange = { start: string; end: string; label: string };

export const toRange = (start: Date, end: Date): DateRange => ({
  start: iso(start),
  end: iso(end),
  // a human-readable label, for showing your work later on
  label:
    iso(start) === iso(end)
      ? format(start, 'EEEE, MMMM d')
      : `${format(start, 'EEEE, MMMM d')} through ${format(end, 'EEEE, MMMM d')}`,
});

// The single source of truth for what a named range means. The system prompt
// renders these, and the tool handler resolves against them - so there is
// exactly one implementation of "last weekend" in the codebase.
export const buildNamedRanges = (
  now: Date,
  locale: Locale = enUS
): Record<NamedRange, DateRange> => {
  // passing a locale makes startOfWeek respect that locale's first day of
  // the week - Sunday for en-US, Monday for en-GB, and so on
  const thisWeek = startOfWeek(now, { locale });
  const lastWeek = subWeeks(thisWeek, 1);
  const yesterday = subDays(now, 1);
  const lastMonth = subMonths(now, 1);

  // find the most recently *completed* Saturday.
  // date-fns getDay: 0 = Sunday ... 6 = Saturday
  const daysSinceSaturday = (getDay(now) + 1) % 7;
  const weekendInProgress = daysSinceSaturday <= 1;
  const lastWeekendStart = subWeeks(
    subDays(startOfDay(now), daysSinceSaturday),
    // if it's currently Sat or Sun, that weekend hasn't finished yet, so
    // "last weekend" is the one before it - a week further back
    weekendInProgress ? 1 : 0
  );

  return {
    today: toRange(now, now),
    yesterday: toRange(yesterday, yesterday),
    last_weekend: toRange(lastWeekendStart, addDays(lastWeekendStart, 1)),
    this_week: toRange(thisWeek, now),
    last_week: toRange(lastWeek, subDays(thisWeek, 1)),
    this_month: toRange(startOfMonth(now), now),
    last_month: toRange(startOfMonth(lastMonth), endOfMonth(lastMonth)),
  };
};

export const buildTemporalContext = (
  timeZone: string, // IANA, e.g. 'America/Denver'
  locale: Locale = enUS
) => {
  // TZDate carries the time zone with it, so every date-fns call below
  // stays in the user's zone instead of quietly falling back to the server's.
  // startOfHour, not the raw timestamp - rounding this matters for prompt
  // caching; see the companion post linked below
  const now = startOfHour(TZDate.tz(timeZone));

  const ranges = Object.entries(buildNamedRanges(now, locale))
    .map(([name, { start, end }]) => `- ${name}: ${start} to ${end}`)
    .join('\n');

  return `Current date and time: ${format(now, "yyyy-MM-dd'T'HH:mm:ssXXX")}
Day of week: ${format(now, 'EEEE')}
Time zone: ${timeZone} (${tzAbbreviation(now, timeZone)})
Locale: ${locale.code} - weeks start on ${format(startOfWeek(now, { locale }), 'EEEE')}

Pre-resolved date ranges. Use these names exactly, rather than calculating dates yourself:
${ranges}`;
};
```

Now the model isn't calculating anything. It's looking things up, which is a task it's actually good at.

`buildNamedRanges` is deliberately a plain function of `now`, with no clock inside it. That makes it trivial to test - freeze a Tuesday, freeze a Sunday, freeze the Sunday that daylight saving ends, and assert on the ranges - and it means the next section can reuse it verbatim.

## Design your tool schema so dates resolve in your code

The reference block gets you a long way, but there's a second layer worth adding: make it possible for the model to _hand the date problem back to you_.

Instead of a tool that only accepts explicit dates, accept a named period as well:

```ts
const searchConversations = {
  name: 'search_conversations',
  description:
    'Search customer conversation history. When the user describes a time ' +
    'period in words ("last weekend", "this month"), pass `relative_range` ' +
    'and let the system resolve it. Only use `start_date` and `end_date` when ' +
    'the user gives you explicit calendar dates.',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'What to search conversation text for',
      },
      relative_range: {
        type: 'string',
        // exactly the names rendered into the system prompt above
        enum: [
          'today',
          'yesterday',
          'last_weekend',
          'this_week',
          'last_week',
          'this_month',
          'last_month',
        ],
        description: 'A named time period. Prefer this over explicit dates.',
      },
      start_date: {
        type: 'string',
        description: 'ISO 8601 calendar date, YYYY-MM-DD. Inclusive.',
      },
      end_date: {
        type: 'string',
        description: 'ISO 8601 calendar date, YYYY-MM-DD. Inclusive.',
      },
    },
    required: ['query'],
  },
};
```

Three things to call out here, because they all matter more than they look:

**The enum is the same vocabulary as the system prompt.** `buildNamedRanges` renders `last_weekend` into the prompt and `last_weekend` is what the schema accepts - one list of names, generated from one piece of code. When those two drift apart, the model reads `this week` upstairs, sends `past_7_days` downstairs, and you get a range nobody wrote a test for.

The **tool description is where you steer behavior**. "Prefer this over explicit dates" in the description does more work than the same sentence buried in your system prompt. Be specific about _when_ to reach for each parameter, not just what each one is.

And **spell out the format**. `ISO 8601 calendar date, YYYY-MM-DD` leaves no room for the model to hand you `08/04/2026` and let you find out at runtime which of those numbers was the month.

Then resolve it in your handler, where you have a real date library and real tests:

```ts
import { TZDate } from '@date-fns/tz';
import { format, startOfHour, subYears, type Locale } from 'date-fns';
import { enUS } from 'date-fns/locale';

import {
  buildNamedRanges,
  toRange,
  type DateRange,
  type NamedRange,
} from './temporal-context';

const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

// Midnight on a calendar date, *in the user's zone*.
// Watch out here: passing a bare string like '2026-08-01T00:00:00' to
// TZDate parses it in the server's zone first and then re-renders it,
// which can silently shift the date by a day. Pass components instead.
const atMidnight = (isoDate: string, timeZone: string) => {
  const [y, m, d] = isoDate.split('-').map(Number);
  const date = new TZDate(y, m - 1, d, timeZone);
  // rejects dates like 2026-02-31, which would otherwise roll forward
  return format(date, 'yyyy-MM-dd') === isoDate ? date : null;
};

// Same function that built the system prompt, so a name the model read up
// there always means the same thing down here.
const resolveNamedRange = (
  name: string,
  timeZone: string,
  locale: Locale = enUS
): DateRange => {
  const now = startOfHour(TZDate.tz(timeZone));
  const ranges = buildNamedRanges(now, locale);
  const match = ranges[name as NamedRange];

  // an unrecognized name means the model invented one. Throw rather than
  // fall through to "no date filter" - a loud error it can correct beats a
  // silent search of everything.
  if (!match) {
    throw new Error(
      `Unknown range "${name}". Use one of: ${Object.keys(ranges).join(', ')}`
    );
  }

  return match;
};

export const resolveRange = (
  input: { relative_range?: string; start_date?: string; end_date?: string },
  timeZone: string,
  locale: Locale = enUS
): DateRange | null => {
  // named range: we do the math, so it's right every time
  if (input.relative_range) {
    return resolveNamedRange(input.relative_range, timeZone, locale);
  }

  // explicit dates: trust, but verify
  if (input.start_date && input.end_date) {
    if (!ISO_DATE.test(input.start_date) || !ISO_DATE.test(input.end_date)) {
      throw new Error('Dates must be ISO 8601 calendar dates (YYYY-MM-DD)');
    }

    const start = atMidnight(input.start_date, timeZone);
    const end = atMidnight(input.end_date, timeZone);

    if (!start || !end) {
      throw new Error('Dates must be real calendar dates');
    }
    if (end < start) {
      throw new Error('end_date must be on or after start_date');
    }
    // a range starting in 2023 is a strong sign the model guessed
    if (start < subYears(TZDate.tz(timeZone), 2)) {
      throw new Error('Range starts more than 2 years ago - please confirm');
    }

    // same shape as a named range, so callers never have to care which
    // branch produced it
    return toRange(start, end);
  }

  return null; // no date filter - search everything
};
```

Those validation errors are worth the keystrokes. When a tool throws, most frameworks hand the error text back to the model, which gets a chance to correct itself instead of silently querying 2023.

## One caching trap before you ship this

There's a bill-shaped bug hiding in everything above, and I want to flag it here even though it deserves its own post.

You're about to put a timestamp into your system prompt. Prompt caching is a **prefix match** - providers reuse cached work only up to the first byte that differs - so a raw `new Date().toISOString()` sitting above ten thousand tokens of instructions will drop your cache hit rate to exactly zero. Permanently. With no error and no warning.

Two habits keep you out of it:

**Round the timestamp** to the coarsest precision your feature can tolerate. That's why `buildTemporalContext` above calls `startOfHour` instead of using the raw clock - hourly is plenty for resolving "last weekend," and it means you invalidate once an hour instead of on every request.

**Put the volatile block last**, after your cache breakpoint, so your expensive stable instructions cache cleanly in front of it.

I shipped this bug and only caught it on an invoice. The full write-up - ordering, TTLs, the multi-turn wrinkle, and how to actually verify a cache hit - is here: [why your prompt cache hit rate is zero](/posts/prompt-cache-hit-rate-zero).

## Close the loop: show the user the date range you searched

One more thing, and it's the cheapest reliability win in this whole post.

Have your tool return the range it resolved, and have your assistant say it out loud:

```ts
const range = resolveRange(input, timeZone, locale);
const results = await searchConversations(input.query, range);

return {
  resolved_range: range, // hand it back to the model
  results,
};
```

Then, in your system prompt:

```
When a search covers a date range, state the range you searched in plain
language before giving results. For example: "Searching conversations from
Saturday, August 1 through Sunday, August 2..."
```

Now your rep sees:

> Searching conversations from Saturday, August 1 through Sunday, August 2... I found one call about Limewash, from George Whitfield.

If the range is wrong, a human catches it instantly - because a human knows what "last weekend" means and does not need to be told. You've converted a silent failure into an obvious one, which is the entire game.

It also covers the cases where your interpretation is defensible but still isn't the one the person had in mind. "Last week" is the clearest example: our code resolves it to a calendar week, and plenty of people say "last week" meaning the last seven days. Both readings are reasonable, and no amount of prompt engineering picks the right one every time. Showing your work lets the person who _does_ know just say "no, go back further."


## Wrapping up

The whole fix comes down to four moves:

1. **Inject the current date, time zone, day of week, and locale** into your system prompt. If you're integrating the model, nobody else is doing this for you.
2. **Pre-resolve common ranges** rather than asking the model to do calendar math it's bad at.
3. **Let your tools accept named periods** and resolve them in code, where you have a date library and tests.
4. **Show the resolved range to the user**, so wrong answers stop being silent.

And [keep an eye on that cache hit rate](/posts/prompt-cache-hit-rate-zero) while you do it - rounding that timestamp is the difference between a cached prompt and a surprising bill.

None of this is complicated. It's just easy to skip, because nothing fails loudly when you do - and "nothing fails loudly" is a genuinely bad property for software that people are trusting with real questions.


Your LLM doesn't know what day it is: date handling for AI tool calls

Give your model a clock: put the date in your system prompt

A date alone isn't enough: time zone, day of week, and locale

Design your tool schema so dates resolve in your code

Close the loop: show the user the date range you searched


## Test, trust the data, and optimize your site for better results

In this video, I dive into A/B testing with PostHog to boost newsletter signups on my site. I walk you through my process-from identifying issues with signups, switching email platforms, to experimenting with different UX elements. I'll show you how to set up and run A/B tests, and explain why trusting the data is crucial for making smart, data-driven decisions. If you're a developer or UX enthusiast, this video will help you refine your own website's user experience.

The code for my site is available on github - you can see the Pull Request for the changes associated with this video here: https://github.com/mbifulco/blog/pull/832

## Watch the first two episodes in this series:

1. [Product Analytics for engineers: Debugging a conversion problem on my next.js site](https://mikebifulco.com/posts/debugging-a-conversion-problem-on-my-nextjs-site)
2. [Fixing the bug behind my Conversion Problem](https://mikebifulco.com/posts/fixing-my-conversion-problem)

## Video Timestamps

- 00:00 Introduction and Series Overview
- 00:35 Identifying the Signup Problem
- 00:59 Switching to Resend
- 01:11 Exploring AB Testing
- 01:19 Sponsorship by PostHog
- 02:11 Website Elements and Hypotheses
- 04:07 Implementing AB Tests
- 05:03 Setting Up PostHog Experiments
- 07:20 PostHog Implementation Details
- 08:31 Testing and Analyzing Results
- 10:52 Tell me what you think!

<details>

  <summary>

    <b>Transcript</b>

  </summary>

[00:00:00] **Mike Bifulco:** Hello, and welcome back to tiny improvements. My name is Mike And since we last talked, I've been working on a problem on my website. This is the third video in a series that I'm doing on trying to get people, to sign up for my newsletter.

[00:00:11] If you're new here, I read a weekly newsletter called tiny improvements.

[00:00:13] That is meant for product developers, startup founders, indie hackers, people who are interested in building products. Where I share the things that I've learned, building products that companies like Google and Stripe and Microsoft, and more recently building a venture capital backed startup I'm co-founder of a company called Craftwork. We went through Y Combinator last summer. And so this is my way of giving back. I'm trying to give away the things that I know for free, because I've been really lucky in my career.

[00:00:34] And I want you to be as lucky as I have been. So since you're here, let's talk about where we've been in the first video. I discovered that I had a problem with signups and people weren't subscribing. I was using convert kit for my newsletter at the time and was having some sort of mystery problem with signups.

[00:00:47] So I added a bunch of telemetry to show me when signups were happening and to try and detect failures from that experience, I found that. I was getting some mystery failures with convert kit in my implementation of my newsletter signup form. And that's [00:01:00] what led me to what I did in the second video, which is where I replaced convert kit with Resend.

[00:01:03] So now I use Resend email platform for both sending my newsletters and getting people to sign up for my mailing list. That's been really nice so far. In this video I'm exploring the next thing I wanted to get into, which is AB testing stuff on my site.

[00:01:16] So let's take a look at that and see what that actually means in practice.

## Sponsored by Posthog

[00:01:19] **Mike Bifulco:** Hey, all this video series is sponsored by PostHog. After seeing my first video, they reached out about a sponsorship, which is really cool.

[00:01:25] And frankly, I'm flattered to see it. I was planning on making these videos either way and that's because I really enjoy PostHog. I also really enjoy building products and seeing things improve over time. . I wouldn't take a sponsorship from something that I don't believe in and don't use, I hope you're enjoying this series and I hope you're learning something.

[00:01:39] If you're really into it, it might also be worth giving. PostHog a shot. One of my favorite things about the platform is that they're free tiers, unbelievably generous. You can get a whole lot out of PostHog for free before paying anything to decide if it's worth it for you.

[00:01:50] There's also a self host option. If you want to go that route and PostHog also has a ton of open source software, which means you can have influence over the product itself.

[00:01:58] I think that's really amazing. And the team has been [00:02:00] super responsive so far. So if you want to check it out, go to PostHog dot com slash Mike Bifulco. There'll be a link in the description. It will let them know I sent you and it means a lot to me.

[00:02:09] Thanks so much. I hope you enjoy the rest of the video.

[00:02:11] Okay, this is my site and this is one of the things that I'm interested in testing to see if I can make a difference in the amount of people signing up.

[00:02:17] When you visit my site, read one of my newsletters or any of the articles on my site. There's a bunch of things that are made available at the top of the pages, a cover image and a title things you're probably used to seeing, I have this nice dynamic. Table of contents, which is really helpful I also record audio versions of some posts, which is why we see this podcast embedded here. if we scroll through the post, when you get towards the end of it, a couple of things happen.

[00:02:36] This pop-up, that just flew in from the left is a thing called polite pop. This is where the first call to action typically comes for someone to subscribe to my newsletter. I've got a couple of hypotheses on how we can do better here. What I want to do is test the copy.

[00:02:48] That's rendered here to see if there's maybe a different treatment, that we can show. To people to get them more compelled to sign up. I might also choose to remove this. It kind of is just an ag and I think people are really well-trained to just dismiss pop-ups and [00:03:00] try and get them out of their face.

[00:03:01] And it's a little bit of a rude experience while you're on a site. I see loads of people coming to my site and clicking this. No thanks button. I've got tons of telemetry on that. That may not be long for this world.

[00:03:09] The other thing that I see, and I think this is worth testing straight away is at the bottom of each post.

[00:03:14] I have this giant banner, which is this big striking thing that says ship products that matter. And I really like this. This is something I workshopped for awhile, trying to come up with a slogan or phrase, something that was sort of attention grabbing. That's supposed to give people a reason to sign up.

[00:03:28] However, I think what I've done here is I built something that is so different from everything else. That's that seen on my site that. By the time you get down here, as you scroll down and you get this great big dark banner that appears, it's pretty obvious that the article is over and then I'm not giving you any more value here. And so what I want to test is if I can replace this with something that's a little more subtle.

[00:03:47] So maybe not a giant banner like this, but something that says, Hey, I write this cool newsletter. I think you might like it. Please subscribe. And maybe Tiki into people's psychology a little bit to keep them reading on the page. watching back some replays of people visiting the site. [00:04:00] It's pretty common to see someone get to about here and go away.

[00:04:02] And if they leave before they get down here, I've lost. So. we're going to try a couple of things here and that's. Where AB testing comes in.

## A-B Testing in PostHog

[00:04:08] an AB test is exactly what it sounds like. I have version a version B and sometimes C D E F a number of different versions of one bit of user experience that I want to test against each other to see how they perform. The idea here is to see that if I do this versus that is one going to get me more people signing up for my newsletter or not.

[00:04:24] **Mike Bifulco:** And we can kind of test some hypothesis from there. Now there's some really important statistics involved in how this works. What I really like is that when you collect data, the math will tell a story. And if you're willing to trust the math and listen to what the statistics say, you can probably make a good data driven decision to move yourself from doing well, to doing better and incremental change over time will do really well.

[00:04:46] But you have to be comfortable with trusting what the statistics say. And let me be the first to tell you that there's a lot to learn about that, and it can be really counter-intuitive. I am far from a statistics expert. I have learned a lot of mathematics in my life.

[00:04:57] You have to learn to trust the statistics. [00:05:00] And so that's what we're going to try to do here. Let me get off my high horse. Let's talk about this. So this is my first experiment is called newsletter banner treatments. So you give it a name, which is a human readable thing, and then our feature flag key.

[00:05:10] So this is the key that we'll use programmatically to make decisions based on this experiment. So I gave it newsletter banner treatments as the key. The description here again is a human readable thing. It's meant for me when I go review these later on to see what this experiment was all about.

[00:05:23] So I may fill this in with more detail, but the idea is I want to test different UX presentations of the newsletter banner that appears at the bottom of articles. To see which one performs best.

[00:05:32] By default PostHog will give you a control, which is the fallback value. So the control is meant to be in scientific method speak.

[00:05:39] That means the thing that we know how it performs and the baseline for the experience right now, that's that big dark banner that I show on my site that I was just showing you that people sort of. Seem to scatter away from. I'm running two tests against that in this case. So I'm going to test a simple implementation and a hero implementation. Those are bits of UI that I've built alternatives for.

[00:05:58] And I'll show you what they look like. [00:06:00] So if I come through and I hit, continue on this experiment, we'll see that PostHog does a little bit of thinking. And it goes to do some give me some numbers on roughly what this would look like. And what I want to check is my newsletter subscribed event.

[00:06:11] So I'm hoping to see more of these newsletter subscribed things happening. With one variant of this versus the other, they'll probably all perform slightly differently. We're going to pick the one that wins out of the three. So. I've picked the event that I want to use. If I go to the next page here, what I get is the goal for the experiment.

[00:06:28] So this now shows me everything in one view. What it's saying at the very top is this is a draft. I haven't actually started it yet. By results are not significant, meaning I haven't collected enough data to make a decision. And the feature flags name is here.

[00:06:39] Down here, we get implementation details from PostHog, which is literally code snippets that you can use in your application. So you can switch through these and see what they look like.

[00:06:47] There's react native there's no, there's Ruby, all kinds of stuff in here. What's really cool is they show you exactly how to do this. So you load the feature flag using the feature flags name. If you have a user ID, like an email address, if someone's logged in, you can pass that [00:07:00] into, they always get a consistent experience per user. And then you make a decision based on what comes back. So the feature flag will say for this person render a simple one. It might come back and say for this person render a hero one and you do different things based on that. So what I'll do is I'll hit launch on this thing, It'll sort of thing for a second and go live and I'll, show you what the implementation looks like, next.

[00:07:20] Okay, implementation time. So I'm using post hogs library called PostHog JS.

[00:07:26] Thanks sports, some really nice react components, which I'm using in this implementation here. So this experiment name, newsletter, banner treatments is what we just saw on the site. These are the three different experiment variants.

[00:07:35] So these are the things that the experiment will tell me to render for different users. And we'll collect data on that. And I'm using a thing called PostHog feature, which is a react component exported by post hog, which takes in the name of the flag. As well as the part of the experiment to match.

[00:07:50] So what this is saying is we're going to do this with the newsletter experiment. So if it comes back and says control, we're going to render this thing, the fancy component, which is the newsletter banner that's currently shown on [00:08:00] the site with the dark background.

[00:08:01] I've created two other variants. The simple one here is based on a fairly standard tailwind component library. And this one called hero is one that I was using on other pages on my site, but wasn't consistently showing on the bottom of articles.

[00:08:13] now I'm taking all three of these things. And for about a third of users, I'll show each one of these and we'll track. How many of them convert to newsletter subscriptions over the next. Week or so, and we'll see what comes back.

[00:08:23] Next thing to see is what this looks like in the browser, because PostHog also provides some tools for you to be able to poke around with these and make sure it works well before you roll it out to your users.

## PostHog's A-B Testing tools in the browser

[00:08:31] **Mike Bifulco:** All right back here on post-talk and here's what I want to show you.

[00:08:35] from any page on PostHog, you can get to this handy thing called toolbar. If I click into this, this gives me the ability to launch a PostHog specific toolbar within the context of my site. So it doesn't really fancy injection of content. And it renders PostHog using what I believe is a Chrome extension.

[00:08:50] And so if I click on this, it's going to load my local host, which I've told is where I'm running my site. This is what the tool bar looks like.

[00:08:55] Typically you'll see it. Like this, when it first comes up and we're really interested in this [00:09:00] feature flags. Functionality here. So there's a bunch of things here. You can do actions and heat maps and all kinds of stuff like that. But let's take a look at feature flags first. I'm going to navigate to one of my newsletters, the most recent one, we were just checking this out and I'm going to scroll to the bottom and I'm going to go to this feature flags thing here and already something looks different, This is not the banner that was showing before. And this is a sign that my experiment is working. you can see here, I can manually override the experiments that I'm seeing personally in development.

[00:09:25] And as I toggle through these, I get three different presentations. this one might look familiar. This is the hero one I had before. This is the simple implementation that I wanted to take a look at. And then here's the control implementation. the important thing to test here is we're trying to test things that could produce the same output against each other. When users come to this page, I want to make sure they can submit this form and get the output that I want from each of them, which is that newsletter subscribed event.

[00:09:46] So from this control one, This is a newsletter subscription form. First name and email address is exactly what we want to see the simple form, same thing. First name, email address, and then the hero form. Once again, first name and email address. So. [00:10:00] All the primitives are here. I have three different variants of this thing.

[00:10:03] The next thing to do is to set this live and just record some traffic for awhile. there are some statistical minimums. We have to get a certain amount of users interacting with each one of these, to be able to say whether it worked or not. And the next part is just waiting. So we're going to spin this up on PostHog.

[00:10:17] We're going to collect some data over the next week or two, however long it takes, and then we'll start to make some decisions based on that and go into the next step from there.

[00:10:23] So that's all there is to it. It's a little bit of implementation. It's a little bit of work to set up the three different variants, but now I need to trust the statistics. I need to listen to what comes back from post-hoc as the experiment runs. And tweak my site design based on the data that comes back. My guess is it'll probably take about two weeks for this to come back with meaningful results. But lucky for me, I can run a couple of experiments in parallel, as long as the two different experiments don't interfere with each other. I can probably still draw a valid conclusion from it. So over the next week or so I'll watch this and I'll see what happens.

## What do you think?

[00:10:52] **Mike Bifulco:** If you've been hanging on for the whole series so far, I'm really curious what you think of this.

[00:10:55] Is this something you would find useful for your site? Do you have an idea of experiments you'd like to run? Do you have [00:11:00] questions about this stuff?

[00:11:01] I spent a bunch of my career working in design and user experience. So this sort of thing is a process that I really enjoy, but I can understand that it might be frustrating too, especially if you just want to get to results.

[00:11:10] If you have questions for me, feel free to drop them in the comments. . Your ideas are always welcome here. There's no criticism too big or too small. I'd love to hear what you're thinking. Thanks so much. My name is Mike bi-fold co this is tiny improvements and we'll catch up for the next one.

</details>


Unlocking A/B Testing with PostHog: Improving Newsletter Signups

Test, trust the data, and optimize your site for better results

Watch the first two episodes in this series:

PostHog's A-B Testing tools in the browser


## I publish a newsletter called Tiny Improvements

[My little newsletter](https://mikebifulco.com/newsletter) is all about making small, incremental improvements to your work and home life, especially if you're building a product or company. I've been publishing it for a while now, and I've been using ConvertKit to manage my subscribers and send out the newsletter.

<Aside>

Note: This is a follow-up to my [previous post on using ConvertKit with Remix](https://mikebifulco.com/posts/publish-your-newsletter-with-convertkit-api-remix). If your site is built using [**Remix.run**](https://remix.run), you'll probably want to head over there.

</Aside>

In this post, we'll go over how I use the ConvertKit API to publish a newsletter page for a site built with [Next.js](https://nextjs.org).

## Publish past issues to grow your newsletter

I recently started publishing back-issues of my [newsletter](https://mikebifulco.com/newsletter) to my site, so that I can share them as evidence of the type of writing I do. In addition to being SEO-indexable, it allows me to share the newsletter with people who aren't subscribed to it, with a link to subscribe at the bottom of each issue.

I wanted to explore a way to make _my_ process incrementally better, by using the [ConvertKit API](https://developers.convertkit.com/) to automate the publishing process with the same workflow that I use to send newsletters to subscribers.

## Using the ConvertKit API to publish newsletters to a Next.js site

Setting up an automated newsletter page is fairly simple, at least in theory:

1. Write newsletters and send them, using ConvertKit's broadcast features (for the sake of this post, we'll use the term "newsletter" and "broadcast" somewhat interchangeably).
2. Use the ConvertKit API's list-broadcasts endpoint to query for every published broadcast, to populate a newsletter index page
3. For each published broadcast, use the ConvertKit API to get the details of that broadcast, and then render the content of that broadcast on a page.
4. For SEO purposes, add each published newsletter page to `sitemap.xml`, with all the appropriate metadata.

To get newsletters from the ConvertKit API, I set up 2 helper functions in `/src/utils/convertKit.js`. First is `getNewsletter()`, which takes a broadcast ID and returns the details of that broadcast.

```js
export const getNewsletter = async (broadcastId) => {
  const res = await fetch(
    `https://api.convertkit.com/v3/broadcasts/${broadcastId}?api_secret=${CONVERTKIT_API_SECRET}`
  );

  // rename "broadcast" to "newsletter" for consistency
  const { broadcast: newsletter } = await res.json();

  return newsletter;
};
```

The second is `getAllNewsletters()`, which returns a list of all published broadcasts. In its simplest form, this function looks like this:

```js
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();

  // rename "broadcasts" to "newsletters" for consistency
  const { broadcasts: newsletters } = data;

  return newsletters;
};
```

<Aside type="warning">

We are using an environment variable to supply the variable `CONVERTKIT_API_SECRET` - it is **super important** to keep this value secret, and not share it on the client-side of your app.

</Aside>

### Keeping your ConvertKit API Secret key safe on Next.js sites

For this example, we're using `CONVERTKIT_API_SECRET` environment variable only on the server-rendered parts of our site, because we _do not want it to be exposed to the client_. To make this value accessible only server-side, add it to a file called `.env` or `.env.local`, according to [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#loading-environment-variables). **Make sure you add `.env` and `.env.local` to your [`.gitignore` file](https://mikebifulco.com/posts/gitignore-io-is-great), so you don't accidentally commit it to your repository.**

Importantly, this environment variable should only be exposed server-side, because we _didn't_ name it with a `NEXT_PUBLIC_` prefix - to read more about using environment variables to web clients, check out [Next.js documentation](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser).

### Rendering the newsletter index page

Now that we have a way to get a list of all published newsletters, we can use that to render a page with a preview of each past issue. I created a new file called `/src/pages/newsletter/index.js` to render the newsletter index page.

On this page, we use `getStaticProps` to fetch our list of newsletters on the server, and then pass them to render function, to display a list of links to each newsletter page.

<small>

_note: I stripped out the styling/presentation code from this example to keep
it focused on data loading logic._

</small>

```jsx
import { Link } from 'next/link';

import { getAllNewsletters } from '../../utils/convertKit';
import slugify from '../../utils/slugify';

export const getStaticProps = async () => {
  const newsletters = await getAllNewsletters();

  return {
    props: {
      newsletters,
    },
  };
};

const NewsletterIndexPage = ({ newsletters }) => {
  return (
    <>
      <h1>All Newsletters</h1>
      <ul>
        {newsletters?.map((newsletter) => (
          <li key={newsletter.id}>
            <Link href={`/newsletter/${slugify(newsletter.subject)}`}>
              {newsletter.subject} - {formatDate(newsletter.published_at)}
            </Link>
          </li>
        ))}
      </ul>
    </>
  );
};

export default NewsletterIndexPage;
```

You may have noticed that I'm also using a helper function called `slugify`, which uses the npm package `slugify`. This function takes a string and returns a skewer-case-version-of-it, which is useful for creating browser-friendly URLs from strings.

```js
import makeSlug from 'slugify';

export const slugify = (string) => {
  return makeSlug(string, {
    replacement: '-',
    remove: /[\[\],?*+~.()'"!:@]/g,
    strict: true,
    lower: true,
  });
};

export default slugify;
```

This is an optional step that caused me a fair bit of heartache - the easiest way to link to individual newsletter pages is to use the broadcast ID, but I wanted to use a more human-readable URL, so I used `slugify` to create a URL-friendly version of the newsletter subject.

The downsides of this approach are:

- each newsletter _must_ have a unique URL
- there's not a way to efficiently map a URL to a broadcast ID, so we have to iterate over all broadcasts to find the one that matches the URL (which you'll see in the next section)

For now, I can live with this approach, since this computation is done once during build time, and until I have hundreds of newsletters, it shouldn't be too big of a performance hit.

### Rendering a single newsletter page

Now that we have a page listing all published newsletters, we need to create a page template to render a single newsletter. I created a new file called `/src/pages/newsletter/[subject].js` to render the newsletter index page (note, once again, that presentation and styling code is removed here for simplicify):

```jsx
import { useEffect } from 'react';

import {
  broadcastTemplateParse,
  getAllNewsletters,
} from '../../utils/convertKit';
import slugify from '../../utils/slugify';

export const getStaticPaths = async () => {
  const newsletters = await getAllNewsletters();

  return {
    paths: newsletters.map((newsletter) => ({
      params: {
        subject: slugify(newsletter.subject),
      },
    })),
    fallback: false,
  };
};

export const getStaticProps = async (context) => {
  const newsletters = await getAllNewsletters();

  const { subject } = context.params;
  const slug = slugify(subject);

  const newsletter = newsletters.find(
    (newsletter) => slugify(newsletter.subject) == slug
  );

  return {
    props: {
      newsletter,
    },
  };
};

const SingleNewsletterPage = ({ newsletter }) => {
  const { subject } = newsletter;

  return (
    <>
      <h1>{subject}</h1>
      <div
        dangerouslySetInnerHTML={{
          __html: broadcastTemplateParse({ template: newsletter.content }),
        }}
      />
    </>
  );
};

export default SingleNewsletterPage;
```

The `getStaticPaths` function is used to generate a list of all possible URLs that should be pre-rendered. In this case, we're using the `getAllNewsletters` function to fetch a list of all published newsletters, and then using the `slugify` function to create a URL based on the newsletter's subject.

The `getStaticProps` function is used to fetch the data for a single newsletter, based on the URL. We use the `getAllNewsletters` function to fetch a list of all published newsletters, and then use `newsletters.find()` to look for the newsletter whose subject line matches the URL for the current page when run through `slugify`. This uses a JavaScript API called [Array.find()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find), which is used to find single item in an array that matches a condition.

#### Render the body using dangersoulySetInnerHTML

To render the contents of the newsletter, we are using a scary-looking React API pattern - `dangerouslySetInnerHTML`. This is a [React API](https://reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml) that allows you to render HTML that you have received from an API, and is generally considered a security risk. However, in this case, we are using it to render HTML that we have generated ourselves, and we are at least somewhat confident that it is safe to render. Generally speaking, this is a technique that shouldn't be used unless you are confident that the HTML you are rendering is safe.

#### Helper functions for displaying ConvertKit newsletter content

We're also using 2 helper functions, which are defined in `/src/utils/convertKit.js`:

```js
import { Liquid } from 'liquidjs';

const engine = new Liquid();

export const broadcastTemplateParse = ({ template, data }) => {
  const t = template.replaceAll('&quot;', '"');
  const res = engine.parseAndRenderSync(t, data);
  return res;
};

export const newsletterHasValidThumbnail = (newsletter) => {
  const { thumbnail_url: thumbnailUrl } = newsletter;
  if (!thumbnailUrl) return false;
  if (thumbnailUrl.startsWith('https://functions-js.convertkit.com/icons'))
    return false;
  return true;
};
```

The `newsletterHasValidThumbnail` function is a helper function that checks if the newsletter has a valid thumbnail image. ConvertKit provides a default thumbnail image for all newsletters, but you can also upload your own, by adding an image to your newsletter's body. This function checks if the thumbnail is the default image, and if so, returns `false` so we can skip rendering it.

The `broadcastTemplateParse` function is a helper function that takes a newsletter template and parses it with the [Liquid](https://shopify.github.io/liquid/) templating language. This is how ConvertKit allows you to customize the HTML of your newsletter, and use dynamic data like the subscriber's name, or the date the newsletter was sent.

**An important caveat:** There are _lots_ of little cases where this might not work perfectly, due to all of the amazing things you can do with Liquid in ConvertKit. At the moment, my newsletter uses fairly basic liquid customization - this may not do the trick for you if you're using more advanced features. Please test your implementation thoroughly!

### Adding more detail to the index page

At the time of writing this post, ConvertKit's v3 API is in "active development" - and as such, it's likely not feature complete. For example, the [current API for list-broadcasts](https://developers.convertkit.com/#list-broadcasts) provides a minimal amount of data about each broadcast:

```bash
curl https://api.convertkit.com/v3/broadcasts?api_secret=<your_secret_api_key>
```

```json
{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
```

Since we want to create an index page that shows a thumbnail for each newsletter, we need to query the API for more information about each newsletter. At the moment, the best way to do this is to query the API for each newsletter individually. It's not ideal, since we need to send an API call for each newsletter shown on the index page, but I'm hoping that with a bit of feedback, ConvertKit will add more data to the list-broadcasts API endpoint.

We already have a function to query the API for a single newsletter (remember `getNewsletter` from earlier?), so we can use that to query the API for each newsletter on the index page.

#### Filter out un-published newsletters

The list-broadcasts endpoint also doesn't currently return whether or not a given broadcast was _published_ yet - which means that if you draft a future broadcast on your ConvertKit dashboard, it will still be returned by the list API. I don't want to share these yet-to-be-sent newsletters on any of my sites, so we'll add some logic to `getAllNewsletters` to filter out any newsletters that haven't been published yet.

#### Don't render newsletters with duplicate subject lines

There are some cases where I send the same newsletter multiple times, with the same subject line, to different audiences - usually because I've forgotten to include some details in the original broadcast. This results in multiple broadcasts with essentially the same content. I don't want to show these on my site, so I added some logic to deduple any newsletters that have the same subject line, displaying only the most recent one (which should be the most correct, in theory).

This is the updated code for `getAllNewsletters` in `convertKit.js`:

```jsx
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();
  const { broadcasts } = data;

  // get details for each individual newsletter
  const newsletters = await Promise.all(
    broadcasts.map((broadcast) => getNewsletter(broadcast.id))
  );

  // hackish dedupe here - sometimes we publish a newsletter a _second_ time as a correction, or to a different audience.
  // In those cases, they should always have the same subject. We're using subject as a way to deduplicate newsletters in that case
  const dedupedBySubject = {};

  // return only newsletters that have been published, and sort by most recent to oldest
  newsletters
    .filter((newsletter) => !!newsletter.published_at)
    .sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
    .forEach((newsletter) => {
      // the first one we encounter in this order will be the newest, so if there's one already we don't make any changes to the object map
      if (!dedupedBySubject[newsletter.subject])
        dedupedBySubject[newsletter.subject] = newsletter;
    });

  let nls = [];
  // iterate over the map we have of subject->newsletter, and push into a fresh array, which we'll return
  for (let subject in dedupedBySubject) {
    nls.push(dedupedBySubject[subject]);
  }

  return nls;
};
```

And with that, our basic implementation is complete - we've created a `/newsletter` page that shows a list of all of our newsletters, with a thumbnail image for each one. We've also added a `/newsletter/[subject]` page that shows the full content of a given newsletter.

## Next steps

There are a few things I'd like to add to this implementation in the future:

- I'm unhappy with the bottleneck I've created for myself using `slugify` on the subject line to create the URL slug. I'd like to find a more efficient way to do this. A reasonable fallback for now might be to use the `BroadcastId` as the slug instead of the subject line, but those aren't human-readable.
- This implementation presents some challenges for SEO - getting newsletter entries to show up in my site's `sitemap.xml` is currently done at build time, which means that new newsletters won't show up in the sitemap until I rebuild the site. In the future, I'll either need to generate the sitemap dynamically, or implement [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching/incremental-static-regeneration) so that new newsletters are added to the sitemap as soon as they're published.
- I'm pretty diligent about [embedding opengraph metadata](https://mikebifulco.com/posts/reset-your-open-graph-embeds-on-linkedin-twitter-facebook) on the pages on my site, including images and excerpts from the article to use as previews on sites like twitter and LinkedIn. This implementation makes that tricky, as determining _which_ image to use as the cover for a given newsletter is a bit of a challenge. Right now I'm using the first image within a newsletter. I'm not sure what the best solution is here, but I'm open to suggestions!

## Wrap-up

I hope this post has been helpful to you, and that you've learned something new about how to use ConvertKit's API to create a custom newsletter index page for your Next.js site. I'd also love it if you checked out Tiny Improvements, my little newsletter about making better products and a better life - [mikebifulco.com/newsletter](https://mikebifulco.com/newsletter).

If you have any questions, or if you've found a bug in my code, please feel free to reach out to me on Twitter [@irreverentmike](https://twitter.com/irreverentmike)!


Growth hack: Publish newsletters to your Next.js site with ConvertKit API

I publish a newsletter called Tiny Improvements

Publish past issues to grow your newsletter

Using the ConvertKit API to publish newsletters to a Next.js site

Keeping your ConvertKit API Secret key safe on Next.js sites

Render the body using dangersoulySetInnerHTML

Helper functions for displaying ConvertKit newsletter content

Don't render newsletters with duplicate subject lines


## I publish a newsletter called Tiny Improvements

[My little newsletter](https://mikebifulco.com/newsletter) is all about making small, incremental improvements to your work and home life. I've been publishing it for over a year now and I've learned a lot about how to make it better.

It's a great way to share less-formal insights with the people who have given me access to their inbox - a privilege which I don't take lightly. It also helps me keep my writing skills sharp, and it's a great way to get direct feedback on my ideas.

Although the audience for my newsletter has been growing, and recently hit [some milestones](https://twitter.com/irreverentmike/status/1569796408043253760), I realized that I had quite a bit of great writing that went out once, via email, and was never seen again. I wanted to make it easier for people to find and read my past newsletter content without subscribing, as way to show the value it provides. I also wanted to take advantage of the [SEO benefits](https://mikebifulco.com/posts/seo-tools-for-new-web-projects) of having past issues of my newsletter content indexed by search engines.

In this post, we'll go over how I use the ConvertKit API to publish a newsletter page for a site built with [Remix](https://remix.run).

## Improve discoverability by publishing past issues

I have a second, important use case for publishing newsletters online. I also maintain my wife's website - [primaryfocus.tv](https://primaryfocus.tv) - which she uses to promote her business and YouTube channel (go [subscribe](https://youtube.com/c/primaryfocus)!).

Primary Focus has a newsletter, and I wanted to make it easy for her to publish her newsletter to her website as well. In fact, I wanted to give her a way to get her newsletter on her website with zero effort - and I was pleased to find that I could do that with the [ConvertKit API](https://developers.convertkit.com/).

Ideally, the workflow should look like this: newsletters are drafted and published in ConvertKit, and, once sent to her subscribers, automatically published to the website as well. This way, she can focus on writing and sending her newsletter, without adding an additional workflow to update her site.

Her site is built with Remix, so this post will go over the details of implementation for publishing past ConvertKit newsletters to a remix site, using their API.

## Using the ConvertKit API to publish newsletters to a Remix site

Setting up an automated newsletter page is fairly simple, at least in theory:

1. Write newsletters and send them, using ConvertKit's broadcast features (for the sake of this post, we'll use the term "newsletter" and "broadcast" somewhat interchangeably).
2. Use the ConvertKit API's list-broadcasts endpoint to query for every published broadcast, to populate a newsletter index page
3. For each published broadcast, use the ConvertKit API to get the details of that broadcast, and then render the content of that broadcast on a page.

To get newsletters from the ConvertKit API, I set up 2 helper functions. First is `getNewsletter()`, which takes a broadcast ID and returns the details of that broadcast.

```js
export const getNewsletter = async (broadcastId) => {
  const res = await fetch(
    `https://api.convertkit.com/v3/broadcasts/${broadcastId}?api_secret=${CONVERTKIT_API_SECRET}`
  );

  // rename "broadcast" to "newsletter" for consistency
  const { broadcast: newsletter } = await res.json();

  return newsletter;
};
```

The second is `getAllNewsletters()`, which returns a list of all published broadcasts. In its simplest form, this function looks like this:

```js
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();

  // rename "broadcasts" to "newsletters" for consistency
  const { broadcasts: newsletters } = data;

  return newsletters;
};
```

<Aside type="warning">

We are using an environment variable to supply the variable `CONVERTKIT_API_SECRET` - it is **super important** to keep this value secret, and not share it on the client-side of your app.

</Aside>

### Keeping your ConvertKit API Secret key safe on Remix sites

Remix provides a has a handy filename convention to ensure certain code _only_ runs serverside - any file that ends in `.server.ts` (for TypeScript) and `.server.js` (for JavaScript) will only be run on the server. This is perfect for keeping our ConvertKit API secret safe. I created a file called `/app/lib/util/convertkit.server.js` with the two functions above, to make sure to only ever access the secret key in there.

### Rendering the newsletter index page

Now that we have a way to get a list of all published newsletters, we can use that to render a page with a preview of each past issue. I created a new file called `/app/routes/newsletter/index.jsx` to render the newsletter index page.

<small>

_note: I stripped out the styling/presentation code from this example to keep
it focused on data loading logic._

</small>

```jsx
import { useLoaderData } from '@remix-run/react';
import { NewsletterCTA, NewsletterListItem } from '~/components';
import { getAllNewsletters } from '~/lib/util/convertKit.server';

export const loader = async ({ params, request }) => {
  return {
    newsletters: await getAllNewsletters(),
  };
};

const NewsletterListPage = () => {
  const { newsletters } = useLoaderData();

  return (
    <>
      <h1>Read past newsletters</h1>
      {newsletters.map((newsletter) => (
        <NewsletterListItem newsletter={newsletter} key={newsletter.id} />
      ))}

      {/* make sure to add a "hey please subscribe to the newsletter" widget to this page! */}
      <NewsletterCTA />
    </>
  );
};

export default NewsletterListPage;
```

This is a fairly standard implementation, if you're familiar with Remix. We use the loader pattern to fetch the list of newsletters, and pass them to the render function for the component with the `useLoaderData()` hook. We then render a list of `NewsletterListItem` components, which shows a header image and title for each newsletter, along with a link to the page for that specific newsletter.

### Rendering a single newsletter page

Now that we have a page listing all published newsletters, we need to create a page template to render a single newsletter. I created a new file called `/app/routes/newsletter/$id.jsx` to render the newsletter index page (note, once again, that presentation and styling code is removed here for simplicify):

```jsx
import { useLoaderData } from '@remix-run/react';
import NewsletterCTA from '~/components';
import config from '~/config';
import {
  broadcastTemplateParse,
  newsletterHasValidThumbnail,
} from '~/lib/util/convertKit';
import { getNewsletter } from '~/lib/util/convertKit.server';

// render meta tags on page for SEO
export const meta = ({ data }) => {
  const { newsletter, canonical } = data;
  const publishedAt = new Date(newsletter.published_at);

  const description = `Primary focus newsletter: ${
    newsletter.subject
  }, published on ${publishedAt.toLocaleDateString()}`;

  return {
    description,
    title: newsletter.subject
      ? `${newsletter.subject} - ${config.meta.title}`
      : config.meta.title,
    'og:image': newsletterHasValidThumbnail(newsletter)
      ? newsletter.thumbnail_url
      : null,
    'og:type': 'article',
    'og:title': newsletter.subject,
    'og:description': description,
    'og:url': canonical,
    'twitter:card': 'summary_large_image',
  };
};

export const loader = async ({ params, request }) => {
  const { id } = params;
  const newsletter = await getNewsletter(id);

  return { newsletter };
};

const NewsletterPage = () => {
  const { newsletter } = useLoaderData();

  const publishedAt = new Date(newsletter.published_at);
  return (
    <>
      <h1>{newsletter.subject}</h1>
      <p className="publish-date">{publishedAt.toLocaleDateString()}</p>
      <div
        dangerouslySetInnerHTML={{
          __html: broadcastTemplateParse({ template: newsletter.content }),
        }}
      />
      <NewsletterCTA />
    </>
  );
};

export default NewsletterPage;
```

Once again, we use the loader pattern to query the ConvertKit API for details about this specific newsletter, and pair that with `useLoaderData()` to provide that information to the page render function. We also use the `meta` function pattern to render meta tags for SEO purposes - you can read more about that in the [Remix docs](https://remix.run/docs/en/v1/api/conventions#meta).

#### Render the body using dangersoulySetInnerHTML

To render the contents of the newsletter, we are using a scary-looking React API pattern - `dangerouslySetInnerHTML`. This is a React API that allows you to render HTML that you have received from an API, and is generally considered a security risk. However, in this case, we are using it to render HTML that we have generated ourselves, and we are at least confident that it is somewhat safe to render. Generally speaking, this is a technique that shouldn't be used unless you are confident that the HTML you are rendering is safe.

#### Helper functions for displaying ConvertKit newsletter content

We're also using 2 helper functions, which are defined in `/app/lib/util/convertKit.js` (note that these are **not** in `convertkit.server.js`, since we need them on the client side):

```js
import { Liquid } from 'liquidjs';

const engine = new Liquid();

export const broadcastTemplateParse = ({ template, data }) => {
  const t = template.replaceAll('&quot;', '"');
  const res = engine.parseAndRenderSync(t, data);
  return res;
};

export const newsletterHasValidThumbnail = (newsletter) => {
  const { thumbnail_url: thumbnailUrl } = newsletter;
  if (!thumbnailUrl) return false;
  if (thumbnailUrl.startsWith('https://functions-js.convertkit.com/icons'))
    return false;
  return true;
};
```

The `newsletterHasValidThumbnail` function is a helper function that checks if the newsletter has a valid thumbnail image. ConvertKit provides a default thumbnail image for all newsletters, but you can also upload your own, by adding an image to your newsletter's body. This function checks if the thumbnail is the default image, and if so, returns `false` so we can skip rendering it.

The `broadcastTemplateParse` function is a helper function that takes a newsletter template and parses it with the [Liquid](https://shopify.github.io/liquid/) templating language. This is how ConvertKit allows you to customize the HTML of your newsletter, and use dynamic data like the subscriber's name, or the date the newsletter was sent.

**An important caveat:** There are _lots_ of little cases where this might not work perfectly, due to all of the amazing things you can do with Liquid in ConvertKit. At the moment, my newsletter uses fairly basic liquid customization - this may not do the trick for you if you're using more advanced features. Please test your implementation thoroughly!

### Adding more detail to the index page

At the time of writing this post, ConvertKit's v3 API is in "active development" - and as such, it's likely not feature complete. For example, the [current API for list-broadcasts](https://developers.convertkit.com/#list-broadcasts) provides a minimal amount of data about each broadcast:

```bash
curl https://api.convertkit.com/v3/broadcasts?api_secret=<your_secret_api_key>
```

```json
{
  "broadcasts": [
    {
      "id": 1,
      "created_at": "2014-02-13T21:45:16.000Z",
      "subject": "Welcome to my Newsletter!"
    },
    {
      "id": 2,
      "created_at": "2014-02-20T11:40:11.000Z",
      "subject": "Check out my latest blog posts!"
    },
    {
      "id": 3,
      "created_at": "2014-02-29T08:21:18.000Z",
      "subject": "How to get my free masterclass"
    }
  ]
```

Since we want to create an index page that shows a thumbnail for each newsletter, we need to query the API for more information about each newsletter. At the moment, the best way to do this is to query the API for each newsletter individually. It's not ideal, since we need to send an API call for each newsletter shown on the index page, but I'm hoping that with a bit of feedback, ConvertKit will add more data to the list-broadcasts API endpoint.

We already have a function to query the API for a single newsletter (remember `getNewsletter` from earlier?), so we can use that to query the API for each newsletter on the index page.

#### Filter out un-published newsletters

The list-broadcasts endpoint also doesn't currently return whether or not a given broadcast was _published_ yet - which means that if you draft a future broadcast on your ConvertKit dashboard, it will still be returned by the list API. I don't want to share these yet-to-be-sent newsletters on any of my sites, so we'll add some logic to `getAllNewsletters` to filter out any newsletters that haven't been published yet.

#### Don't render newsletters with duplicate subject lines

There are some cases where I send the same newsletter multiple times, with the same subject line, to different audiences - usually because I've forgotten to include some details in the original broadcast. This results in multiple broadcasts with essentially the same content. I don't want to show these on my site, so I added some logic to deduple any newsletters that have the same subject line, displaying only the most recent one (which should be the most correct, in theory).

This is the updated code for `getAllNewsletters` in `convertKit.server.js`:

```jsx
export const getAllNewsletters = async () => {
  const response = await fetch(
    `https://api.convertkit.com/v3/broadcasts?api_secret=${CONVERTKIT_API_SECRET}`
  );
  const data = await response.json();
  const { broadcasts } = data;

  // get details for each individual newsletter
  const newsletters = await Promise.all(
    broadcasts.map((broadcast) => getNewsletter(broadcast.id))
  );

  // hackish dedupe here - sometimes we publish a newsletter a _second_ time as a correction, or to a different audience.
  // In those cases, they should always have the same subject. We're using subject as a way to deduplicate newsletters in that case
  const dedupedBySubject = {};

  // return only newsletters that have been published, and sort by most recent to oldest
  newsletters
    .filter((newsletter) => !!newsletter.published_at)
    .sort((a, b) => new Date(b.published_at) - new Date(a.published_at))
    .forEach((newsletter) => {
      // the first one we encounter in this order will be the newest, so if there's one already we don't make any changes to the object map
      if (!dedupedBySubject[newsletter.subject])
        dedupedBySubject[newsletter.subject] = newsletter;
    });

  let nls = [];
  // iterate over the map we have of subject->newsletter, and push into a fresh array, which we'll return
  for (let subject in dedupedBySubject) {
    nls.push(dedupedBySubject[subject]);
  }

  return nls;
};
```

And with that, our journey is complete - we've created a `/newsletter` page that shows a list of all of our newsletters, with a thumbnail image for each one. We've also added a `/newsletter/$id` page that shows the full content of a given newsletter.

## Wrap-up

I hope this post has been helpful to you, and that you've learned something new about how to use ConvertKit's API to create a custom newsletter index page for your Remix site. To see what this looks like in practice, head over to [primaryfocus.tv/newsletter](https://primaryfocus.tv/newsletter).

In my next post, I'll share how I used a similar implementation in **Next.js** on my site - [mikebifulco.com](https://mikebifulco.com).

If you have any questions, or if you've found a bug in my code, please feel free to reach out to me on Twitter [@irreverentmike](https://twitter.com/irreverentmike)!


Publish your newsletter to your Remix site with the ConvertKit API

Improve discoverability by publishing past issues

Using the ConvertKit API to publish newsletters to a Remix site

Keeping your ConvertKit API Secret key safe on Remix sites


## SEO & analytics help grow site traffic

Whether you're working on your own blog, a news site, or building a product, you _absolutely must_ care about your site's SEO. If your site is not optimized for search engines, it is harder to find, leading to fewer visitors and potential customers. SEO tools can help you improve the usability of your site, making it easier for users to find the information they are looking for.

These are the tools that I use to monitor and enhance my sites' performance. The can help you build a site that is easier to find and use, too.

## ahrefs webmaster tools

You only need to spend a few moments researching SEO online before ahrefs pops up _somewhere_ in your results. In addition to their incredible [blog](https://ahrefs.com/blog/) and [studies](https://ahrefs.com/blog/category/data-studies/) on how search works on the web, they provide a fantastic suite of free tools for monitoring and improviing the SEO on your sites.

<Image
  publicId="posts/seo-tools-for-new-projects/ahrefs-audit"
  alt="Screenshot of a weekly audit email from ahrefs - showing a 100 SEO score for mikebifulco.com, with a few warnings."
  caption="There's always room to improve SEO, and ahrefs webmaster tools makes it easy to digest"
/>

I have found [ahrefs webmaster tools](https://ahrefs.com/webmaster-tools) to be absolutely invaluable in keeping an eye on my sites' content. Once you register a free account and verify that you have control of the sites you want to monitor, ahrefs will kick off a weekly audit of all the pages on your domain. It will check for common pitfalls, and give your site a health score from 0-100. If you're a dev, it may be helpful to think of it as a linter for SEO.

I've used it to find and fix countless problems with my sites, from broken links to missing Canonical URLs, removing unnecessary redirects and finding opportunities to link existing articles to one another.

You will get weekly audit reports in email, which let you know when things change - this can be helpful in situations where things out of your control end up affecting your site. Ever had someone take down an article that you link to? Ahrefs will find it.

## Google Search Console

My adoption of [Google Search Console](https://search.google.com/search-console/about) come from what I learned taking Monica Lent's [Blogging for Devs](https://bloggingfordevs.com) course.

Google Search Console gives you reports on how and when people see your site pop up in Google Search results. Note that it won't track people _on your site_ like Google Analytics and Fathom do - just your performance in search. This is a useful litmus for your site's organic growth and authority. If you're investing in sharing your expertise and building a searchable site, your performance on Google Search Console should grow over time. In other words, you can see whether you're gaining traction via SEO or not.

To get started, you'll need to register your site with the Google Search Console. Verifying your ownership takes a few quick steps, and doesn't require you to add Google Analytics (which is helpful if, like me, you've chosen [Fathom](https://mikebifulco.com/posts/why-fathom-analytics) for its privacy-first features).

Best of all, it's free! Just register and follow instructions to add a DNS record, or upload a file to a specific place to verify that you own the site you're interested in monitoring. You should make sure to have a sitemap on your site - they're easy to generate, and worth the time to get right. This is what Google's crawlers primarily use to index your articles for search results.

I use the Search Console to make decisions about things to write about next, and track the progress of my site over time. At the moment, Google will keeps 16 months of your site's traffic history around for you to analyze, but that history starts once you've registered you site with the Search Console. So, the sooner you get set up, the better!

## Fathom Analytics

[Fathom](https://usefathom.com) is privacy first analytics for the web. According to their site, _Fathom is a Google Analytics alternative that doesn’t compromise visitor privacy for data. We revolutionized website analytics by making them easy to use and respectful of privacy laws (like GDPR and more)._

If you've never paid attention analytics for your web properties, Fathom will be a revelation - it's super useful to have an understanding of which pages on your site are getting traffic, where that traffic is coming from, and what times of day are most busy.

If you've used Google Analytics in the past, you may be surprised just how freeing it is to use an analytics tool that prioritizes analytics. You _really_ don't need to know _who_ is on a given page - instead, focusing on the content on your site which is being visited, and the journey readers take to get there is a super useful tool to have when you're researching and writing new articles.

It's great, and puts your readers' privacy first. Google's advantage is quickly vanishing due to new regulations, and privacy tools that are being built into browsers and operating systems. Fathom does a great job of providing value without fishing for every minute detail about your readers.

Fathom is lightweight and ridiculously easy to use. The Fathom team provides docs for a variety of platforms and JAMstack site builders, including [Gatsby](https://usefathom.com/docs/integrations/gatsby), [ConvertKit](https://usefathom.com/docs/integrations/convertkit), [Next.js](https://usefathom.com/docs/integrations/next), [Vue](https://usefathom.com/docs/integrations/vue), [Webflow](https://usefathom.com/docs/integrations/webflow), [Wordpress](https://usefathom.com/docs/integrations/wordpress), and quite a few more.

I've written a bit about my experiences with Fathom before. You may want to check out my other articles, including: [Why I switched to Fathom for Analytics](https://mikebifulco.com/posts/why-fathom-analytics) and [How to add Fathom Analytics to your Remix.run app](https://mikebifulco.com/posts/add-fathom-analytics-to-remix)

### Self-host Fathom for free - Fathom Lite

If you're hesitant to pay for Fathom, they do also provide an open source version called [Fathom Lite](https://github.com/usefathom/fathom) - you'll need to configure and host it yourself, but it should give you an idea of what Fathom's premiums service is like.

If you're interested in trying out Fathom's paid service, use my [**referral link**](https://usefathom.com/ref/DPSSYB) for a discount to get you started.

## Cloudflare

I use [Cloudflare](https://cloudflare.com) to manage the DNS records for all of my sites. In addition to having a _really_ straightforward UI for DNS management, they offer a host of other features to keep your sites running well. This includes automated protection for DDoS attacks, maintenance mode, and performance enhancements such as origin server optimization and caching.

Cloudflare provides a [Free Tier](https://www.cloudflare.com/plans/) that will work for most personal sites. You'll need to set up an account, look for the instructions to add your domain to your Cloudflare account, and then update your DNS settings as needed.

Because I own domains from a variety of registrars, it's really nice to be able to manage DNS for all of them in one place. They also provide a ton of other great dev tools, like [Cloudflare Workers](https://workers.cloudflare.com/), which you can use to add interactivity to your site.

## F5Bot

<Image
  publicId="posts/seo-tools-for-new-projects/f5bot"
  alt="Screenshot of f5bot.com - get an email for when you're mentioned online!"
  caption="F5bot is free, and dead simple to set up. "
/>

The pitch for [f5bot](https://f5bot.com) is simple - as they say, it is a service that will help you to "Get an email when you're mentioned online!".

It's completely free, and takes just moments to set up - you just need to create an account, and set up keywords for the service to track. When your keywords are mentioned on [Reddit](https://reddit.com), [Hackernews](https://news.ycombinator.com), or [Lobste.rs](https://lobste.rs), you'll get a tidy little email in your inbox.

<Image
  publicId="posts/seo-tools-for-new-projects/f5bot-notification "
  alt="screenshot of a notification from f5bot in my gmail inbox. It's a simple plaintext email with a link to an article on mikebifulco.com that was mentioned on Reddit."
  caption="This is what typical notification from f5bot looks like."
/>

Notifications come _very_ quickly - in my experience, I see them within minutes of my sites being mentioned online. This is hugely helpful because it allows you to respond quickly, strike up a conversation, and make a connection with the people who are sharing your work. Those connections are the backbone of building a great personal brand online.

You can set up any search keyword you want, so if there's a competitor or topic that you're hoping to keep an eye on, it's great for that, too.

Overall, I highly recommend [f5bot](https://f5bot.com) - it's an incredibly useful tool, it's free, and it couldn't be easier to set up.

## Related reading

If you're going on the SEO-improvement journey for your sites, you might find these helpful:

- [Why I switched to Fathom for Analytics](https://mikebifulco.com/posts/why-fathom-analytics)
- [How to add Fathom Analytics to your Remix.run app](https://mikebifulco.com/posts/add-fathom-analytics-to-remix)
- [Don't center-align paragraph text](https://mikebifulco.com/posts/dont-center-paragraph-text) - this is utterly unrelated to SEO, but c'mon, do better.
- [SEO for Devs](https://seofordevs.com) - I absolutely cannot recommend this **free course** enough. Monica Lent has a masterful understanding of SEO, and I've learned a ton from her over the years.


SEO tools I used to grow my sites to 20k+ visitors/month


## Semantic HTML makes your sites better

Semantic HTML is important because it helps improve the accessibility of a web page and makes the code more readable. Semantic elements are those that clearly describe their meaning in a way that is easy for both humans and machines to understand.

Search engines can more easily parse and understand semantic HTML, [which can help improve your website's SEO](https://developers.google.com/style/semantic-tagging). Semantic HTML uses tags to describe the meaning of content on a page, rather than just its presentation. This can help search engines better understand the content of a page and index it appropriately.

### Using h2 as a subtitle for an h1 is incorrect

According to the [html spec](https://html.spec.whatwg.org/multipage/dom.html#heading-content-2), `h1` through `h6` tags are meant to indicate the structure of a document. In other words, each page should have at most 1 `<h1>` tag, and `<h2>` elements should be _sub-sections_ of that `h1` - not additional descriptions for it.

This [warning from the HTML spec](https://html.spec.whatwg.org/multipage/dom.html#sectioning-content) does a great job of explaining it:

> For example, the following snippet, intended to represent the heading of a corporate site, is non-conforming because the second line is not intended to be a heading of a subsection, but merely a subheading or subtitle (a subordinate heading for the same section).
>
> ```html
> <body>
>   <h1>ACME Corporation</h1>
>   <h2>The leaders in arbitrary fast delivery since 1920</h2>
>   ...
> </body>
> ```

(07/05/2022) As of the time of this writing, whatwg goes on to recommend use of `hgroup` in its solution. [According to MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hgroup#usage_notes), hgroup should not be used, as it is not supported by assistive technologies needed for accesible reading of HTML sites.

## Use this code to add subtitles to headings

The correct semantic structure of HTML for a heading with a subtitle is straightforward - nest your `<h1>`, etc with in a `<header>` tag, and include a `<p>` tag with an appropriate class name as a sibling to that `h1`:

```html
<header>
  <h1>How to bootstrap a product as a solo founder</h1>
  <p class="tagline">
    Important lessongs learned from building 10 products on my own in 2 years
  </p>
</header>
```

For more details on this, check out [MDN docs on the header tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header), and their [semantics section](https://developer.mozilla.org/en-US/docs/Glossary/Semantics).

### 🚨 UPDATE: I was wrong! 🚨

The first version of this article was wrong! I previously recommended using the `<hgroup>` tag as per the whatwg spec, but I was corrected by [@AnalyticsEqv](https://twitter.com/AnalyticsEqv) on twitter:

<blockquote class="twitter-tweet">
  <p lang="en" dir="ltr">
    MDN specifically recommends against &lt;hgroup&gt; because assistive
    technologies don&#39;t support it.
  </p>
  &mdash; EQV Analytics 🇺🇦 (@AnalyticsEqv){' '}
  <a href="https://twitter.com/AnalyticsEqv/status/1544328749272993792?ref_src=twsrc%5Etfw">
    July 5, 2022
  </a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8" />

Thanks for the correction! I definitely get things wrong sometimes, and I'm always happy to correct myself when appropriate.

## Did you find this helpful?

You might also like these other articles I've written:

- [How to run dependabot locally on your projects](https://mikebifulco.com/posts/run-dependabot-locally)
- [No Floating Promises: an eslint rule to prevent async code errors](https://mikebifulco.com/posts/eslint-no-floating-promises)
- [JavaScript tips: nullish coalescing](https://mikebifulco.com/posts/nullish-coalescing-javascript)

If you want to hear more from me, consider subscribing to my newsletter 👇🏼


The correct semantic HTML for adding subtitles to h1 tags

Using h2 as a subtitle for an h1 is incorrect

Use this code to add subtitles to headings


Building a website using the Remix.run web app framework? This tutorial will teach you how to add privacy-first analytics to your Remix site with Fathom.

## How to set up Fathom on your Remix site

1. Sign into your account with [Fathom](https://usefathom.com/login), and create a new site.
2. Open the settings for that site, and look for _Script settings_. Hit the clipboard icon to copy the Script tag for your site.

   <Image
     publicId="posts/add-fathom-analytics-to-remix/script-settings"
     alt="Script settings for one of my sites on Fathom's dashboard"
     caption="You site's embed code will be on the script settings page. Hit the clipboard button to copy the code"
   />

3. Open up your Remix site in your IDE of choice. open `root.tsx` (or `root.jsx` if you're using JavaScript instead of TypeScript), and paste your embed code right before the `<Script />` tag:

```jsx
return (
  <html lang="en">
    <head>
      <Meta />
      <Links />
    </head>
    <body>
      <Layout>
        <Outlet />
      </Layout>
      <ScrollRestoration />

      <script
        src="https://cdn.usefathom.com/script.js"
        data-site="TRSSCIOR"
        defer
      />
      <Scripts />
      <LiveReload />
    </body>
  </html>
);
```

<small>

_Note: ☝🏽 I've edited the `<script>` tag here to be self closing, rather than having `<script></script>`. It should work either way._

</small>

4. Start your site with `npm run dev` or `yarn dev` and visit any page (you may have to hit reload if you had the page open already). You should see this reflected in your fathom dashboard in real time!
   <Image
     publicId="posts/add-fathom-analytics-to-remix/tracking-results"
     alt="You'll know it's working when you see a live visitor on your fathom dashboard"
     caption="You'll know it's working when you see a live visitor on your fathom dashboard"
   />

## Try out Fathom - it's great!

I've been using Fathom for years, and am a happy paying customer. If you'd like to give it a shot, you can get $10 off of Fathom when you **use my referral link [https://usefathom.com/ref/DPSSYB](https://usefathom.com/ref/DPSSYB)** to get started.

## If you enjoyed this video

- I wrote a post when I initially adopted fathom, called [Why I switched to Fathom for analytics](https://mikebifulco.com/posts/why-fathom-analytics)
- Make sure to [subscribe to my YouTube channel](https://www.youtube.com/channel/mikebifulco)


#tutorial: 7 posts tagged