
## The Big Idea

Every message is a moment of influence. Make the nudge helpful and you'll create power users and build loyalty.

## What is Nudge Theory?

Nudge Theory is a framework for guiding user behavior through subtle, persuasive techniques. It is based on the idea that people are more likely to change their behavior if they are given a choice that is easy to make.

In other words, a little proactive messaging goes a long way.

### Why Nudge Theory Matters

There's a little bit of behavioral science at play when a product uses thoughtful nudges in its onboarding. Research in behavioral economics shows that small, well-timed cues can help people adopt new habits and tools more easily. In other words, a gentle nudge at the right moment can make all the difference.

## A concrete example: Blacksmith

That's exactly what we found with [Blacksmith](https://blacksmith.sh?utm_source=tinyimprovements&utm_medium=email&utm_campaign=nudge-theory-for-guiding-user-behavior). It promised to speed up our CI workflows for less cost, something my team at [Craftwork](https://craftwork.com) would benefit from immensely.

<Image
  publicId="newsletters/nudge-theory-for-guiding-user-behavior/blacksmith-value-prop"
  alt="A screenshot of the Blacksmith's home page value prop"
/>

Our initial onboarding was smooth - the software generated a PR to swap our CI workflows onto their infrastructure. The speed boost was immediate, and life-changing for my team.

### Thoughtful Nudges in Action

What really impressed me was what happened a day later - each day, I would receive an email with a new tip, rooted in behavioral insights, to guide us step-by-step on how to get the most value from Blacksmith.

From the first message, Blacksmith gently introduced us to one feature at a time. Each day, a new tip arrived - ensuring that the game-changing features the Blacksmith team built didn't get lost in my haste to try the product out on Day 1.

<Image
  publicId="newsletters/nudge-theory-for-guiding-user-behavior/blacksmith-drip-campaign"
  alt="A screenshot of the Blacksmith's onboarding process"
  caption="Zero code-changes required? Sign me up."
/>

They could have spent a lot of time developing a slick, highly-interactive onboarding wizard -- which I almost certainly would have skipped. Instead, a slick little drip campaign offered even more value for my team.

You better believe I tried each one.

---

## Use these powers for good

- The Wikipedia entry for [Nudge Theory](https://en.wikipedia.org/wiki/Nudge_theory) is a great primer - it may sound wishy-washy, but this is real behavioral science.
- Nudge Theory is, of course, a two-sided coin - there's a great paper on [ethical concerns with nudging](https://journals.sagepub.com/doi/10.1177/10434631231155005) that is worth a read.

So, how will you turn this knowledge into action? Whether you're building a product or trying to influence people to be better neighbors, there is a whole lot of power in the way you reach people with your messaging.










The Psychology Hack Hiding in Great Products


## I'm new to TypeScript.

I've been using TypeScript to build software for my new company, [Craftwork](https://craftwork.com). I've been pretty open about the fact that I'm new to TypeScript, and have been blissfully writing non-type-safe javascript code since somewhere around 2005.

Of course, that's all changing.

This new project is built with [create-t3-app](https://create.t3.gg), a framework for building TypeSafe apps with Next.js and TRPC. Out of the box, t3 is configured with some sensible (and fairly strict) settings for both eslint and TypeScript's tsconfig.

If you're familiar with TypeScript, Eslint, and tsconfig you may want to skip ahead to [My last resort to fix TypeScript errors in VS Code](#my-last-resort-to-fix-typescript-errors-in-vs-code).

### ESLint in a nutshell

If you're not familiar, _eslint is a **linter**_ - a tool that will help you identify and fix code quality and formatting issues in your code.

ESLint is a popular linter for JavaScript, and it can also be used with TypeScript. It provides a wide range of configurable rules that you can use to enforce consistent code style and identify potential bugs. ESLint is highly extensible, which means you can customize it to fit your specific needs. For example, you can use it to enforce your team's coding standards, or to catch common mistakes that TypeScript can't detect on its own.

### tsconfig in a nutshell

When you're working on a TypeScript project, `tsconfig.json` is a configuration file that allows you to specify how the TypeScript compiler should behave when it compiles your code.

The purpose of `tsconfig.json` is to provide a single source of truth for your TypeScript project's configuration. It allows you to specify options such as the target version of JavaScript you want to generate, the module system you want to use, the paths to your project's source files, and many other settings.

One of the main benefits of using `tsconfig.json` is that it allows you to enforce a consistent set of rules across your project. You can use it to enforce specific compiler options, which helps to ensure that your code is consistent and that everyone on your team is using the same settings. `tsconfig.json` also allows you to configure your project's build pipeline, so you can easily automate the process of compiling and bundling your TypeScript code.

Additionally, `tsconfig.json` allows you to take advantage of features like incremental compilation, which can significantly improve the speed of your builds by only compiling the parts of your project that have changed since the last build.

## How TypeScript works in VS Code

There are a few steps required to set up TypeScript to work with VS Code. If you haven't done this yet, you should follow the instructions on VisualStudio.com to get started: [TypeScript in Visual Studio Code](https://code.visualstudio.com/Docs/languages/typescript).

When you open a TypeScript file in VS Code, the TypeScript language server will start in the background. The language server is a separate process that provides language features like IntelliSense, code navigation, and code refactoring. It also provides the ability to run TypeScript code in the editor. Because TypeScript has _many_ options and plugins, the language server uses the `tsconfig.json` file in your project to determine the rules it should use to compile your code.

VS Code needs to determine which version of TypeScript to use, so it will look for a `package.json` file in your project. If it finds one, it will use the version of TypeScript specified in the `devDependencies` section. If it doesn't find a `package.json` file, it will use the version of TypeScript that is bundled with VS Code.

---

## My last resort to fix TypeScript errors in VS Code

Sometimes, when I'm working on a TypeScript project, I'll get an error in VS Code that I can't figure out. I'll check and double-check against articles and tutorials online, or ask my hyper-smart TypeScript friends ([Sean Rogers, everyone](https://seanrogers.dev/)), and despite doing everything I can think of to address the problem, sometimes I just can't get the error to go away.

Here's what I do when I find myself in this situation:

### Make sure VS Code is using the correct version of TypeScript

Sometimes VS Code's TypeScript process doesn't use the right version of TypeScript for the project I'm working on. For me, this seems to happen after updating TypeScript versions, or when switching between projects that use different versions of TypeScript.

To check which version of TypeScript VS Code is using, open the Command Palette (Ctrl+Shift+P on Windows, or &#8984; on a Mac) and type `TypeScript: Select TypeScript Version`.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/select-typescript-version"
  alt="Select TypeScript Version in the command palette in VS Code"
/>

If the version of TypeScript that is selected is not the one you expect, select the correct version from the list. Generally speaking, you'll want to select the version of TypeScript that is specified in your project's `package.json` file, by selecting `Use Workspace Version` option.

### Restart the TS server process

If that doesn't fix the problem, or VS Code was already running my workspace's version of TypeScript, the next thing I'll do is restart the TS server process. This is the background process being run by VS Code to actually analyze and compile your TypeScript code into JavaScript. Sometimes this process malfunctions, and restarting it can fix the problem.

To restart the TS server process, open the Command Palette (Ctrl+Shift+P on Windows, or &#8984; on a Mac) and type `TypeScript: Restart TS Server`.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/select-typescript-version"
  alt="Select TypeScript Version in the command palette in VS Code"
/>

### Restart the ESLint server process

On occasion I'll also need to restart the ESLint server process. Just like it sounds, this is the process that analyzes your code for linting errors, according to the rules specified in your project's `.eslintrc` file and the version of ESLint that is specified in your project's `package.json` file.

<Image
  publicId="posts/typescript-vscode-error-fix-last-resort/restart-eslint-server"
  alt="Restart ESLint Server in the command palette in VS Code"
/>

## If that doesn't work, I'm out of ideas

..and by that, I mean I'm still learning. There's loads to learn about TypeScript, and I've found quite a few great resources online from devs like me who have shared their experiences and knowledge. I hope this article helps you - and if you're looking for more, check these out:

- Kent C. Dodds has a great article called [Using fetch with TypeScript](https://kentcdodds.com/blog/using-fetch-with-type-script) which I nearly have memorized at this point. This is the problem I was trying work through when I discovered that I needed to restart the TS server process in VS Code.
- [James Q. Quick](https://www.youtube.com/@JamesQQuick) has a great YouTube channel where he shares tips and tutorials for building web apps with a wide variety of frameworks and technologies.
- I've got some more articles on working with TypeScript in VS Code, including [Refactoring TypeScript React components in VS Code](https://mikebifulco.com/posts/refactoring-typescript-react-components-vscode#resources-for-learning-typescript)


Steps I take to fix stubborn TypeScript errors in VS Code

My last resort to fix TypeScript errors in VS Code

Make sure VS Code is using the correct version of TypeScript


## Extracting types from a JavaScript object

I am brand new to TypeScript, and far from an expert. So far, I really enjoy using it to build React apps with Next.js. As I'm growing the skills I'll need to be a better TypeScript developer, I'm finding that a fairly typical chore for me is to refactor my code to extract types from a JavaScript object. For example, I often find myself writing code in react components that looks a lot like this:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};

export default PageLayout;
```

There is no type-checking going on in this code as it is written. I've been writing react with good ol' plain JavaScript for so long that creating components like this is reflexive for me. I'm not even thinking about it.

Eventually during implementation I get to the point where adding some complexity to the component requires me to add some type-checking. At that point, I usually refactor the component to lambda syntax, and add a type annotation to the component:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};

export default PageLayout;
```

Next, I'll add a type annotation to the `children` prop:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout = ({ children }: { children: React.ReactNode }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Taking it a step further, I'll give the function a return type signature, using `React.FC` and generics to define the props:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Up to this point, I don't really mind the way this component was written in any of the previous refactors. It's clearly getting more complex, but I can still understand what's going on. But what if I wanted to add a `variant` prop to the component? I'd have to add another type annotation to the function signature:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

const PageLayout: React.FC<{
  children: React.ReactNode;
  variant: 'dark' | 'light' | 'black' | 'tan';
}> = ({ children, variant }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header variant={variant} />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Even with a little prettier formatting, this is getting a little hard to read. This is where I usually extract the props into a type, and then use that type in the function signature:

```tsx
import Footer from '@components/Footer';
import Header from '@components/Header';

type PageLayoutProps = {
  children: React.ReactNode;
  variant: 'dark' | 'light' | 'black' | 'tan';
};

type PageLayout = React.FC<PageLayoutProps>;

const PageLayout: PageLayout = ({ children, variant }) => {
  return (
    <>
      <section className="min-h-[100vh] pb-8 sm:pb-12 lg:pb-12">
        <Header variant={variant} />
        <div className="lg:relative">{children}</div>
      </section>
      <Footer />
    </>
  );
};
```

Now _this_ I like! The props for this page are defined in a single place, and the function signature is much easier to read.

## Using VS Code's refactor menu to extract types

As it works out, VS Code has loads of functionality to make this sort of work quicker. The refactor menu can be accessed by highlighting some code, right clicking on it, and selecting `Refactor...`. There are a number of TypeScript-specific functions provided which can help you refactor your code.

In this case, we can extract types from our component's signature in a few steps:

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-1"
  alt="VS Code Screenshot: Select the entire `React.FC<` return type and right clicking on it"
  caption='Select the entire `React.FC<` return type and right click on it, and Choose "Refactor..." from the context menu.'
/>

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-2"
  alt="VS Code Screenshot: Choose 'extract type to type alias' from the refactor menu"
  caption='Select "Extract type to type alias" to extract the type into a type alias'
/>

<Image
  publicId="posts/refactoring-typescript-react-components-vscode/refactor-3"
  alt="VS Code Screenshot: Give the extracted type a name, and hit enter."
  caption="Give the extracted type a name, and hit enter."
/>

## Bonus: Add JSDoc comments to your types for better intellisense

If you want to take it further, you can add a JSDoc comment to the type definition to add some documentation. This is a good way to document your code, and it's also a good way to get better intellisense for your code if it's supported in your editor:

```tsx
import Footer from "@components/Footer";
import Header from "@components/Header";

type PageLayoutProps = {
  children: React.ReactNode;
  variant: "dark" | "light" | "black" | "tan";
};

/**
 * The PageLayout component is used to wrap all pages in the application.
 * It provides a consistent header and footer, and a consistent layout for
 * the page content.
 * @param {object} props
 *   @param {React.ReactNode} props.children - The page content
 *   @param {"dark" | "light" | "black" | "tan"} props.variant - The color variant for the page
 * @returns {JSX.Element}
 **/
const PageLayout: PageLayout = ({ children, title }) => {

  /* etc */
```

## Don't learn TypeScript, just use it

...and by that I mean that TypeScript is a _great_ enhancement to building things with JavaScript, but you do not need to be an expert on TypeScript to use it by any means. I've been starting to use TypeScript more and more in my projects, and I've found that I can get a lot of mileage out of it without having to learn every single detail about it.

Theo from [t3.gg](https://t3.gg) has a great video that sums up my learning strategy for TypeScript pretty well, called Don't Learn TypeScript. I highly recommend watching it, or putting it in your queue for your next coffee break:

<YouTube youTubeId="kRiD6ZpAN_o" />

## Resources for learning TypeScript

As I mentioned, I'm fairly new to TypeScript - I only just started using it in the past few months. If you're learning TypeScript and are looking for some great places to learn, check these out:

- [Matt Pocock's YouTube channel](https://www.youtube.com/@mattpocockuk) is a library of really interesting videos about TypeScript. He shares tutorials as well as experience-driven, nuanced opinions about TypeScript (_when should I use an interface instead of a type?_ etc). IMO he's the defacto expert on TypeScript in real life.
- [TypeScript Course](https://www.typescriptcourse.com/) is a fantastic _free_ email course from [Joe Previte](https://jsjoe.io) [(@jsjoeio)](https://twitter.com/jsjoeio). It's a to learn TypeScript a little bit at a time.
- [TypeScript Deep Dive](https://basarat.gitbook.io/typescript/) is just what it sounds like - a thorough deep dive into TypeScript. It's a free book, with an available paid course on Udemy for those who want more .
- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html) is the official TypeScript documentation. For better or worse, I don't think it's a great place to start, but it contains every detail you might possibly need. I've found myself coming back to it from time to time to look up specific features and to help debug this-and-that.


Refactoring TypeScript React components in VS Code

Extracting types from a JavaScript object

Using VS Code's refactor menu to extract types

Bonus: Add JSDoc comments to your types for better intellisense


## Your about page tells the world who you are, and what matters to you

For many developers, the about page is one of the most important pages on your website. It tends to be one of the most highly-visited pages on many devs' sites. It serves as the page that will tell the world who you are, and what matters to you. It's also the page that will help you stand out from the crowd, and help you connect with your audience.

Similarly, your [GitHub profile README](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-profile/customizing-your-profile/managing-your-profile-readme) is the first thing that people will see when they visit your profile on GitHub. I've seen many creative uses for personal GitHub profile pages, but they are most commonly used as a place to share a bio, and to connect with your audience.

They Sounds awfully similar, no?

This week, I decided that for me at least, they _should_ be one in the same. [My personal about page](https://mikebifulco.com/about) and my [GitHub Profile](https://github.com/mbifulco) contained a lot of overlapping information, but weren't _quite_ the same. My site is built with Next.js, and I use an extension of Markdown called MDX to write my content. My GitHub profile README is written in Markdown. Because of this, keeping them in sync turned out to be pretty easy.

## Setup and background

Making this setup work requires some modifications to your Next.js site, and it's important to understand how things work before you dive in. Here's a quick overview of how this setup works:

### Content flows from GitHub -> your Next.js site

In this setup, the source of truth for content on the about page will be GitHub Profile README. From the next.js site, we fetch the README and render it on the About page using a library called [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote).

So, to update our bio in _both places_, we'll edit the README file on GitHub. This will update the content on our About page, as well as our GitHub profile README.

### About next-mdx-remote

[`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote) is an npm library that provides an API for loading remote MDX files into Next.js. It allows developers to write their pages in [MDX](https://mdxjs.com/docs/), an extension of [Markdown](https://daringfireball.net/projects/markdown/) that supports embedded React components. It also provides an API for loading the MDX files from a remote URL, allowing developers to use an external CMS or content storage system to manage their page content. This is exactly what we need to sync our About page and our GitHub profile README, which is written in Markdown.

## How to sync your Next.js site About page to your GitHub README

Here's how you can set this up:

1. First, create an About page on your Next.js site. Typically, this means creating a file in the `/pages/` directory of your source code called `about.jsx` (or `about.tsx` if you're using TypeScript).

```jsx
// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

export default function About({ source }) {
  return <Layout>{/* content from GitHub will go here */}</Layout>;
}
```

2. Next, create a GitHub profile README. If you haven't done this before, Monica Powell ([@indigitalcolor](https://twitter.com/indigitalcolor)) has a great tutorial - [How to create a GitHub profile README](https://aboutmonica.com/blog/how-to-create-a-github-profile-readme). This is where you'll write your bio - and this is the file that will be synced to your About page.

3. Now you'll need to set up next-mdx-remote on your Next.js site. Once your readme is fetched from GitHub, we will use this library to serialize it as MDX -- in other words, to transform it from Markdown to renderable react components for Next.js.

If you don't already have it installed, you can install it with npm, yarn, or pnpm.

```bash {1,3-5}
npm install next-mdx-remote
# or
yarn add next-mdx-remote
# or
pnpm add next-mdx-remote
```

4. Next, we need to grab the raw Markdown from our GitHub README, and feed it into next-mdx-remote. I chose to do this in getStaticProps, which means it will be fetched and rendered once when my site is built, and then cached. This is fine for my use case, but if you're updating your about page frequently, you may want to use getStaticProps instead, to fetch your README on every page render.

So, back in `pages/about.jsx`:

```jsx {1,3-5}
import { serialize } from 'next-mdx-remote/serialize';

// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

// fetch personal README from github and return it as mdx in getserversideprops
export async function getStaticProps() {
  const res = await fetch(
    // replace this with your own README's raw URL (see below)
    'https://raw.githubusercontent.com/mbifulco/mbifulco/main/README.md'
  );
  const content = await res.text();

  // include mdxOptions as needed on your site
  const mdxSource = await serialize(content /*, mdxOptions */);

  return {
    props: {
      mdxSource,
    },
  };
}

export default function About({ source }) {
  return <Layout>{/* content from GitHub will go here */}</Layout>;
}
```

To get the raw URL for your README, go to your GitHub profile, and click on the README file. Then, click the "Raw" button in the top right corner of the file. Copy the URL from the address bar, and replace the URL in the code above with your own.

5. Finally, you can render your README in your About page using MDX Remote.

```jsx
// If you want to have MDX render custom components, you can import them here
import { components } from '~/utils/mdx-components';
import { MDXRemote } from 'next-mdx-remote';
import { serialize } from 'next-mdx-remote/serialize';

// For sake of example, we'll use a Layout component to represent the visual layout of the page
import Layout from '../components/Layout';

export async function getStaticProps() {
  // fetch personal README from github
  const res = await fetch(
    // replace this with your own README's raw URL
    'https://raw.githubusercontent.com/[YOUR_USERNAME]/[YOUR_USERNAME]/[YOUR_DEFAULT_BRANCH]/README.md'
  );
  const content = await res.text();

  // include mdxOptions as needed on your site
  const mdxSource = await serialize(content /*, mdxOptions */);

  // pass the mdxSource to the page component in props
  return {
    props: {
      mdxSource,
    },
  };
}

export default function About({ mdxSource }) {
  return (
    <Layout>
      {/* note: passing in components is optional */}
      <MDXRemote {...mdxSource} components={components} />
    </Layout>
  );
}
```

Bingo bango, we're there! Now, whenever you update your README, your About page will reflect those changes the next time your site is built. If you'd like to see how [the about page for my site](https://mikebifulco.com/about) is implemented, you can check out the [source code on GitHub](https://github.com/mbifulco/blog/blob/main/src/pages/about/index.js), since it's all Open Source!

## More Next.js goodness

If you enjoyed this post, you might want to check out some of my other [articles on next.js](https://mikebifulco.com/tags/nextjs) :

- [Publish newsletters to your Next.js site with ConvertKit API](https://mikebifulco.com/posts/publish-your-newsletter-with-convertkit-api-next-js)
- [What it's like to migrate a high-traffic website from Gatsby to Next.js](https://mikebifulco.com/posts/migrate-gatsby-to-nextjs-apisyouwonthate-com)
- [https://mikebifulco.com/posts/mdx-auto-link-headings-with-rehype-slug](https://mikebifulco.com/posts/mdx-auto-link-headings-with-rehype-slug)


Sync your About page and your GitHub bio on your Next.js site

Your about page tells the world who you are, and what matters to you

Content flows from GitHub -> your Next.js site

How to sync your Next.js site About page to your GitHub README


<Aside type="warning">

## The bottom line: It's time to leave Twitter

As Twitter changes, ask yourself: Are you willing to follow any authority, even at the expense of your values? Before your next tweet, consider what staying truly costs-and explore new spaces that reflect your integrity.

</Aside>

## The Milgram Experiment

In 1961, a Yale University researcher named Stanley Milgram conducted a series of experiments as a part of his research on behavioral psychology. The goal of the experiment was to test participants' tendency to obey authority figures when under pressure.

The experiment was conducted on 40 volunteers -- all men between the ages of 20 and 50, from a variety of educational and economic backgrounds.

Milgram later summarized findings from the experiment in an essay titled _The Perils of Obedience_.

The results were breathtaking.

### The Experiment: Setup

Each study was guided by an _Experimenter_ dressed in a lab coat, who explained to participants that they'd be doing a "scientific study on memory and learning." When they arrived, participants were paired with an actor who they were _told_ was another participant in the study.

The actor was secretly working with the researcher, and during the experiment was instructed to play the role of a _Learner_.

The volunteer participant was given the role of _Teacher_. The Experimenter then explained that the study would involve the Teacher asking the Learner a series of questions. For each incorrect answer, the Teacher would be asked to hit a button which would administer an electric shock to the Learner. Subsequent incorrect answers would result in a shock of increasing intensity, from 15V to 450V.

The Learner was strapped into a device that looked like an electric chair, and then separated from the Teacher so that they could not see one-another.

<Image
  publicId="posts/twitter-and-the-perils-of-obedience/experiment-setup"
  alt="Diagram of the setup used for the Milgram Experiment, with the Experimenter and Teacher on one side of a wall, and the Learner on the other."
  caption="Credit: diagram of the Milgram experiment from Wikipedia"
/>

In reality, there were no shocks being administered, but this was unknown to the study participant playing the role of the Teacher. The actor playing the role of the Learner was instructed to pretend to be in pain, and recordings of increasingly alarming cries of pain were played when shocks were administered.

When the highest shock level was reached, the Learner fell completely silent.

During the experiment, if the Teacher showed hesitation to continue, the Experimenter gave them a series of specific instructions:

1. Please go on.
1. The experiment requires that you continue.
1. It is _absolutely essential_ that you continue.
1. You have no other choice; you _must_ go on.

These "prods" were given in order, and the second was only given if the Teacher refused to continue after the first (and so on).

The experiment was halted when the Teacher refused to continue despite all four prods, or when the Teacher reached the highest shock level three times in a row.

<Image
  publicId="posts/twitter-and-the-perils-of-obedience/experiment-photos"
  alt="Photos from the original Milgram experiment, credit Stanley Milgram."
  caption="Photos from the original Milgram experiment, credit Stanley Milgram"
/>

### What would you do?

Let's take a minute to pause here - put yourself in the shoes of the Teacher. You're in a lab, and you're told that you're taking part in a study on learning and memory. Everything you're seeing and hearing seems to be controlled, official, and legitimate.

Do you think you would continue to administer shocks to the Learner, even when they were clearly in pain?

What do you think the average person would do?

<span className="mb-8 flex items-center justify-center text-2xl">
  <Colophon />
</span>

### The Experiment: Results

As you might expect, every participant in the study indicated a desire to stop the experiment at least once. Many were visibly upset by the experience, and despite this, carried on following the Experimenter's instructions.

Before conducting the experiment, researchers surveyed a cohort of students and fellow researchers, to get a sense of what they thought the average person would do. In aggregate, they estimated that 1.2% of people would continue the experiment through the full 450V shock.

<Image
  publicId="posts/twitter-and-the-perils-of-obedience/predicted-results"
  alt="Predicted Results: 1.8% complete the full series of shocks, 98.2% refuse to continue at some point"
  caption="Surveys predicted that very few participants would carry out the full series of shocks"
/>

However, the actual results of the experiment revealed a disturbing truth about human behavior:

<Image
  publicId="posts/twitter-and-the-perils-of-obedience/actual-results"
  alt="Actual Results: 59.1% completed the full series of shocks, 40.9% refused to continue at some point"
  caption="The experimental results were much more grim."
/>

Very nearly 60% of participants carried out the full series of shocks, carrying the study to its conclusion -- even when the Learner sounded like they were clearly in pain, and until they fell silent.

Recreations of this experiment have produced similar results, [as recently as 2009](https://www.apa.org/news/press/releases/2008/12/replicating-milgram).

Milgram's experiment revealed the ease with which people obey authority figures - even when it conflicts with their morals. Twitter, under Musk, can feel like a modern replication of this phenomenon. With reduced moderation and authority shifting dramatically, users face their own “shock button”: Do they accept increasingly extreme content and directives, or walk away?

Like Milgram's participants, twitter users are nudged to compromise their ethics - creating a tension that asks: _how far will you go?_

## Obedience and the Perils of Twitter

I can't help but draw a connection between the Milgram experiment and the current state of Twitter since its acquisition by Elon Musk. Twitter has turned into a public experiment, testing our willingness to obey rules set by an authority figure, despite many less damaging alternatives.

Since Elon purchased the company, we've seen the voltage knob get turned up steadily and swiftly.

Under Musk's leadership, Twitter's employee base has been slashed from 7,500 to approximately 2,000, in an attempt to make the company profitable. It appears that Musk may be trying to avoid paying severance to these now-former employees. There are already [several lawsuits pending](https://www.reuters.com/technology/twitter-says-lawsuit-over-layoffs-lacks-merit-has-delayed-severance-pay-2022-11-22/) against the company.

A recent tweet from Musk included a poll which resulted in the reinstatement of former (and twice-impeached) president Trump's account.

For me, this was the final straw.

<Tweet align="center" tweetLink="irreverentmike/status/1594455660040572928" />

Since then, another poll from Musk has resulted in an abhorrent policy change: virtually all accounts that were previously suspended for violating Twitter's rules will be reinstated.

<Tweet align="center" tweetLink="elonmusk/status/1595473875847942146" />

Pandora's box is open, and the monsters are flooding in. Twitter has already seen a spike in hate speech, harassment, and abuse. Without significant and drastic changes in moderation, it will become a breeding ground for countless nightmares and real-world dangers. This will worsen the echo chamber effect for far-right conspiracy theorists, like those who participated in the January 6th, 2021 insurrection at the US Capitol.

This is a very real, very observable truth: racists, abusers, and other dangerous people are being given "amnesty" to come back the platform.

Legions of [advertisers have pulled their ad spend](https://www.npr.org/2022/11/25/1139180002/twitter-loses-50-top-advertisers-elon-musk) from Twitter as a result of Musk's takeover. I've seen many individuals abandon their Twitter accounts in the wake of these changes, moving to Mastodon or LinkedIn.

## We must build bridges

Why are so many people still active on Twitter, despite the steady stream of bad news? I can think of at least a few things:

### Career

Some have built a career around their Twitter presence and following. Heck, my personal Twitter account was a big part of my job [until recently](https://mikebifulco.com/newsletter/leaving-stripe-going-viral) - it's certainly much easier for me to abandon ship now that my job no longer relies on Twitter for outreach.

I can understand a deep hesitancy to abandon a platform that has been so central to your life, especially without a clear "winner" as an alternative. Embracing a new platform like Mastodon, Threads, or Bluesky requires starting from zero. It can be exhausting to build a new following, and it's hard to know if you'll ever reach the same level of engagement.

### Community Support

There are incredible communites on Twitter like `#BlackTechTwitter`, which has grown to be a critical resource for many people of color in tech. The logistics of getting hundreds-of-thousands of people to move to a new platform is staggering. The LA times recently published [an interview](https://www.latimes.com/business/story/2022-11-07/black-twitter-influencers-others-debate-leaving-twitter) with Pariss Chandler, the founder of [Black Tech Pipeline](https://blacktechpipeline.com/) and creator of the `#BlackTechTwitter` hashtag, discussing the challenges associated with leaving the platform.

It is encumbent on all of us to provide space and time for communities like these to find a new home. Moreover, it's critical that the new homes we create are _at least as valuable_ as Twitter was at its peak. There is a complex cost-benefit analysis for every community member to consider, and we must be mindful of that.

### News and Information

Some use Twitter as a way to keep up with relevant news in their industry. This feels like a solvable problem to me, but it faces a challenge of momentum. Until enough industry experts are sharing news elsewhere, these people will remain on twitter out of habit and convenience.

So -- if you find yourself using twitter and another platform for news, consider sharing useful information on the other platform. It's a small step, but it can make a big difference.

### Lack of social pressure

When it came down to it, even I was hesitating to leave twitter without _seeing someone else do it_ first.

In my first job after undergrad, I had a boss who frequently used the phrase "You are far more influential than you think". Those have proven to be very wise words.

Social pressure will be a necessary component of the transition away from a Twitter run by Elon Musk. I'm hopeful that we'll see more people leave the platform, and that the momentum will build. If and when you decide to consider greener pastures, use your influence and make it known to your community.

## Learning from the Milgram Experiment

Years after the experiment was complete, in his book _Obedience to Authority,_ Stanley Milgram ruminated the results of his now-infamous experiment:

> Ordinary people, simply doing their jobs, and without any particular hostility on their part, can become agents in a terrible destructive process. Moreover, even when the destructive effects of their work become patently clear, and they are asked to carry out actions incompatible with fundamental standards of morality, relatively **few people have the resources needed to resist authority.**

This is not the time to be complacent. We must build a bridge to a better future, and we must do it together.

## If not now, when?

Friends, it's time to start leaving Twitter. Move your news and discussions elsewhere, and bring your people with you. When you're ready, shutter your accounts, delete the app, and move on. I know it's hard, but it's time. Every moment we spend on Twitter is feeding legitimacy to a platform that is enabling abusers, endangering global politics, and destroying the fabric of our society.

Do not allow the voltage to rise by relying on Twitter as your primary social platform.

Perhaps most importantly, make it clear to your friends and neighbors from marginalized groups that their voices are valuable, and welcomed on the platforms you move to.

Bring your voice and your conversations elsewhere, and send the message that with its current leadership, Twitter is no longer a place for you.

<Image
  publicId="posts/twitter-and-the-perils-of-obedience/experiment-1"
  alt=""
/>
<Image
  publicId="posts/twitter-and-the-perils-of-obedience/experiment-2"
  alt=""
/>
<Image
  publicId="posts/twitter-and-the-perils-of-obedience/experiment-3"
  alt=""
/>

## Footnote: on the ethics of the Milgram Experiment

It's important to note that in the years since Milgram Experiment was conducted, it has been criticized for its methodology. [Research Ethics](https://en.wikipedia.org/wiki/Research#Research_ethics) is a complex and nuanced topic, and I don't believe that the experiment would be approved by modern ethics boards in its original form. However, I believe that the results of the experiment are still relevant, and that the experiment itself is still a valuable tool for understanding human behavior.

The experiment _has_ been recreated in a more ethical manner, with the same results. [This article](https://www.apa.org/news/press/releases/2008/12/replicating-milgram) from the American Psychological Association summarizes the results of a 2008 replication of the experiment, which was conducted by a team of researchers at Yale University. In this version of the study, participants were screened to ensure that they were not at risk of being harmed by the experiment, and were given the option to withdraw from the study at any time. The maximum simulated voltage level for the Learner was decreased to 150V, and a test shock was given to participants at 15V, as compared to 45V in Milgram's original study.

The results of the 2009 study were the similar to the original experiment.

## References

Information about the Milgram experiment can be found from the following resources:

- [APA Psych Net - Behavioral Study of obedience.](https://psycnet.apa.org/record/1964-03472-001)
- [Obedience to Authority](https://hardcover.app/books/obedience-to-authority) by Stanley Milgram
- [Internet archive - Obedience to authority: an experimental view](https://archive.org/details/obedien_mil_1974_00_3145)
- [Wikipedia entry for the Milgram experiment](https://en.wikipedia.org/wiki/Milgram_experiment)
- [APA - Replicating Milgram: Researcher Finds Most Will Administer Shocks to Others When Prodded by ‘Authority Figure’](https://www.apa.org/news/press/releases/2008/12/replicating-milgram)
- [APA - Replicating Milgram (pdf)](https://www.apa.org/pubs/journals/releases/amp-64-1-1.pdf)

### More perspective on leaving twitter

In my research for this post, I came across a few other articles about leaving Twitter, and I wanted to share them here:

- [Black Twitter influencers, other thought leaders debate leaving Twitter. But for what?](https://www.latimes.com/business/story/2022-11-07/black-twitter-influencers-others-debate-leaving-twitter) Alexandra Olson and Maryclaire Dale, LA Times via AP
- [“A double-edged sword”: 4 women of color on Elon’s Twitter takeover](https://www.mic.com/impact/elon-musk-twitter-women-leaving)
- [Why I Quit Elon Musk's Twitter](https://www.newyorker.com/news/daily-comment/why-i-quit-elon-musks-twitter) by Jelani Cobb, New Yorker

<small>

_Note: The photo used for the cover of this article is from [john elfes](https://unsplash.com/@johnelfes?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText) on [Unsplash](https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)_

</small>


Twitter and the Perils of Obedience

The bottom line: It's time to leave Twitter

Footnote: on the ethics of the Milgram Experiment


Recently, I've been asking developers what they think of no-code tools. Friends, I'm here to tell you - some of the responses I've gotten are extremely frustrating.

They range from discouraging to straight up disparaging, especially for newbies who are excited about the prospect of building something for the first time.

"no-code tools?" I had one developer tell me. "What are those? Another bubble that's going to burst?"

"I wouldn't trust any tool that makes it easy for people with no coding experience to make a website," said another. "It's only a matter of time before something goes wrong and we'll have to rebuild it the right way."

"no-code is just a fad," said a third. "Real developers code. That's what separates the wheat from the chaff."

Ouch. I get it. I really do.

Maybe these developers have put in their 10,000 hours (or more) and they've honed their skills to become masters of their craft. They've seen "no-code" come into the spotlight, and they're rightfully skeptical.

But here's the thing: I'm not asking for your permission. I'm not asking for your blessing. I'm not even asking for your approval. I am imploring you to give these tools a serious look. They can save you time, and they're going to go a long way to build the next generation of software developers - whether you're ready or not, no-code tools will be a big part of the future.

## Devs are often insecure about using no-code tools

For some, mentioning the use of no-code tools can induce fear around job security, the validity of use cases for no-code tools, and some future need to “rebuild it later the right way”. This is understandable, but also wrong. Devs are not insecure about no-code because it is no-code. We are insecure about it because of what it represents. no-code is a new way of building things that is not as intuitive for them (yet). It represents a shift in the way things are done that may even threaten their jobs. But the thing is, this shift is inevitable.

The world is moving towards more no-code and less handwritten code. This is a trend that is only going to accelerate.
So, instead of being insecure about it, devs should embrace it. We should learn how to use no-code tools in harmony with hand-coded software, and strive to become no-code experts. This way, there is an opportunity to stay relevant in a no-code world and become the experts that companies will need to build the next generation of no-code products.

## I use no-code tools all the time

Any time I can take advantage of no-code tools, I do. It saves me time, lowers complexity, and results in that many fewer things needing my attention to be maintained in the long run. Some quick examples for you:

- I use an automated “sign up for my newsletter!” embed on [my personal website](https://mikebifulco.com) to interrupt readers at just the right time and ask for their email address. I configured [Polite Pop](https://politepop.com/) entirely on their website, and embedded it in my next.js site with a simple copy/paste
- For [APIs You Won't Hate](https://apisyouwonthate.com), we have several Zapier automations set up to populate an Airtable when someone submits a contact form. The process is different for sponsors vs. general contact - and I can change it any time without redeploying the site.
- I have uptime monitors on all of my web properties - I get a handy text from [Fathom](https://usefathom.com) any time a site goes down for more than 60 seconds
- I use [Google Home](https://home.google.com/welcome/) (shout out to my former team @ Google!) to automate my morning routine - the lights in my bedroom come up like an artificial sunrise, and by the time I get down to my kitchen, there's soft music playing, and my espresso machine is warm and ready to pull a shot.
- I use [Shortcuts for iOS](https://support.apple.com/guide/shortcuts/welcome/ios) on my iPhone for all sorts of things - turning off lights and making sure the doors are locked in my home at night, sending an automated text with my location to tell someone I'm headed their way, you name it.
- I use a [Stream Deck](https://www.elgato.com/en/stream-deck) to swap between camera views during livestreams, to toggle lights and set the temperature in my home office, and to hang up zoom calls or toggle my microphone without having to switch apps on my computer.

To be perfectly honest, I'm probably using many more that I've already forgotten about. I'm willing to bet that this short list probably spurred some recognition for you, too - you're probably already using no-code!

## You're probably already using no-code

Even in your dev work, you're probably already using a variety of no-code tools, whether you realize it or not. I certainly am! Vercel, Netlify, Cloudflare Pages, and GitHub Pages are great hosting options that require little-to-no-code to set up. Configuring web servers used to be a full-time job for every large project. Airtable is a great no-code alternative for gathering and storing data in a database. Chat widget tools like Intercom, Drift, and Front can be dropped onto any website by including one script and provide a massive superpower for messaging users and responding to customer support issues. Even everyday analytics tools like Google Analytics, Fathom, and Plausible are essentially no-code integrations that replace what used to be heaps of code for building telemetry into an app.

Stripe is investing in no-code tools to help business owners get things done more quickly. From Payment Links to Customer Portal to Pricing Tables, we're helping business owners and platform builders, because at the end of the day, your time is best spent doing things that add value to your products and services - and our no-code integrations give you more time to do just that.

If you've read this far and you find yourself thinking "these aren't no-code tools" because they can't be used to build an entire web app, I'd encourage you to rethink what "no-code" means. no-code tools are simply tools that allow you to get things done without writing code. They don't have to be a replacement for all of your code; think of them as an incredibly powerful complement to it.

## No-code doesn't mean low quality

No-code tools are often more reliable because they're built by teams of developers who are focused on a specific problem. They also tend to be more secure because they're not as complex as an entire web app, so there are fewer opportunities for bad actors to exploit vulnerabilities.

## No-code doesn't mean no extensibility

No-code tools also don't mean you have to compromise on features or customization. Many no-code tools offer APIs or other ways to extend their functionality. If you do find yourself needing more, you can always use a no-code tool as a starting point and then add custom code on top. They are a powerful way to get things done quickly and without having to write a lot of code.

There exists a dev subculture that hypes up building software in the most steampunky way (see: vim, mechanical keyboards, etc). It glorifies "make it look like I'm doing something super difficult and specialized" in a way that makes it hard to get started. This culture gets promoted for a variety of reasons - many of which are innocuous. For example, many developers are introverts, and so they express their personality through the things they use and build. We also tend to be tuned into the latest news on bleeding-edge tech, and because of that, many of us like to collect and show off our gear.

With that said, I don't think this kind of enthusiasm is entirely a bad thing.

I think it's great that there are people out there who love their keyboards, and their vim customizations, and who are willing to share that with the world. I also think it's great that there are people who are passionate about using those tools to build amazing things.

Things become problematic when they're used as a form of gatekeeping.

It's important to consider that this may deter new developers who are just getting started. Just remember that at the end of the day, it's all just a bunch of tools - and you can use whatever tools you want to build whatever you want.

## How to turn yourself into a no-code cheerleader

If you're a traditional developer, you may have already decided that no-code is not for you. You may think that it is “taking the easy way out”, and that it can't possibly work for anything more than the most basic apps. I'm here to tell you that you're wrong. no-code tools are powerful. They're flexible. They're easy to use. And they're getting better all the time. If you're a traditional developer, I challenge you to give no-code a try. Spend a few hours with one of the many no-code platforms out there and see what you can build. I think you'll be surprised.

## Go ahead, give no-code a try

Ready to dive in? There's plenty of great resources online for taking advantage of no-code tools.

- [Apps Without Code](https://www.appswithoutcode.com/)
- [Automate All the Things](https://www.aatt.io/)
- [r/nocode](https://redditcom/r/nocode)

If you're not using no-code already, give some of these tools a try. And if you are using them, showcase your efforts whenever possible - especially to your dev friends who may be skeptical.

- [If This, then That (IFTTT)](https://ifttt.com)
- [N8n](https://n8n.io/)
- [Zapier](https://zapier.com/)

As I mentioned earlier, [Stripe has a growing portfolio of no-code tools](https://stripe.com/docs/payments/no-code). These are a few that I'd recommend to anyone looking to dip their toes into the cool, refreshing waters of having to write less code:

### Payment Links

[Payment Links](https://stripe.com/docs/payments/no-code#send-a-payment-link) are a quick and easy way to share a URL for a specific product with your customers. You can create as many payment links as you need, and they can be used anywhere you might share a link. [Check out the docs](https://stripe.com/docs/payments/no-code#send-a-payment-link) for more information on getting started with payment links. You may also want to check out my other post, [No-code payments: How to use Stripe with customized NFC tags](https://dev.to/stripe/no-code-payments-how-to-use-stripe-with-customized-nfc-tags-3c1o).

### Pricing Table

You can use the Stripe Dashboard to configure a [Pricing Table](https://stripe.com/docs/payments/checkout/pricing-table) UI component, and embed it on your website. This will allow your customers to see pricing information and be taken to checkout without any custom code. The pricing table is designed to be flexible and fully responsive, and uses recommended practices for selling subscription-based products online.

### Customer Portal

The [Stripe Customer Portal](https://stripe.com/docs/customer-management/activate-no-code-customer-portal) is a Stripe-hosted solution for customer self-serve management of subscriptions. This allows your customers to change and cancel their subscriptions as needed, and includes a complete checkout workflow for collecting and updating their payment information.

## Wrapping up

So, what do you think? Have I made a compelling case for using no-code tools? I'd love to hear about the no-code and low code integrations you're using - drop me a comment below to show off your stuff, or track me down on twitter [@irreverentmike](https://twitter.com/irreverentmike).

If you've made it this far, thanks for reading. I think there's a better world out there for all of us if we embrace no-code, and extend an olive branch to our less technical friends who are interested in building apps with no-code tools.

<Aside type="note">

Author's note: This post was originally written as part of my work as a
Developer Advocate at [Stripe](https://stripe.com). As of November 2022, I no
longer work at Stripe, but I'm still a big fan of their products and the work
they do.

</Aside>

<small>

_Stripe fam: If you want to re-host this article on a stripe-owned URL, [get in touch!](mailto:hello@mikebifulco.com)_

</small>


Devs: It's okay to use no-code tools

Devs are often insecure about using no-code tools

How to turn yourself into a no-code cheerleader


## 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


<Aside type="note">
  _This article was written during my time at Stripe as a Deveoper Advocate, and was co-authored by my inimitable teammate, [Charlie Gerard](https://charliegerard.dev/)._

I do not speak for Stripe, and this article is not official company policy, etc. and so on. It's just my experience with friction logs from my time at Stripe.

</Aside>

## What is a friction log?

Friction logging is a practice that can be used by engineering teams building products to track and improve upon issues that users experience while using a product. The goal of friction logging is to make a given product better for everyone involved. End users and developers get a product that delivers value more directly, the team building the product gets a more attached, happier user base, and salespeople have an easier time showing value to potential customers.

At [Stripe](https://stripe.com), we use Friction logs to share feedback with product teams about the products we build. This is at least part of the mission of our DevRel team. Our goal is to be the voice for devs who use Stripe's products to build their own. We often serve as the liaisons between these worlds: the devs using our products, and the engineering teams building them.

Stripe also encourages all employees to actively participate in giving feedback. During onboarding, every new Stripe is given training on how to give feedback on products, and the process for creating friction logs.

## Parts of a friction log

<Image
  publicId="posts/how-stripe-uses-friction-logs/parts-of-a-friction-log"
  alt="Parts of a friction log"
/>

### Context

The context describes the persona of the person reviewing the feature, as well as what they were trying to accomplish. For example, if you are reviewing a new API endpoint and this is your first time using the feature, it is important to mention this as part of your persona. You can try to write the context by answering the following questions:

- How experienced are you with the feature?
- What were you trying to build?
- Which parts of the feature is this friction log about?

Below is an example of context for a friction log about setting up a new printer:

<Image
  publicId="posts/how-stripe-uses-friction-logs/example-context"
  alt="Example context for a friction log about setting up a new printer"
/>

### Pros and cons

Once you've written the context, you can move on to summarizing the pros and cons you've experienced.

This part should be a list of bullet points clearly stating the parts of the feature or experience that you enjoyed or thought were useful, and the ones that you think could be better or did not match your expectation of how the feature should work.

<Image
  publicId="posts/how-stripe-uses-friction-logs/example-pros-and-cons"
  alt="Example pros and cons for a friction log about setting up a new printer"
/>

### Detailed stream of consciousness

Finally, the detailed stream of consciousness is the part where you should be giving feedback without necessarily following a specific structure. You should write it as you are going through your experience trying to use the feature. It can include anything you think could be useful to the team, no matter how small. Feel free to add screenshots, GIFs showing your interaction with the tool, links, etc.

We are all different in how we use tools, our level of knowledge and expertise, the applications we're trying to build, so any piece of feedback is valuable to help improve a product.

To give you an idea, here's an example of how this part of the friction log might look:

<Image
  publicId="posts/how-stripe-uses-friction-logs/example-stream-of-consciousness"
  alt="Stream of consciousness example for a friction log about setting up a new printer"
/>

## Framework for a great Friction log

### Share size (S/M/L) up front

**Small** - The friction log is small and manageable. It can be completed in a reasonable amount of time without feeling like a burden.

**Medium** - The friction log is of a moderate size. It may take some time to read, but it is not excessively long.

**Large** - The friction log is large and may take some time to consume. These likely capture larger user journeys, and show a holistic view of a process, as opposed to a small bit of confusion with a single feature.

### Make the journey clear

The friction log should make it clear what journey the user is taking, and what steps they are taking along the way, as well as context on their persona ("I'm brand new to collecting payments on the web", or "This is the 3rd major release of my product, but we need to add support for taking payments in Canada"). Additionally, The log should be easy to follow so that the intended audience can understand it -- whenever possible, use language that your product teams and stakeholders will understand without having to go do research of their own.

### Highlight both joy & frustration

While it is critical to share opportunities for improvement in a product, it is also extremely valuable to share what is going well. This helps to build trust with your engineering team, and can be a good reminder that you all share the same goal: making the product as good as it possibly can be.

### Be illustrative

Wherever it may be helpful, provide screenshots, videos, or other visuals to help explain the process you've undertaken, and the real experiences you've had. This may take the form of a link to a developer screencast for longer friction logs.

### Describe issues objectively

This is where emotional intelligence is critical. Avoid using emotionally loaded language, and instead describe the issues objectively. Something like "I got confused between steps 6 and 7, and went back to this docs page to look for what I missed" is far more helpful than "I wasted 2 hours on this, it's so bad!".

### Share your feedback broadly

At Stripe, when a friction log is completed, it is shared to an email list that includes the entire company, as well as with the specific team working on the feature or product being highlighted. This takes advantage of the network effect: when everyone can see your feedback, it's more likely that you'll start a conversation with a broad audience of affected parties.

You may find that there are people who actively disagree with your perspective - don't fret, this is usually a good thing! Exposing your friction log to people with a diversity of experience and background means that any suggested changes to your product will be more considerate of a larger userbase.

### Follow-up!

It's also good practice to follow up directly with people who may be tasked with coming up with fixes related to your friction log. Keeping an open dialog is important - it helps ensure that feedback is given and received in good faith, and that the outcome of your work is a meaningful solution (even if it isn't implemented right away).

**This is where the magic happens.** All your work in crafting a great friction log is worthless if you don't follow through and make sure that it has an impact on the product your company is building. Making sure that your log results in the creation of new feature requests and bugs is a good starting point - do your best to be a steward for these tickets after their creation, so that they are prioritized thoughtfully in your team's backlog.

The last bit of follow up comes after the implementation and release of updates to the product: tell the world! Update docs and release notes with the new changes, and follow up directly with affected users wherever possible. This is your opportunity to show them that your team is working hard to make things better for them. Let them know that you built something because of them, and that you're always open to more feedback. This creates attachment and loyalty, and is the virtuous cycle that great product teams strive for.

## On giving feedback

A friction log is essentially a detailed piece of feedback, so to ensure that it is helpful and received well, there are a few important points you need to keep in mind.

### Emotional intelligence is important

Emotional intelligence encompasses self-awareness, social awareness, empathy and relationship management. Writing a friction log focuses on your personal experience with a feature or product, however, you have to keep in mind that it will be read by people who have put a lot of time and effort into building what you are using.

Try to put yourself in their shoes and avoid using language that isn't very considerate. For example, instead of saying something like “This is by far the worst API I've ever used”, which is not only rude but also unhelpful, you could change it to “I've struggled using this API because X, Y, Z”. This way, your feedback changes from a general comment to one more focused on your personal experience, and it is more helpful to explain what you struggled with so the team can take action to make improvements. Additionally, try not to use the pronoun “you” to address your feedback. Instead of saying “the API endpoint you implemented isn't clear”, you could say “This API endpoint was a bit unclear to me”. This focuses your comments on the feature itself, instead of whoever implemented it.

### Trust is a critical ingredient

When giving any kind of feedback, trust is very important. In general, your teammates want you to do well and you should have a common goal of making the experience better for your users so, when receiving feedback, you should know it comes from a place of care. However, if your company doesn't have a great collaboration culture or if you only recently joined, it can be difficult to have this sense of trust. Before you try to implement friction logs as part of your process, make sure that you get to know your team members. If necessary, schedule calls to go through your friction logs with people so they can understand the state of mind you were in when you wrote your feedback.

### Giving feedback is hard; receiving it is even harder

A bit earlier in this post, I talked about emotional intelligence and how you should put yourself in other people's shoes when writing your friction log. This can be a difficult process when the feedback you need to give is not the most positive. However, remember that receiving feedback is even harder. If you're on the receiving side, try to detach yourself from what you are reading and remember that this is an opportunity to improve. If this is not something you are used to doing, it can be a bit difficult at first and might take a few tries to get comfortable with. Hopefully, the more you do it, the more you'll realize how beneficial it is, not only on a personal level but for all your users.

### Summary

If you're not already using friction logging as part of your product development process, you should definitely consider adopting it. Here's why:

- It can help you identify opportunities for improvement in your product, by highlighting bottlenecks and weaknesses.
  Showing that you listen to users and actively make changes to your product based on their feedback builds user trust and loyalty
- Friction Logging can help to build a culture of trust and feedback, and incentivize emotional intelligence in communication between your colleagues
- In the long run, friction logging can help you save time and money by ensuring that your product is constantly improving.
  Get our friction logging templates
- We've created a [friction logging toolkit](https://github.com/mikeb-stripe/friction-logging-toolkit) for you to use if you're interested in getting started with Friction Logging at your company
- You may also want to check out [frictionlog.com](https://frictionlog.com) - they provide lots of great articles, examples, and resources on Friction logging.

## About my co-author

<center>

![Charlie Gerard headshot](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qrn3697iitskc063b8y8.png)

</center>

Charlie Gerard is a Developer Advocate at Stripe, a [creative technologist](https://charliegerard.dev/) and [Google Developer Expert](https://developers.google.com/community/experts). She loves researching and [experimenting with technologies](https://charliegerard.dev/). When she's not coding, she enjoys spending time outdoors, trying new beers and reading.


How Stripe Uses Friction Logs to Improve their Products

Giving feedback is hard; receiving it is even harder


The [Orton Effect](https://www.capturelandscapes.com/orton-effect-explained/) is a photography technique that involves taking two pictures of the same scene, one with a long exposure and one with a shorter exposure, and then combining them. The result is an image that has both the sharpness of the long exposure and the detail of the shorter exposure. While it's not an exact replica, we can simulate a phoo filter for the Orton Effect using CSS and React.

## Emulating the Orton Effect in CSS

To emulate the Orton Effect in CSS, we need to layer 2 copies of the same image on top of one other. To accomplish that, we'll nest them under a single parent - in this case, the [`figure` element](https://developer.mozilla.org/en-US/docs/web/html/element/figure). Note that for the second image, we set [`aria-hidden=true`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden), and intentinally set `alt` to an empty string, so that Screen Readers and other visual assistive tools skip them. won't encounter the repeated image element. You can read more about that and other accessibility features of HTML on [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden).

```html
<figure class="orton-effect">
  <img
    src="https://source.unsplash.com/tRDGs9utMUo/1600x900"
    alt="A man in the crosswalk on a city street"
  />
  <img
    src="https://source.unsplash.com/tRDGs9utMUo/1600x900"
    aria-hidden="true"
    alt=""
  />
</figure>
```

Next, we'll use a CSS rule to apply some styles to the _first_ of the two images (in HTML-speak, that's the one on top).

```css
figure.orton-effect img:first-of-type {
  position: absolute;
  mix-blend-mode: lighten;
  filter: blur(50px);
  opacity: 50%;
}
```

We're setting `position: absolute;` to layer this image on top of its sibling within the `<figure>` element. The remaining 3 lines of CSS set the top image to use the `lighten` blend mode, apply a gaussian blur using `filter`, and make the top image partly translucent by way of the `opacity` CSS property.

This creates a hazy, glassy effect:

### Before:

<img
  src="https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995195/posts/orton-effect-css-react/crosswalk.jpg"
  alt="A man in the crosswalk on a city street"
/>

### After:

<OrtonEffectImage
  src={
    'https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995195/posts/orton-effect-css-react/crosswalk.jpg'
  }
  alt="A man in the crosswalk on a city street"
  blurRadius={50}
  opacity={50}
/>

It's subtle - but it is there, adding just a slight haze over the light parts of the photo, like a morning fog settling in over a dreamscape.

## The Orton Effect in React

To apply this to an adjustable React Component, we'll use CSS-in-JS to make blur and opacity dynamic. There's many ways to get this done, of course, so you may prefer a different approach. This is what a simple react component for this layout might look like:

```jsx
const OrtonEffectImage = ({ alt, blurRadius, opacity, src }) => {
  return (
    <figure>
      <img
        src={src}
        alt={alt}
        style={{
          mixBlendMode: 'lighten',
          filter: `blur(${blurRadius}px)`,
          opacity: `${opacity}%`,
          position: 'absolute',
        }}
      />
      <img src={src} ariaHidden alt="" />
    </figure>
  );
};
```

This gives us a reusable component that just needs a few parameters passed in - for example:

```jsx
<OrtonEffectImage
  src={
    'https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995539/posts/orton-effect-css-react/snowy.jpg'
  }
  alt="A snowy landscape"
  blurRadius={30}
  opacity={70}
/>
```

Note that a few things have changed here - we're no longer using a named CSS class (`.orton-image`) to select and modify images via CSS. The CSS is now specified on the `img` tag itself, and because it is passed in via `style` prop, it is a JavaScript Object -- so keywords have gone from skewer-case to camelCase, and there's commas where we once had semicolons. Additionally, we're using ES6 String templates to interpolate style rules from the opacity and blur radiuses passed in.

There's some improvement to be done from here - you should do some error checking to make sure that opacity stays between 0 and 100%, and that the blur radius is a positive integer. It's also a good idea to provide some sensible fallback values for those options, in case they're not provided. I'll leave that up to you to implement.

## The Orton Effect in Action

Below you will see the Orton Effect applied to a handful of other images from Unsplash.

I've taken the above example a little further, and made blur and opacity adjustable, so that you can see how each parameter changes the image effect.

I've found that an opacity of somewhere between 25 and 50% and tends to create a nice, subtle effect. The "right" blur radius is a bit more dependent on the specific image.

<OrtonEffectImage
  src={
    'https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995539/posts/orton-effect-css-react/snowy.jpg'
  }
  alt="A snowy landscape"
  blurRadius={30}
  opacity={70}
  showControls
/>

<OrtonEffectImage
  src={
    'https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995644/posts/orton-effect-css-react/cafe.jpg'
  }
  alt="A scene at a local cafe"
  blurRadius={30}
  opacity={70}
  showControls
/>

<OrtonEffectImage
  src={
    'https://res.cloudinary.com/mikebifulco-com/image/upload/v1662995728/posts/orton-effect-css-react/pond.jpg'
  }
  alt="A pond with sunlight filtering through autumn leaves overhead"
  blurRadius={30}
  opacity={70}
  showControls
/>

## Summary

The Orton effect is a photography technique that involves taking two images - one in focus and one out of focus - and overlaying them to create a third image with a dreamy, ethereal quality.

It turns out that this effect can also be simulated using CSS and React! All you need is a bit of code to overlay two images and some CSS to blur one of the images.

If you're looking to add a touch of magic to your photos, then recreating the Orton effect with CSS and React is a great way to do it.

If you found this post useful, I'd love it if you'd consider subscribing to [my newsletter, Tiny Improvements](https://mikebifulco.com/newsletter) - I share articles and resources that catch my attention, as well as my perspective on tech news, designing products, and living a fulfilling life.


The Orton Effect - dreamy photo effect in CSS and React


I live in a fast-growing city in the southeast US, where urban design and city planning are always a hot topic. As population density has increased, it's become apparent that Charlotte needs to make drastic and sweeping changes to accommodate the growing number of people living in the area.

Naturally, this means I'm also reading heaps about urban planning - which is where I first heard the term **third place** being used.

## What is the third place?

As defined by [Brookings](https://www.brookings.edu/blog/up-front/2016/09/14/third-places-as-community-builders):

> (...the) **Third place** is a term coined by sociologist Ray Oldenburg, referring to _places where people spend time between home ('first' place) and work ('second' place)._

Third places have traditionally been where people go to socialize, to relax, and to be a part of their community. You've probably seen them in urban areas, in the form of a town square, piazza, or public park. They might also be a subway station, a heavily trafficked intersection, or a kiosk on a street corner.

<Image
  publicId="posts/remote-work-and-the-third-place/lisboa"
  alt="A photo of a city street in Lisbon, with people walking together and talking"
  caption="Lisbon, Portugal is full of third spaces - public streetcorners, kiosks, and cafes buzzing with people chatting and relaxing."
/>

These spaces are important for people to feel like they belong, and have purpose beyond just home and work. It gives space for one to decompress and find entertainment, to find reprieve from the pressures of work and home life.

Simply put - the third space is a place where you're not expected to work or look after your household and family chores. It's an important part of life and finding balance. Each and every one of us will have our own personal third spaces. Spending time regularly in your third space can provide balance and tranquility, social interaction, and serendipity.

## Suburban living erases the third place

Notably, for people living in suburban places, the third place may be completely missing - folks commuting from the suburbs will skip third places as they drive straight to and from work. This phenomenon is particularly common amongst americans, where it is typical to drive to work, rather than walking, cycling, or taking public transit.

As you might imagine, this means that people living like this don't experience the benefits of a third place in the same way that an on-foot commuter might. This is particularly harmful for people who need a third place the most - those with demanding jobs, parents with young children, and so on.

<Image
  publicId="posts/remote-work-and-the-third-place/suburbia-overhead"
  alt="overhead photo of a suburban neighborhood"
  caption="Photo by Raphaël Biscaldi on Unsplash"
/>

## City living fosters the third place

For people living in cities, the third place is often more accessible. City dwellers are more likely to live in smaller apartments, which encourages them to get out more often. City dwellers are also more likely to use public transit or walk to work, which gives them time to relax or socialize on their way to and from work.

The third place is an important part of city life, and it's one of the things that makes cities such great places to live.

## The third place and remote work

People who work remotely may find themselves one degree further away from a third place - living and working in the same place can create a life with only one place - blurring the lines between home-space and work-space. This makes finding the benefits of a third place even more challenging.

The past several years of post-pandemic-living have been extremely challenging for all of us - and for many, adapting to remote work has had a steep learning curve. I have found that in order to work remotely and live well, I have needed to make a concerted effort to build a life that intentionally includes second and third places that fit into my routines.

## Finding your third place

If you're looking for a third place, there are a few things you can do to find one that's right for you.

The first step is to find a place that suits you. If you're an introvert, you might want a third place that's quiet and relaxing. If you're an extrovert, you might want a third place that's lively and social. There are third places for all kinds of people, so it's important to find one that's right for you.

One way to find a third place that suits you is to explore. Wander around your neighborhood and see what kinds of places there are. Visit a shop or a park you've never been to, or take a class at a new gym. If you see a place that looks interesting, go in and check it out. You might find a third place that you never would have thought of otherwise.

### The third place: community, socialization, and balance

For each of us, the third place will be a unique choice. It might be your favorite coffee shop, your back yard, a beach, a hiking trail, or something completely different. What's important here is that the third space is literally anything other than where you do home-things and office-things - if you work from home, this has to work for you. Find something that makes you feel good, energized, empowered, different. For me, this has taken many forms:

#### Coworking spaces

<Image
  publicId="posts/remote-work-and-the-third-place/atlas-local"
  alt="Photo of a coworking space, with people working at desks in an open office space"
  caption="Atlas Local coworking in Greenville, SC, USA"
/>

Coworking is obviously near and dear to my heart, since [I once built a coworking product](https://mikebifulco.com/tags/smpl). These are great because they supplant your typical work community with likeminded, colocated people who don't have the same problems as you. You can complain to them or unplug completely from work and just hang out. In my experience, people are far more likely to have a eureka moment at a coworking space than in the stuffy hallways of your typical cube farm or open office.

Serendipity is a happy byproduct of interacting with people who don't have the same colleagues as you. Their problems and joys are different, and they can share their perspective on your world, just as you can do the same for them.

#### Cafes

<Image
  publicId="posts/remote-work-and-the-third-place/coffee-shop"
  alt="A laptop sitting on a table at a coffee shop"
  caption="Coffee shops are great for relaxing, reading, and watching the world go by."
/>

My god, do I love a good cafe. I have great gear for making coffee at home, yet I still spend plenty of time at cafes. This is because, for me, there's a change in mindset at a cafe. I know I typically have 1-2 hours of comfortable time at any given cafe, and I can hammer through some really great work during this time. It also requires transit/transition time on either side of it, where I can clear my mind, give myself a break, see nature, go for a bike ride/drive/etc. This has a multiplicative effect on my productivity - small doses of repose are amazing.

### Touch grass, feel the sun

<Image
  publicId="posts/remote-work-and-the-third-place/touch-grass"
  alt="Photo of a bicycle leaning against a fence, with a green riverbed behind it"
  caption="There's no replacement for spending time outside."
/>

Many times, I'll use the great outdoors as my third space. Going for a long walk in the morning (1-2hrs) while listening to a podcast can set my energy for the day. When I know I've got calls/meetings/deadlines all day, this helps me to feel like I haven't burned an entire day behind my computer screen. This can also take the form of a run or a bike ride or (whatever you do to exercise) - turning your mind off of work really is a booster. Don't let hustle porn ruin your perception of your own throughput (but don't lie to yourself, either). At the end of the day, you still have to get things done, but doing so with a mindful eye on balance can keep you healthier and happier in the long run.

There are also times where I know I'll be on a super long call (30min+) where I just need to listen - going for a walk during these calls (even in super hot or super cold weather) is often a guarantee that I'll pay better attention to the content of the call than if I'm left to poke around in my browser, on twitter, reddit, etc. I have several regular 1:1s with teammates where this is the expectation and the norm. Even though we're not in the same place, we will pop our earbuds in and go for a walk at the same time, talking together like a normal old phonecall instead of performing business-normality in front of a web cam.

## Conclusion

Generally, I've been extremely happy as a remote worker for a long time by creating a series of third places for myself. If you're new to working remotely, and you're having a difficult time being productive, this may provide some relief. It's also a great way to meet new people, and to find a sense of community.

If you live in a city, there's a good chance you already have a third place. If you live in a suburb, you might have to work a little harder to find one. Either way, it's important to find a third place that suits you, and to make it a habit to spend time there.

<small>

_(Quick privilege note: I'm lucky to have an exceptionally charmed life. There are countless people who have been through an unimaginable hell during the pandemic. There's also plenty of people who can barely make ends meet, and don't have time to fret over finding the perfect way to bring balance to their life. I do not mean to trivilize or minimize these lived experiences in any way.)_

</small>

## Publications about Third Places:

- [The Wellbeing thesis](https://thewellbeingthesis.org.uk/foundations-for-success/importance-of-taking-breaks-and-having-other-interests/) says breaks can reduce or prevent stress, help to maintain performance throughout the day and reduce the need for a long recovery at the end of the day
- [How Do Work Breaks Help Your Brain?](https://www.psychologytoday.com/us/blog/changepower/201704/how-do-work-breaks-help-your-brain-5-surprising-answers) says _“Movement breaks” are essential for your physical and emotional health, and that breaks restore motivation, especially for long-term goals._
- [Atomic Habits](https://atomichabits.com) - habits are the compound interest of self-improvement, and finding a (series of) third place(s) is a _huge_ part of that - there's a great [primer video on Atomic Habits](https://youtu.be/U_nzqnXWvSo) from the book's author, James Clear.

## More from me

If you liked this, you may appreciate my articles from the early days of the pandemic:

- [Are you suddenly a remote worker? Let's figure it out together.](https://mikebifulco.com/posts/are-you-suddenly-a-remote-worker)
- [On normalcy](https://mikebifulco.com/posts/on-normalcy)


The third place - the secret to a happy life for remote workers

The third place: community, socialization, and balance

Oh, hello