piratematt.com v3—Overview & Getting Started

Series: Personal/Professional Website
Sub-series: piratematt.com v3
Entry: 01—Overview and Getting Started
First Published: April 2023

Introducing the (sub)series

Hello fellow internet denizens, welcome to this series! I’ll be covering my journey crafting my personal/professional website. Expect some narratives, some musings on tools/techniques chosen, some steps to how I got things working, and some reflections on lessons learned. Although slightly confusing, my first subject is actually the third version of my site. I might go back and add entries/sub-series about my first two versions but, to be frank, I don’t think they’re worth writing about.

Without further ado, let’s dive into my most recent version of piratematt.com with a question:

How did I get to the third version?

Version 1 was a fairly standard linux box—CentOS if my memory serves me well—spun up on a free year of AWS. On this box, I ran Node.js with Express and either Jade or Pug templates. To be honest, I have no desire to search my branch history for a definitive answer. It was a fine setup, but it was overkill. The site didn’t do anything. In the end, once my free year was up, I decided to cut the cost and build a new version.

I set aside very little time to build Version 2, so I kept it a quick and dirty endeavor. My desire for something free led me to github pages. I leveraged vanilla HTML, CSS, and JavaScript files to get a static site hammered out in a few days (including a few design tweaks). Like I said, I wanted something fast, not something good, and this fit the bill. It was a slightly nostalgic experience, reminding me of when I was first learning to code—before learning about loops, I would just copy and paste things around that I wanted repeated. This version worked but it was a pain to update and I felt guilty because it clearly violated the principles of tight cohesion, and loose coupling.

These feelings of guilt and the desire to tackle a smaller project with next.js (more on this decision later) led me to Version 3.

Touching on the frameworks/tools/technologies I selected for v3

One of the first things I tackled in version 3 was picking what frameworks/tools/technologies I wanted to use. I knew upfront that I wanted a next.js project that I would build locally and host statically via github pages, but the rest took a little bit of thinking. I’ll briefly touch on my final selections below. In no particular order, here’s a list:

• GitHub Pages – static hosting from the /docs directory
• React – shiny (and popular) front end library
• Next.js – “the React Framework for the Web”
• Styled components – ”visual primities for the component age”
• Jest + React Testing Library – Jest as the testing framework, and the React flavor of Testing Library to align tests closely with actual user behavior as well as keeping accessibility in the forefront
• Google fonts – Next.js has some nifty built-in handling for google fonts, even when building and exporting
• TypeScript – “JavaScript with syntax for types”
• namecheap – purchasing and configuring domains

GitHub Pages – static hosting from the /docs directory

I was already using GitHub Pages for Version 2 of my site. Since I’m not adding any additional functionality to my site for Version 3, there was no reason to select anything else. It meets all my needs. It’s simple and easy static hosting. With a quick addition of a TXT record to my domain service, I set up my own url—piratematt.com. With the check of a box, I enforce https. Lastly, it's got low-to-no operating costs—I even consider free to me because I’ve been paying for github for years now for other reasons. (Note: it can still be free to you if you don’t want to pay, just make sure your repository is public.)

React – shiny (and popular) front end library

I selected React for simple reasons. I’m familiar with it having used it professionally, and have been looking for an excuse to flex those muscles again. I also enjoy it. I find it particularly powerful when building reusable, extensible visual component libraries. Data can get a bit tricky, but that’s been my experience no matter what web framework I’ve used.

Next.js – “the React Framework for the Web”

To make a long story short, I was using a KTDA, Kepner Tregoe Decision Analysis, to pick a web application framework for a different project (Orbital Goals—software to help me keep track of my own particular style of annual goal planning). Next.js came out as one of the top options. I wanted to understand next.js better before I made my final call, but I was feeling overwhelmed by unfamiliar terms, patterns, etc. I knew I’d need to do more than read documentation and complete a hello-world-project to attain the knowledge I was seeking.

Rather than diving into an unstarted project with an unfamiliar framework, I combined two items on my todo list, merging my search for knowledge with my desire to modernize piratematt.com. I could easily see that converting my existing static brochure site to a new framework was a significantly smaller step than building authentication, APIs, databases, a UI library, etc. from scratch in said framework.

Looking back, I’m glad I did. Tackling a smaller problem, I found it much easier to get comfortable navigating next.js documentation, build framework specific vocabulary, and start employing effective search terms. I was especially pleasantly surprised how quickly I was able to craft a stable build, export, qa, and deploy process. Even the additional frameworks/tools/technologies I choose—such as styled components and TypeScript—didn’t slow me down.

I’m pleased to state that Next.js is quite well built for my purposes → Craft a personal/professional website with modern tools, techniques, and frameworks, establishing an easy way to build it statically and host it simply on GitHub Pages. I’m glad I selected it.

Styled Components – “visual primitives for the component age”

Styled components were introduced to me by a coworker who was jazzed about them (shoutout to Peeler). At first I found them frustrating. Too much time spent in the CSS trenches ingrained in me a preference for only applying styling through sleek, powerful, cascading style sheets that carefully and intentionally leverage specificity to apply cohesive styling throughout a site with a single source of truth and little to no repetition.

After a while, I came to enjoy the simplicity of encapsulating the styles affecting a component right there within the component itself. Support for themes within Styled Components and the reusable nature of React components produced a similar result to well crafted CSS strategies, but without the extra mental burden of knowing what CSS in what files were affecting the elements you were working on. It still doesn’t feel as elegant to me, but experience has taught me to trade elegance for ease of understanding 9 times out of 10. I find the benefit teams gain when onboarding new members is typically all the payoff needed, but more and more I find myself thanking past-me for choosing the clear path over a clever one when I’m revisiting code I don’t remember crafting.

Jest + React Testing Library – Jest as the testing framework, and the React flavor of Testing Library to align tests closely with actual user behavior as well as keeping accessibility in the forefront

Both of these were selected, in addition to my appreciation for them, because of my prior professional experience with them. I find Jest to be one of the simplest testing frameworks I’ve ever used and I appreciate the philosophy behind Testing Library. Its default attention to accessibility ensures I adopt an empathetic mindset when crafting code. Its focus on mimicking actual user interactions gives me confidence I’m testing impactful behavior. That said, it’s a hammer and not everything is a nail. I often find myself writing typical unit tests for utilities, data-transformers, etc.

Google fonts – Next.js has some nifty built-in handling for google fonts, even when building and exporting

Google fonts is my goto for finding fonts I’m actually licensed to use. I was delighted to find Next.js had a way to natively, and performantly, pull them in.

TypeScript – “JavaScript with syntax for types”

I’m slowly coming aboard the TypeScript train 🚂. Professionally I have the most experience with Flow(type), but it seems clear to me that TypeScript is winning the battle of prevalence. I selected TypeScript for this project to get some more practice with it.

namecheap – purchasing and configuring domains

Namecheap was the first place I purchased a domain, and I’ve stuck with them ever since. They also do some other things like hosting, email, etc. but I’ve never felt the need for their other services. Domain purchasing and identity protection on those domains is good enough for me!

Discussing my approach to getting started with v3

Step 1 – Read the docs

My primary goal with any new tool/framework/etc. is to be able to orient myself. What is it good at doing? What is it bad at doing? What vocabulary does it establish? How quickly will I be able to find answers within the documentation? When do I need to broaden my search to the internet? What is the magic combination of search terms I need to use to get actually usable results?

What’s the best way I have to become oriented?

Well as an old professor of mine once advised me: sometimes you just have to sit down and read the man page. Of course modern frameworks don’t have man pages in the traditional sense (although many lower-level tools do), the advice still applies. Yes, you will be overwhelmed. No, everything won’t stick. The goal isn’t to come out of your first readthrough as an expert. Instead, focus your first readthrough on absorbing as much as you can.

With this in mind, I sat down and read through the Next.js docs. I was pleasantly surprised to find that they begin with well crafted Getting Started and Basic Features sections. Being new to next.js, but not to Web Frameworks, I skimmed the advanced topics unless I knew it applied to something I wanted to do or use for this project (static HTML export, custom 404 page, etc.). Before I knew it, things were running locally and I was beginning to work through transforming my vanilla HTML/JS/CSS files from Version 2 into reusable React components.

Step 2 – Incrementally deliver locally until a stable “MVP” state is reached

Once I completed my first readthrough of the docs and got “hello world” out of the way, I sat down and identified some iterative deliverables and identified what I considered to be the MVP (minimum viable product) and SLC (simple, loveable, complete) states for the project. These terms don’t map super well to projects with solely internally focused drivers like this website rebuild, but even in nonideal circumstances I find them useful focal points.

Oversimplifying the giant checklist in my README file, the deliverables I identified look something like this:

• Have Next.js serve the existing HTML/JS/CSS so I can start incrementally updating each page.
• Get Styled Components up and running locally, playing nice with Next.js’s dev server.
• Incrementally replace each version 2 page with React Components.
  • Start with the header and footer because these are shared by nearly every page.
  • Abstract reused components as you go.
• MVP state is reached when each existing page is converted to React components leveraging Styled Components.
• Develop deployment process.
• Add Jest, and React Testing Library.
  • Write tests for the few non-presentational components.
  • Update deployment process to include tests.
• Convert the project to TypeScript, utilizing the deployment process along the way.
• Improve the deployment process.
• SLC state is reached when tests are written/passing, and all files are converted to TypeScript files.
• Write and publish blog entries about the experience.

Of course my carefully laid plans didn’t survive contact with reality, but they stayed relatively close. I’ll share a few highlights of my real-time adaptations below.

I never did get my existing V2 files working alongside Next.js powered pages. After a brief attempt I realized the way Next.js handles images, links, head tags, and the like meant I couldn’t simply return full, unaltered HTML files from within the framework. I could add them after next.js produced its static output, but I didn’t know how that was going to work yet and didn’t want to tackle it until I had something to actually deploy, so I took this deliverable off the list.

I successfully componentized almost all of my V2 site’s behavior, but I pretty quickly realized my implementation of the site’s easter egg wasn’t going to be as straightforward as I wanted. I pushed its completion to be an aspect of my SLC state.

Step 3 – Develop deployment process

I’m going to go into more details about this process in a future entry so I’ll keep this section brief. For now, I’ll just say that I was able to develop this process much quicker and with less headaches than I was anticipating. DevOps is always a toss up for me. Production infrastructure causes me enough stress that I tend to over prepare in an attempt to lessen it. Through a combination of npm scripts, an additional repository, and a subdomain I was able to get something up and running in less than a day. It’s by no means the paragon of deployment processes, but it suits my needs well enough for this project.

Step 4 – Push past stable to “SLC”

Once I had successfully replaced my production site with a statically built and exported Next.js site, I got tests written/running and TypeScript written/building. All the while, I was refining my deployment process and pushing updates live. I was well on my way to SLC, but I realized I had a few more adaptations to make to my plans. Stepping back, I realized I’ll consider this project in a SLC state and Version 3 truely wrapped up when all these entries are published, and I’ve successfully added a site easter egg back into production. There’s work yet to be done.

Previewing future entries in the series

If writing these entries is now a necessary piece to consider this project simple, loveable, and complete, what incremental deliverables do I have planned for this series? Of course this plan might not survive contact with reality either... but at the moment I’m planning on entries to cover:

• Getting Styled Components (React) working with Next.js
• Getting Jest + React Testing Library working with Next.js
• Getting TypeScript working with Next.js
• Deploying Next.js to Github Pages
• Final thoughts and conclusions

If you’ve made it this far, thanks for reading! If you have comments, critiques, cautions, or clairvoyances please feel welcome to share them!