AWS access that revokes itself

AWS Dynamic DNS

AWS Solutions Architect Associate Certification

Battlesnake Programming Competition 2018

Book Notes: DevOps Handbook, The

Dark Mode React Toggle

Deno Tests & GitHub Actions CI

Deploy a Next.js Static Site to GitHub Pages

Migrating Frontend Assets During Grails 2 → 3 Upgrade

Lightshift Game

Markdown based Code Block Syntax Highlighting

Building a Mechanical Keyboard from Scratch

My Introduction to Game Development

Next.js Tag Pages

Node CI/CD Pipeline using GitHub Actions & AWS Elastic Beanstalk

Resources I Found Valuable in 2022

Small Form Factor PC Build Part 1

Small Form Factor PC Part 2 - Water Cooling

Shipping ECS Fargate logs to Datadog with FireLens (and what broke)

Static Site Search Part 3 - Optimizing the Index

Static Site Search Part 1 - Preprocessing Articles

Static Site Search Part 2 - Search Component

How I use my Synology NAS as my personal cloud

What is a Synology NAS?

What I'm Learning in 2022

What is DevOps?

## Background

Superflux.dev (this site) uses markdown files for articles. I've been using *Marked* ([GitHub](https://github.com/markedjs/marked), [NPM](https://www.npmjs.com/package/marked)) to parse my markdown articles to html.

With my current setup, code just gets rendered to `<code>` blocks. I have applied some simple styling to them, a background colour and a monospace font, so they stand out as code. But they're pretty basic looking and boring.

![Screenshot of code where all the text is simply white on a dark background. No colors.](markdownsyntaxhighlight1.png)

What I'd like to have is rich code syntax highlighting. I find my own code blocks hard to read because they're just plain text; highlighting would be a big readability improvement.

## What I'm currently doing

With *Marked* you can override the renderers for each element.

Mostly I just let *Marked* parse my markdown into semantic html. I am overriding a few elements: `<h#>` tags and `<img>` to apply some styling.

The *Marked* docs for the renderer are [here](https://marked.js.org/using_pro#renderer).

*utils/markedUtils.ts*
```typescript
export const renderer = {
	image(href: string, title: string, text: string) {
		const nonRelativeHref = "/images/posts/" + href;
		return `
			<img src="${nonRelativeHref}" alt="${title}" class="article-image" />
		`;
	},
	heading(text: string, level: number, raw: string) {
		switch(level) {
			case 2:
				return `
					<h2 id="${raw}">
						<span class="underline">${text}</span>
					</h2>
				`;
			default:
				return `
					<h${level} id="${raw}">${text}</h${level}>
				`;
		}
	}
}
```

Then in my *pages/blog/\[slug\].tsx*, I import this renderer config and configure *Marked* with it.

```tsx
import { marked } from "marked";
import { renderer } from "../../utils/markedUtils";

marked.use({ renderer });
```

Then in the page component for *\[slug\].tsx* I use `dangerouslySetInnerHTML` and `marked.parse` to insert the rendered html of the markdown in the DOM.

```tsx
<div dangerouslySetInnerHTML={{ __html: marked.parse(post.content) }}></div>
```

This worked well enough for a time. But an issue I was running into with this solution is that the renderer element overrides are just expecting strings, which means just html elements. I can't override them with rich React components because they wouldn't get converted to html.

Now there's probably a way to get syntax highlighting in `<code>` blocks using plain old *Marked* with html. But since I'm using React and Next I thought it would be nice to pull in a nice React code syntax highlighter.

## Marked with React components

First I needed a way to override elements in the markdown renderer with React components.

Luckily there's a package just for that! *marked-react* ([GitHub](https://github.com/sibiraj-s/marked-react), [NPM](https://www.npmjs.com/package/marked-react?activeTab=readme)). This actually uses *Marked* to parse markdown, but you can provide React components as overrides and you can simply use it in React instead of using `dangerouslySetInnerHTML`.

First I refactored my markdown rendering to use *marked-react*.

```shell
npm i marked-react
```

After installing, in my *pages/blog/\[slug\].tsx* I import it and use it in place of the `<div>` that I was setting the html in.

```tsx
import Markdown from "marked-react";

//...

  <Markdown>{post.content}</Markdown>

//...
```

Next I ported over my existing customizations I was using for headers and images from *Marked*. It's very similar to the previous configuration. The types are different and I can return TSX/JSX. I changed *markedUtils.ts* -> *markedUtils.tsx* to support TSX.

*utils/markedUtils.tsx*
```tsx
export const renderer = {
	image(src: string, alt: string) {
		const nonRelativeHref = "/images/posts/" + src
		return <img src={nonRelativeHref} alt={alt} className="article-image" />
	},
	heading(children: ReactNode, level: number) {
		switch(level) {
			case 1:
				return <h1 id={children.toString()}>{children}</h1>
			case 2:
				return(
					<h2 id={children.toString()}>
						<span className="underline">{children}</span>
					</h2>
				)
			case 3:
				return <h3 id={children.toString()}>{children}</h3>
			default:
				return <h4 id={children.toString()}>{children}</h4>
		}
	}
};
```

I had to tweak the heading logic a bit since I couldn't template in the heading level.

I import and pass this renderer to the `<Markdown>` component.

```tsx
<Markdown renderer={renderer}>{post.content}</Markdown>
```

With this config I was back to where I was before, but now I have the capability to use React components and TSX/JSX to override elements in the markdown renderer.

## Overriding the code element renderer

The documentation for *marked-react* is lacking, but looking at the Typescript for the `<Markdown>` component's `renderer` prop reveals the syntax. You can override the `code` renderer which is the block level `<code>` element, and the `codespan` renderer which is the inline `<code>` element.

First I needed to find a react component to render code blocks with syntax highlighting. A quick search landed me on [*react-code-blocks*](https://www.npmjs.com/package/react-code-blocks). It seemed popular enough for my needs. And seemed to have the features I wanted. It lets you pass the language for appropriate syntax highlighting, and it has a nice selection of default themes available.

I import the `CodeBlock` component into my *utils/markedUtils.tsx*, along with the *dracula* theme.

```tsx
import { CodeBlock, dracula } from "react-code-blocks";
```

Then in the renderer object, in my *utils/markedUtils.tsx*, I can override the `code` renderer with this new component

```tsx
export const renderer = {
	code(code: ReactNode, lang: string) {
		return <CodeBlock
			text={code.toString()}
			language={lang}
			showLineNumbers={false}
			theme={dracula}
		/>
	},
	// ...
}
```

I'll override the inline `codespan` renderer as well. I'll just apply a class name here as I don't need syntax highlighting for inline code.

```tsx
export const renderer = {
	code(code: ReactNode, lang: string) {
		return <CodeBlock
			text={code.toString()}
			language={lang}
			showLineNumbers={false}
			theme={dracula}
		/>
	},
	codespan(code: ReactNode) {
		return <code className={"inline-code"}>{code}</code>
	}
	// ...
}
```

So my *utils/markedUtils.tsx* looks like this overall:

```tsx
import { ReactNode } from "react";
import { CodeBlock, dracula } from "react-code-blocks";

export const renderer = {
	code(code: ReactNode, lang: string) {
		return <CodeBlock
			text={code.toString()}
			language={lang}
			showLineNumbers={false}
			theme={dracula}
		/>
	},
	codespan(code: ReactNode) {
		return <code className={"inline-code"}>{code}</code>
	},
	image(src: string, alt: string) {
		const nonRelativeHref = "/images/posts/" + src
		return <img src={nonRelativeHref} alt={alt} className="article-image" />
	},
	heading(children: ReactNode, level: number) {
		switch(level) {
			case 1:
				return <h1 id={children.toString()}>{children}</h1>
			case 2:
				return(
					<h2 id={children.toString()}>
						<span className="underline">{children}</span>
					</h2>
				)
			case 3:
				return <h3 id={children.toString()}>{children}</h3>
			default:
				return <h4 id={children.toString()}>{children}</h4>
		}
	}
};
```

This worked pretty well out of the box! I just overrode a few styles to get it matching my overall aesthetic for the site.

```scss
code {
	font-size: 1rem !important;
	font-family: $font-code !important;
	line-height: 1.4rem !important;
	padding: 14px !important;
}

// select the container span that react-code-blocks applies
span:has(code) {
	border-radius: 10px !important;
	box-shadow: 0 2px 10px rgba(black, 0.2);
}

.inline-code {
	background: lighten($color-main-bg, 10%);
	border-radius: 5px;
	padding: 2px 6px !important;
}
```

You can see the code blocks in action in this article! I added a screenshot in case I change the setup later.

![Screenshot of code showing the new syntax highlighting colors on a code sample](markdownsyntaxhighlight2.png)

## Conclusion

Well that's it! I upgraded my markdown renderer to *marked-react* to support JSX/TSX and React components. And I was then able to import and use *react-code-blocks* to render nice code blocks.

I'll probably experiment more with the available themes to see if something else fits my website's aesthetics better, but I'm pretty happy with how it looks. I find the code blocks to be far more readable now.

Thanks for reading 🙏🏻

## Resources

- *marked-react* - [GitHub](https://github.com/sibiraj-s/marked-react) & [NPM](https://www.npmjs.com/package/marked-react?activeTab=readme)
- *react-code-blocks* - [NPM](https://www.npmjs.com/package/react-code-blocks)


![](./static-site-search-optimizing-the-index.jpg)

## Static Site Search Series

This is Part 3 of a series on building a static site search from scratch.

[Part 1 - Preprocessing Articles](https://superflux.dev/blog/static-site-search-preprocessing-articles) walked through building a search index for all my markdown articles using their Title, Tags, and Excerpt as search spaces. The index is a map of all valid search terms and their corresponding article matches.

[Part 2 - Search Component](https://superflux.dev/blog/static-site-search-search-component) walked through creating a React component to use this search index. I used the Ant Design Select component as a base, then performed custom filtering using the search term and the search index. This gave me a simple and fast search experience for my blog. The main downside was the search index ended up being ~700kb for only my 20 articles.

In this part, I'm going to cover some optimizations I made to get that search index from ~700kb to ~22kb (for 20 articles).

## The Issue to solve

With my original implementation of the search index, I was storing the full post title and slug for each matching search term. This was convenient when performing the lookup because the data was right there. The issue is the amount of redundancy in the index. Each post title string and slug string was stored 100s of times.

With 20 posts my search index was ~700kb. That's a big chunk of data to download. And it will grow exponentially with the number of posts since each post adds 100s of entries.

So I had two thoughts to increase the efficiency of the search index. Using unique integer post IDs, and removing unneeded/unlikely search terms.

## Post IDs

Previously my posts didn't need IDs, beyond the unique post slugs. But now there's a nice use case.

First I added unique IDs to each articles metadata. Just simple consecutive & unique numbers counting up from 1.

```text
---
title: Static Site Search Part 1 - Preprocessing Articles
date: April 3, 2024
author: Tyrel Delaney
tags: static-site-generators nextjs javascript typescript search
hero: /images/posts/static-site-search-preprocessing-articles.jpg
excerpt: In this series of articles I discuss how I created a client-side search for my static website. After looking at a few options out there for static sites and Next.js projects, I decided the challenge to build my own search from scratch would be more enjoyable. This first article discusses how I preprocess my articles into a search index.
id: 20
---
```

In my `PostData`/`PostMetadata` DTO I added the `id` field

```typescript
export interface PostMetadata {
	title: string;
	slug: string;
	date: string;
	excerpt: string;
	hero: string;
	tags: string[];
	id: number;                 // <--
	readTimeInMinutes?: number;
}

export interface PostData extends PostMetadata {
	content: string
}
```

Then in my search index preprocessor script, I alter what I'm saving for each search term. Instead of a `{ title: string, slug: string }[]` for each search term I just save the post `id` in an array, a `number[]`.

In my _preprocessors/search-index/search-index.ts_, my `addToIndex` function looks like this

```typescript
const addToIndex = (searchIndex: Map<string, number[]>, key: string, post: PostData) => {
  if (!searchIndex.has(key)) {
    searchIndex.set(key, new Array());
  }
  let found = false;
  for (let item of searchIndex.get(key)) {
    if (item === post.id) {
      found = true;
    }
  }
  if (!found) {
    searchIndex.get(key).push(post.id);
  }
}
```

This change cut the search index size by more than 1/10. From ~700kb down to 62kb.

## Remove ngrams that don't start from the beginning of a token

In my original algorithm I was slicing all possible ngrams of length `n` from each token. For example, when `n = 3` and the token is `typescript`, the ngrams would be `typ`, `ype`, `pes`, `esc`, `scr`, `cri`, `rip`, and `ipt`. This covers a lot of bases for possible partial search terms, but it's very unlikely folks are typing `ipt` and intending to find matches for `typescript`. Its much more likely and common folks are typing the word from the beginning and simply expecting matches on partial words.

The previous implementation looked like this
```typescript
export const createNGrams = (token: string): Set<string> => {
	const n = 10;
	const nGrams: Set<string> = new Set();
	for (let nx = 1; nx <= n; nx++) {
		for (let i = 0; i < token.length - nx + 1; i++) {
			const nGram = token.slice(i, i + nx);
			nGrams.add(nGram);
		}
	};
	if (token.length > n) {
		nGrams.add(token);
	}
	return nGrams;
}
```

I changed it so I'm only saving substrings starting from the beginning of a token

```typescript
export const createNGrams = (token: string): Set<string> => {
	const n = 10;
	const nGrams: Set<string> = new Set();
	for (let nx = 1; nx <= n; nx++) {
		nGrams.add(token.slice(0, nx));      // <--
	};
	if (token.length > n) {
		nGrams.add(token);
	}
	return nGrams;
}
```

This reduced the number of index entries from 4044 to 1449, and further reduced the size of the final JSON from ~62kb to ~22kb.

Great! Now that my search index is a reasonable size, lets refactor my website to use this new index format.

## Importing search index during build time rather than lazy loading during runtime

Now that the search index is so small, I'd like to just fetch it in my build process and bundle it with the server-side rendered pages. Rather than loading it lazily.

This isn't necessary, the small file size gives a big performance boost. But doing it this way feels more in-line with Next static site generation.

### What I need for my search component

Since the search index now just contains the post IDs, I also need a list of posts to reference via their IDs.

So to make this refactor work I need pass the list of `PostMetadata` and the search index to my search component

### getStaticProps

In each of my pages (I have 3: *index.tsx*, *blog/\[slug\].tsx*, and *blog/tags/\[tag\].tsx*) within their `getStaticProps` I need to fetch and return the `PostMetadata[]` and the search index.

The first gotcha I ran into was I was loading the search index from disk and then parsing it back into it's `Map<string, number[]>` type. The issue with this is Next doesn't like returning this type from `getStaticProps` because `Map` isn't serializable (why not? 🤷🏻‍♂️). So instead what I do is just serialize it myself and return it as a `string`.

I created this helper function to fetch the search index from disk:

*utils/searchIndexFileUtils.ts*
```typescript
import fs from "fs";

export const getSearchIndex = (): Map<string, number[]> => {
	const searchIndexFilePath = "public/search-index.json";
	const searchIndexFile = fs.readFileSync(searchIndexFilePath, "utf-8");
	const searchIndexMap = new Map<string, number[]>();
	const searchIndexJson = JSON.parse(searchIndexFile);
	for (const key of Object.keys(searchIndexJson)) {
		searchIndexMap.set(key, searchIndexJson[key]);
	}
	return searchIndexMap;
}
```

I then also created these functions to convert this to and from JSON. I put these in a separate file from `getSearchIndex` because I wanted to be able to use them client-side and the `import fs from "fs"` would cause issues with that.

*utils/searchIndexUtils.ts*
```typescript
export const searchIndexToJson = (map: Map<string, number[]>): string => {
	const obj = Array.from(map.entries());
	return JSON.stringify(obj);
}

export const jsonToSearchIndex = (jsonStr: string): Map<string, number[]> => {
	const entries = JSON.parse(jsonStr) as [string, number[]][];
	return new Map(entries);
}
```

Then in each page, I refactored `getStaticProps` to fetch the `PostMetadata[]` and the search index. Here's the example from my *index.tsx* page:

```typescript
export const getStaticProps: GetStaticProps = async (
	context
): Promise<GetStaticPropsResult<{posts: PostMetadata[], searchIndexJson: string }>> => {
	const searchIndex = getSearchIndex();
	const searchIndexJson = searchIndexToJson(searchIndex);
	const postMetadataList: PostMetadata[] = getPostMetaData();
	return {
		props: {
			posts: postMetadataList.sort(sortPostsByDate),
			searchIndexJson
		},
	};
};
```

Make sure to also modify the corresponding props for the page component to handle the new props type. In this case it's `{ posts: PostMetadata[], searchIndexJson: string }`.

## Refactoring Search Component

Next I needed to add these values as props to my search component. Originally it was importing the search index itself within a `useEffect`. Now instead I want to pass the search index along with the posts metadata list in through props.

I add these values as props to my `SearchInput` component

*components/elements/SearchInput.tsx*
```tsx
export interface Props {
	searchIndexJson: string;
	postMetadataList: PostMetadata[];
}

export default function SearchInput(props: Props) {
	// ...
}
```

In the component's `useEffect`, I removed the logic I had to lazy load the search index from disk, and replaced it with some simple logic to deserialize the search index from json.

```tsx
useEffect(() => {
	if (!searchIndex.size) {
		setSearchIndex(jsonToSearchIndex(props.searchIndexJson));
	}

	// ...
})

```

Then in my `onChange` function, where I'm doing the work to convert the search term to an options list to display as the search results, instead of directly pulling the post title and slug from the search index I pull the post ID from the search index and then find that post's metadata in `props.postMetadataList`. Reference [my previous article on the Search Component](https://superflux.dev/blog/static-site-search-search-component) to see more details, but the relevant change is:

```tsx
const onChange = (searchTerm: string) => {

	// ...

	if (searchIndex.size && searchIndex.has(searchTerm)) {
		const newOptions = new Array<OptionValue>();
		for (const id of searchIndex.get(searchTerm)) {
			const postMetadata: PostMetadata = getPostMetadataById(id, props.postMetadataList);
			newOptions.push({
				value: postMetadata.slug,
				label: postMetadata.title
			});
		}
		setOptions(newOptions);
	} else {
		setOptions([]);
	}
	
}
```

That `getPostMetadataById` function is just doing a simple find right now. Perhaps in the future I'll refactor that `PostMetadata[]` into something more efficient so I can do a quick lookup by ID.

```typescript
export const getPostMetadataById = (id: number, postMetadataList: PostMetadata[]): PostMetadata => {
	return postMetadataList.find((post) => post.id === id);
}
```

## Conclusion

Ok great! I've cut the size of the search index down from ~700kb to ~22kb. I'm pulling my PostMetadata list into more places than before, but it's much smaller than the search index so say overall the data load per page is ~25kb. Huge improvement.

The search is maybe slightly slower than before, because I'm not just doing a simple Map lookup on the search term anymore. But we're talking like ~1ms or less, so it's not even noticeable. 

In the future, as my number of posts grow, I think I'd like to refactor the `PostMetadata[]` to be a Map on the post IDs instead. Something like `Map<number, PostMetadata>`. That would allow for quick lookup of both the search term results from the search index, and a quick lookup of the corresponding PostMetadata for each search result.

I'll leave it here for now. Thanks for reading, and I hope you found some value in this static site search series. Remember to visit [Part 1](https://superflux.dev/blog/static-site-search-preprocessing-articles) & [2](https://superflux.dev/blog/static-site-search-search-component) to see the my original implementation this refactor is building on.


![](./static-site-search-search-component.jpg)

## Static Site Search Series

In [my previous article on this topic](https://superflux.dev/blog/static-site-search-preprocessing-articles), I talked about preprocessing my articles and creating a search index. This search index allows for quick referencing the articles that match a particular search term.

In this article I'm going to talk about how I used this search index to perform searches.

## Desired Behaviour

I wanted a couple things from my search. I wanted it to display results in real-time as you searched, and I didn't want to implement any kind of search results page. I wanted it to just be intuitive and quick.

## Search Component

I use [Ant Design](https://ant.design) a bit on this site. It's just a library I'm familiar with.

They offer a component that they call [Select with Search](https://ant.design/components/select#select-demo-search). It's essentially a multi-select dropdown that lets you filter the options by typing into a text input.

By default, you provide it a list of options, and then the search will filter those options. You can customize the callbacks for both when an item is clicked or you press return, and the search callback that occurs whenever the input changes.

This was close enough to what I wanted and I'll describe how I customized it.

I started by making a wrapper around the Ant Design Select component so I can easily customize it and then stick it wherever I need to.

It started off something like this

*components/elements/SearchInput.tsx*
```tsx
import React from "react";
import { Select } from 'antd';

export default function SearchInput(props) {
	return (
		<Select
		    showSearch
		    placeholder="Select a person"
		    optionFilterProp="children"
		    options={[
			  {
				value: 'jack',
				label: 'Jack',
			  },
			  {
				value: 'lucy',
				label: 'Lucy',
			  }
		    ]}
		/>
	)
}
```

To more easily type the `options`, I created a little `OptionsValue` interface at the top of the file:

```tsx
interface OptionValue {
	label: string;
	value: string;
}
```

## Loading the Search Index

I'm doing this a very sketchy way, I think. I'm really not a frontend developer so I kinda just made this up as I went.

My plan is eventually to slim down the index enough that I can just build it in with the rest of my static site, but for now since it's 600+ KB I tried to lazy load it to not mess with the initial page load.

Essentially I'm just loading the file in a `useEffect` and setting it into the component state.

*components/elements/SearchInput.tsx*
```tsx
export default function SearchInput(props) {
	const [searchIndex, setSearchIndex] = useState<Map<string, object>>(new Map());

	useEffect(() => {
		if (!searchIndex) {
			import("./search-index.json")
				.then((data) => {
					const indexMap = new Map<string, object>();
					for (const key of Object.keys(data)) {
						indexMap.set(key, data[key]);
					}
					setSearchIndex(indexMap);
				})
				.catch((error) => {
					console.error("Error loading search index", error);
				})
		}
	}, []);

	return (
		<Select
		    showSearch
		    placeholder="Select a person"
		    optionFilterProp="children"
		    options={[
			  {
				value: 'jack',
				label: 'Jack',
			  },
			  {
				value: 'lucy',
				label: 'Lucy',
			  }
		    ]}
		/>
	)
}
```

## Options

So I could have just provided a list of the article titles to this component and called it a day. I wouldn't have had to bother with all the preprocessing and indexing. But that would only have let me search the titles, not the tags and the excerpts.

With my search index I get a lot more nuance. For example if you search "docker" you get 1 result which is my post titled "What I'm Learning in 2022", which just wouldn't work with a simple title search.

First I initialize an empty options array in component state

```tsx
const [options, setOptions] = useState<OptionValue[]>([]);
```

Then I pass this to the `Select` component

```tsx
<Select
	showSearch
	placeholder="Search"
	suffixIcon={<SearchOutlined />} // Custom Ant icon to show in the right of the input field
	options={options}
/>
```

Great! So now I have my search index available, and I can now implement my custom search functionality using the index.

## onSearch

The Select component from Ant Design has an overridable `onSearch` function. I'm going to override this function and use the current search term to populate the `options` using the values from the `searchIndex`.

A couple things I do in this code:

- I check to make sure I'm not repeating the same searches. Not sure how necessary this is or not, I don't remember. This uses a `useRef` on the component to track the search iterations and a `useState` to track the previous search term.
- I check for empty string search terms and simply set an empty list in the `options`, no need to check the search index.
- I was doing some stuff with lodash `debounce` and `useMemo` to delay the search, but I'm not sure if this is necessary. I'll show it afterwards as optional.

After those checks, I imply lowercase the search term and then pull the value from the `searchIndex`.

If the search term doesn't exist as a key in the `searchIndex` I simply set an empty array in `options`.

If the search term does exist, then I pull the values from the `searchIndex` for that key, I convert the `{ title: string, slug: string }` into a `{ value: string, label: string }` where `value` = `slug` and `label` = `title`. I build a new options array of all the values from that search term and then set that new array into `options` component state.

When that `options` component state gets set, the component then re-renders showing the new options.

Here's the code for this `onSearch` handler

```tsx
const [searchIndex, setSearchIndex] = useState<Map<string, object>>(new Map());
const [options, setOptions] = useState<OptionValue[]>([]);
const fetchRef = useRef(0);
const [previousSearchTerm, setPreviousSearchTerm] = useState<string>("");

const onChange = (searchTerm: string) => {
	fetchRef.current += 1
	const currentFetch = fetchRef.current;
	if (currentFetch !== fetchRef.current) {
		return;
	}
	if (searchTerm.length < 1) {
		setOptions([]);
		return;
	}
	searchTerm = searchTerm.toLowerCase();
	if (searchTerm === previousSearchTerm) {
		return;
	}
	setPreviousSearchTerm(searchTerm);

	if (searchIndex.entries() && searchIndex.has(searchTerm)) {
		const newOptions = new Array<OptionValue>();
		for (const item of searchIndex.get(searchTerm) as { title: string, slug: string}[]) {
			newOptions.push({
				value: item.slug,
				label: item.title
			})
		}
		setOptions(newOptions);
	}
}
```

Then on the `Select` component I pass a few more props.

- I set `filterOption={false}`. This essentially disables the built-in filtering using the search term and the labels. I don't need it to filter the results because I'm filtering the `options` myself.
- I pass a reference to my `onSearch` function in the `onSearch` prop.
- I pass a simple sort function in the `filterSort` prop to organize the options alphabetically.
- I pass `notFoundContent={null}` to get rid of the default empty state when no search results are found. This just hides the results pane when empty. Could maybe do some nicer customization here.

The component looks something like this:

```tsx
<Select
	showSearch
	filterOption={false}
	onSearch={onSearch}
	placeholder="Search"
	suffixIcon={<SearchOutlined />}
	filterSort={(a: OptionValue, b: OptionValue) => (a?.label ?? "").toLowerCase().localeCompare((b?.label ?? "").toLowerCase())}
	notFoundContent={null}
	options={options}
/>
```

![](./static-site-search-component-screenshot.png)

## Navigate to the selected page

Lastly, we want to actually navigate to the corresponding page if a value in the search is clicked.

We can pass a `onSelect` prop that handles this. In this function I simply use the `value` from the selected option which is the `slug` of the post, and Next `useRouter` to navigate to that page.

The function is as simple as this:

```tsx
const router = useRouter();

const navigateToArticle = (value: string) => {
	router.push(`/blog/${value}`);
}
```

And thats it! I won't touch on styling or how I placed this component on my website. You can see that for yourself! Also the styling is going to be unique for your project if you're looking to replicate this.

The final code for my customized component looks like this

*components/elements/SearchInput.tsx*
```tsx
import React, { useEffect, useState, useRef } from "react";
import { Select } from 'antd';
import { SearchOutlined } from '@ant-design/icons';
import { useRouter } from 'next/navigation'

interface OptionValue {
	label: string;
	value: string;
}

export default function SearchInput() {
	const router = useRouter();
	
	const [searchIndex, setSearchIndex] = useState<Map<string, object>>(new Map());
	const [options, setOptions] = useState<OptionValue[]>([]);
	const fetchRef = useRef(0);
	const [previousSearchTerm, setPreviousSearchTerm] = useState<string>("");
	
	const onChange = (searchTerm: string) => {
		fetchRef.current += 1
		const currentFetch = fetchRef.current;
		if (currentFetch !== fetchRef.current) {
			return;
		}
		if (searchTerm.length < 1) {
			setOptions([]);
			return;
		}
		searchTerm = searchTerm.toLowerCase();
		if (searchTerm === previousSearchTerm) {
			return;
		}
		setPreviousSearchTerm(searchTerm);
	
		if (searchIndex.entries() && searchIndex.has(searchTerm)) {
			const newOptions = new Array<OptionValue>();
			for (const item of searchIndex.get(searchTerm) as { title: string, slug: string}[]) {
				newOptions.push({
					value: item.slug,
					label: item.title
				})
			}
			setOptions(newOptions);
		}
	}

	const navigateToArticle = (value: string) => {
		router.push(`/blog/${value}`);
	}

	useEffect(() => {
		if (!searchIndex) {
			import("./search-index.json")
				.then((data) => {
					const indexMap = new Map<string, object>();
					for (const key of Object.keys(data)) {
						indexMap.set(key, data[key]);
					}
					setSearchIndex(indexMap);
				})
				.catch((error) => {
					console.error("Error loading search index", error);
				})
		}
	}, []);

	return (
		<Select
			showSearch
			filterOption={false}
			onSearch={onSearch}
			onSelect={navigateToArticle}
			placeholder="Search"
			suffixIcon={<SearchOutlined />}
			filterSort={(a: OptionValue, b: OptionValue) => (a?.label ?? "").toLowerCase().localeCompare((b?.label ?? "").toLowerCase())}
			notFoundContent={null}
			options={options}
		/>
	)
}
```

## Add delay to the search

If your running into some issues with your search firing multiple times, or you'd just like to add a delay for aesthetics, you can use `useMemo` and lodash `debounce`. Simply wrap your `onChange` function in the following

```tsx
const onChange = useMemo(() => {
	const getItems = (searchTerm: string) => {
		// your logic for filtering the options
	}
	return debounce(getItems, 50); // delay in ms
}, [searchIndex])
```

## Resources

- [Ant Design Select component](https://ant.design/components/select)

## Repository

This website in it's entirety is viewable on [GitHub](https://github.com/tyrelh/personal-site-nextjs).

The search logic doesn't have it's own repo yet. But I'll update that here if I ever split it out.

## Conclusion

I think this turned out really well. It works great and really only took a couple of days to figure out end-to-end. It was a pretty interesting and fun project too.

I was going to call this "Next.js Static Site Search", but in the end with this solution it really has nothing to do with Next. You should be able to incorporate this into any statically generated site, particularly those using Markdown and React, although you should be able to adapt it to other stacks as well.

This is working quite well for me in it's current state, but there are lots of optimizations to be made. If I get around to those I'll post a third part to this series explaining the optimizations I implemented.

Thanks for reading!


This article was written around July 2023.

If you'd like to learn how to deploy a static site using Next.js to GitHub Pages, [check out a previous article of mine on the topic](https://superflux.dev/blog/github-pages-using-nextjs).

This functionality for my website was heavily inspired by [Bionic Julia's post on the same topic](https://dev.to/bionicjulia/creating-dynamic-tag-pages-with-nextjs-nested-routes-nah).

![black next js logo on a plain white background](next-js-logo.png)

## Tl;dr
- [Goal](#goal): To make tag pages that filter my articles by a tag
- [Get tags from posts](#get-tags-from-posts): First step is to collate all the unique tags from my markdown article files.
- [Build the pages for tags](#build-the-pages-for-tags)
	- [getStaticPaths](#getstaticpaths): Get the unique list of tags to build the routes for.
	- [getStaticProps](#getstaticprops): For each tag, get the filtered list of posts.
	- [Tags page template](#tags-page-template): Render the filtered list of posts on a new page.
- [Link to tag pages](#link-to-tag-pages): I altered my hashtag component to link to the appropriate tag route.
- [Small gotcha](#small-gotcha): Need to strip some character from tags since they need to be URL safe now.
- [Conclusion](#conclusion)
- [Resources](#resources)

## Goal

My goal with this project was to make the tags I'm already displaying alongside articles to be clickable links that filter my posts by that tag.

My markdown posts already contain metadata that includes tags, so luckily I don't need to go back and tag all my posts.

## Get tags from posts

The first step is to get a list of the tags from our posts. This is so we can build the pages for each.

I built a function to read the tags from all my post markdown files. The tags are contained in their frontmatter. I use a `Set` to only get the unique tags with no duplicates.

```tsx
import { PostData } from "../dtos/PostData";

export const getTagsFromPostDataList = (postData: PostData[]): string[] => {
  const tags = new Set<string>(); // Set forces only unique tags
  postData.forEach(function (postDatum) {
    postDatum.tags.forEach(function (tag) {
      tags.add(tag);
    });
  }); 
  return Array.from(tags);
}
```

And I get the posts using an existing method that reads the posts from the files system, and parses the markdown and frontmatter from them into a list of custom `PostData` objects.

```tsx
import matter from "gray-matter";
import fs from "fs";
import path from "path";
import { PostData } from "../dtos/PostData";
import { calculateReadTimeOfText } from "./textUtils";

export const getPostData = (): PostData[] => {
  const files = fs.readdirSync(path.join("posts"));
  const postDataList: PostData[] = files.map((filename) => {
    const slug = filename.replace(".md", "");
    const markdownWithMeta = fs.readFileSync(
      path.join("posts", filename),
      "utf-8"
    );
    const { data: frontmatter, content } = matter(markdownWithMeta);
    const readTimeInMinutes = calculateReadTimeOfText(content);
    const postData: PostData = {
      title: frontmatter?.title,
      slug: slug,
      date: frontmatter?.date,
      hero: frontmatter?.hero,
      excerpt: frontmatter?.excerpt,
      tags: frontmatter?.tags ? frontmatter.tags.split(" ") : null,
      readTimeInMinutes: readTimeInMinutes,
      content: content
    };
    return postData;
  });
  return postDataList
}
```

Ok, so now I have a list of all the unique tags. Now what?

## Build the pages for tags

I wanted to have the tag pages follow the */blog/tags/\<tag\>* URL scheme. So I created a *tags* folder nested in */pages/blog* and created a new file named *\[tag\].tsx*. The square brackets mean this is a template file for the tag page. There will be a page generated for each unique tag.

[Next.js docs on Dynamic Routes](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes)

### getStaticPaths

Within the tag template we need two methods. `getStaticPaths` will gather a list of all the paths that need to be generated. In this case it's a list of all the unique tags since they'll be used in the url path for each tag page in the format */blog/tags/\<tag\>*.

```tsx
export const getStaticPaths: GetStaticPaths = async (context): Promise<GetStaticPathsResult> => {
  const postData: PostData[] = getPostData();
  const tags = getTagsFromPostDataList(postData);
  const paths = tags.map((tag: string) => ({
    params: { tag }
  }));
  return {
    paths: paths,
    fallback: false
  };
};
```

I use the functions I defined above to pull the unique tags from my markdown articles and generate the paths.

[Next.js docs on *getStaticPaths*](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-paths)

### getStaticProps

Next is `getStaticProps`. This function gathers the props that are passed to each tag page to render. In this case we want to pass a list of the articles that have a given tag which comes in through `params`.

I use the same function again to get all the post data, then I filter the posts to only the sunset that have the given tag.

```tsx
export async function getStaticProps({ params }: Params) {
  const postDataList: PostData[] = getPostData();
  const postsForTag: PostData[] = postDataList.filter((post: PostData) => 
    post.tags.includes(params.tag)
  );
  return {
    props: {
      tag: params.tag,
      postsForTag: postsForTag.sort(sortPostsByDate)
    },
  }
}
```

When returning the subset of posts I also make sure they're sorted by date so that I can render them in decending order on the tag page.

[Next.js docs on *getStaticProps*](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props)

### Tags page template

The last thing to do is build the template for the tag page itself. This was extremely simple as I was able to reuse components I already had.

I have a `ArticlePreviewList` component from the homepage that generates a list of previews for a given list of post data. Other than that there are some headings and misc.

```tsx
export default function TagPage({tag, postsForTag}) {
  return (
    <>
      <HeadW title="superflux" />
      <StickyHeader title={tag} path={["blog","tags"]}/>
      <SectionHeading>
        #{tag}
      </SectionHeading>
      <ArticlePreviewList articleMetadataList={postsForTag} />
      <SectionHeading>
        Get in touch
      </SectionHeading>
      <p>
        Feel free to contact me via <Anchor href="https://twitter.com/tyreldelaney">Twitter</Anchor>!
      </p>
    </>
  );
}
```

And that's it! With those few pieces Next.js will handle the rest for us. During the build step it will generate all the pages on all the routes for each tag.

![](tag-page-screenshot.png)

## Link to tag pages

One last piece is to make it easy to navigate to these new pages. I already had a visual tag component I was using within the article previews, just for informational purposes.

I created a new Hashtag component that wraps Ant Design's Tag component. So now I can apply a Next `Link` within that. I also have a custom `Anchor` component that obfuscates the Next `Link` away. Since it's a hashtag component I can hard code the route with just the tag prop itself being the final portion of the route.

```tsx
import { Tag } from "antd"
import Anchor from "./Anchor"

export interface Props {
  tag: string
}

export default function Hashtag(props: Props) {
  return (
    <Anchor key={props.tag} href={`/blog/tags/${props.tag}`}>
      <Tag key={props.tag}>#{props.tag}</Tag>
    </Anchor>
  )
}
```

## Small gotcha

One small issue I ran into is one tag I was using contained a `/` character, `ci/cd`. This wasn't a very forward thinking decision on my part.

I just needed to search through my articles and remove the `/` character from that tag, making it just `cicd`. Much simpler than trying to code for it.

## Conclusion

I've had tags on my posts for some time now, but this functionality makes them much more useful. Clicking a tag now brings you to a page that contains articles curated by that tag.

It's basic functionality, but it's still rewarding to build it yourself.

## Resources

- [Creating Dynamic Tag Pages With NextJS Nested Routes](https://bionicjulia.com/blog/creating-dynamic-tag-page-nextjs-nested-routes) 
- [Next.js docs on Dynamic Routes](https://nextjs.org/docs/pages/building-your-application/routing/dynamic-routes)
- [Next.js docs on *getStaticPaths*](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-paths)
- [Next.js docs on *getStaticProps*](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-static-props)

Let's say you've built an nice new static site using Next.js and you want to host it on GitHub Pages. Well there's a few steps to get it working, but it isn't too hard.

![next js logo and github logo](./NextJSGitHubPagesHero.png)

This article assumes you already have a website built locally and you're just looking to host it on [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages). In the future I may write some how-tos for creating a blog using markdown and Next.js.

In this example I'm going to outline how I deploy to my main GitHub Pages repo for [superflux.dev](https://superflux.dev). It's hosted in my GitHub account's [main Pages repository](https://github.com/tyrelh/tyrelh.github.io). Everyone has access to this special repo. Just create a new repo with the title _your-github-username.github.io_. GitHub will serve the static content there on your own subdomain `https://your-github-username.github.io`. You can even connect a custom domain like I did, I'll talk about that optionally at the end.

You can also use this tutorial to push repo-specific pages. Google for that if your unfamiliar.

## Tl;dr

* [Static content](#static-content): A quick overview of how to build static assets for a Next.js site.
* [Install gh-pages package](#install-gh-pages-package): There's a lovely NPM package that makes it very simple to deploy static assets to GitHub Pages.
* [Branch setup](#branch-setup): I use two repositories on GitHub, one for my source code and one that is the Pages repository that gets hosted under your username.
* [Deploy script](#deploy-script): The deploy script uses the *gh-pages* package.
	* [Static content directory](#static-content-directory): Set the *out* directory in the deploy script that Next.js outputs static assets to when building and exporting.
	* [Remote & branch](#remote--branch): Set the remote and the branch that you want *gh-pages* to push your static assets to.
	* [Force push to remote](#force-push-to-remote): Allow the deploy script to force-push changes to your GitHub Pages repo.
	* [\_next hidden folder](#_next-hidden-folder): Some tweaks to make GitHub Pages play nicely with Next.js
* [\[Optional\] Configure a custom domain](#optional-configure-a-custom-domain): Allow a GitHub Pages site to be served over a custom domain name.
* [Resources](#resources)
* [Conclusion](#conclusion)

## Static content

GitHub Pages can only serve static content. You need to be able to export your Next.js project to static code. You can do this by running

```shell
next build && next export
```

`next export` will export the static code for your project to the _out/_ directory. This is the code we're going to want to host on GitHub Pages.

To simplify and make it easy to remember I added this as a `build` script in my *package.json*. Add/edit the `build` script:

```json
"build": "next build && next export"
```

## Install gh-pages package

I've used this package in the past and it works well for GitHub Pages websites. *[gh-pages](https://github.com/tschaub/gh-pages)* is a simple little tool that makes it easy to push projects to GitHub Pages repos or branches.

```shell
npm install gh-pages --save-dev
```

## Branch setup

I store my website source in a separate repository, in my case a repo called [personal-site-nextjs](https://github.com/tyrelh/personal-site-nextjs). By default *gh-pages* will deploy your static site to the `origin` remote. But we can change that. I like to keep the `origin` for my source repo pointing to the source remote.

* `personal-site-nextjs`: repo containing the source code for my website. I do development here
* `tyrelh.github.io`: my main GitHub Pages repo. This is were the compiled static assets are served from

You can also just use separate branches in the same GitHub Pages repository if you prefer. One for the source and one for the public assets. That feels messy to me so I prefer to keep them separate.

## Deploy script

Next we'll setup a deploy script in our _package.json_ to deploy our static content!

In your _package.json_ create a new script. Remember it should be on the same level as the other scripts, in the `"scripts"` block:

```json
"deploy": "gh-pages"
```

Now this by itself wont work yet, but I'm going to step you through each additional step to get the `gh-pages` command working. If you want to [skip to the end and just see the final script](#conclusion), go ahead!

### Static content directory

First you want to tell it what directory that your static assets are in. Remember this is the directory that `next export` in your `build` script outputs to. By default this is the _out/_ directory in your project. Make sure you run your build script first so that your static files are here.

Use the `-d` flag to set the directory.

```json
"deploy": "gh-pages -d out
```

### Remote & branch

We want to make sure `gh-pages` knows where it should push our static code to for hosting. It's good to set this up first so you don't accidentally push code somewhere you don't intend to.

For the `gh-pages` command, you can use the `-b` flag to tell it the remote branch you want to push to. Whatever the default branch of your _username.github.io_ repo is will work. `main` or `master` for example.

```json
"deploy": "gh-pages -d out -b main"
```

Next you'll want to set the remote. I like to hard code this in the script itself. Since it's going to be static for this project I don't see any reason not to. You can use the `-r` flag to set a remote URL. Copy the remote URL from your _username.github.io_ repo.

```json
"deploy": "gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git"
```

### Force Push to Remote

When deploying new static content to your GitHub Pages repo, generally you're going to want to overwrite what is there. At least this is the simplest way to do it. Before setting this just double check that your branch and remote are set correctly. You don't want to overwrite anything you don't intend to!

Use the `-f` flag to force the push to the remote, overwriting files and changes that may exist on the remote.

```json
"deploy": "gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git -f"
```

Ok! We're almost there! If this was a Jekyll project, or maybe a standard React project this would probably be all you need. But since we're using Next.js there is one more piece of config we need to do.

### \_next Hidden Folder

In your _out/_ directory of static assets, you should see a folder called _\_next/_. This is where Next.js puts your compiled JavaScript and CSS.

By default, GitHub pages actually ignores folders beginning with a \_. This is because GitHub Pages is setup to use Jekyll. Jekyll considers folders beginning with \_ to be hidden folders, so GitHub Pages just doesn't serve them.

You can deploy the code as is, and it will look like it worked since you can see the _\_next/_ directory in you _username.github.io_ repo. But any requests to those assets when you visit your website will result in a 404 not found error.

To fix this you need to add a file named _.nojekyll_ to the root of your _username.github.io_ repo. You can do this right on the GitHub website to test it out. Once that file is there and you give it a couple minutes to take effect, your website should work without 404 errors!

But now if you deploy your static code again that file will get erased, breaking your website. We need to incorporate this file into our deploy or build scripts. I put it at the beginning of my deploy script, but you could also put it at the end of your build script too if that makes more sense to you.

We want to create that `.nojekyll` file in our _out/_ directory after our code is built, but before we deploy it using `gh-pages`.

At the beginning of your deploy script, add an `echo` command to create the file. The file can contain anything, I just echo the string `true`. Use the `&&` between the `echo` and `gh-pages` commands so that they will run sequentially.

```json
"deploy": "echo 'true' > ./out/.nojekyll && gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git -f"
```

This wont quite work, because by default `gh-pages` ignores hidden dotfiles! To tell `gh-pages` you want to include dotfiles (that's files beginning with a .), use the `-t` flag on the `gh-pages` command.

```json
"deploy": "echo 'true' > ./out/.nojekyll && gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git -f -t"
```

And that's basically it!

## Configure your repo for GitHub Pages

You'll need to make sure your repo is configured for Pages. Go to your repo, click on the repo _Settings_, and click _Pages_ on the settings side bar. See the [GitHub Pages docs](https://docs.github.com/en/pages/getting-started-with-github-pages) for more general info about hosting static content.

## \[Optional\] Configure a custom domain

After you follow the [instructions here](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site) to setup your custom domain with your GitHub Pages website, you'll notice that you need a _CNAME_ file in the root of your repo for the domain to map correctly.

Since our deploy process overwrites all the files in our GitHub Pages repo on each deploy, we need to add this file to our deploy/build process so it will be included each time. This is similar to what we needed to do for the _.nojekyll_ file.

At the beginning of your deploy script, add another `echo` command. You want to output the root domain for your website to a file called _CNAME_. In my case my root domain is `superflux.dev`.

```json
"deploy": "echo 'superflux.dev' > ./out/CNAME && echo 'true' > ./out/.nojekyll && gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git -f -t"
```

Make sure to include the `&&` between each command so they run sequentially!

## Resources

* Allow the _\_next_ folder to get picked up in repo: https://github.blog/2009-12-29-bypassing-jekyll-on-github-pages/
* `gh-pages` package to easily deploy to GitHub Pages repositories: https://github.com/tschaub/gh-pages
* GitHub Pages docs: https://docs.github.com/en/pages/getting-started-with-github-pages
* GitHub Pages custom domain docs: https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site

## Conclusion

And now that's it! To summarize we built a deploy script in our _package.json_ that looks like this

```json
"deploy": "echo 'true' > ./out/.nojekyll && gh-pages -d out -b main -r https://github.com/tyrelh/tyrelh.github.io.git -f -t"
```

You'll want to make sure your `-b` branch is pointing to the branch being served on your GitHub Pages repo, and that the `-r` remote is the URL of your GitHub Pages repo.

After building your website locally just run `npm run deploy` to push your static code to your GitHub Pages site! Remember the `gh-pages` package uses _git_ to push code to the remotes, so you'll need to configure your username, email, and credentials to authenticate the push to your GitHub Pages repo.

Reach out to me on Twitter [@tyreldelaney](https://twitter.com/tyreldelaney) if you have any questions, comments, or suggestions!

*Note: this article was written in April 2022. It sat for a while in my queue of articles as we were gearing up to have our first child. Hopefully nothing has changed drastically with Next.js and GitHub Pages that renders this info unusable.*


I developed a dark and light theme for this site and built a toggle to switch between them. Also I used media queries to set the default theme to match the visitors operating system choice.

![Sun and moon icons](DarkModeToggle-1.svg)

## Tl;dr
* [Introduction](#introduction): I am dark mode obsessed. Every app I use I attempt to make it dark themed. 😎
* [Theme Switch](#theme-switch): I built a switch to allow a visitor to toggle between light and dark theme.
* [Styles](#styles): I nested the styles for both light and dark theme together. You may want to separate them so that you can selectively download.
* [Media Query](#media-query): You can set the theme based on the visitor's operating system choice!
* [React Component](#react-component): Bundling everything up into a nice component.
* [Github Repo](#github-repo): You can roll your own dark theme using my toggle.

## Introduction
I've been obsessed with dark themes for a while now. To the point were I will essentially boycott an app or service if I cannot find a way to theme it dark. Just the thought of staring into a blinding white screen is giving me a headache right now.

Ever since a very early iteration I have had my personal website styled with a dark theme. But as I get further into my career as a software developer the thought that anyone but myself might actually look at my website is a looming fear. Is it ready for that? Perhaps in software development this may be skewed just a bit but I think in general people prefer the more expected light colours of the internet. Google is light, Amazon is light, nothing popular is dark.

## Theme Switch
I decided to implement a theme switch. After reading a bit into how others accomplished this it turned out to be quite simple. The hard part is actually designing a light theme for my site.

Essentially all you need to do is create a toggle, checkbox, or button that will apply or remove a class from the HTML `body`. Depending on how your site (or app) is designed you could apply this class to some other parent component, but since I was using the body background I decided to just use the body.

I built a button based toggle switch. The onClick method will do

```javascript
document.body.classList.toggle("dark-mode");
```

## Styles
Now, in your CSS, whatever styles you want overridden when this theme is toggled just add the `dark-mode` class selector.

For example

```css
body {
  background-color: #fff;
  color: #222;
}

body.dark-mode {
  background-color: #333;
  color: #eee;
}
```

or some SCSS

```scss
h1 {
  color: #222;
}

.dark-mode {
  h1 {
    color: #eee;
  }
}
```

I prefer having the dark and light styles right next to each other in the file, but some might notice that you are always downloading both styles even if only one is being used. Maybe if I ever decide to separate them I'll write another article about how that worked.

## Media Query
A piece of functionality I really wanted was rather than choosing light or dark as the default for everyone and forcing them to press the switch I wanted to default to their OS theme choice. MacOS, Windows 10, iOS, and Android all have dark-mode support so wouldn't it be nice if you could just set the theme based on that? You can!

```css
@media (prefers-color-scheme: dark) {
  // styles
}
```

You can query for either `dark` or `light`. You can use this media query directly in your styles to make your site completely reactive to the user OS choice. The issue with that is that it greatly complicates being able to switch between the themes.

I opted to just write my styles around the theme class I created for `body`. Then in my javascript I use the media query to set the initial mode of my switch component.

```javascript
componentDidMount() {
  const userPrefersDarkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
  if (!userPrefersDarkMode && !this.state.darkMode) {
    this.themeToggleOnClick()
  }
}
```

If your default theme is light, this `componentDidMount` will automatically switch it to dark on page load if the user has their OS set to dark.

## React Component
Since I a working in React I bundled the logic and layout for the switch into a `ThemeToggle` component. I personally used the Icon and Tooltip components from the [Ant Design](https://ant.design) library to simplify a few things and provide a nice tooltip if someone doesnt understand what the icon represents.

```jsx
import React from "react";
import "./themeToggle.scss";
import { Tooltip, Icon } from "antd";

export default class ThemeToggle extends React.Component {

  constructor(props) {
    super(props);
    this.state = {
      lightMode: false
    };
  }
  
  componentDidMount() {
    const userPrefersDarkMode = window.matchMedia("(prefers-color-scheme: dark)").matches;
    if (!userPrefersDarkMode && !this.state.lightMode) {
      this.toggleTheme()
    }
  }

  toggleTheme = async () => {
    await this.setState({
      lightMode: !this.state.lightMode
    });
    document.body.classList.toggle("light-mode");
  };

  MoonSvg = () => {
    return (
      <svg className="toggle-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 30 30">
        <path className="moon-icon"/> // EXCLUDED SVG PATH FOR BREVITY
      </svg>
    )
  };

  SunSvg = () => {
    return (
      <svg className="toggle-icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
        <path className="sun-icon"/> // EXCLUDED SVG PATH FOR BREVITY
      </svg>
    )
  };

  render() {
    return (
      <Tooltip
        title={`Toggle ${!this.state.lightMode ? "Light" : "Dark"} Mode`}
        placement="bottomRight"
        arrowPointAtCenter
        mouseEnterDelay={0.2}
      >
        <div className="toggle-container">
        {
          (this.state.lightMode) ?
            <Icon component={this.MoonSvg} onClick={this.toggleTheme} />
            :
            <Icon component={this.SunSvg} onClick={this.toggleTheme} />
        }
        </div>
      </Tooltip>
    );
  }
}
```

And here are the styles I used for this button

```scss
@import "../../colors.scss";

.toggle-container {
  width: 60px;
  height: 60px;
  font-size: 40px;
  line-height: 66px;
  top: 16px;
  right: 21px;
  position: fixed;
  z-index: 3;
  border-radius: 30px;
  background-color: rgba($color-main-bg, 0.9);
  text-align: center;

  @media (min-width: 375px) and (max-width: 812px) {
    line-height: 64px;
  }

  .toggle-icon {
    width: 1em;
    height: 1em;

    .sun-icon {
      fill: $color-main-text;
    }

    .moon-icon {
      fill: $color-main-text-light-theme;
    }
  }
}

.light-mode {
  .toggle-container {
    background-color: rgba($color-main-bg-light-theme, 0.9);
  }
}
```

You can see I ended up also storing the toggle state in the component state. That way I can easily conditionally switch between the sun and moon icon.

Also switched things around a bit. For my website I still treat the dark theme as default and the light theme as the exception. Therefore I am tracking the state as lightTheme = true/false rather than darkTheme. Same thing, just do whatever works best in your brain.

## Github Repo
In addition to the source here which is specific to my implementation and also uses Ant Design I have posted a [Github repository](https://github.com/tyrelh/dark-mode-react-toggle) with a more generic React component that lets you have theme switch.

All you need to do is include the component and then create your own styles for a dark theme nested within a `.dark-theme` class on the `body`.

Have a nice day! 😎

During a recent project to convert my JavaScript & Node [Battlesnake](https://play.battlesnake.com/) over to TypeScript & [Deno](https://deno.land/), I decided I would also create a more robust suite of tests for it.

![Deno and Github logos with an addition symbol between them](DenoTestsAndGithubActionsCI.png)

If you are unfamiliar with [Battlesnake](https://play.battlesnake.com/), it is an online and in-person programming competition where you build a AI in the form of a REST API that can play a multiplayer version of the classic game [Snake](https://en.wikipedia.org/wiki/Snake_(video_game_genre). You can check out details on their [website](https://play.battlesnake.com/) to learn more, and even watch some past events on their [Twitch channel](https://www.twitch.tv/BattlesnakeOfficial).

## Tl;dr
* [Deno Tests](#deno-tests): Deno includes a very simple test runner framework.
* [Github Actions](#github-actions): Github actions allow you to automate tasks based on triggers within your Github repo.
* [Create the workflow](#create-the-workflow): A .yml file describes a series of actions you would like to perform based on a trigger.
* [Automate Deno tests](#automate-deno-tests): Just add a `run: deno test` command to your workflow .yml.

## Deno Tests
[Deno](https://deno.land/) includes a simple test runner for tests in js, ts, jsx, or tsx files. It can be run with:

```bash
deno test
```

To create tests, all you need to use is use the `Deno.test()` method included with Deno within files ending in *test* (`{*_,}test.{js,ts,jsx,tsx}`) anywhere in your project structure. I put mine in *tests/*.

Example of a basic test:

```typescript
import { assert } from "https://deno.land/std/testing/asserts.ts";
import { root } from "../app/main.ts";

Deno.test("Root response contains expected fields", () => {
  // when
  const result = root();
  // then
  assert(result?.apiversion);
  assert(result?.author);
  assert(result?.head);
  assert(result?.tail);
  assert(result?.color);
});
```

This test is simply asserting that values exist for these specified fields.

You can add many tests to single files by calling `Deno.test()` over and over again. You can also make as many test files as you like, Deno will automatically execute all the files it recognizes ending in *test* (`{*_,}test.{js,ts,jsx,tsx}`).

Visit the [Deno Testing docs](https://deno.land/manual/testing) for more info about creating tests.

Easy! So now I can create a robust set of unit tests for my Battlesnake AI.

Since the game Battlesnake works by [sending you the entire game state for every move](https://docs.battlesnake.com/references/api), I can also save the game state JSON from particularly tricky moves and use them within their own tests. The output can be compared against the single best move, or even a set of equally good moves if their are multiple. Creating tests like this tests the behaviour of the AI overall and ensures that changes to the behaviour aren't making the AI perform worse on moves it previously was able to do correctly.

So now that I have tests up and working, I wanted to automate them using Github Actions.

## Github Actions
Github Actions are still quite new to me and I hadn't touched them at all before this project. I just assumed it would be complicated to set up.

For what I wanted to do for this project it was actually trivial. Couldn't have been easier.

What I wanted was to run these tests automatically whenever pushing to my repository. I figured this Deno app is pretty simple all things considered, so I shouldn't have to mess around with Docker or anything like that.

I'll step you through what I did.

## Create the workflow
Github Actions are based around these things called workflows. They are essentially .yml scripts that describe the series of events you want to perform in your action.

If you click the Actions tab within the repo you want to create the Action you will be presented with a Get started with GitHub Actions page. This page has many example actions you get you started for so many different languages, frameworks, and platforms. It will even suggest actions to you based on the contents of your repo. I chose the *Skip this asn set up a workflow yourself* option.

![Get started with Github Actions](DenoAndGithubActions-get-started-with-github-actions.png)

This plops you into a web editor and gives you a basic example workflow .yml file to start with. It looks something like this:

```yaml
# This is a basic workflow to help you get started with Actions

name: CI

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v2

    # Runs a single command using the runners shell
    - name: Run a one-line script
      run: echo Hello, world!

    # Runs a set of commands using the runners shell
    - name: Run a multi-line script
      run: |
        echo Add other actions to build,
        echo test, and deploy your project.

```

With this you can actually click the *Start commit* button and that will guide you to commit this .yml file to your repo within the *.github/workflows/* directory.

You can see near the top of that file that there are triggers for `on push` and `on pull_request` attached to the master branch. You can try to push something to master and see it work!

If you visit the Actions tab of your repo now you will see your Actions and the history of all the times they have run. You can click into them for more details and to see the console outputs. Also by default it will email your Github account email whenever an action fails. I imagine this can be changed somewhere if you don't like that.

![Github Actions](DenoAndGithubActions-github-actions.png)

## Automate Deno tests
Now I wanted to try to run my tests using Deno. I knew this would involve installing Deno somehow so I searched around.

I found [this repo](https://github.com/denolib/setup-deno) from [denolib](https://github.com/denolib) with exactly what I wanted.

Really all you need to do is add the `uses` line pointing to this repo to your workflow .yml file under the `steps` section. You can also include the Deno version you prefer. Then within the `run` section you now have access to `deno` and all of its functions.

So now my workflow .yml file looks like this:

```yaml
name: CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@master
    - uses: denolib/setup-deno@master
      with:
        deno-version: v1.x
    - run: deno run https://deno.land/std/examples/welcome.ts
```

One really cool feature of Deno is that you can run scripts from the web right in the terminal, and you can also do this right within Github Actions. That is what the URL is doing in

```yaml
- run: deno run https://deno.land/std/examples/welcome.ts
```

You can run this and then look within your Github Actions for the console output from this example *welcome.ts* file.

So now to run my tests, all I needed to do was change that `deno run` command to `deno test`. My final .yml workflow looks something like this:

```yaml
name: CI

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  run-tests:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@master
    - uses: denolib/setup-deno@master
      with:
        deno-version: v1.x
    - run: deno test
```

Now every time I push to my master branch all my tests will be run, including any new tests I just committed, and I will be notified both on the Github UI and in my email if any tests fail. I can then log into Github and look at the output to see what failed.

I hope this small guide helped you out and showed you just how simple both Deno and Github Actions are!


I started this project in 2018 to help teach myself better object-oriented programming structure, game update/draw loops, and JavaScript in general.

Implemented using the P5.js framework for the draw loop and canvas drawing functionality with nothing else but vanilla JavaScript.

[![Screenshot of game with triangle representing the ship in the center and white asteroids all around](lightshift-game-2.png)](https://tyrelh.github.io/lightshift-game/)

You can [play the game](/lightshift-game/index.html) right now!

Controls:

* Left & Right Arrows: Turn
* Up & Down Arrows: Boost
* Shift: Shoot
* Control: Jump

## Basic Overview

Overall there is a game object that contains many layers of the game for title screen, end screen, and game functionality.

Each game layer contains objects associated with its purpose. For example the game layer contains a ship object representing you and an asteroids layer which itself contains many asteroid objects.

All layers and objects implement `update` and `draw` methods. The `update` method will update the state of a particular object for that frame, and then the `draw` method will draw it with the new state.

The layers serve to group similar objects as well as delegate calls to `update` and `draw`. For example each frame `game.update()` is called. This call simply causes `game` to loop through all the layers it contains and call `update` on them, and so forth. Until finally a layer calls `update` on a base object that contains state. That state is then updated!

## Future Updates

1. A couple portions of spaghetti code associated with collisions that needs to be cleaned up.
2. AI ships that maybe enter after a particular point  and try to ruin your day. A simple following mechanism with collision avoidance for the asteroids seems sufficient enough to start.
3. New items that allow for ship upgrades like weapons or shields. Currently every 1000 pts a one-time use shield drops from an asteroid. Perhaps it would make more sense to have the items drop from enemy ships rather than asteroids.
4. The lightshift RGB effect on all the assets isnt being drawn very efficiently. Improvements could be made.
5. Touch controls for mobile.

## Github Repo

The code for this is available on [Github](https://www.github.com/tyrelh/lightshift-game).

Any feedback or comments are welcome! This is very much in an alpha state.



#javascript

Markdown based Code Block Syntax Highlighting

Dec 24, 2024 4 Minute Read

Static Site Search Part 3 - Optimizing the Index

April 18, 2024 8 Minute Read

Static Site Search Part 2 - Search Component

April 10, 2024 7 Minute Read

Static Site Search Part 1 - Preprocessing Articles

April 3, 2024 15 Minute Read

Next.js Tag Pages

March 25, 2024 6 Minute Read

Deploy a Next.js Static Site to GitHub Pages

July 23, 2023 8 Minute Read

Dark Mode React Toggle

June 28, 2020 6 Minute Read

Deno Tests & GitHub Actions CI

May 23, 2020 6 Minute Read

Lightshift Game

Feb 1, 2020 1 Minute Read

Get in touch