![wide: Austin Central Library. &copy; 2019 John Apostol](hero.jpg)

A while back, I had a personal website built to show the portfolio of projects I had completed up to that point. It was built on Rails, my technology of choice at the beginning of my software career. Many years later, I decided to rebuild my site as a blog to jumpstart my motivation and creativity.

Here's how I built this site using modern technologies and sensibilities.

---

# The Use Case
I love building things and writing. That said, I didn't have an up-to-date place to put up anything. I figured that I should try to share my work and thoughts in a blog format where each post could stand alone. Eventually I would organize pieces to be more cohesive.

This blog would be an archive of myself and my work over the years. Mostly I would write about software but I figured that I could branch out into my other interests over time.

My goals were to bring myself joy in both developing `johnapostol.com` and when writing content.

## Joy in coding
* Fun to write code for the blog
* Scalable technology
* Proud to be fully custom made

## Joy in writing
* Fun to write content for the blog
* Easy to manage and publish
* Displays code samples as beautifully as prose

I had started a [Medium account](https://medium.com/@johnapost) not too long before I began this project. I liked the ease of putting up content on Medium, but more than anything, I really liked the way Medium *looked*. After some sleuthing I found that I could syndicate my content to Medium and get canonical references back to my own domain.

I could also seed my blog with content I had already written on Medium. Sweet!

---

# My Tech Choices
One of my favorite parts of any project is picking my tech at the beginning. In projects like these, I usually reach for a mix of my favorite tools and also treat this as an opportunity to learn some new ones.

## TypeScript
I'm a big fan of static typing in a JavaScript environment. At one point, [flow](https://flow.org/) was my go-to, because types were easily stripped away without a compiler. I could continue to rely on [babel](https://babeljs.io/) for JavaScript compilation. These days, [TypeScript boasts the same capability](https://www.typescriptlang.org/docs/handbook/babel-with-typescript.html) as well as overwhelming community support. If I can easily use TypeScript in any project, I will.

## Next.js
I see no better way to get a fully custom website up and running other than writing it with the [Next.js framework](https://nextjs.org/). It allows for ultimate control on top of very sensible defaults. See, I like using babel, webpack and TypeScript, but I don't like working hard to configure those tools. Most of the React-flavored frontend toolchain is taken care of with a simple Next.js application. Oh and I wanted to use React under the hood because of familiarity and overall ease of development.

Lastly, I felt empowered to build my app as a static site. I felt that Next.js had the best guidance for building that while giving me freedom to pepper in dynamic functionality with serverless functions and APIs if I ever decided to go down that road.

## Vercel
Heck, if I'm using Next.js, *which was created by Vercel*, I may as well *host my app on [Vercel](https://vercel.com/)*. Their *Hobby* tier is free forever and with careful management of my dynamic content (I have none in production), I could skate by with their usage limits indefinitely. Next.js and Github integration are top-notch. Not to mention the edge CDN. I had managed to avoid paying for server costs with my last host, why start now?

![center: Hosting, caching, preview deployments; all for the price of free.](vercel.jpg)

## Markdown
I'm comfortable with Markdown syntax. It's simple to read and write, and looks great in diffs as well. I didn't want to deal with custom formatting HTML elements and working with WYSIWYGs. Markdown content is also very portable. I had seen other people bend Markdown formatting to their presentation needs and knew I could too.

## Why not Gatsby?
Gatsby was still coming into its own as a Cloud provider at the time. While the static React framework was great, I didn't see much benefit moving away from the Next.js + Vercel ecosystem.

---

# Main Concepts
Now with something to build and some tools to build it, I had to find a way to tie everything together neatly in a repo. I got to work.

Next.js + TypeScript + Vercel came together beautifully. The most I had trouble with for these pieces was learning about the new features and breaking changes in the latest Next.js release and figuring out if I should be using `interface` or `type` keywords when typing my React component props.

The first real problem came when I tried to realize my vision of writing in Markdown and having React components format my words. It was (and is) very doable with plenty of examples online. Before thinking of solutions, though, I really had to consider the problem.

I wanted to **write content in Markdown** and host all of that **in a single repository** with **no database or server-side logic**. All logic had to be performed at **compile time**.

This was in order to scale my blog for free within Vercel's generous usage limits.

## Thinking as a user
One nice thing about a personal project like this is I'm the user. I could consider how much involvement and manual effort I would stomach to get this thing built. And if I wanted to favor DevX over UX at any point, I could just do it.

As John, the writer, I wanted to write content in only Markdown. My primary directive was **that no HTML should clutter up my words as I wrote**.

---

# Code
After identifying my needs as a user, I could zero in on the code needed to reach my goals. First, I needed a library that could parse Markdown and allow me to process formatting like *italics*, **bold**, or `code` into React components that I could custom style.

Thankfully, there's an excellent library for this called [react-markdown](https://github.com/rexxars/react-markdown/). It elegantly handles Markdown rendering by allowing you to specify what component should be responsible for rendering each bit of formatting. See how it's used in `[slug].tsx`.

```javascript
// [slug].tsx
import React from "react";
import ReactMarkdown from "react-markdown";
import CodeBlock from "../../components/CodeBlock";
import Heading from "../../components/Heading";
import Image from "../../components/Image";
import Link from "../../components/Link";
import Paragraph from "../../components/Paragraph";

const Post = () => {
    const renderers = {
    code: CodeBlock,
    heading: Heading,
    image: Image,
    link: Link,
    paragraph: Paragraph,
  };

  return (
    <ReactMarkdown source={postBody} renderers={renderers} />
  )
}
...
```

Now I could render Markdown into bespoke components for my blog! My content looked as follows. Notice the frontmatter at the top of the file, which is used for metadata.

```markdown
---	
title: "Using Redux with Vanilla JS"	
preview: "What follows is an explanation of how I've used Redux to make a production vanilla JS app more maintainable."	
slug: "using-redux-with-vanilla-js"	
tags: ["software", "javascript"]	
---	

![wide](hero.jpg)

Redux is a popular state management library for JavaScript apps that is routinely paired with frameworks like React or Angular. What follows is an explanation of how I’ve used Redux to make a production vanilla JS app more maintainable.	

I’m hoping this is useful for anyone out there who is looking for a real-world Redux + vanilla JS example beyond a button incrementer or to-do app.
```

The next trick was figuring out how to import my Markdown files at build time. I could have gone the loader route, which would allow me to import raw `.md` into my pages, but decided that it would serve me better to convert my Markdown files into JSON for making simple queries. This allowed me to build out dynamic slugs with the Markdown frontmatter and have an index of posts to display on my site.

For that, I needed the help of [processmd](https://github.com/tscanlin/processmd) to.. process my `.md`.

I wired up a `build` command in my `package.json` to run processmd with file-watching so that it would run as I updated my Markdown files.

```json
// package.json
...
"scripts": {
  ...
  "watch:posts": "processmd posts/*.md --outputDir content --summaryOutput content/summary.json --watch"
},
...
```

As I wrote out my content, processmd would create `.json` files, one for each post. Let's take a look at `getInitialProps()` within `[slug].tsx`.

```javascript
Post.getInitialProps = async ({
  query: { date, preview, slug },
}) => {
  const { bodyContent, title } = await import(`../content/${date}.json`);

  return {
    date,
    postBody: bodyContent,
    preview,
    slug,
    title,
  };
};
```

Another neat thing about processmd is that it can create a `summary.json` manifest file for you. I used this to list out all the posts I had available on my blog.

```json
// summary.json

{	
  "fileMap": {	
    "content/2019-01-30.json": {	
    "title": "Using Redux with Vanilla JS",	
    "preview": "What follows is an explanation of how I've used Redux to make a production vanilla JS app more maintainable.",	
    "slug": "using-redux-with-vanilla-js",	
    "tags": ["software", "javascript"],	
    "dir": "content",	
    "base": "2019-01-30.json",	
    "ext": ".json",	
    "sourceBase": "2019-01-30.md",	
    "sourceExt": ".md"	
  },
  ...
}
```

Now, if I import `summary.json`, I could display a list of my posts on the index page. I'll zoom in on the important part.

```javascript
...
export const getStaticProps = async () => {
  const summary = await import("../content/summary.json");
  const { sourceFileArray, fileMap } = summary;

  const recent = sourceFileArray.slice(-5).reverse();
  const posts = recent.map((sourceFile) => {
    const destFile = sourceFile
      .replace("posts/", "content/")
      .replace(".md", ".json");

    return {
      ...fileMap[destFile],
      date: fileToDate(destFile),
    };
  });

  return { props: { posts } };
};
```

Now that the guts of my development and writing process were in place, I could go about styling the individual components that make up each post.

---

# Inspired by Medium

I'll be perfectly honest, Medium has an amazing reading experience. I could write absolute drivel and it would look good on Medium. There's plenty of air and space that makes it a pleasure to read. I didn't think I could do any better without a big investment like hiring a designer.

I figured the best way to make my content pop was to lift styles from the best source. I dug into Medium's styles and lifted what made sense, tweaking and adjusting to retain the same breezy qualities, while fitting my own sensibilities.

You can see the difference between the styles for my **[Building a Serverless React App on Firebase Functions](/post/building-a-serverless-react-app-on-firebase-functions)** post hosted on my blog and syndicated on Medium.

![center: On the left is Medium. On the right is my blog.](compare.png)

## Polishing

I had some room to get fancy with all the raw pieces coming together. I wanted a clean way to show my author byline and my post title. I played with a couple options and ultimately decided to have a byline that transitions into a sticky navigation element as readers scroll. It took a lot of finessing and I'm very proud of the final effect.

---

# Not yet done

My blog is being continually improved, both through code and content. Maybe my pace of delivery isn't great (this post has been in draft for 4 months), but I greatly enjoy using what I built.

There were some final problems I still had to overcome! At a certain point, it became clear I had made a mistake in having my site be fully static code driven. I had to eventually move away from my `processmd` setup. In a follow-up post, I will get into how I migrated from a static generated blog into a CMS-driven static generated blog powered by [GraphCMS](https://graphcms.com/). Please look forward to it.

How I Custom-built My Markdown Blog

![wide: My baby Chrome extension](hero.jpg)

Honestly, I thought that Chrome extensions were more effort than they were worth to develop. I thought my extension would have to be useful for other people on the Chrome Web Store. Here’s how I was wrong.

*Skip to “Making the Extension” if you just want the goods.*

# The Use Case

I work at [The Zebra](https://www.thezebra.com/). It’s a neat place with smart software engineers collaborating on interesting problems.

Any place that has software engineers has people griping and sniping about their tools. We’re craftspeople and take pride in our efficiency.

At The Zebra, we have an expectation that developers will squash their commits before merging into `master`. This was not an issue back when we used GitHub for hosting our Git repos. GitHub had useful configuration that allowed admins to enforce squashed commits. All was right with the world. A few folks *really* wanted us to delete our source branches. 🤷

We found no such option when we moved over to GitLab. In fact, our developers found an [old GitLab issue](https://gitlab.com/gitlab-org/gitlab/issues/17613) asking for this functionality (2 years old at the time of writing).

We’ve lived with it for a little over half a year before I decided to look into whether a Chrome extension could solve the problem for us. At least, it could solve it for me.

# The Setup

At the core of our issue was that the GitLab Merge Request UI had a little checkbox that controlled squashing commits on merge. We simply needed that box to be checked as the Merge Request screen loaded, effectively protecting our squash commit culture by default. Bonus if developers could uncheck the box in case they *really* wanted to include their discrete commits in `master`.

I didn’t want to read a single bit of Chrome Extension documentation. I actively refused to. It was nearing midnight and I gave myself a 30 minute time limit to make things interesting.

So I set off to Google how to do this. I found a great article by thoughtbot.. but it was over a few screens worth of scrolling so I decided to just skim the code to see if I could get the gist. I had Netflix to watch, ice cream to eat.

*What’s to stop you from doing the same thing? Nothing really, go ahead.*

# Making the Extension

I needed exactly two files for my purposes:

```markdown
gitlab-squash-default
|- manifest.json (small config for extension)
`- content.js (the actual browser code)
```

The `manifest.json` file is just that; a manifest. This is how Chrome will understand your extension and when to apply it.

---

## manifest.json

```json
{
  "manifest_version": 2,
  "name": "GitLab Squash Default",
  "version": "0.1",
  "content_scripts": [
    {
      "matches": ["https://gitlab.com/*/merge_requests/*"],
      "js": ["content.js"]
    }
  ]
}
```

Here’s a rundown of the most important values.

* `name`: How you’ll recognize your extension when applying it
* `manifest_version`: This should be set to `2` as the earlier version isn’t supported. Don’t ask me why; I skimmed, remember?
* `content_scripts`: You probably want your extension to run against a single URL or a URL pattern. Set that here. It’s nice to know that you can use wildcards. My extension is only applied to URLs that begin with `https://gitlab.com/` and must then include `/merge_requests/` in the middle of the path somewhere. I also specify what file runs against those matching URLs.

---

## content.js

```javascript
window.addEventListener('load', () => {
  checkSquash = setInterval(() => {
    const checkbox = document.querySelector("input[name='squash']")
    if (checkbox) {
      checkbox.checked = true;
      clearInterval(checkSquash);
    }
  }, 250);
});
```

And that’s all the JS that I needed to make the functionality. This little code snippet would fire whenever the URL matched GitLab’s Merge Request screen and the desired checkbox would be checked upon its availability in the DOM. 🎉 🎉 🎉

---

# Enabling the Extension

With those two files written, follow these steps to enable it for your use:

* Go to `chrome://extensions/` in the Chrome.
* Enable `Developer mode`. This is a toggle on the top right of the page as of Chrome 80.
* Click `Load unpacked` and select the directory your files are in.
* Enable the extension, the name will match what’s in `manifest.json`.
* Test it by going to your specified URLs!

If you don’t see that the extension is working correctly, check for errors on the extensions page. You can also reload the extension after making changes.

---

That’s it, hope that helps you. Feel free to check out my extension if you like. Yep, I’m hosting my extension for GitLab on GitHub.

I’d appreciate any comments if you found this useful or entertaining. I’m looking to start writing more and could use the encouragement. Also, we’re always [hiring at The Zebra](https://www.thezebra.com/careers/).

## Resources

* [My extension, gitlab-squash-default](https://github.com/johnapost/gitlab-squash-default)
* [The thoughtbot article I skimmed](https://thoughtbot.com/blog/how-to-make-a-chrome-extension)
* [The Chrome Extension documentation I never read](https://developer.chrome.com/extensions/devguide)

Creating a Chrome Extension Without Much Effort

![wide](hero.jpg)

Redux is a popular state management library for JavaScript apps that is routinely paired with frameworks like React or Angular. What follows is an explanation of how I’ve used Redux to make a production vanilla JS app more maintainable.

I’m hoping this is useful for anyone out there who is looking for a real-world Redux + vanilla JS example beyond a button incrementer or to-do app.

---

# Background

Let’s go back to late 2017/early 2018. The subject app is in production and has ~8 engineers actively developing. This ain’t your trendy universal React app. It’s purpose-built for managing content for our company.

The backend framework is Django and includes Wagtail as a CMS. The frontend is babel-transpiled vanilla JS with SCSS as a preprocessor. Templates are all handled by Django’s built-in templating system.

The frontend app has its roots in the Knockout JS framework, but this was reduced to vanilla JS in pursuit of faster page loads and script executions. Most of the frontend logic is meant to handle simple features like sharing to social networks, subscribing to a newsletter, and submitting forms.

Each page stands alone and references its own template CSS file for styles, and template JS file for logic. Since we don’t use a frontend framework at runtime, the pages are much faster than our competitors.

---

# Identifying the problems

As our app grew, we had to support more CMS templates that were used for even more pages. Common bugs would appear and reappear as we worked. Problems fell into two categories.

## 1. Code reuse was arbitrary and difficult

Our frontend code had duplication stemming from over-eager classical inheritance patterns. There were multiple levels of inheritance that had to be traversed to understand how a certain page’s logic would differ from another, very similar page.

This got worse with time.

Template functionality requirements were fluid. It was hard for newer hires to conform to the intricate inheritance layers when making changes. A ticket would be raised to fix a bug on one page with the assumption that it would apply to all templates. Unfortunately, that wasn’t the case.

## 2. Asynchronous data, without any management

Some code would make asynchronous data requests to a separate server. The response data existed only within the context of the requesting function. This was fine until we ran into situations where we wanted to share data between separate functions.

Some features required data from multiple asynchronous functions and an engineer would have to manually invoke those functions and do it in the right order. It wasn’t immediately clear what that order was and why it was important until bugs cropped up in staging environments.

It was especially awful with the duplication and confusing inheritance patterns already pervasive in the code. Plus, unit test coverage wasn’t very good.

---

# Composing a solution with Redux

I audited the entirety of the frontend application and reduced all logic into small building blocks called **features**. These features almost never interacted with each other. They simply wanted to run, process some template data, attach event handlers to the DOM, and had no need to exist after that.

Our app’s multilevel inheritance structure only existed to group features common to a template. I could accomplish the same thing and reduce cognitive load by simply composing our features together.

for this, I used the `compose()` utility that Redux provides. See what kind of effect it has on the code below.

## Before: multilevel inheritance

```javascript
class BasePage {
  constructor() { console.log('Setting up base page') }
};

class HeaderPage extends BasePage {
  constructor() {
    super();
    this.initHeader();
  }
  initHeader() { console.log('Initializing header') }
};

class FormPage extends HeaderPage {
  constructor() {
    super();
    this.initForm();
  }
  initForm() { console.log('Initializing form') }
};

class FormNoHeader extends FormPage {
  constructor() { super() }
  // Empty method so that this.initHeader() in FormPage constructor does nothing
  initHeader() {}
};

class DifferentFormNoHeader extends FormPage {
  constructor() { super() }
  initHeader() {}
  initForm() { console.log('Initializing different form') }
}

const formPage = new FormPage();
// Output:
// Setting up base page
// Initializing header
// Initializing form

const formNoHeader = new FormNoHeader();
// Output:
// Setting up base page
// Initializing form

const differentFormNoHeader = new DifferentFormNoHeader();
// Output:
// Setting up base page
// Initializing different form
```
*Most problems arose when we wanted to copy template functionality except for one or two pieces of logic.*

## AFTER: functional composition

```javascript
import { compose } from 'redux';

const setup = () => { console.log('Setting up base page') };
const initHeader = () => { console.log('Initializing header') };
const initForm = () => { console.log('Initializing form') };
const differentForm = () => { console.log('Initializing different form') };

const formPage = compose(initForm, initHeader, setup)();
// Output:
// Setting up base page
// Initializing header
// Initializing form

const formNoHeader = compose(initForm, setup)();
// Output:
// Setting up base page
// Initializing form

const differentFormNoHeader = compose(differntForm, setup)();
// Output:
// Setting up base page
// Initializing different form
```
*Beautiful*

Switching to functional composition proved to be highly beneficial. I was able to remove all logic related to individual templates since they are just comprised of features. This reduced the complexity of our frontend immensely!

Each feature comes with its own set of unit tests. These are easy to write, because of the isolated nature of the code. If unit tests are easy to write, they will get written more often, helping the team keep up with maintenance.

By using `compose()` we can also bundle features together and import that bundle all at once. This is helpful for when we create a new Django template X that needs to be like template Y, but with the addition of feature Z.

## Bundled features

```javascript

import { compose } from 'redux';

// Features
const setup = () => { console.log('Setting up base page') };
const initHeader = () => { console.log('Initializing header') };
const initForm = () => { console.log('Initializing form') };
const initSlider = () => { console.log('Initializing slider') };

// Similar to the BasePage and HeaderPage classes
const basePage = setup();
const headerPage = initHeader(basePage);

// We can take the headerPage bundle and compose off of that
const formSliderPage = compose(initSlider, initForm)(headerPage);
// Output:
// Setting up base page
// Initializing header
// Initializing form
// Initializing slider
```

# Sharing data with Redux

I didn't bring Redux in as a dependency just for `compose()`. I also needed a way to share data between features and manage async calls. I needed to use a data store.

To be a feature, a function..

* must be unary (accept only the Redux store as an argument)
* must return our app’s store for the next function in the chain
* must not be async

## A typical feature

```javascript
const makeLinksAlert = store => {
  const links = document.querySelector('a')
  Array.from(links).forEach(el => {
    el.addEventListener("click", () => { alert('alert!') });
  });
  return store;
};
```
*A lot of our features do small things like this.*

Each feature has access to the [Redux store](https://redux.js.org/basics/store#store), which is powerful.

At the same time, it’s important to restrict features from blocking on async requests during the initial script evaluation. It would be disastrous if a form wasn’t responsive as soon as it was visible. So I only `dispatch()` and `getState()` when it makes sense (typically on user interaction).

The Redux store maintains the state of important async calls. I dispatch relevant actions as async calls are made inside features. Features can subscribe to the store and fire once a value is truthy. This provides a way to chain asynchronous calls between features without having to rely on bloated Promise chains.

I created a simple subscribe function to accomplish this. Note that it also unsubscribes once the callback fires.

## Subscribe utility

```javascript
const passConditions = (conditions, state) =>
  conditions.every(condition => {
    const path = condition.split(".");
    // Check to see if condition values are truthy
    return !!path.reduce(
      (accum, curr) => (accum && accum[curr] ? accum[curr] : null),
      state
    );
  });

// Conditions are an array of string paths to access store keys.
// ["quoteId.value"] would only fire if nested key value was truthy.
// A store like { quoteId: { value: true } } would suffice.
export default (conditions, callback) => store => {
  let fired = false;
  // The redux store subscribe returns an unsubscribe function
  const unsubscribe = store.subscribe(() => {
    const state = store.getState();
    if (!passConditions(conditions, state)) return;
    // This line is to pass tests
    if (unsubscribe) unsubscribe();
    // The unsubscribe call is not enough to ensure the callback only fires once
    if (!fired) callback(state, store);
    fired = true;
  });
  return store;
};
```

There are circumstances where a feature is waiting on multiple async calls to fire. Simply subscribe to both async values and wait for them both to be valid.

## Using subscribe utility

```javascript
import subscribe from './subscribe'

// Store state
// {
//   form: {
//     loaded: true,
//     emailInput: {
//       value: 'email@domain.com'
//     }
//   }
// }

const validateInput = 
  subscribe(['form.loaded', 'form.emailInput.value'], state => {
    console.log('Validating input');
  });
```
*The validateInput feature will fire once when both conditions are truthy. It will unsubscribe afterwards.*

---

# Conclusion
I’m pleased to have found a use for Redux outside of React and to have applied some of the functional programming techniques I’ve been studying. The refactors have been thriving in production for a year now and our frontend code is healthier than ever.

Benefits recap:

* Removal of template JS logic
* Smaller, focused units of code
* Easier to test
* Less async bugs

That said, I’m still working to improve on this concept.

We’ve had engineers import a feature, without realizing that it already exists in the compose chain via a feature bundle. This means that feature would execute twice. I’m working on a solution for that.

Since template JS files have become tacit compose functions, I can evaluate the Django template at compile time and come up with the features that should be composed. Tie that to the CMS blocks, deploy dynamic JS to a CDN, and now we can build features without worrying about templates at all.

Maybe I’ll have a follow-up next year. 😄

John Apostol

Posts about JavaScript

How I Custom-built My Markdown Blog

Creating a Chrome Extension Without Much Effort

Using Redux with Vanilla JS