In a [previous post](/blog/syntax-highlight-code-in-markdown), I discussed how to get code syntax highlighting and individual line highlighting working in [react-markdown](https://github.com/remarkjs/react-markdown) using `react-syntax-highlighter` and `parse-numeric-range`. Custom components are a powerful way to extend `react-markdown`.

In this guide, we will create a custom component to that converts Markdown images into [Next.js Image components](https://nextjs.org/docs/api-reference/next/image). We'll get the best of both worlds with the terse syntax of Markdown and the powerful optimization and configuration of the `next/image` component. As a bonus, we will add the ability to add an image caption directly in the markdown as well.


### Create `Markdown.tsx`

```tsx
// Markdown.tsx
import Image from 'next/image'
import ReactMarkdown from 'react-markdown'


const MarkdownComponents: object = {
  // Code will go here
}

return (
  <ReactMarkdown
    children={your.content.here}
    components={MarkdownComponents}
  />
)
```


### Add Custom Metastring Logic

If you want to get right down to business, here is the final code. Read on to see how it all works.

```tsx
p: (paragraph: { children?: boolean; node?: any}) => {
  const { node } = paragraph

  if (node.children[0].tagName === "img") {
    const image = node.children[0]
    const metastring = image.properties.alt
    const alt = metastring?.replace(/ *\{[^)]*\} */g, "")
    const metaWidth = metastring.match(/{([^}]+)x/)
    const metaHeight = metastring.match(/x([^}]+)}/)
    const width = metaWidth ? metaWidth[1] : "768"
    const height = metaHeight ? metaHeight[1] : "432"
    const isPriority = metastring?.toLowerCase().match('{priority}')
    const hasCaption = metastring?.toLowerCase().includes('{caption:')
    const caption = metastring?.match(/{caption: (.*?)}/)?.pop()

    return (
      <div className="postImgWrapper">
        <Image
          src={image.properties.src}
	        width={width}
	        height={height}
	        className="postImg"
	        alt={alt}
	        priority={isPriority}
	      />
	        {hasCaption ? <div className="caption" aria-label={caption}>{caption}</div> : null}
      </div>
    )
  }
  return <p>{paragraph.children}</p>
},
```


With the above code we can use the standard Markdown style image syntax: `![AltTextHere](/image.jpg)` and we will get a Next Image component rendering the image.

We can also use JSON metastrings inside the Alt text to define a `width` and `height`.


<div class="note">As of Next.js 11, <code>next/image</code> <a href="https://nextjs.org/blog/next-11#automatic-size-detection-local-images">no longer requires</a> height and width to be explicitly defined for local images, <em>but</em> for this to work, the image's src must be declared using the <code>import</code> keyword, which wont work for us since we aren't hardcoding a specific image.</div>

Finally, we can optionally preload images which will render above the fold by applying the `Next/Image` prop `priority`. All meta info contained within curly braces will be stripped before rendering.

Here's how we'd define a width of `786`, height of `432` and flag as a `priority` image:

```markdown
![AltText {priority}{768x432}](/image.jpg)
```

To add a caption to our image, we can do something like:

```markdown
![AltText {768x432} {priority} {caption: Photo by Someone}](/image.jpg)
```

### So How Does it Work?
It's mostly `react-markdown`'s built-in [component overrides](https://github.com/remarkjs/react-markdown#appendix-b-components) with some Regex magic sprinkled in. Let's break it down:


### The Logical Starting Point

```tsx
const MarkdownComponents: object = {
  img: image => {
  
    return (
      <Image
        src={image.properties.src}
        alt={image.properties.alt}
        height="768"
        width="432"
      />
    )
  },
}
```


The above code _should_ work, and it sort of does. It replaces a standard Markdown image with a fancy Next Image component. But if you pop open the console, there is an error. The image is wrapped in a paragraph tag. Not a major issue, but we can make it cleaner.


### Fixing the Wrapping Paragraph Issue

By default in Markdown, images are wrapped with a paragraph tag. While this isn't the worst thing in the world, it's technically not valid HTML. Let's fix that:

```tsx {1-4, 16}
p: paragraph => {
  const { node } = paragraph
	
	if (node.children[0].tagName === "img") {
	  const image = node.children[0]
	  
	  return (
	    <Image
	      src={image.properties.src}
	      width="768"
	      height="432"
	      alt={image.properties.alt}
	    />
	  )
	}
  return <p>{paragraph.children}</p>
},
```


Much better, _but_, the image dimensions are hardcoded and it would be nice to utilize Next's `Priority` prop to preload the top-most image in our blog which renders above the fold.


### Setting the `Next/Image` Dimensions

```tsx {6-11,16-17}
p: paragraph => {
  const { node } = paragraph
  
	if (node.children[0].tagName === "img") {
    const image = node.children[0]
    const metastring = image.properties.alt
    const alt = metastring?.replace(/ *\{[^)]*\} */g, "")
    const metaWidth = metastring.match(/{([^}]+)x/)
    const metaHeight = metastring.match(/x([^}]+)}/)
    const width = metaWidth ? metaWidth[1] : "768"
    const height = metaHeight ? metaHeight[1] : "432"
	  
    return (
      <Image
        src={image.properties.src}
        width={width}
        height={height}
        alt={image.properties.alt}
      />
    )
  }
  return <p>{paragraph.children}</p>
},
```


We are declaring a `metaHeight` and `metaWidth` which will look for curly braces in the alt tag and return an array with a string for our height and width based on the numbers we entered between the curly braces and the letter x: `{768x432}`. These variables will also be used for error handling.


Next, we declare `width` and `height` which give us the value for our Image component height and width attributes and utilizing ternaries, we set fallbacks if there are no dimensions declared in a metastring.


And finally, we declare `alt` and strip out the curly braces from the alt text.


### Taking Advantage of the `priority` Prop

It'd be nice to have some way to apply the Next/Image prop `priority` to preload above-the-fold images.


```tsx {13,22}
const MarkdownComponents: object = {
  p: paragraph => {
    const { node } = paragraph
	
    if (node.children[0].tagName === "img") {
      const image = node.children[0]
      const metastring = image.properties.alt
      const alt = metastring?.replace(/ *\{[^)]*\} */g, "")
      const metaWidth = metastring.match(/{([^}]+)x/)
      const metaHeight = metastring.match(/x([^}]+)}/)
      const width = metaWidth ? metaWidth[1] : "768"
      const height = metaHeight ? metaHeight[1] : "432"
      const isPriority = metastring?.toLowerCase().match('{priority}')
	
      return (
        <Image
          src={image.properties.src}
          width={width}
          height={height}
          className="postImg"
          alt={alt}
          priority={isPriority}
        />
      )
    }
    return <p>{paragraph.children}</p>
  },
}
```


We simply look for the metastring `{priority}` and then conditionally render the `priority` prop. Nice!

### Adding an Image Caption
As a bonus, it's nice to add the ability to easily add an image caption from inside the markdown. To do this, we just add a bit more regex to look for a `{caption:}` metastring. Anything after the colon will be displayed as your image caption.

Notice we are also wrapping the image component with a div. This will allow us to contain the caption together with the image.

<div class="note">
Even if you decide not to utilize the caption functionality, I recommend using the wrapping div in order to target with your CSS to add bottom margin or padding. Without this, the Next/Image component sometimes does wonky things.
</div>


```markdown
![AltText {768x432}{priority}{caption: Photo by Someone}](/image.jpg)
```

Our code would look like this:

```tsx {13-14, 17, 26}
p: (paragraph: { children?: boolean; node?: any}) => {
  const { node } = paragraph

  if (node.children[0].tagName === "img") {
    const image = node.children[0]
    const metastring = image.properties.alt
    const alt = metastring?.replace(/ *\{[^)]*\} */g, "")
    const metaWidth = metastring.match(/{([^}]+)x/)
    const metaHeight = metastring.match(/x([^}]+)}/)
    const width = metaWidth ? metaWidth[1] : "768"
    const height = metaHeight ? metaHeight[1] : "432"
    const isPriority = metastring?.toLowerCase().match('{priority}')
    const hasCaption = metastring?.toLowerCase().includes('{caption:')
    const caption = metastring?.match(/{caption: (.*?)}/)?.pop()

    return (
      <div className="postImgWrapper">
        <Image
          src={image.properties.src}
	        width={width}
	        height={height}
	        className="postImg"
	        alt={alt}
	        priority={isPriority}
	      />
	        {hasCaption ? <div className="caption" aria-label={caption}>{caption}</div> : null}
      </div>
    )
  }
  return <p>{paragraph.children}</p>
},
```
 
I would prefer to have used a regex lookbehind for a cleaner and more modern approach to stripping the caption from our metastring. Unfortunately Safari does not support this, so we do something less than ideal here as a workaround:

```javascript
  const caption = metastring?.match(/{caption: (.*?)}/)?.pop()
```
 
### Working Example

And here is the code working in this very blog post. This is fully created with our extended markdown, and it's rendered using Next/Image!

![Sample Image by Panic, Inc. {768x432} {caption: Photo courtesy of Panic, Inc.}](https://res.cloudinary.com/amir-ardalan/image/upload/v1649789438/Blog/playdate2_mfxyhy.jpg)

### Final Thoughts
`react-markdown`'s custom component capability is quite powerful. I have chosen to implement the Gatsby style JSON metastring to extend my markdown but you could take the concepts I've presented and run with them in any direction you see fit.

Use Next/Image with React Markdown

Here is some fancy syntax highlighting using `react-syntax-highlighter` and `react-markdown` in Next.js!

```tsx {5}
const Hello = () => {

  return (
    <div>
      Let's dive into syntax highlighting!
    </div>
  )
}

export default Hello;
```

So how exactly is it done? Most info about this references a [now deprecated](https://github.com/remarkjs/react-markdown/blob/main/changelog.md#600---2021-04-15) way of doing this (`renderer` is no longer a thing). With a bit of digging through [the docs](https://github.com/remarkjs/react-markdown#use-custom-components-syntax-highlight) here's how you can get code syntax highlighting in Next.js (and Typescript).

### Install Dependencies

`npm i react-markdown react-syntax-highlighter`

If you're using TypeScript, you will also want the Types. The following command will add the types package as a development dependency:  
`npm i @types/react-syntax-highlighter -D`

### Configure the `ReactMarkdown` Component

I will assume you already have some page or component where you are processing Markdown. In the case of `react-markdown` you may have a component called `Markdown.tsx` that looks something like this:

```tsx
// Markdown.tsx

import { FC } from 'react;
import ReactMarkdown from 'react-markdown';

type MarkdownProps = {
  markdown: string & { content?: string };
};

const Markdown: FC<MarkdownProps> = ({ markdown }) => {

  return (
    <ReactMarkdown>
      {markdown.content}
    </ReactMarkdown>
  )
}

export default Markdown;
```
In this basic example, the `ReactMarkdown` component is being passed raw markdown with the prop `markdown.content`. You can change this to work for your project.

From here, let's simply add the `components` prop to `ReactMarkdown`. This gives us the ability to add `SyntaxHighlighter` in the next steps.

```tsx {12-14, 18}
// Markdown.tsx

import { FC } from 'react;
import ReactMarkdown from 'react-markdown';

type MarkdownProps = {
  markdown: string & { content?: string };
};

const Markdown: FC<MarkdownProps> = ({ markdown }) => {

  const MarkdownComponents: object = {
    // SyntaxHighlight code will go here
  }

  return (
    <ReactMarkdown
      components={MarkdownComponents}
    >
      {markdown.content}
    </ReactMarkdown>
  )
}

export default Markdown;
```


### Choose the Right SyntaxHighlighter Import for Your Project
The [official documentation](https://github.com/react-syntax-highlighter/react-syntax-highlighter#react-syntax-highlighter) covers this quite well, but here's the tl;dr:

- Unless you want a massive JS bundle on your markdown pages, you should only be using the [Light Build](https://github.com/react-syntax-highlighter/react-syntax-highlighter#light-build). You will need to manually import the specific languages you are going to be syntax highlighting in your markdown.
- If you're using Next.js, change the theme import from `…/dist/esm/…` to `…/dist/cjs/…`. Hopefully ESM is fully [supported in Next.js](https://github.com/vercel/next.js/issues/9607) soon.
- If you want to syntax highlight TSX/JSX you must use Prism. Highlight.js does not support TSX or JSX.

For the rest of this guide, I will be using the Prism Light Build with cjs imports. I will add TSX, TypeScript, SCSS, Bash, Markdown, and JSON support. Simply add whichever languages you'd like to use. [Check here](https://github.com/react-syntax-highlighter/react-syntax-highlighter/blob/master/AVAILABLE_LANGUAGES_PRISM.MD) for languages supported by Prism.

```tsx {4-18}
// Markdown.tsx

import { FC } from 'react;
import ReactMarkdown from 'react-markdown';
import { PrismLight as SyntaxHighlighter } from 'react-syntax-highlighter';
import tsx from 'react-syntax-highlighter/dist/cjs/languages/prism/tsx';
import typescript from 'react-syntax-highlighter/dist/cjs/languages/prism/typescript';
import scss from 'react-syntax-highlighter/dist/cjs/languages/prism/scss';
import bash from 'react-syntax-highlighter/dist/cjs/languages/prism/bash';
import markdown from 'react-syntax-highlighter/dist/cjs/languages/prism/markdown';
import json from 'react-syntax-highlighter/dist/cjs/languages/prism/json';

SyntaxHighlighter.registerLanguage('tsx', tsx);
SyntaxHighlighter.registerLanguage('typescript', typescript);
SyntaxHighlighter.registerLanguage('scss', scss);
SyntaxHighlighter.registerLanguage('bash', bash);
SyntaxHighlighter.registerLanguage('markdown', markdown);
SyntaxHighlighter.registerLanguage('json', json);

const Markdown: FC<MarkdownProps> = ({ markdown }) => {

  type MarkdownProps = {
    markdown: string & { content?: string };
  };

  const MarkdownComponents: object = {
    // SyntaxHighlight code will go here
  }

  return (
    <ReactMarkdown
      components={MarkdownComponents}
    >
      {markdown.content}
    </ReactMarkdown>
  )
}

export default Markdown;
```

### Configure the `SyntaxHighlighter` component and add Line Highlighting Functionality

Let's finally start adding code for our `ReactMarkdown` custom component. We will import a [theme](https://github.com/react-syntax-highlighter/react-syntax-highlighter/blob/master/AVAILABLE_STYLES_PRISM.MD) and `parse-numeric-range` for the line highlight logic.

```tsx {4-5, 13, 14-55}
// Markdown.tsx

...
import rangeParser from 'parse-numeric-range';
import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';

type MarkdownProps = {
  markdown: string & { content?: string };
};

const Markdown: FC<MarkdownProps> = ({ markdown }) => {

  const syntaxTheme = oneDark;

  const MarkdownComponents: object = {
    code({ node, inline, className, ...props }) {
      const hasLang = /language-(\w+)/.exec(className || '');
      const hasMeta = node?.data?.meta;

      const applyHighlights: object = (applyHighlights: number) => {
        if (hasMeta) {
          const RE = /{([\d,-]+)}/;
          const metadata = node.data.meta?.replace(/\s/g, '');
          const strlineNumbers = RE?.test(metadata)
            ? RE?.exec(metadata)[1]
            : '0';
          const highlightLines = rangeParser(strlineNumbers);
          const highlight = highlightLines;
          const data: string = highlight.includes(applyHighlights)
            ? 'highlight'
            : null;
          return { data };
        } else {
          return {};
        }
      };

      return hasLang ? (
        <SyntaxHighlighter
          style={syntaxTheme}
          language={hasLang[1]}
          PreTag="div"
          className="codeStyle"
          showLineNumbers={true}
          wrapLines={hasMeta}
          useInlineStyles={true}
          lineProps={applyHighlights}
        >
          {props.children}
        </SyntaxHighlighter>
      ) : (
        <code className={className} {...props} />
      )
    },
  }

  ...
}

export default Markdown;
```

- First we check for the existence of the metadata to prevent TypeScript errors if it's undefined.
- Inside of the `applyHighlights` function, we declare `RE` as our Regex checker.
- Then we declare a variable called `metadata` that removes any spaces from the object.
- `strlineNumbers` checks the metadata against the Regex and ensures the object contains only numbers, hyphens, commas. 
- `rangeParser()` spits out an array of line numbers based upon the range we defined in markdown!
- We then check which lines to highlight and apply a data attribute `data="highlight"` on the spans wrap the lines we defined.

We now have the ability to style `data="highlight"` with some CSS. I will leave this up to you, as it will be highly dependent on the look and style you are going for.

### Controlling Line Highlighting in Your Markdown

So now that you have your component code in place for `React-Markdown` and `SyntaxHighlighter`, how do you actually highlight lines of code within your markdown?

```markdown
```tsx {3-4, 8}
```

Simply add curly braces with comma separated line numbers and/or ranges of line numbers!

### Adding Custom CSS

You can easily target your `ReactMarkdown` and `SyntaxHighlighter` components like so. You may have to use some `!important` tags to target certain elements within the Syntax Highlighting, which is less than ideal, but it works.

<div class="note">The following example is CSS-in-JS (Emotion specifically). Notice the class names and refactor the following for your CSS setup. I plan to update this guide to use Tailwind CSS in the future.</div>

```tsx {10-29, 37, 49}
// Markdown.tsx
...

const Markdown: FC<MarkdownProps> = ({ markdown }) => {

  ...

  const MarkdownComponents: object = {

    const styleMarkdown = css({
      '.codeStyle, pre, code, code span': {
        // Your SyntaxHighlighter override styles here
      },
      code: {
       // Your general code styles here
      },
      'pre code': {
        // Your code-block styles here
      },
      'h3 code': {
        color: 'inherit'
      },
      'span.linenumber': {
        display: 'none !important'
      },
      '[data="highlight"]': {
        // Your custom line highlight styles here
      },
    })

    code({ node, inline, className, ...props }) {
     
      ...

      return hasLang ? (
        <SyntaxHighlighter
          className="codeStyle"
          ...
        >
          {props.children}
        </SyntaxHighlighter>
      )
    }
  }

  return (
    <ReactMarkdown
      ...
      css={styleMarkdown}
    >
      {markdown.content}
    </ReactMarkdown>
  )
}

...
```



### Fixing Mobile Issues

There is a known issue with Prism where your CSS background color for the line highlight will not extend past the viewport. So when you scroll horizontally on a mobile screen, the highlighting abruptly ends.

There are a lot of over-engineered recommendations to fix it, including wrapping the pre tag in a container to apply more styles. The fix I came up with is hacky, yet elegant:

```scss
code: {
  transform: translateZ(0);
  min-width: 100%;
  float: left;
  & > span {
    display: block;
  }
}
```

I had almost forgotten about floats but hey... it works 🤷


### Removing Line Numbers

The lineNumber prop _must_ be set to `true` or the line highlighting won't work at all. If you'd like to disable the line numbers, this should do the trick:

```scss
span.linenumber { display: none; }
```

A better solution would be to write some additional functions to accept more meta strings for doing things like setting titles, disabling/enabling line numbers, etc. but I'll leave that for another day (and a future guide).

Whew, there you have it. Syntax highlighting your markdown in React using TypeScript with custom line highlighting. 🙌

Syntax Highlight Code in Markdown

### What Are Heading Anchors?
If you are not already familiar with heading anchors, check out any `README.md` on GitHub or hover over a heading within most blog posts and you will likely see a small link icon or hashtag to the left of the title, indicating that you can click to anchor to that specific heading.

If you'd like to link someone to a specific part of a blog post, you can simply click the title you want to send them to and the address bar is automatically populated with an anchor that will link directly to that section.

### Why Not Download an Existing Package?
There are excellent rehype and remark plugins such as [remark-autolink-headings](https://github.com/remarkjs/remark-autolink-headings) and [rehype-slug](https://github.com/rehypejs/rehype-slug). If your goal is to get this feature working as quickly as possible, those are great options.

The issue arises when you do this for every little feature in your blog. If you are loading in 5-10+ plugins into `react-markdown` you are going to be shipping enormous javascript bundles to the client.

Extending `react-markdown` is super simple and your visitors will feel the difference in [first contentful paint](https://developer.mozilla.org/en-US/docs/Glossary/First_contentful_paint) times.

### Create `Markdown.tsx`

In this example, I am passing in the raw markdown to our component with the `markdown` prop:

```tsx
// Markdown.tsx
import ReactMarkdown from 'react-markdown';

export default function Markdown({ markdown }) {
	
	const MarkdownComponents: object = {
		// Code will go here
	}
		
	return (
		<ReactMarkdown
		  components={MarkdownComponents}
		>
		  {markdown.content}
		</ReactMarkdown>
	)

};

```

### Create `generateSlug.ts` in `utils` Folder
We will use this to generate the anchor slug.

```typescript
// generateSlug.ts

export const generateSlug = (str: string) => {
  str = str?.replace(/^\s+|\s+$/g, '');
  str = str?.toLowerCase();
  const from = 'àáãäâèéëêìíïîòóöôùúüûñç·/_,:;';
  const to = 'aaaaaeeeeiiiioooouuuunc------';

  for (let i = 0, l = from.length; i < l; i++) {
    str = str.replace(new RegExp(from.charAt(i), 'g'), to.charAt(i));
  }

  str = str
    ?.replace(/[^a-z0-9 -]/g, '')
    .replace(/\s+/g, '-')
    .replace(/-+/g, '-');

  return str;
};
```

### Import `generateSlug.ts` and Customize the Heading Node

In my blog, I am using the `H3` heading for blog post headings. Change this to whatever fits your needs:

```tsx {3, 5-7, 10-32}
// Markdown.tsx
import ReactMarkdown from 'react-markdown';
import { generateSlug } from '@/utils/generateSlug';

interface H3Props {
  children: React.ReactNode;
}

...

h3: (props: H3Props) => {
  const children = Array.isArray(props.children)
    ? props.children
    : [props.children];
  const heading = children
    .flatMap((element) =>
      typeof element === 'string'
        ? element
        : element?.type !== undefined &&
          typeof element.props.children === 'string'
        ? element.props.children
        : []
    )
    .join('');

  const slug = generateSlug(heading);

  return (
    <h3 id={slug}>
      <a href={`#${slug}`} {...props}></a>
    </h3>
  );
},
...
```

Here we are targeting the `h3` headings in the markdown and iterating through the returned node arrays via a `flatMap` method. The flatMap will look for anything inside the title that isn't a normal string, such as a `code` object.

We initially create an empty string assigned to the variable `heading` and concatenate any code objects with the strings. Once we have a heading string, we pass it to the `generateSlug` function, and finally we tell the `ReactMarkdown` component to output an h3 element with an anchor inside of it that contains our newly generated slug.

### Dealing with Backticks or Other Special Characters

In the case of this blog, I like to use `code` inside of my headings. If you want to do this and you are using `react-markdown` , for example, you will need to do some slight modifications to output the correct slug, as strings inside of the backticks are nested within our array as their own object. Here is an example of how you could ensure words in backticks are included in the slug but the backticks themselves are omitted:

```typescript
// example alternate logic for backticks which register as code
// and are nested as their own object inside of the string
const heading = children
  .flatMap((element) =>
    typeof element === 'string'
      ? element
      : element?.type !== undefined &&
        typeof element.props.children === 'string'
      ? element.props.children
      : typeof element === 'object' && element.props?.children?.flatMap
      ? element.props.children.flatMap((child: object) => {
          if (typeof child === 'string') return child;
          return '';
        })
      : ''
  )
  .join('');
```
Other special character use-cases could  probably be handled inside of the `generateSlug.ts` util. An easy way to find what needs to be done is to log the content you are attempting to iterate over with the flatMap.

### Improve UX with CSS

You may want to add a scrolling animation to your page when a user clicks an inbound anchor link or clicks on one of the headings. This helps orient the user to the action that has occured (the page is moving to bring an anchor into view). The following CSS should do the trick:  
  
```scss
html {
	scroll-behavior: smooth;
}
```

### Final Thoughts

You can wrap the markdown component in a class to target with CSS or pass a css prop directly to the `ReactMarkdown` component. From there it's up to you to style your link/hashtag icon on hover to indicate your titles are now anchors.

Generate Blog Heading Anchors in React-Markdown

![Panic Playdate {priority}{768x432}{caption: Photograph courtesy of Panic, Inc.}](https://res.cloudinary.com/amir-ardalan/image/upload/v1649790823/Blog/playdate_mtqftq.jpg)

<div class="note"><a href="https://play.date/" rel="noopener noreferrer">Playdate</a> is an upcoming handheld gaming device produced by <a href="https://panic.com/" rel="noopener noreferrer">Panic</a> and designed in collaboration with <a href="https://teenage.engineering/" rel="noopener noreferrer">Teenage Engineering</a>.</div>

In this guide, I'll show you how to get started developing your own Playdate game using VSCode on MacOS. If you're familiar with basic game development concepts and comfortable writing code in C or Lua, skip the primer and disclaimer and [jump ahead](#download-playdate-sdk) to the good stuff. Otherwise, read on.

### Introduction

There are two things that are incredibly exciting to me about the upcoming Playdate device. First, I have an affinity for 1bit pixel art, and second, every Playdate works as a development kit out of the box.

Game development and programming in general can feel inaccessible to non software engineers. Panic has set out to create something that while incredibly niche, offers a low barrier to entry to get starting making your own game for the device.

There are two distinct ways of approaching game development on the Playdate; [Playdate Pulp](https://play.date/pulp/) and [Playdate SDK](https://play.date/dev/). Pulp is a browser based game creation tool that requires little to no programming knowledge. With Pulp, you can create simple games and learn about the fundamentals of game development if you are coming in completely fresh to the world of programming. The SDK is a traditional game development environment, you'll use an IDE to code your game, compile the code to a game file, and sideload the game onto a Playdate simulator. The SDK allows you to write your game using either **C** or **Lua** programming languages.

In this guide, I will show you how to get going using the SDK and Lua. Lua is a lightweight, high-level programming language with a C API that compiles down to bytecode. If you're proficient in C then go ahead and use that instead.

If you're brand new and curious about trying Pulp, I recommend checking out [SquidGodDev](https://www.youtube.com/watch?v=p4eLcP3hgJc) on YouTube.

### Design Considerations

Before getting started, it is worth noting that the playdate resolution is `400x240px` and the display is `2.7in`. The pixel density is fairly high for such a small screen. Because of this, traditional sprite and image sizes may appear small. A GameBoy-style `16x16` character sprite would need to be doubled in size (`32x32`) to appear the same size on the Playdate. Ultimately, this is a stylistic choice, but it is worth noting before you spend hours laboring over hand-crafted 1bit pixel art (don't ask me how I know 😒).

### Disclaimer
With that primer out of the way, let's get started configuring the development environment! You will be expected to know the basics of game development and it is up to you to write testable Lua code toward the end steps of this guide. If you're just getting started with Lua and game development, but you have familiarity with other programming languages, you should be good to go. Just refer to the documentation (more on that below). If this sounds good, continue reading.

### Download Playdate SDK
Open the [Playdate Dev](https://play.date/dev/) page and follow the instructions to download the SDK. Open the .zip you previously downloaded and double-click the `PlaydateSDK.pkg` file. Step through the installation and install to the default `Developer` directory in your home folder.

### Open the Playdate Documentation
The Playdate API docs are included locally in the root of the `PlaydateSDK` folder. If you're using Lua, you will want to use `Inside Playdate.html`.

### Install Lua
`brew install lua`

<div class="note">If you don't have homebrew installed, check out their official <a href="https://docs.brew.sh/Installation" rel="noopener noreferrer">installation instructions.</a></div>

### Configure VSCode
Install the following VSCode plugin: [Playdate by Orta](https://marketplace.visualstudio.com/items?itemName=Orta.playdate). Once the extension is installed, while in VSCode, press f1 or `shift+command+p`. Search `> settings.json` and select **Preferences: Open Settings (JSON)**. Add the following code to your `settings.json` file:

```json {4}
{
  "Lua.diagnostics.globals": ["playdate", "import"],
  "Lua.workspace.library": [
    "/Users/yourHomeFolderName/Developer/PlaydateSDK/CoreLibs"
  ],
}
```
Make sure to update `yourHomeFoldername` to your home folder. To find your home folder, open Finder and open your home folder using `shift+command+h`.

### Set Up Automatic Compilation and Sideloading

Inside the `Developer` directory where you installed the `PlaydateSDK`, create a new folder for your game (name anything you'd like): `YourGameName`. Open `YourGameName` in VSCode and create a new directory called `.vscode`.

Create two new files inside of the `.vscode` directory: `launch.json` and `tasks.json`.

Paste the following inside `launch.json` and update `YourGameName` to include the game name you chose for the game directory earlier.

```json {12}
// launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "request": "launch",
      "type": "playdate",
      "name": "Run app in Playdate simulator",
      "preLaunchTask": "Compile App",
      "source": "${workspaceFolder}/Source",
      "output": "${workspaceFolder}/../PlaydateSDK/Disk/Games/YourGameName.pdx",
    }
  ]
}
```

Now open `tasks.json` and paste the following, edit `YourGameName`:

```json {8}
// tasks.json

{
  "version": "2.0.0",
  "tasks": [{
  "label": "Compile App",
  "command": "pdc",
  "args": ["Source", "../PlaydateSDK/Disk/Games/YourGameName.pdx"],
  "type": "shell"
  }]
}
```

### Create a Basic Directory Structure
In the root directory of your game project, create three folders: `Source`, `images`, and `sounds`.

### Create Your First Game File
In the `Source`, make a new file called `lua.main`. This is the first file that is loaded by the Playdate.

```lua
-- lua.main

import "CoreLibs/object"
import "CoreLibs/graphics"
import "CoreLibs/sprites"


local function initalize()
	--your code here
end

initalize()

function playdate.update()
	--your code here
end
```

By this point you are ready to start adding your own code. All that is left now is to test the configuration of our Playdate extension and project file structure.

If you have zero clue what do at this point but are curious to see if everything is set up properly, that is okay! Try just loading a simple background image into the simulator. Create an 400x200px image called `background.png`, put it in your project's `images` folder, then add the following to `lua.main`:

```lua
-- lua.main

import "CoreLibs/graphics"
import "CoreLibs/sprites"

local gfx <const> = playdate.graphics

local function initalize()
	playerImage = gfx.image.new("images/player")

	local backgroundImage = gfx.image.new("images/background")
	gfx.sprite.setBackgroundDrawingCallback(
		function(x, y, width, height)
			gfx.setClipRect(x, y, width, height)
			backgroundImage:draw(0, 0)
			gfx.clearClipRect()
		end
	)
end

initalize()

function playdate.update()
	gfx.sprite.update()
end
```


### Compiling and Loading your Game to the Simulator

Now the moment you've been working toward,  with your initial game code in place, press `f5` and your `.pdx` compiled game will automatically compile and the Playdate Simulator will open with your game loaded.

If it doesn't work, there is likely an issue with your directory structure or `task.json` / `launch.json` files. Double check you have these configured properly with your project directory name in place of the placeholders I provided.

### Best Practices Before Uploading to a Remote Repository

If you plan to upload your project to GitHub or other repository, it's good practice to create a `.gitignore` and `README.md` file.

Since we're developing on Mac, you can start with the following. Add anything else as needed:

```json
// .gitignore

.DS_Store
```

Create `README.md` and add any relevant info about your project:

```markdown
// README.md

# YourGameName

A Playdate game by YourName
...
```

### Final Thoughts

Good luck, and happy hacking! If you make something cool, or have any questions, hit me up [on Twitter](https://twitter.com/amirardalan).

Big thanks to [Orta](https://marketplace.visualstudio.com/publishers/Orta) for the excellent VSCode extension.



Get Started with Playdate SDK on MacOS

<div class="note">In this guide, I will show you how to implement a copy code to clipboard feature with <a href="https://github.com/remarkjs/react-markdown" target="_blank" rel="noopener noreferrer">react-markdown</a> using TypeScript. Once again, we will be utilizing the custom component feature.</div>

<div class="note>If you're using `react-markdown` you may be interested in other customizations I've written about including [line highlighting](/blog/syntax-highlight-code-in-markdown) with `react-syntax-highlighter` and using the [Next/Image component](/blog/use-next-image-with-react-markdown) in your markdown.</div>

### Introduction to Custom Components with React Markdown

The [official documentation](https://github.com/remarkjs/react-markdown#appendix-b-components) shows this example for overriding various elements in your markdown.

> "The keys in components are HTML equivalents for the things you write with markdown. Every component will receive a `node` (Object). This is the original hast element being turned into a React element."

```tsx
// Markdown.tsx
import ReactMarkdown from 'react-markdown'

<ReactMarkdown
  components={{
    // Map `h1` (`# heading`) to use `h2`s.
    h1: 'h2',
    // Rewrite `em`s (`*like so*`) to `i` with a red foreground color.
    em: ({node, ...props}) => <i style={{color: 'red'}} {...props} />
  }}
/>
```

This is an incredibly powerful feature. It allows us to select any HTML element rendered from markdown and modify it.

For the sake of this guide, we are going to be targeting the `pre` element which wraps code blocks.

### Targeting the Pre Element

Let's start by setting up a `<pre>` element and passing it the existing props to keep the existing functionality of our code blocks. This will set us up to be able to add our button to copy the code. We'll also create a type interface for our custom node object.

```tsx {4-11,15-17}
// Markdown.tsx
import ReactMarkdown from 'react-markdown'

interface PreNode {
  node?: any
  children: Array<object>
  position: object
  properties: object
  tagName: string
  type: string
}

<ReactMarkdown
  components={{
    pre: (pre: PreNode) => {
      return <pre {...pre}></pre>
    }
  }}
/>
```

At this point, everything should look the same... we are overriding the existing `<pre>` elements with the same thing that was rendering before. But now we have a place to put our custom code.

### Adding the Copy Button and Click Handler

Here we will add a wrapping div around the `<pre>` tag. This will give us a way to absolutely position the copy button over the code block.

```tsx {9-12}
// Markdown.tsx

...
<ReactMarkdown
  components={{
    pre: (pre: PreNode) => {

      return (
        <div className="copyCode">
          <button onClick={()=> handleCopyCode()} />
          <pre {...pre}></pre>
        </div>
      )
    }
  }}
/>
```

And the corresponding CSS, for this guide, I am using [Emotion](https://emotion.sh/docs/introduction), but it should be simple enough to refactor to whatever type of CSS you're using.

```typescript
// Markdown.tsx
import ReactMarkdown from 'react-markdown'

const styleMarkdown = css({
  '.copyCode': {
    position: 'relative',
    button: {
      zIndex: 1,
      position: 'absolute',
      top: 13,
      right: -10,
      backgroundColor: 'var(--code-highlight)',
      borderRadius: 5,
      textTransform: 'uppercase',
      fontSize: 13,
      padding: '.1rem .4rem .2rem',
      color: 'var(--color-bg)',
      '&:after': {
        content: '"📋"',
      },
    },
    '&.active button:after': {
      content: '"☑️"'
    }
  }
})

<ReactMarkdown
  css={styleMarkdown}
...
```

### Accessing the Raw Code Data for Copying

Let's create a variable that stores the raw data for this code block. Using standard dot notation, we're accessing the raw string from the underlying markdown. This string, along with other useful data, is passed to the `node` object from the base Hast element.

```tsx {8}
// Markdown.tsx

...
<ReactMarkdown
  css={styleMarkdown}
  components={{
    pre: (pre: PreNode) => {
      const codeChunk = pre.node.children[0].children[0].value
      
      return (
        <div className="copyCode">
          <button onClick={()=> handleCopyCode(codeChunk)} />
          <pre {...pre}></pre>
        </div>
      )
    }
  }}
/>
```

### Setting up State for Our 'Copied' UI Element

Now let's import `useState` and set up our state for styling the button to notify the user that the code has been copied to their clipboard. Note that the `className` is being refactored to support a ternary linked to our state.

We'll initially set the state to `false`, and then `true` once the button is clicked along with our code to copy the `codeChunk` to the clipboard.

Lastly, we will utilize a `setTimeout` to display the "copied" styling for 5 seconds. This simple feedback makes it clear that the code was, in fact, copied.

```tsx {2, 9-18, 20}
// Markdown.tsx
import { useState } from 'react'

...
<ReactMarkdown
  css={styleMarkdown}
  components={{
    pre: (pre: PreNode) => {
      const codeChunk = pre.node.children[0].children[0].value
      
      const [codeCopied, setCodeCopied] = useState(false)
      const handleCopyCode = (codeChunk: string) => {
        setCodeCopied(true)
        navigator.clipboard.writeText(codeChunk)
        setTimeout(() => {
          setCodeCopied(false)
        }, 5000)
      }
      return (
        <div className={codeCopied ? 'copyCode active' : 'copyCode'}>
          <button onClick={()=> handleCopyCode(codeChunk)} />
          <pre {...pre}></pre>
        </div>
      )
    }
  }}
/>
```

### Putting it all Together

We now have a button on each code block that copies the raw code data to clipboard. We're also utilizing a state management hook to visually notify users that the action was successful ✨.


```tsx
// Markdown.tsx
import { useState } from 'react'
import ReactMarkdown from 'react-markdown'

const styleMarkdown = css({
  '.copyCode': {
    position: 'relative',
    button: {
      zIndex: 1,
      position: 'absolute',
      top: 13,
      right: -10,
      backgroundColor: 'var(--code-highlight)',
      borderRadius: 5,
      textTransform: 'uppercase',
      fontSize: 13,
      padding: '.1rem .4rem .2rem',
      color: 'var(--color-bg)',
      '&:after': {
        content: '"📋"',
      },
    },
    '&.active button:after': {
      content: '"☑️"'
    }
  }
})

interface PreNode {
  node?: any
  children: Array<object>
  position: object
  properties: object
  tagName: string
  type: string
}

<ReactMarkdown
  css={styleMarkdown}
  components={{
    pre: (pre: PreNode) => {
      const codeChunk = pre.node.children[0].children[0].value
      
      const [codeCopied, setCodeCopied] = useState(false)
      const handleCopyCode = (codeChunk: string) => {
        setCodeCopied(true)
        navigator.clipboard.writeText(codeChunk)
        setTimeout(() => {
          setCodeCopied(false)
        }, 5000)
      }
      return (
        <div className={codeCopied ? 'copyCode active' : 'copyCode'}>
          <button onClick={()=> handleCopyCode(codeChunk)} />
          <pre {...pre}></pre>
        </div>
      )
    }
  }}
/>
```


### Final Thoughts

It's quite simple to extend `react-markdown` with custom component overrides. [Unified](https://unifiedjs.com/) provides a lot of out of the box [Rehype](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins) and [Remark](https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins) plugins which may suit your needs, but there is currently no plugin for copying the markdown code to clipboard. I'm glad I didn't have the temptation to add a dependency to the project when making my own feature was so easy (and fun!).


In addition to `react-syntax-highlighter`, my custom [Next/Image](blog/use-next-image-with-react-markdown) component, and this copy to clipboard feature, I am using [rehype-slug](https://github.com/rehypejs/rehype-slug), [rehype-auto-link-headings](https://github.com/rehypejs/rehype-autolink-headings), [rehype-raw](https://github.com/rehypejs/rehype-raw), and [remark-gfm](https://github.com/remarkjs/remark-gfm). I may write some guides on  a few of those plugins and my configurations in the future.

As always, you can find me on [Twitter](https://twitter.com/amirardalan) if you have any questions.✌️

Copy Code to Clipboard with React Markdown

I've recently hit 30 days straight of at least one commit per day to an open source repository. My personal portfolio and an NFT gallery project have had me heads down in Next.js and TypeScript. I didn't set out with a goal to complete a streak of any kind but I have been in a flow-state, having a ton of fun writing code.

Over the course of the past month of building projects, a few things of note have stood out, I’m going to share those in this post.


### Harness the Power of the Community

While building out the search functionality for this blog, I received a feature enhancement request from someone who was following my repo on GitHub. They presented a specific use case that I had not considered, and it was a significant improvement over what I had in place. I built out the enhancement and my site was much better for it.

This is part of the magic of open source. I can spend hours, days, weeks designing and building out a feature but there’s almost always room for improvement. Sometimes it takes a set of fresh eyes to bring a great idea to the surface.


### Build First, Polish Later

This one is paramount if you need to get a long list of things built out and working together, quickly. I found myself taking a “quick and dirty” approach to building a feature and spending the majority of my initial time cross-browser/device and UX testing.

Once things feel good from a UI/UX perspective, I like to do a solid SEO, Accessibility, and Developer Experience pass. I moved hardcoded data out of components, put meta information in place in the appropriate areas, manually tested keyboard navigation, added the appropriate ARIA tags and ensured code was performant, reusable (where appropriate), and easy to read.


### Use the Application

Become a user of your own product. I like to get my mind in the frame of an end-user. Testing as an item on a checklist isn’t helpful for anyone, you’ve got to use the application. Major issues, improvement ideas, and quirks arise when you step away from the IDE and and spend 30 minutes using your app.

Use your app on your iPhone, then test it on that old phone you have laying around. Open it in Microsoft Edge. Try it on OSX and iOS Safari. Try Firefox, Chrome, Android, tablets, ultrawide monitors, and your TV. You will learn a ton about shortcomings of User Interface and functionality if you try for yourself on different devices.

And “using the app” doesn’t stop there. Try turning off WiFi and connecting to a mobile hotspot, how’s the performance and load times? Notice any issues? You might need loading indicators or smaller json payloads when browsing on a slow connection.


### Design From Your Own Head

Controversial opinion — unless you are brand new and learning the basics — skip the tutorials, Dribbble, and Twitter. Ditch the UI libraries and style guides.

Everyone learns, works, and processes things differently. What works for me, may not work for you. With that said, I find the external resources to cloud my judgement, intuition, and personal development as a designer. When I’m in the process of designing or building, I do it almost exclusively without external ideas or inspiration.

Once I have a baseline, I then refine and iterate for the sake of functionality and usability. I refine styling 15-20+ times. I am careful to keep my original Adobe XD design up to date as I make changes. Through this iteration I find my own design identity and visual language.


### Final Thoughts

Coming up with an idea, then designing, developing, and iterating on it is invaluable experience for developers of all skill levels. You’ll learn a lot about the _how_ and _why_, but more than anything you learn about yourself. You figure out how you learn, what keeps you motivated, what makes it fun for you personally, and  what tools and processes are effective for getting your project built.

If you’re kicking around the idea of refreshing your portfolio, creating an app that you will find useful, or exploring something new that you find interesting; do it! Come up with a plan, dive in, and don’t stop until it’s done. Then when it’s done, USE IT. Then make it better. Happy coding 👨‍💻🥳

30 Days of Writing Code

Setting up Google Anaylytics is fairly straight forward, but it can be easy to get tripped up when doing so in Next.js for the first time. In this guide, I will show you how to get GA running in your Next.js app in just a few easy steps.

<div class="note">Make sure to create a GA4 property in Google Analytics. Universal Analytics will no longer be supported as of July 1, 2023.</div>

### Add your Google Analytics ID to `.env`

If you don't already have one, create a file called `.env`. Make sure to add this file to your `.gitignore` as this is a place to store sensitive information that should never be uploaded to a git repository.


```typescript
NEXT_PUBLIC_ANALYTICS_ID=G-XXXXXXXXXX
```

### Add Data Layer to `_document.tsx`

If you don't already have one, create a [custom Document](https://nextjs.org/docs/advanced-features/custom-document) page and add the script tags provided by Google Analytics:

```typescript {9-21}
// _document.tsx

import { Html, Head, Main, NextScript } from 'next/document'

export default function Document() {
  return (
    <Html>
      <Head>
        <script
          async
          src={`https://www.googletagmanager.com/gtag/js?id=${process.env.NEXT_PUBLIC_ANALYTICS_ID}`}
        />
        <script
          dangerouslySetInnerHTML={{__html: `
            window.dataLayer = window.dataLayer || [];
            function gtag(){dataLayer.push(arguments);}
            gtag('js', new Date());
            gtag('config', '${process.env.NEXT_PUBLIC_ANALYTICS_ID}');
            `,
          }}
        />
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

```


### Create `gtag.ts` in `lib` Folder

This will get the initial tracking set up for your app.

```typescript
// gtag.ts

declare global {
  interface Window {
      gtag: any
  }
}

export const pageview = (url: URL) => {
  window.gtag('config',
    process.env.NEXT_PUBLIC_ANALYTICS_ID, {
    cookie_flags: 'SameSite=None;Secure',
    page_path: url,
  })
}

export const event = ({ action, category, label, value }) => {
  window.gtag('event', action, {
    event_category: category,
    event_label: label,
    value: value,
  })
}
```

### Create `useGtag.ts` in `utils` Folder

Here we will utilize Next's `useRouter` in order to send route information to Google Analytics. 

<div class="note">Technically, this isn't a custom hook since it doesn't have state, but you can't utilize <code>useEffect</code> inside of a normal function (and this isn't a component). I have chosen this name and path for code organization purposes, but you can alternatively put the useEffect directly in <code>_app.tsx</code></div>

```typescript
// useGtag.ts

import { useEffect } from 'react'
import { useRouter } from 'next/router'
import * as gtag from '@/lib/gtag'

const useGtag = () => {
  const router = useRouter()
  useEffect(() => {
    const handleRouteChange = (url: URL) => {
      gtag.pageview(url)
    }
    router.events.on('routeChangeComplete', handleRouteChange)
    return () => {
      router.events.off('routeChangeComplete', handleRouteChange)
    }
  }, [router.events])
}

export default useGtag
```

### Invoke `useGtag` Function in `_app.tsx`

```typescript {3, 6}
//_app.tsx

import useGtag from '@/components/useGtag'

function MyApp({ Component, pageProps }) {
  Analytics()
  return <Component {...pageProps} />
}

export default MyApp
```

### Add Environment Variable to Production Server
This is an easy step to forget. Be sure to set up `NEXT_PUBLIC_ANALYTICS_ID` (from your `.env` file) on your server.

### Filter Internal Traffic
Now that GA is up and running, the final step is to ensure you aren't tracking your own visits. You will need [your IP address](https://www.google.com/search?q=whats+my+ip). Once you have your IP, log in to Google Analytics.

1. From the main page, look to the bottom left of the screen and click on the gear (Admin) icon ⚙️.
2. On the Admin screen, ensure you are on the correct GA4 property that you just set up. Click on **Data Streams**.
3. Click the **Add stream** button and click on your app address.
4. On the "Web stream details" panel, at the very bottom, click **More Tagging Settings**.
5. On the "More tagging settings" panel, click **Define internal traffic**
6. Click on the **Create** button, add a _Rule name_ (e.g. Home), and leave _traffic_type value_ as "internal". Finally, select _Match type:_ **IP Address Equals** and then paste your IP address into the _Value_ input.
7. Click the **Add condition** button. Repeat these steps for any other IPs you want to filter.
8. Click the Admin gear icon ⚙️, then select **Data Settings > Data Filters**
9. On the "Data filters" page click the three dots to the right of the Internal Traffic filter and select "Activate Filter".

### Final Thoughts

That's it! 🎉 If you run into any issues, I recommend installing Google Analytics Debugger, it's available for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/ga-debugger/) and [Chrome](https://chrome.google.com/webstore/detail/google-analytics-debugger/jnkmfdileelhofjcijamephohjechhna?hl=en).

Google Analytics is a great way to keep track of who visits your site, where they are coming from, what they are looking at, and how long they are spending doing so. While it's packed with features and customizations, the UI is a bit clunky and it can be overkill for a small site. I have been on the lookout for something modern, lightweight, and free. If you know of anything that fits that description, [hit me up on Twitter](https://twitter.com/amirardalan) and let me know!

Implement Google Analytics in Next.js

In this article we are _not_ going to build the next Google. Instead, we will create a fast and lightweight blog post and category search using TypeScript and React.


<div class="note">For the sake of simplicity, this guide will cover functionality only. You can apply your own styling to the final result!</div>


### The Problem

You have built a React-based blog and you have a blog page that displays your posts. As your content continues to grow, you will end up with a very long list (or many pages) of blog content. It would be nice for users to be able to quickly search through the blog for relevant content _or_ to find content they previously read and are seeking out again.


### Features and Considerations

My blog has a simple category system, each post is tagged with a single category. I want to be able to search through the blog posts by title _and_ by category. I'd also like to have a simple category navigation above the search input that is dynamically generated based upon the categories which exists on all published posts. The search will initially search by title. If a search query begins with a `#`, then the posts will be searched by category. Finally, if a category is found, we can continue to search post titles within that category (`#code markup`).


### Create `compareID.ts`

This function will vary depending on the data structure of your blog posts. For my setup, each post has an object, and each object has a unique ID. I can use the sort method on my blog feed Array and then pass this compare function to the sort method. This tells the code to sort the object in my array based on the ID. Modify this for your own use. Check out the [MDN Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort) for further reading on `sort()`.

```typescript
// compareID.ts

// Sort Blog posts by ID
type ID = { id: number }

const compareID = (a: ID, b: ID) => {
  if ( a.id < b.id ) return -1
  if ( a.id > b.id ) return 1
  return 0
}

export default compareID
```


### Create `BlogPostFilter.tsx`

This is where the bulk of our code will go. This file will render our blog posts and initially sort them based on `compareID.ts`, then it will allow us to further filter post based on title and/or category.

We will start by importing `{useState}` from react and our `compareID` util that we just created:

```tsx
// BlogPostFilter.tsx

import { useState } from 'react'
import compareID from '@/utils/compareID'
// We will eventually add a few more things here


const BlogPostFilter = () => {

  const [search, setSearch] = useState('')
  
  // Most of our code will go here!

}

export default BlogPostFilter
```


### Render Our Posts

Let's get the blog posts displaying, I already have a component `BlogPost` that renders the post title and link, publish date, reading time and teaser copy. My blog post data is coming from the `{feed}` prop which I am passing into this component. It contains a unique ID for each post.


```tsx {5,12-33}
// BlogPostFilter.tsx

import { useState } from 'react'
import compareID from '@/utils/compareID'
import BlogPost from '@/components/BlogPost'


const BlogPostFilter = ({ feed }) => {

  const [search, setSearch] = useState('')

  const filteredPosts = feed

  const RenderPosts: Function = () => {
    if (filteredPosts.length > 0) {
      return (
        filteredPosts.sort(compareID).reverse().map((post: Record<string, string>) => (
          <span key={post.id}>
            <BlogPost post={post} />
          </span>
        ))
      )
    } else null
  }

  return (
    <>
      <div className="post">
        <RenderPosts />
      </div>
    </>
  )
}

export default BlogPostFilter
```

### Adding the Search Input

```tsx {4-12}
// BlogPostFilter.tsx

...
  <div>
    <input
      type="text"
      placeholder="Search posts"
      value={search}
      aria-label="Search posts"
      onChange={(e) => setSearch(e.target.value)}
    />
  </div>
  <div>
    <RenderPosts />
  </div>
...
```


### Create a Category Navigation

```tsx {6-34}
// BlogPostFilter.tsx

...
  return (
    <>
      <nav>
        <ul>
          <li>
            Categories:
          </li>
          <li>
            <button
              onClick={() => setSearch('')}
              onKeyPress={() => setSearch('')}
              className={search === '' ? "all active" : "all"}
              aria-label="All"
            >
              All
            </button>
          </li>
          {activeCategories.sort().map((category, index) => (
            <li key={index}>
              <button
                onClick={() => handleCategoryLink(category)}
                onKeyPress={() => handleCategoryLink(category)}
                className={search.split(' ')[0] === '#'+category ? "active" : ""}
                aria-label={category}
              >
                {category}
              </button>
            </li>
          ))}
        </ul>
      </nav>
      
      <div>
        <input
          type="text"
          placeholder="Search posts"
          value={search}
          aria-label="Search posts"
          onChange={(e) => setSearch(e.target.value)}
        />
      </div>
      <div>
        <RenderPosts />
      </div>
    </>
  )
}

export default BlogPostFilter
```


### Expand Upon `RenderPosts` Function

Let's add a category link above each blog post to give users a way to quickly filter all posts by that category. We will also add an error state with the ability to clear the search if no matches were found.

```tsx
// BlogPostFilter.tsx

...
  const RenderPosts: Function = () => {
    if (filteredPosts.length > 0) {
      return (
        filteredPosts.sort(compareID).reverse().map((post: Record<string, string>) => (
          <span key={post.id}>
            <button
              onClick={() => handleCategoryLink(post.category)}
              onKeyPress={() => handleCategoryLink(post.category)}
              aria-label={post.category}
            >
              {post.category}
            </button>
            <BlogPost post={post} />
          </span>
        ))
      )
    } else {
        return (
          <span>
            No posts found.
            {feed.length > 0 ?
            <button
              onClick={() => setSearch('')}
              onKeyPress={() => setSearch('')}
              aria-label="Clear search"
            >
              {' '}Clear Search
            </button>
            : null}
          </span>
        )
    }
  }
...
```


### Implementing the Search Functionality

This is the core of the search functionality. It will allow users to input a search term and we'll try to match our blog titles to their search. If they begin the search query with a `#` we will search instead by category. If a category is found and the user continues to search, it will further drill down posts _within_ that specific category by once again searching by title.

Note that the `filteredPosts` variable we created earlier has been slightly refactored here.

```tsx {7-36}
// BlogPostFilter.tsx

const BlogPostFilter = ({ feed }) => {

  const [search, setSearch] = useState('')

  const handleCategoryLink = (category: string) => {
    setSearch('#'+category)
    window.scrollTo(0, 0)
  }

  const activeCategories: Array<string> = Array.from(new Set(feed.map((post: Record<string, object>) => {
    return post.category
  })))

  const searchResults = (search: String, feed: Array<object>) => {
    const categorySearch = search[0] === '#'
    const categoryMatch = activeCategories.indexOf(search.slice(1).split(' ')[0]) > -1
  
    // if #, search categories
    if (categorySearch) {
      // if category matches categories, search titles with category
      if (categoryMatch) {
        return feed.filter((data: { category: string, title: string }) => 
          data?.category?.toLowerCase().includes(search.slice(1).toLowerCase().split(' ')[0]) && 
          data?.title?.toLowerCase().includes(search.replace(/#[a-z]+/, '').trim().toLowerCase()))
      }
      return feed.filter((data: { category: string }) => 
        data?.category?.toLowerCase().includes(search.slice(1).toLowerCase()))
    }
    // if no #, just search titles
    return feed.filter((data: { title: string }) => 
      data?.title?.toLowerCase().includes(search.toLowerCase()))
  }

  const filteredPosts = searchResults(search, feed)
...
```

### Putting it All Together

```tsx
// BlogPostFilter.tsx

import { useState } from 'react'
import compareID from '@/utils/compareID'
import BlogPost from '@/components/BlogPost'



const BlogPostFilter = ({ feed }) => {


  const [search, setSearch] = useState('')

  const handleCategoryLink = (category: string) => {
    setSearch('#'+category)
    window.scrollTo(0, 0)
  }

  const activeCategories: Array<string> = Array.from(new Set(feed.map((post: Record<string, object>) => {
    return post.category
  })))

  const searchResults = (search: String, feed: Array<object>) => {
    const categorySearch = search[0] === '#'
    const categoryMatch = activeCategories.indexOf(search.slice(1).split(' ')[0]) > -1
  
    // if #, search categories
    if (categorySearch) {
      // if category matches categories, search titles with category
      if (categoryMatch) {
        return feed.filter((data: { category: string, title: string }) => 
          data?.category?.toLowerCase().includes(search.slice(1).toLowerCase().split(' ')[0]) && 
          data?.title?.toLowerCase().includes(search.replace(/#[a-z]+/, '').trim().toLowerCase()))
      }
      return feed.filter((data: { category: string }) => 
        data?.category?.toLowerCase().includes(search.slice(1).toLowerCase()))
    }
    // if no #, just search titles
    return feed.filter((data: { title: string }) => 
      data?.title?.toLowerCase().includes(search.toLowerCase()))
  }

  const filteredPosts = searchResults(search, feed)

  const RenderPosts: Function = () => {
    if (filteredPosts.length > 0) {
      return (
        filteredPosts.sort(compareID).reverse().map((post: Record<string, string>) => (
          <span key={post.id}>
            <button
              onClick={() => handleCategoryLink(post.category)}
              onKeyPress={() => handleCategoryLink(post.category)}
              aria-label={post.category}
            >
              {post.category}
            </button>
            <BlogPost post={post} />
          </span>
        ))
      )
    } else {
        return (
          <span>
            No posts found.
            {feed.length > 0 ?
            <button
              onClick={() => setSearch('')}
              onKeyPress={() => setSearch('')}
              aria-label="Clear search"
            >
              {' '}Clear Search
            </button>
            : null}
          </span>
        )
    }
  }

  return (
    <>
      <nav>
        <ul>
          <li>
            Categories:
          </li>
          <li>
            <button
              onClick={() => setSearch('')}
              onKeyPress={() => setSearch('')}
              className={search === '' ? "all active" : "all"}
              aria-label="All"
            >
              All
            </button>
          </li>
          {activeCategories.sort().map((category, index) => (
            <li key={index}>
              <button
                onClick={() => handleCategoryLink(category)}
                onKeyPress={() => handleCategoryLink(category)}
                className={search.split(' ')[0] === '#'+category ? "active" : ""}
                aria-label={category}
              >
                {category}
              </button>
            </li>
          ))}
        </ul>
      </nav>
      
      <div>
        <input
          type="text"
          placeholder="Search posts"
          value={search}
          aria-label="Search posts"
          onChange={(e) => setSearch(e.target.value)}
        />
      </div>
      <div>
        <RenderPosts />
      </div>
    </>
  )
}

export default BlogPostFilter
```

You should now have a basic category search working using TypeScript and React! It will require a bit of styling and there are also some UX enhancements you can make like a "clear search" icon inside the input and also below filtered posts to make it easier for a user to reset the search, especially if they have scrolled down a page of filtered posts.

---

### Acknowledgements

Big thank you to [Ryan Chase](https://chasery.com) for assisting with refactoring my search function to be cleaner. And shout out to [XHXIAIEIN](https://github.com/XHXIAIEIN) on GitHub for the excellent suggestion to allow searching _within_ an already filtered category. This is an awesome improvement on my original search feature.


Build a Category Search with React

With the launch of this 2021 version of [my portfolio](https://github.com/amirardalan/amirardalan.com) and blog, I've taken a step back from furiously submitting GitHub commits to pause and exhale. The end of a project is a natural time to reflect, and I've been thinking a bit about the motivation behind why I code and the journey that led me here.


I sounds crazy to say, but I've been working on designing and coding websites for the better part of 20 years now. Two whole decades have elapsed while I've mashed away on my keyboard writing code. Sometimes with excitement and unfettered motivation, sometimes with soul-crushing frustration and fatigue, but always with the foundational understanding: _this is what I love to do_.


Love and passion will take you far, if it's honest. Technologies evolve, best-practices change, frameworks and methodologies come and go, but a few things remain constant: I make experiences and interfaces that bridge humans and machines, and the flame of passion for web development continues to burn strong. As far as how the fire started? Let's turn back the hands of time...


### 2000 - The Journey Begins

My first foray into HTML and CSS was in 2000, my freshman year of high school. Picture this: The Matrix had just released. Y2K parties were a thing. I had always been interested in computers, technology and digital design, but I wasn't familiar with web code up to this point. One day at school, a friend of mine showed me her website that she made using [Yahoo! Geocities](https://en.wikipedia.org/wiki/Yahoo!_GeoCities), it blew my mind. She had her _own_ webpage. Complete with profile photo, sparkly, animated gifs, and all kinds stylized borders and dividers. I knew I had to make one too, and so I did. That's right – my first "stack" was Geocities.


### 2002 - The Early years

For the next two years, I obsessed over HTML and CSS and web design. For perspective, this was pre MySpace. I actually had a leg up when _that_ platform (which also featured glitter gifs, (now-deprecated) [blink tags](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blink), and [marquees](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/marquee) – **so** many marquees – came to be.

As if all of this wasn't exciting enough, another piece of software released in 2000 was also making waves on the internet, it featured keyframe animation, vector design tools and a JavaScript-like language called [ActionScript](https://en.wikipedia.org/wiki/ActionScript). This industry giant in the making was known as none other than Macromedia Flash. Our high school's "TV Studio" had a single copy of Flash 4 and myself and a classmate would spend every free moment in that lab, tucked in the back corner of the library, creating vector graphics, animations, motion tweens and hacky ActionScript.

As soon as I had a decent enough grasp on web hosting and creating complete site experiences with Flash, I did what most aspiring webmasters did, I began making small marketing sites for my friends and family members. Eventually I was making websites for my friends' family members, and then their family members colleagues, etc. – I was a bonafide freelancer. Or so I thought.


### 2005 - My First Real Dev Job

Web 2.0 was in full swing. Logos got round, shiny and skeuomorphic. I stayed busy crafting websites and logos as my primary source of income. I had a decent amount of clients but my business sense was immature and I didn't have the foresight to carve out any recurring income through the services I was providing.

I ended up applying for a UI Design job that I found on Craigslist and wound up working at a small, startup software company in the industrial area of Portland's Westside waterfront. We made real estate software that pulled data from the RMLS database and developed an early version of Zillow (before Zillow was a thing). I contributed flash websites, graphic design and User Interface design for a couple years.

I find it amusing looking back, that the first conferences I attended were Real Estate conferences. What a great way for a somewhat shy kid to come out of his shell and acquire some business acumen. Have you ever talked to a Real Estate Agent?!


### 2007 - Becoming My Own Boss

With my first professional gig – a startup no less – under my belt, I decided to ramp up the freelancing I had been maintaining for the prior three years and attempt to grow my client-base to a level of self-sustainability and beyond. Long story short, this was harder than I anticipated. I wouldn't classify this period as a failure, but it was my first time coming face to face with **real** challenges. Big and painful challenges with real people and real money to further complicate things. Nonetheless I plugged away, mostly designing and coding [WordPress](https://wordpress.org/) themes.


### 2011 - Ramping Up My Code & Design Skills

After several years of staying afloat freelancing and learning valuable skills and lessons along the way, I was recommended by a friend to apply for a Front-end development job at a startup in Beaverton, OR called [DealerSpike](https://www.dealerspike.com/). This was my first true full-time development job. I did a bit of design in Photoshop and consultations with clients using design brief skills I had picked up over the previous years. DealerSpike was a very fast-paced environment with a plethora of young talent and a product good enough to propel it one of Oregon's fastest growing businesses for several years running. It was here that I got comfortable working as a member of a large team and communicating effectively with hundreds of clients in the Powersports, RV and Marine industry across the US.


### 2014 - My Big Break

In 2014 I landed a full-time job as a Web Developer I at [Columbia Sportswear Company](https://www.columbia.com/). Compared to everything I had done prior, this felt like the big leagues. I was surrounded by incredibly capable Senior level Engineers and Solutions Architects and corporate executives. I was introduced to Agile Scrum and worked directly with Product Owners, dedicated PMs, UX Architects, and Interface Designers. 

We had a massive project involving launching a localized version of their [Salesforce Commerce Cloud](https://www.salesforce.com/products/commerce-cloud/overview/) Ecommerce platform. I was directly responsible for a huge number of Font-end features on Columbia, [SOREL](https://www.sorel.com/) and [Mountain Hardwear](https://www.mountainhardwear.com/)'s websites.

With a major project successfully launched at a large, publicly traded corporation, and plenty of newfound Front-end knowledge, I set my sights on the next chapter.


### 2015 - First Steps in Leadership

A local (Portland, OR), family-owned and privately-held footwear company was assembling it's first ever in-house web development team. I had previously worked with their new Director of Ecommerce, and I was familiar with the application they were considering for their digital brand relaunch. [KEEN Footwear](https://keenfootwear.com) was seeking to assemble a capable team of experienced developers to build a custom Ecommerce experience for both KEEN and [Chrome Industries](https://chromeindustries.com). I joined the team as a UI Engineering Lead and gained valuable experience in a split development and leadership role. I managed day-to-day updates and replications and orchestrated interviewing and hiring a small team. If I could go back in time and give my past self one piece of advice, it would be to double down on my technical skills and offset the leadership role as a slower, more methodical track.

Hiccups aside, our team collectively pushed forward in the face of uncharted waters as the first development team within the walls of KEEN. I look back fondly on this time, the company and work was fun but it was the people that made it exceptional. We were heads down for the better part of a year and eventually accomplished our goal of launching two new digital brand experiences for KEEN and Chrome. I also acquired like 7 free Chrome bags during this time so that was a plus, I still use them to this day!


### 2018 - Trial by Fire in a Fast-paced Agency

By this point I had loads of experience freelancing, I’d contributed front end code and content management to two enterprise Salesforce Commerce Cloud implementations, and I’d worked at a handful of startups in between. Something I _hadn’t_ done was agency work.

At this point I set out on my biggest and most intense challenge as a developer. As an Application Engineer, I pushed myself well outside of my comfort zone and delved into the world of full stack development. During my year at [DemandPDX](https://www.demandpdx.com/), I acquired deeper knowledge of Salesforce Commerce Cloud development, JavaScript controllers, data structures, application architecture and how to juggle multiple complex codebases at one time. I spent a brief period on "loan" as an in house developer and general Salesforce Commerce Cloud consultant for one of our largest clients, [Hanna Andersson](https://www.hannaandersson.com/). I love and appreciate the people I worked with during this time, and I’m thankful to have experienced a fast paced and challenging agency work environment.


### 2019 - Stepping Away from Ecommerce

The pandemic hit shortly after leaving my agency job and I took some personal time to recharge, reset (and play a bit of Animal Crossing). I then dedicated myself to returning to basics and sharpening my development, design, testing, documentation and workflow efficiency skills.

With so much prior time spent working on Ecommerce and SFCC specifically, I felt a tremendous motivation to branch out and sink my teeth into the modern web development ecosystem outside of online shopping. The "new hotness" modern web technologies. What did I discover? React is really, really fun. Since then I’ve been all-in on learning, and focusing on freelance and personal projects.


### 2021 - React Deep Dive and Beyond

Lately, thanks to the recommendations of my colleague and friend [Ryan Chase](https://chasery.com), I was introduced to Next.js, Emotion and PostgreSQL. At this time, I'm placing major emphasis on JavaScript, Typescript and React. I'm especially fond of [Next.js](https://nextjs.org/), [Emotion](https://emotion.sh/docs/introduction), [Three.js](https://threejs.org/) and [Prisma](https://www.prisma.io/), all which were used to help create this site and blog!

I am committing myself fully to continuing the journey of technical learning and mastery of fullstack development. Lately I feel like I did when I first discovered Geocities or when I first tried Flash. My experience as a web developer is a journey. It will always have ups and downs, but the constants will remain: I make experiences and interfaces for _people_, and I _love_ what I do.

----

- Located in Portland, OR
- Currently available for hire
- Download [my resume](/amir-ardalan-resume.pdf)

2021: A Dev Odyssey

<div class="note">This guide is for Mac OS</div>


So you've got a [PostgreSQL](https://www.postgresql.org/) database up and running on [Heroku](https://heroku.com).


When developing and testing, it is critical to keep an eye on the health and usage of your database in real time. Monitoring your Postgres database via Terminal is fairly easy, but there are a lot of steps.


Before getting started, there are a couple of things to note:


- In this guide I am using/referencing ZSH `%`. But everything should work just fine using Bash `$`.
- This guide assumes you've already created an app and set up your PostgreSQL database. If not, follow [Heroku's guide](https://devcenter.heroku.com/articles/heroku-postgresql#set-up-postgres-on-mac).
- _Use the command line at your own risk._ 


### Install Homebrew

In the Terminal, run:  
`% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`


On MacOS you may encounter this error:


```bash
fatal: invalid branch name: init.defaultBranch =  Failed during: git init -q
```


It's essentially an issue with Homebrew attempting to initialize a git repository to clone itself, but failing. Here are the steps I took to resolve it:


1) `% cd /usr/local/Homebrew`  
2) `% git config --global init.defaultBranch master`  
3) `% /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`


Homebrew should now be installed for use via Terminal on your Mac.


### Install Heroku CLI and Login

To install Heroku CLI run the following commands:  
1) `% brew tap heroku/brew && brew install heroku`   
2) `% heroku login`


When prompted, press any key to be redirected to your  browser to authenticate. Boom, you're in.


### Connect to the Heroku App Linked to Your DB

Back in the Terminal run:  
`% heroku pg:info -a your-app-name`


You should see something like:  


```bash
=== DATABASE_URL
Plan:                  Hobby-dev
Status:                Available
Connections:           0/20
PG Version:            13.2
Created:               2021-05-15 11:06 UTC
Data Size:             9.0 MB
Tables:                4
Rows:                  13/10000 (In compliance)
Fork/Follow:           Unsupported
Rollback:              Unsupported
Continuous Protection: Off
Add-on:                postgresql-XXXXX-XXXXX
```


Great! You can now access your PostgreSQL data via command line.


<div class="note">Hobby-tier databases often have limited connections. If your connections are maxing out, investigate why, and look to modify your code to reduce requests and open connections. If you quickly need to terminate all connections and restore functionality, simply run: <code>heroku pg:killall -a your-app-name</code></div>


### Using `watch` to Monitor Your Database

Now let's take it one step further and install and utilize `watch` to continuously monitor our database. `watch` is a simple CLI tool for monitoring data at a set interval. Let's ensure you have `watch` installed (if you are running ZSH you may not).


1) `% type watch` will inform you if `watch` is installed  
2) If not installed, run: `% brew install watch`


Now run:  
`% watch heroku pg:info -a your-app-name`


You now have a view of your database that refreshes every 2 seconds. ⏲


<div class="note example">to refresh every 10 seconds, you would run: <code>% watch -n 10 heroku pg:info -a your-app-name</code></div>


Here are some additional arguments:


```bash
-d – Highlights differences between iterations
-h – Displays a help message, then exits
-n secs – Specifies the interval between executions of the command in seconds
-t – Tells watch not to display the header
-v – Prints version information, then exits
```


That's it! Happy monitoring. 🎉

---

### Additional Documentation

For full documentation, follow the [Using the CLI](https://devcenter.heroku.com/articles/heroku-postgresql#using-the-cli) guide on Heroku.

Monitoring Heroku PostgreSQL

### What's This For?

Supabase's free-tier Postgres offering doesn't come with a backup feature. If you need to make a quick copy of your database, its possible to manually back it up with a simple `pg_dump` bash script.

<div class="note">
This guide assumes you have a Postgres database on Supabase and have <a href="https://docs.brew.sh/Installation" target="_blank" rel="noopener noreferrer">Homebrew</a> installed.
</div>


### Install Postgres

```bash 
brew install postgresql
```

Check out the [official documentation](https://wiki.postgresql.org/wiki/Homebrew) for detailed instructions. There is also info on how to switch versions if you have a version mismatch with your database.

### Create a Backup Script

Go to your [Supabase Dashboard](https://supabase.com/dashboard/projects), select your DB, and click the `Connect` button for the details you need to complete this script:

```bash 
pg_dump 'postgres://postgres.[username]:[password]@[host].supabase.com:5432/postgres' > prod_db_backup.sql
```

### Run the Script

Now that you've formed your backup script, simply run it in your Terminal. Your backup file will appear in the directory that you run the script in. If you need to automate the backups, this script would be a good starting point.

[Reach out to me on X](https://x.com/amirardalan) if you have any questions.

Blog — Amir Ardalan

Manually Backup Supabase Postgres Database