![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: View of the Bernese Alps from Schilthorn. &copy; 2019 John Apostol](hero.jpg)

This is a step-by-step guide to building your own serverless React app with the practicality afforded by Next.js and the Firebase ecosystem.

After reading about Next.js’s new serverless mode and attending ServerlessDays ATX, I got the itch to wire up a simple example for a Firebase-flavored serverless app.

**Read before you proceed: Firebase bundles all of your functions together and doesn’t natively support per-function bundling. A sufficiently large app with many routes may run into scaling issues. [See this comment.](https://github.com/firebase/firebase-tools/issues/1163#issuecomment-472071855)**

I wrote this all before I found this out so I’m publishing this anyway. Proceed if you dare!

---

First, let's take a look at our toolbox.

## Next.js

If you’ve ever built a major React app from scratch, you know what config hell it can be. Next.js is an opinionated, fully-featured React framework that gives you sane defaults upfront. Later on, you can customize your .babelrc and webpack config to suit your app’s needs. You can even pre-render your app on the server (or function in our case).

Most important for our purposes, Next.js features a new serverless mode that’s optimized for cold starts and small function size.

## Firebase Functions

*AKA Cloud Functions for Firebase*

Can’t have serverless functions without a serverless hosting provider. There’s servers running our code somewhere but we want them abstracted away.

The Firebase platform is a nice choice, because it can scale with your app’s needs for a data store, authentication, logging (albeit simple), static file hosting, and user file storage. There’s a little bit of a learning curve when integrating with some features but I’ve generally found it simpler to work with when compared to something like AWS.

*That said, permissions are currently platform-wide with beta support for per-function IAM. Be wary if you’re keen on following the principle of least privilege.*

The rest of this post will explain how to set everything up step-by-step. If you’d rather get going with less hand-holding, see this repo instead:

[repo: Demo for serverless NextJS on Firebase functions.](https://github.com/johnapost/nextjs-firebase-fns-demo)

---

# From scratch

Fire up your text editor and `mkdir` something fancy, then let’s get started!

Begin by installing or swapping over to Node.js 8. Use the version of `npm` bundled with that to run these commands.

1. `npm init`
2. `npm install next react react-dom`

Our app’s main dependency is on the `next` package, which lists `react` and `react-dom` as peer dependencies. Installing just `next` is not enough.

Specify `"engines": { "node": "8" }` in your `package.json` so Firebase Functions knows which runtime to provide you.

*One of my secret joys is to use the latest version of Node.js in whatever new project I work on. Hold off on that urge here, because it’s important to note that **Firebase Functions only support Node.js 6 or Node.js 8 runtimes** as of this writing. Lock it down for now to avoid any headaches later.*

Let’s continue by installing some more dependencies.

1. `npm install firebase-admin firebase-functions`
2. `npm install firebase-tools --save-dev`

`firebase-admin` and `firebase-functions` are necessary for your functions to run on Firebase, while `firebase-tools` is what you'll use to deploy and manage your app.

After setting up those dependencies, let’s create a new Firebase project for our app to live in. Visit https://console.firebase.google.com/ and follow the on-screen steps in order to create a project.

Once you have your project, you can associate your code:

1. `npx firebase login`
2. `npx firebase use --add`

The first command will launch your browser and prompt to login to the Google account associated with your Firebase project. Use the second command to select the project you just created.

Notice that a .firebaserc file was created in your project directory. This file serves to map local development aliases to Firebase projects. If you create more projects and define more aliases, `npx firebase use [alias]` can be used later to swap deploy targets. A common scenario is swapping between production and staging environments.

We should have a directory structure that looks like this:

```markdown
|-node_modules *new*
|-.firebaserc *new*
|-package-lock.json *new*
`-package.json *new*
```

---

OK, now we will need to build a simple Next.js app with routing.

Different routes are served by different functions (at runtime). We can deploy new code on separate routes without breaking our whole Next.js app!

Create a directory structure with blank files like so:

```markdown
|-node_modules
|-src *new*
| `-app *new*
|   |-components *new*
|   | `-Nav.js *new*
|   |-pages *new*
|   | |-About.js *new*
|   | `-Index.js *new*
|   `-static *new*
|     `-placeholder.json *new*
|-.firebaserc
|-package-lock.json
`-package.json
```

All upcoming examples will assume this directory structure.

Let’s build out the `Nav` component:

```javascript
// src/app/components/Nav.js

// Next.js has a nice router we'll use
import Link from 'next/link'

// The links are based on the URLs that will serve those pages
export default () =>
  <ul>
    <li>
      <Link href='/'><a>Home</a></Link>
    </li>
    <li>
      <Link href='/about'><a>About</a></Link>
    </li>
  </ul>
```

Now wire up those two pages, `Index` and `About`:

```javascript
// src/app/pages/Index.js

import Nav from '../components/Nav.js'

export default () =>
  <>
    <Nav />
    <p>Index page</p>
  </>
```

```javascript
// src/app/pages/About.js

import Nav from '../components/Nav.js'

export default () =>
  <>
    <Nav />
    <p>About page</p>
  </>
```

The static directory is where your app can store static files like favicon.ico or robots.txt. Having any file here is necessary for defining Firebase hosting route configs. placeholder.json is an empty file here just for this purpose.

---

# Create the serverless functions

Now let’s add serverless functions to handle each app route:

```markdown
|-node_modules
|-src
| |-app
| | |-components
| | | `-Nav.js
| | `-pages
| |   |-About.js
| |   `-Index.js
| `-functions *new*
|   `-index.js *new*
|-.firebaserc
|-package-lock.json
`-package.json
```

Inside the newly minted functions directory, we’ll have a single index.js file that serves as a function manifest for our route functions. This file will export each individual named route, as you can see:

```javascript
// src/functions/index.js

// Here's firebase dependency for handling HTTP requests
const onRequest = require('firebase-functions').https.onRequest

// These relative paths will exist after compiling everything
const index = require('./next/serverless/pages/index')
const about = require('./next/serverless/pages/about')

// These named exports will map to Firebase Function names
exports.index = onRequest((req, res) => index.render(req, res))
exports.about = onRequest((req, res) => about.render(req, res))
```

*Note: index.js is one large bundle. Don't mistakenly believe that each export is its own bundle!*

---

# Compiling and deploying!

Our super simple app and super simple route functions are ready. Now we can put the pieces together and get everything running in Firebase.

First, we’ll create a config file for Next.js:

```javascript
// src/app/next.config.js

module.exports = {
  target: "serverless",
  distDir: "../../dist/functions/next"
}
```

Great, we’ve configured Next.js to bundle each page individually and where to put those bundles.

Now, we’ll define some simple scripts and include those in our package.json file so that we can automate some common tasks:

```json
{
  "scripts": {
    "build:app": "next build src/app",
    "dev": "next src/app"
  },
  "dependencies": {
    "firebase-admin": "^7.0.0",
    "firebase-functions": "^2.2.0",
    "next": "^8.0.3",
    "react": "^16.8.3",
    "react-dom": "^16.8.3"
  },
  "devDependencies": {
    "firebase-tools": "^6.4.0"
  },
  "engines": {
    "node": "8"
  }
}
```

`"build:app"` is self-explanatory. This will build out our app using direction from the src/app/next.config.js file we created. Go ahead and run it now with `npm run build:app` if you wish. You’ll notice a new dist directory at your project root. You can find your app page bundles nested within that.

dev is even simpler. You can now use `npm run dev` to hack away at your app with a modern local development server.

Let’s install a few more dependencies to make our lives easier:

`npm install cpx rimraf --save-dev`

I like using `cpx` for recursive file copying and `rimraf` for recursive file deletion, because they work just as well on my Mac OS X and Windows machines.

Update package.json with some more scripts:

```json
{
  "scripts": {
    "build:app": "next build src/app",
    "build:functions": "cpx \"src/functions/**/*.*\" dist/functions",
    "build:public": "cpx \"src/app/static/**/*.*\" dist/public/static",
    "clean": "rimraf dist",
    "copy:deps": "cpx \"*{package.json,package-lock.json}\" dist/functions",
    "dev": "next src/app"
  },
  "dependencies": {
    "firebase-admin": "^7.0.0",
    "firebase-functions": "^2.2.0",
    "next": "^8.0.3",
    "react": "^16.8.3",
    "react-dom": "^16.8.3"
  },
  "devDependencies": {
    "firebase-tools": "^6.4.0"
  },
  "engines": {
    "node": "8"
  }
}
```

`build:functions` doesn’t *build* functions necessarily. In this simple project we’ve written Node.js 8 compatible code so it’s enough to copy our functions over to dist as they are.

`build:public` copies static assets from the src/app/static directory. Our lone placeholder.json file will be served by our app’s domain once deployed.

`clean` is for deleting our dist directory to ensure we are properly building our app from scratch before each deploy.

`copy:deps` is interesting. It copies our dependencies over to the function directory. This ensures that we are using the same dependencies in our serverless functions and client code. One would have to define a separate set of npm dependencies within the src/functions directory without something like this.

The final piece of the puzzle is the firebase.json file, which we’ll create now:

```json
{
  "functions": {
    "predeploy": "npm run clean && npm run build:app && npm run build:functions && npm run copy:deps",
    "source": "dist/functions"
  },
  "hosting": {
    "predeploy": "npm run build:public",
    "public": "dist/public",
    "rewrites": [
      {
        "source": "/about",
        "function": "about"
      },
      {
        "source": "**/**",
        "function": "index"
      }
    ]
  }
```

`functions.predeploy` runs our package.json scripts in order to ensure that each deploy is reproducible.

`functions.source` points to the dist/functions directory as the source of our serverless functions. Our compiled manifest file, dist/functions/index.js, sits in that directory and its named exports are our functions.

`hosting.predeploy` contains the package.json script responsible for setting up our static assets.

`hosting.public` points to dist/public, which is the directory that will have its contents uploaded as static assets.

`hosting.rewrites` is a mapping of URL endpoints to functions. This configuration points /about to the about page function, while all other routes will be served by the index page function. You can think of this config as your router!

With the addition of firebase.json, our directory structure resembles this:

```markdown
|-node_modules
|-src
| |-app
| | |-components
| | | `-Nav.js
| | `-pages
| |   |-About.js
| |   `-Index.js
| `-functions
|   `-index.js
|-.firebaserc
|-firebase.json *new*
|-package-lock.json
`-package.json
```

And we can now deploy our entire project to Firebase.

`npx firebase deploy`

Firebase will deploy our static code (`placeholder.json`), deploy our serverless functions, and rewrite our app routes to be served by those same functions.

At the end of the deploy you will see a **Hosting URL** for your project, something like **https://[project-name].firebaseapp.com**. Check it out!

One thing you’ll notice if you haven’t dealt with serverless applications before is that initial visits to routes will feel slower because the functions serving those routes go through a cold start if they haven’t been used recently. If a function has been invoked recently, it’s considered hot and will respond much more quickly. Having regular traffic to your functions will keep them hot. Thankfully, Next.JS’s serverless mode optimized for cold starts.

---

That's it! Please let me know if you found this post helpful at all! 😃

---

# Thanks

* [Next.js 8](https://nextjs.org/blog/next-8) for encouraging serverless deployments!
* [ServerlessDays ATX](https://atx.serverlessdays.io/) for inspiring me to write something serverless!
* [James Hegedus](https://codeburst.io/@jthegedus) for his excellent Firebase posts!

John Apostol

Posts about Next.js

How I Custom-built My Markdown Blog

Building a Serverless React App on Firebase Functions