DEV Community: piratematt

Last Month's Reading 24/01 – January 2024

piratematt — Wed, 07 Feb 2024 01:46:44 +0000

Last Month's Reading; a non-exhaustive list.

Early Month

The True Purpose of Testing by Artem Zakharchenko
- "A test becomes useful when it fulfills its purpose."
- "It is only when a test validates the intention that it becomes useful."
- Argues against tests validating how and for tests validating intention.
- Potential counter thought: encapsulation often leads to tests validating how. These aren't inherently bad, asserting your building blocks behave as expected is good. This deserves more pondering.
- "That's what the automated tests are for." <— Oh, so we're talking about a specific type of test.
- I'd love to read an experienced TDD-er's take on this.
Beyond the login page by Thomas Broyer
- A list of questions to think about/tackle when developing authentication.
- I love how well this shows the complexity that often hides behind simplicity.
- "I don't think I ever implemented all of the above perfectly. There are always tradeoffs. But these are things to think about and make choices"
- He points out that this is only authentication, not authorization. There's just a lot to think about here.
Get the Return Type from a Promise in TypeScript by Niall Maher
- I have accessor methods responsible for direct DB access. Several of these are grabbing configured (via the DB) options that power selects for other records. When I passed them to my "select" components I was manually typing them. This felt wrong.
- I quick bit of web sleuthing later, thanks to Niall I had what I need 👇🏻
```
  export async function findRecordsForOptions () { /* ... */ }
  export type RecordOptions = Awaited<ReturnType<typeof findRecordsForOptions>>
```
- Short, sweet, and to the point. Love it!

export async function loader({ request }: LoaderFunctionArgs) { /* ... */ }

export async function clientLoader({ request, serverLoader }: ClientLoaderFunctionArgs) { /* ... */ }

export function HydrateFallback() { /* ... */ }

export default function Component() {
  // This will always be the combined set of server + client data
  const data = useLoaderData();
  return <>...</>;
}

"a bit of a sharp knife" – use wisely and cautiously
Opt-in functionality

Mid – Late Month

Headless components in React and why I stopped using a UI library for our design system by Nir Ben-Yair
- Requirements: Accessibility, Theming, Uniqueness, Browser support, Functionality, Responsiveness, and Maintainability.
- UI Libraries are great, but also inevitably fail you when you start to get complex.
- Short version... Headless can help by being "well tested on multiple browsers, platforms, and devices and deal[ing] with edge cases that I never could or want to deal with myself: stuff like focus management, keyboard navigation, event listeners, accessibility attributes, valid markup and screen reader support"
- I really like the way this seems to be abstracting away the hard details to the communal effort of Open Source but leaving "the work" to the developer's intention. Need to spend some more time digging in here.
The Golden Rule of Assertions by Artem Zakharchenko
- Yes this is the second one from them this month. I suspect the future will bring more.
- Don't test how (implementation), test "the intention behind the system".
- Not... "has been called with". Instead try... "result is as expected".
- There is definitely a time and a place to test implementation. Maybe they don't live in your test suite forever, but if they help you develop working software faster... write them.

Skims and Honorable Mentions

Bytes #252 Your Weekly Dose of JS newsletter from tyler@ui.dev.
Books That Helped Me Become a Tech Lead by Frank Rosner – definitely going to have to come back to this one.
🔐 Session-Based vs. Token-Based Authentication: Which is better?🤔 by Fidal Mathew – Skimming and perusing the comments led me to Beyond the login page mentioned above.
dev.to Meme Monday – ah programming humor.
Bytes #258 Better off Zed – Open source, faster than VS Code from the creators of Atom? I'm listening...

Micro0001—Pattern: Custom Jest Error Messages

piratematt — Thu, 07 Sep 2023 16:04:57 +0000

Series: Micro Blogs
Entry: Micro0001—Pattern: Custom Jest Error Messages
First Published: September 2023
Tags: microblog, jest, tdd, react

Micro Blogs Series – Short posts of lessons learned, patterns, revelations, tips, missteps, etc. from the trenches of crafting software.

🔴 TL;DR

Wrap your Jest expect statements with a try/catch block and add additional context to errors then re-throw them. This way the test failure itself is sufficient to understand what went wrong. Example from asserting a reducer deep-copies state reference values:

for (const [key, value] of Object.entries(reducedState)) {
  // we can ignore any non-reference values
  if (typeof value === 'object') {
    try {
      expect(reducedState[key]).not.toBe(initialState[key]);
    }
    catch(err) {
      err.message = `state.${key} —> ${err.message}`;
      throw err;
    }
  }
}
\

Props to Aart den Braber for the inspiration! Note: this test only checks one-level deep; it is not a true deep-copy.

🌆 Background: TDDing a Reducer

Recently I was developing a module for use with React.useReducer. I was using a few objects within my state: an array and a couple of Set’s. Long story short, as TDD was driving the design of my module, I encountered failing tests resulting from one the reference object values persisting longer than expected. If I recall correctly, one of my state manipulations ended up modifying a set that I was reusing across tests as expected data, rather than cleanly manipulating a set from a deep-copy of state as a reducer should. Oops! 🙈

I successfully found a bug in my code. What’s next? Following TDD, the first step was writing a failing test covering the situation: test that equality (Object.is because that’s what React leverages) fails for any reference values within state (typeof === 'object') when running the reducer.

With my test written and failing, I took the simplest path to get started—hardcoding each key that was storing a reference value. Taking the next TDD step, I looked to refactor. I realized my current implementation would require me to manually update my test and solution anytime I added a new reference value to state, and I knew future-me was highly unlikely to remember to do so. Refactoring, I modified my test to loop through each key-value pair and check for reference values. Now if/when I add new reference values to state my test will continue to serve its purpose! My test code ended up looking something like this:

for (const [key, value] of Object.entries(reducedState)) {
  // we can ignore any non-reference values
  if (typeof value === 'object') {
    expect(reducedState[key]).not.toBe(initialState[key]);
  }
}

This worked great, but it created a new pain. When a value fails to pass the assertion, no information about its associated key is included in the error message, requiring additional work upon failure to diagnose the culprit.

🦓 Pattern: Custom Jest Error Messages

I’ve wanted custom jest error messages for a while. It’s not a frequent desire, but it comes up almost every time I write assertions inside loops. So, every now and then I search the interwebz to see what advice is out there. Most frequently, I find others advising me to add an additional package that provides this functionality. Sure this works, but I try to avoid increasing the attack surface and license management burden when I can. Custom Jest error messages never felt like enough functionality to justify the additional work. Particularly when adding a simple log statement—in the infrequent event of test failure—is sufficient to track down the specific scenario.

Still… I’d rather have the test failure itself tell me exactly what was wrong, so once again I dove into the wilds of the internet. This time I found a pattern that was simple to parse and didn’t require an entirely new package! Props to Aart den Braber for the inspiration!

The pattern: wrap your Jest expect statements with a try/catch block and add additional context to errors then re-throw them. Now my test now looks something like this:

for (const [key, value] of Object.entries(reducedState)) {
  // we can ignore any non-reference values
  if (typeof value === 'object') {
    try {
      expect(reducedState[key]).not.toBe(initialState[key]);
    }
    catch(err) {
      // Pattern props to: https://aartdenbraber.medium.com/custom-error-messages-with-jest-for-assertions-821c69e72389
      err.message = `state.${key} —> ${err.message}`;
      throw err;
    }
  }
}
\

This way I know exactly which referential value is causing the failure directly from the error message, while simultaneously retaining all the inbuilt goodness of the error jest already throws.

piratematt.com v3—Upgrading to Next.js 13

piratematt — Wed, 19 Jul 2023 15:30:53 +0000

Series: Personal/Professional Website
Sub-series: piratematt.com v3
Entry: 02—Upgrading to Next.js 13
First Published: July 2023

Plans never survive contact with reality

This wasn't supposed to be my second entry, but much like the Agile Manifesto I value responding to change over following a plan. Next.js released their next major version, Next.js 13. Things are different… How different is what this entry chronicles. Well… chronicles for a simple static site that is exported and served via github pages. If you're looking for a full comparison I suggest you start with their own blog post on version 13. It's where I started and I found it helpful.

The origin of the pivot

This upgrade journey began when I reached for Next.js to start a new project with a friend and was surprised by the app router. Caught flat footed I scrambled to explain a framework I no longer understood. Rather than simply reverting to an older version I was familiar with, we took some time to read through the docs and get the new lay of the land. Long story short, the project itself is on hold while my friend gets settled into a new job, so I switched my effort to understand Next.js 13 to my personal site. It certainly doesn't need updated, but I want the practice, so here we are.

The work ahead of me

Borrowing a technique from TDD (I'm still new-ish to TDD, but I've been making a concerted effort to practice it lately), I got started by creating a lightweight need/want TODO list. This enables me to give ideas the space they deserve as they crash into my brain, but in a way that lets me keep focus on the small step I'm trying to take when the crash occurs. My initial list was built from reading through the aforementioned blog post as well as the upgrade guide. These initial reads are done somewhere between a skimming pace and a studying pace. The goal isn't to recall everything, but to start to get a feel for the lay of the land. What should I look out for? Where can I read more about how to get XYZ working? Should I switch to the shiny new ABC way of doing things, or stick with what's already got working?

I'm not going to include my actual TODO list because it's not a good communication tool. It's a good working tool. It's constantly modified; items get added, removed, re-added, and re-removed all the time. You get the picture. To outline the work ahead of me I'll split things into two lists.

List 1: The differences in Next.js 13 I want to tackle in this effort.

Switch to the new next/font.
Migrate from the pages router to the app router.
Minimize my use of the use client directive (prioritize server side components).

List 2: A simplified overview of how this reflected in my TODO list.

[ ] upgrade to latest Next.js version
[ ] upgrade ESLint version
[ ] upgrade to Built-in Font
[ ] switch from pages to app router
- [ ] identify server vs client components and update appropriately
- [ ] rework how layouts work
- [ ] refactor <Head> components to metadata exports
- [ ] refactor from styled-components to CSS modules (styled-components require runtime javascript and therefore must be client components)
- [ ] refactor from pages/404.js to not-found.js file

Task 0 – Create a home for the effort and update to the latest versions

I wanted a safe isolated place in my github repository where I could tackle this update effort, so I kicked things off by creating a new branch:

git checkout -b next13
git push origin next13

Now I have a safe space I can frequently push my WIP (work in progress) states to just in case my local machine melts.

So… it turns out I'm already using Next.js 13, "next": "^13.1.6", to be exact. What a twist! ^ref. How did I uncover this? As I was doing my first readthrough I saw they called out that <Link> components no longer needed a child <a> tag to function, and I thought to myself I've never had to do that to get <Link> to work. So I took a quick peek at my package.json git history… and, yup, I've always been on Next.js 13. Fortunately for my sanity it's clear looking at the nextjs.org docs, that there has indeed been a recent switch to the app router, so my confusion wasn't merely the result of some fever dream. 🤞🏻being on Next 13 already makes my “upgrade” easier.

To get the latest and greatest for both Next.js and ESLint, I run:

npm i next@latest react@latest react-dom@latest eslint-config-next@latest

This puts me at the following version (extracted from package.json) 👇🏻

{
  "dependencies": {
    "next": "^13.4.7",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
  },
  "devDependencies": {
    "eslint-config-next": "^13.4.7",
  }
}

I then execute npm run lint in my terminal and fix any reported issues (that aren't a future TODO list item).

Task 1 – Switch to the new `next/font` and away from the `@next/font`

After a brief read through the Font Optimization section of the upgrade guide, I try the following:

// import { Share_Tech_Mono } from '@next/font/google';
import { Share_Tech_Mono } from 'next/font/google';

After a bit of manual checking, I realize this is all I need to do, so I also go ahead and uninstall the old @next/font and delete the commented out import line.

npm uninstall @next/font

That was quick and painless! Another item checked off my TODO list! 🎉

Task 2 – Bye-bye “Pages” router, hello “App” router

I wish I could tell you this was an easy process with clear steps that you can follow in the same order I accomplished them in and succeed, but it ended up being more of an ever expanding FILO (first in, last out) stack of TODOs. I'll do my best to use headers to provide some clarity, but things may jump around a bit.

Task 2.1 – Refactor the home page to use the app router

Trying to take the smallest step I could, I set my targets on replacing the existing home page, pages/index.tsx, with a “hello world” home page powered by the app router. To get started, I added an /app directory and placed a hello world page.tsx file within it.

// app/page.tsx
export const metadata = {
  title: 'Home – piratematt.com'
};

export default function HomePage() => {
  return (
    <h1>Hello Home Page</h1>
  );
}

Then I changed the name of my pages/index.tsx to pages/old_index.tsx to prevent conflicts, and restarted my dev server:

npm run dev

A quick navigation to http://localhost:3000/ showed me my shiny new “hello world” home page. Great! Things are moving along. Next I simply copy the contents of my old home page, styled-components and all. Optimistically I refresh my page. Uh oh, things are no longer working. None of the updates I made to _app.tsx and _document.tsx to get styled-components working are taking effect. Hmmm… time to add a new task to the stack.

Task 2.2 – Refactor `_app.tsx` and `_document.tsx` to the new `app/layout.tsx` structure

Skipping a lot of narratively unnecessary trial and error let's just say this is where my desire to preserve my use of styled-components left me. I discovered each page/component leveraging styled-components needed the use client; directive, which felt wrong because most of my page content is static “brochure content” and has no business not being rendered server-side. To that end, I elected to add another task to my quickly growing stack: refactor to CSS modules and prioritize server-side rendering. (Yes I realize that exporting this specific Next.js project makes it of little consequence in the end. Nevertheless, I saw value in practicing limiting my client-side components.)

Task 2.3 – Refactor styled-components (CSS-in-JS) to CSS modules

This is a task that gets repeatedly put back on the top of my task stack as I tackle pages one at a time. Rather than bore you with that repetitive process, I'll leave a sample of some salient details and move on. Overall the process was fairly simple. Rather than having styles declared inline within my .tsx files, declarations are refactored/extracted to a global.css file and a specific .module.css file which are subsequently imported. If you want to read more, I suggest the Styling section of the upgrade docs.

Before

Global styles and themes were established in a config file in the root directory.

// themeConfig.js
export const theme = {
  colors: {
    bgDark: '#000000e6',
  },
};

export const GlobalStyles = `
  /* redacted for brevity */
`;

These global styles and themes are applied in the pages/_app.tsx file.

// pages/_app.tsx
import { ThemeProvider } from 'styled-components'
import { GlobalStyles, theme } from '../themeConfig';

export default function App(/* redacted for brevity */) {
  return (
    <ThemeProvider theme={theme}>
      <GlobalStyles />
      {/* redacted for brevity */
    </ThemeProvider>
  );
}

Within each component “CSS-in-JS” is written leveraging string interpolation to access the theme variables where desired.

// Footer.tsx
import styled from 'styled-components';

const FooterWrapper = styled.div`
  background: ${(theme) => theme.colors.bgDark};
`;

// Usage of `<FooterWrapper />` in component render redacted for brevity

After

Global CSS and theme variables are set in an app/global.css file. Theme variables are set using the :root pseudo-class selector to make them available everywhere.

/* app/global.css */
:root {
  --bg--dark: #000000e6;
}

body {
  /* redacted for brevity */
}

These globals are then included in the base layout of the app router. There is no need to specifically apply them via className or any other method. This is taken care of for us by Next.

// app/layout.tsx
import './global.css'

// default export redacted for brevity

A .module.css file is created for specific components/pages. It is best practice to use lowerCamelCase for class names as it is easier to dot-access them after they are imported into your component/page files.

/* components/Footer.module.css */
.footerWrapper {
  background: var(--bg--dark);
}

This module specific CSS is imported into a styles variable and then applied where desired by specifying a className for whichever HTML tag or React component you want the styling to apply. Next handles unique class name generation, bundling, etc. all for us.

// components/Footer.tsx
import styles from './Footer.module.css';

export default function Footer() => {
  return (
    <div className={styles.footerWrapper}>
      {/* redacted for simplicity */}
    </div>
  );
}

Pros – Overall, it's fine. Some things are harder/worse, sure, but I found no hills I was willing to die on.

I used significantly less use client; directives to get my CSS-in-JS working.
There's no extra system to learn, it's normal CSS.
Next handles all the hard stuff without customization: unique class name management, bundling, etc.
CSS modules keep the CSS that's affecting your components alongside the components themselves and not hidden away in some massive CSS file.

Cons – Overall, CSS variables are less powerful than systems like SASS/Less/CSS-in-JS.

You can't use CSS variables in media queries yet, so common breakpoints must be manually kept in sync.
You can't nest selectors in CSS, necessitating more lines of CSS to do the same thing.

After I had fully refactored all components and pages to CSS modules I made sure to uninstall the no longer necessary styled-component packages and removed the pages directory entirely. (Note: I made sure I had a commit to roll back to just in case I missed something. You might want to do the same if you're facing a similar migration effort.)

npm uninstall styled-components babel-plugin-styled-components @types/styled-components

At some point in my conversion process I found that my old way of applying my font needed modification to work with CSS modules, so I paused where I was and put another item on the top of the task stack.

Task 2.3.2 – Update font usage for CSS modules

Previously I was using a class name and importing the font into multiple files. Example 👇🏻:

// components/Footer.tsx
import { Share_Tech_Mono } from '@next/font/google';
import styles from './Footer.module.css';

export default function Footer() => {
  return (
    <div className={`${styles.footerWrapper} ${Share_Tech_Mono.className}`}>
      {/* redacted for simplicity */}
    </div>
  );
}

Now I set a CSS variable, once, in the base layout of the app router and simply use it in whatever component/page CSS module file I want

// app/layout.tsx
const shareTechMono = Share_Tech_Mono({
  weight: '400',
  subsets: ['latin'],
  variable: '--font--share-tech-mono',
  fallback: ['monospace'],
});

export default function BaseLayout(/* redacted for brevity */) {
  return (
    <html lang="en" className={shareTechMono.variable}>
      {/* redacted for brevity */}
    </html>
  );
};

/* components/Footer.module.css */
.footerWrapper {
  font-family: var(--font--share-tech-mono, monospace), monospace;
}

The order of task stacking in this narrative and their actual order have well and truly diverged. For the sake of clarity we'll say my next discovery that made its way to the top of my stack arose during the conversion of my second page from the pages router and to the app router.

Task 2.4 – Refactor my second page to use the app router

I often find the first task I take on when refactoring to a new framework/pattern to be a relatively straightforward process. The issues only really start to rear their heads when I tackle a second task. Converting my second page was no exception. The first thing I noticed was that I had too many page.tsx files open in my editor and that is a hill I'm willing to die on. It's hands down my least favorite commonly accepted pattern in all of development. Even one index.js file irks me, because rarely is that file actually an index. Grrr. Anyways, I'll step away from the soapbox and digress.

Task 2.4.1 – Avoid `page.tsx` hell

I wish I could remember who introduced me to this pattern that alleviates my frustrations, but alas I do not remember. The strategy itself is fairly simple. Take on a little bit of extra boilerplate now, so the rest of your time working in the codebase is significantly more enjoyable. Every page of mine adopts the following pattern. page.tsx is pure boilerplate, and actual code is written in files that follow this pattern: UsefulName.page.tsx. For instance, a page accessible at http://localhost:3000/second-page would look something like👇🏻.

This boilerplate page:

// app/second-page/page.tsx
import SecondPage, { metadata as pageMetadata } from './Second.page';

export const metadata = { ...pageMetadata };

export default SecondPage;

Which serves the contents of this file where my actual code lives:

// app/second-page/Second.page.tsx`
export const metadata = {
  title: 'Second – piratematt.com',
};

export default function SecondPage() {
  /* redacted for brevity */
}

Note: I fully expect this boilerplate pattern to be rendered unnecessary by a future Next.js update and/or a configuration. I know I'm not the only developer willing to die on this hill. I spent some time digging around to see if it already existed, but I exhausted the amount I was willing to spend trying to alleviate my frustrations using “official” means and methods. Sometimes you have to know when to go with the sub-optimal solution you can do quickly and confidently over the optimal solution you don't yet know.

We’re once again departing from the actual order of events, but for the sake of the narrative let’s say this is when I came upon my next task for the top of the stack. My second page required a different layout than any of my other pages. Okay, it didn’t need a different layout, but I’m using one because I want to.

Task 2.4.2 – Handle multiple layouts; refactor away from the getLayout pattern

Previously I was using the page.getLayout pattern to dynamically pull in a different layout for a single, on-off page. I could have duplicated layouts, but adhering to DRY (don't repeat yourself) seemed the wiser path. Within the app router, I failed to find a way to repeat my getLayout pattern. Instead I wound up refactoring my code structure to make use of route groups and several nested layout.tsx files.

Oddly enough—considering my previous rant about page.tsx hell—I adopted a slightly different pattern to prevent layout.tsx hell. This is likely due to the fact that I only ever plan on having two layouts, but I knew I'd want to support n pages. When things were all said and done, I ended up with 3 layout.tsx files, 2 route groups, and 1 CommonLayout.tsx component.

Before I dive into example code, let's talk briefly about route groups. Simply put, route groups are a special naming convention for a folder, (normal-layout) for example, that enable us to logically group pages together without adding to the route's URL path. So app/(normal-layout)/about/page.tsx is accessible at http://localhost:3000/about and app/(abnormal-layout)/second-page/page.tsx is accessible at http://localhost:3000/second-page. With that out of the way, consider the following example code.

First we have the CommonLayout component that is imported and utilized in every layout.tsx file.

// app/CommonLayout.tsx
import NavHeader from '../components/NavHeader';
import Footer from '../components/Footer';

export default function CommonLayout({
  abnormal,
  children,
}: {
  abnormal: boolean,
  children: React.ReactNode,
}) {
  return (
    <>
      <NavHeader abnormal={abnormal} />
      <div>{children}</div>
      <Footer abnormal={abnormal} />
    </>
  );
}

Next up we have the base layout that applies to every page the app router serves. You can see it's only doing the bare minimum, leaving the specifics of the layout up to each route group.

// app/layout.tsx
// styles, fonts, etc. redacted for brevity

export default function BaseLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <html lang="en">
      <body>
        {children}
      </body>
    </html>
  );
};

Then we have our two route group layout.tsx files, which are nearly identical, except for a single boolean switch.

// app/(normal-layout)/layout.tsx
import CommonLayout from '../CommonLayout';

export default function NormalLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <CommonLayout abnormal={false}>
      {children}
    </CommonLayout>
  );
};

// app/(abnormal-layout)/layout.tsx
import CommonLayout from '../CommonLayout';

export default function AbnormalLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <CommonLayout abnormal={true}>
      {children}
    </CommonLayout>
  );
};

With our two route groups now setup, our pages reside and are accessible at (note: I removed my Second.page.tsx pattern to simplify things):

First/Home Page lives at app/(normal-layout)/page.tsx and is accessible at http://localhost:3000.
Second Page lives at app/(abnormal-layout)/second-page/page.tsx and is accessible at http://localhost:3000/second-page.

Originally I didn't even have app/layout.tsx. I only had two layout files, one in each route group, but the next task we’re throwing on top of the stack made it a necessary refactor.

Task 2.5 – Refactoring `pages/404.tsx` to `app/not-found.tsx`

The content of my 404/not-found page was a straightforward port. I simply moved the content from pages/404.tsx to app/not-found.tsx. Figuring out what level the layout needed abstracted to and how to minimize repeating myself took some trial and error. Long story short my base app/layout.tsx doesn't do any of the actual layout lifting. As you can see above, that's all handled by my CommonLayout.tsx file.

Previously I had something like this, leveraging the aforementioned getLayout pattern:

// pages/404.tsx
import Layout, { PageType } from '../layouts/MainLayout';

const Page: PageType = function Page404 () {
  return (
    <>{/* redacted for brevity  */}</>
  );
}

Page.getLayout = function getLayout(page) {
  return (
    <Layout>{page}</Layout>
  );
}

export default Page;

Now I have:

// app/not-found.tsx
import CommonLayout from './CommonLayout';

export default function Page404() {
  return (
    <CommonLayout abnormal={false}>
      {/* redacted for brevity */}
    </CommonLayout>
  );
}

Task 2.6 – Refactoring `<Head>` components to `metadata` exports

If you have extra sharp eyes, you may have picked up on the way the app router handles page metadata when I was talking through my page.tsx boilerplate. No longer will Next extract the <Head> component from a page file. Instead you simply export a named metadata object which Next ensures gets converted into header tags and included in the server response. If you attempt to export a metadata object from a client-rendered component/page with the use client; directive, you'll find Next yells at you. You can only modify page metadata server-side.

Example, what previously looked like this:

// pages/about.tsx
export default function AboutPage () {
  return (
    <>
      <Head>
        <title>About - piratematt.com</title>
        <description>A wall of text covering this {'"pirate"'} thing. Complete with a {'tl;dr'}.</description>
      </Head>
      <PageWithTitle title="about">
        {/* redacted for brevity */}
      </PageWithTitle>
    </>
  );
}

Now looks like this:

// app/about/page.tsx
export const metadata = {
  title: 'About – piratematt.com',
  description: 'A wall of text covering this "pirate" thing. Complete with a tl;dr.',
};

export default function AboutPage() {
  /* redacted for brevity */
}

Take-aways & what's next for this series

I like what they're trying to do with Next.js 13 and the app router—be opinionated about structure to increase clarity. The necessity of the use client; directive to leverage state, etc. makes it crystal clear what can be rendered server-side and what requires a client. When all was said and done, I had only a single component that needed the client directive. If it were up to me I'd require a UsefulName.page.tsx pattern instead of just page.tsx but I have a workaround I like well enough to continue using Next.

At the end of the day, if you leverage Next's upgrade guides you won't run into any show-stopping issues when updating to Next.js 13—at least not for a static brochure site. I suspect you may even come to prefer the changes by the end of your efforts, as I have.

What's next in this series? As a part of my upgrade efforts I've taken another look at my planned entries for the remainder of the series and cut it down quite a bit. Next's documentation already does a great job covering some of the topics I had planned, and for some of the others, I simply don't use the associated tools/technologies in this project anymore. Therefore, I've decided to preserve my writing time for other efforts. As it stands now here's the latest and greatest plan:

[x] v3 – Overview & Getting Started
[x] Upgrading to Next.js 13 (this entry!)
[ ] Deploying Next.js to Github Pages
(considering) Final thoughts, conclusions, and future ideas.

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

piratematt.com v3—Overview & Getting Started

piratematt — Mon, 24 Apr 2023 18:51:01 +0000

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!