Nishiki Liu

Vibe check, November 2025

Sat, 22 Nov 2025 18:52:00 GMT

It's been half a year since I've written anything on this blog. Time is passing by faster every day, and I'm reminded by John Mayer's lyrics from Stop This Train:

Stop this train<br /> I wanna get off<br /> And go home again<br /> I can't take the speed<br /> It's movin' in<br /> I know I can't<br /> But honestly<br /> Won't someone stop this train?

I'm now solidly in my mid-30s. My body loudly reminds me of its mortality through lower back pain. I thought it was sciatica; turns out it's arthritis. All those years of poring over lines of code didn't do my back any favors, but this led me to give tai chi a serious try, and that's been a delight.

I've been learning how to attune to myself better. When I feel some spidey sense tingling, I don't just bottle it up and throw it into the sea of my subconscious anymore. I've been learning how to identify what it is. Happiness, sadness, anger, serenity, shame, apprehension. I'm learning how to listen to and trust my emotions for the first time since I've thrown that all out in my childhood. My incredible therapist has been a guiding compass for me, and I can't thank her enough.

I used to identify strongly as a certain type of technologist: a Rails developer who strives for open, empathetic software. I've since loosened that a bit. I'm just someone who wants to help people, and that can take so many different shapes. The last time I wrote in Rails professionally was over 5 years ago, and being away from the ecosystem has made me come to terms with things like:

Tooling that comes out of the box without convention over configuration is just fine, actually. It invites collaboration with your team to develop your own conventions that works best for you all.
Omakase-less development is good, actually. It forces deliberate decision-making for the tooling that you do use, and it allows you to decide together. When you're in charge of implementing a new abstraction layer, you're writing code specifically for your team, and what an amazing avenue to practice empathy that is.
I'm grateful that Hamburger Helper helped me truly learn full-stack development, but the brain worms have since taken over.

Being relentless about choosing technologies was also so tiring. I used to run flavors of desktop Linux on a Dell XPS 13 in the spirit of only running open software. I then transitioned to a Silicon Mac running Asahi Linux because the hardware was great, but I still only wanted to run open software. Now I'm just running macOS on the same machine. I think past me would've yelled out, "But this isn't running open and ethical software!" I was a little too idealistic and dogmatic. There's no pragmatic end to this line of thought. Instead of being sucked into the void that'll eventually lead to something like trying to consider how the physical materials of my transistors were sourced or if a threat actor tampered with the network drivers of my device, I'm just choosing to use a readily available tool that enables me to build, collaborate, and connect.

I'm learning how to choose my battles and know my own limits.

My ZSA layouts

Tue, 13 May 2025 04:00:00 GMT

I've been a huge fan of ZSA for 4 years and counting. They are primarily a keyboard company and they sell three flagship, split keyboard series—two of which I own one of. I use a Moonlander for the home office and a Voyager for when I'm on-the-go. Both are designed to be ergonomic and aesthetic powerhouses that are highly customizable.

I don't want this to be a blog post about the merits of split keyboards or the joy of mechanical keyboards even though this could easily spiral out of control into one. I want to talk about how I landed on the custom layouts that I've flashed on both keyboards and my thought process for their key placements. ZSA allows folks to customize and flash their own key layouts using their tool Oryx, and it's been a lifesaver. I give props to anyone who uses the default layouts, but they are abhorrently unnatural.

Voyager

I want to start by talking about the Voyager. I've adjusted both my keyboard layouts to mostly be based on this board because it has the fewest keys, making it a common denominator of sorts. The Voyager handles three layers, and I've landed on the following:

Layer 0: Main (Voyager)

The first thing to address is the thumb keys. Unlike a traditional keyboard, the Voyager has 4 total keys available for your thumbs. I'm right-handed, so it only made sense for the top-right thumb key to be Return/Enter and the top-left to be Space. I set the secondary thumb keys to be Command on the left and Right Alt/Option on the right due to how frequently I use them and to somewhat mirror their placement on a more standard keyboard.

Due to its compact nature, I had to get a little creative with the placement of modifier keys. I have Command and Alt available via the thumbs, but I still needed access to Control. Oryx lets us customize a key's function based on action taken: tapped, held, double-tapped, and tapped then held. So to closely mirror a standard keyboard, I've set Z to be Left Control when held and X to be Left Option/Alt when held. That way I don't have to twist my brain when switching between ZSA and standard keyboards.

And the last thing I want to point out are the layer keys. These are keys that allow me to switch into the other two layers when held. My Tab key switches to layer 1 when held and Esc switches to layer 2.

Layer 1: Symbols (Voyager)

This layer enables three main things for me: common symbols, function keys, and the numpad.

The numpad lives on the left-most side of the right split, with 0 living on the top-right thumb key. There's an argument to be made that the numpad should be shifted one column over to the right to be better aligned with home row hand placement, but I decided against that mainly to provide more comfortable access to the - key with my right ring finger.

I've duplicated the use of the ` key, one in the very top-left of the board and one where ' normally is. The top-left is to more closely emulate a standard placement of the key and the ' replacement is because that just made sense in my head. ' becomes " when using Shift, so it should evolve into ` when using layer 1.

Layer 2: Media (Voyager)

And finally, the media key layer. I don't actually use media keys all that often, so this one is fairly sparse. The top row is lined with Volume Down, Volume Up, Mute, Brightness Down, and Brightness Up-the only media keys I actually use.

On the right split, I have arrows keys lined up with my fingers in natural position to somewhat follow the placement of arrow keys on standard boards. On the left split, I have mouse movement keys in case I ever end up in a situation where I don't have a mouse or trackpad available to me. The primary right thumb key is Left Click and secondary is Right Click.

Finally, the left split's primary thumb key is SysRq/Print Screen just so I have access to it at all and the secondary is Change Animation which is a ZSA-specific key that lets you cycle through its lighting styles.

Moonlander

Now for the chonker, the Moonlander. As I mentioned above, I've heavily based this layout on the Voyager's so that I don't have to completely context-switch when switching between the two keyboards.

Layer 0: Main (Moonlander)

As you can see, it's pretty similar to the Voyager's main layout. The main differences are with the additional keys available. The thumb keys are arranged slightly differently and there are also more of them. Instead of 4 total thumb keys, we have 6, so I have them revolving around modifiers primarily.

On the left split, I moved Left Control and Left Alt/Option down one row because it's available, and it's accompanied by ` and left/right arrow keys which come standard on the Moonlander. The additional column on the right constitutes volume controls.

On the right split, the additional row contains up/down arrows, brackets, and -, which I believe is default. The additional column is configured with brightness controls and SysRq/Print Screen for convenience.

Layer 1: Symbols (Moonlander)

This layer is, I believe, identical to the Voyager's, so not much to say here!

Layer 2: Media (Moonlander)

Similar to layer 1, this one's also identical to the Voyager's!

Downloads

If you're a Voyager or Moonlander owner, you can download my layouts at the following links: Voyager and Moonlander. At the time of writing, I haven't written any detailed revision messages, but I will make sure to do so from now on!

If you have any questions or would just like to start a conversation with me, I'm happy to engage over email or the fediverse.

Vibe check, April 2025

Mon, 21 Apr 2025 00:00:00 GMT

It's a sunny Sunday in SoCal. I'm sitting on a dark rattan chair right outside a local coffee shop with my laptop on my lap, as its namesake intended, angling away from the rays. There's a slight breeze and I'm watching the leaves of a nearby tree quietly dance. There's been quite a bit of change in my life as of late and felt I haven't had a chance to process it all due to being in go-go-go mode. This is me slowing down and organizing my thoughts & feelings in writing.

On the career front, I "graduated" from Atomic, a Silicon Valley venture studio, to be a full-time employee of Elly, one of its portfolio companies. I was at Atomic for almost 4 years, the second longest time I've stayed at one company. I ended up making the jump for a few reasons, but the biggest amongst them was that I really like the team. At Atomic, one of my responsibilities included augmenting engineering teams of portfolio companies, and I've been helping build Elly's product as well as engineering team for almost two years. That was more than enough time for me to decide to want to join full-time.

Elly is built on a tech stack that I've traditionally shied away from: full-stack, serverless TypeScript. As someone who has preferred to stay in the Ruby ecosystem as much as possible, I'd imagine past me would be shocked at this transition, but it's the people that I work with that matter the most. I don't want this post to become a technical one so I'll spare the details for now, but the way ES6 enables having small, modular files with its associated tests sitting alongside them is also really quite nice.

On the personal front, I moved back closer to LA proper after being on its outskirts for a couple years. There really is something for everyone here. When friends tell me that they don't like LA, I tend to believe it's only because they haven't found their community in the city yet. As an Asian American third culture kid who has lived in less diverse places, it's comforting to live somewhere where a vast variety of cuisines are a short drive away and I have the opportunity to practice multiple languages. I'd love to find a Mandarin as well as Japanese tutor so I can be at least business-level in both. I'm natively conversational, but my vocabulary is sorely, sorely lacking.

I also started taking Brazilian jiu-jitsu & MMA classes. I've never practiced martial arts before, so this has been a breath of fresh air. I wanted a way to stay active while learning a new skill, so why not self-defense? It's been challenging, an amazing workout, and a great way to build community.

As for everything else going on in the world, all I can really say is I'm worried. The US is leaning heavily fascist, we're at a point where open corruption is seemingly without consequences, there are multiple military conflicts occurring outside the borders, and international relations seem generally shaky.

I realize having this small corner of the Internet isn't much, but I love it as my outlet. I migrated it from Jekyll to Nuxt and also from GitHub Pages to Netlify. The title of this post is inspired by Dave Rupert's blog.

I'd love to write more frequently here.

Finding boosts

Thu, 10 Oct 2024 01:30:00 GMT

When I first wrote my first line of HTML back in the early 2000s and saw text appear on the screen, I was elated. It felt like magic; this wasn’t just any instance of mashing a keyboard and seeing something on the screen, it was a deliberate act of formatting and producing a document to be shared on the web. I created this text. I experienced my first boost.

Something that I’ve found so magnetic about writing software is that there are so many opportunities to find little boosts no matter what I might be working on. In my early days, pointing a browser at a local HTML file was my gateway. Nowadays, I make it a point to try and maximize boosts through things like:

Refactoring files so they’re easier to read without language servers or AI copilots.
Writing comments to help future me and team.
Reading code and comments later and quickly understanding what’s going on.
Optimizing server response times and seeing latency graphs go down.
Writing tests and making them green.
Fixing bugs and supplying tests to guard against regressions.
Pair-programming with teammates and reaching ah-ha moments.
Taking advantage of newly shipped CSS features available on all major browsers.
Using CSS instead of JavaScript where possible.
Using HTML instead of JavaScript where possible.
...and the list goes on and on.

Boosts are different for everyone, but they’re important. They’re critically important, maybe. I think cultivating an environment where the team can find boosts directly affects retention and overall happiness. I’ve definitely left jobs where boosts were discouraged.

I’ve started using that vision as a guiding rule of thumb of sorts. Will doing this thing help build a culture of finding boosts? Yes? Okay, I’m going to do it. You don’t need to be in a leadership position to contribute, although that certainly helps.

What do the wider team’s boosts look like? Do they align well? Do they encourage boosts? Communicating to learn each other’s boosts could unlock something.

Find boosts.

A moment of joy with CSS grid

Wed, 07 Feb 2024 18:56:00 GMT

I was recently implementing a seemingly simple layout that could be boiled down to the following:

Some content then some more content with an image to the right. Seems pretty standard. The catch here, though, is that the image must extend all the way to the edge of the viewport while the text must be contained in a center-aligned container with a max-width. Most of the site's other content must adhere to this invisible container as well.

The markup for this looked something like this:

<div class="image-section">
  <div class="image-section__content">
    <h2 class="image-section__heading">...</h2>
    <p class="image-section__paragraph">...</p>
  </div><!-- .image-section__content -->

  <img class="image-section__image" src="..." alt="..." />
</div><!-- .image-section -->

At this point, I was already using .container in multiple sections, and it was styled like:

.container {
  max-width: var(--container-width);
  padding-inline: var(--container-padding);
  margin-inline: auto;
}

But that wasn't going to fly for this particular section since the image must break out of the container. I couldn't just slap some positioning on the image and call it a day.

I ended up implementing that section's layout in CSS grid:

.image-section {
  --grid-container-width: calc(min(var(--container-width), 100vw) - (var(--container-padding) * 2));

  width: 100%;
  display: grid;
  grid-template-columns: 
    minmax(var(--container-padding), 0.5fr)
    calc(var(--grid-container-width) * 0.33)
    calc(var(--grid-container-width) * 0.67)
    minmax(var(--container-padding), 0.5fr);
  align-items: center;
}

.image-section__content {
  grid-column: 2 / 3;
}

.image-section__image {
  grid-column: 3 / 5;
}

With grid-template-columns, I was able to break down the column structure as two columns for the left and right padding, one for the text content, and one for the image. I used minmax() for the padding columns so that the layout was responsive—the normal container's padding is applied on thinner viewports but should center the content and image on wider viewports.

I used a --grid-container-width variable here to essentially say: I want the content columns to have a max-width of --container-width on wider viewports but otherwise should take the entire viewport width on smaller screens. I subtracted the amount of --container-padding twice to account for the left and right padding columns.

And finally, grid-column on the content and image specified which columns they should live in. The content should only take one column but the image needs to extend all the way to the right of the screen.

I think without CSS grid, implementing this would've been a lot jankier. This is responsive, doesn't add unnecessary markup, and doesn't add any position: absolute; or other hard-to-maintain properties in the styles.

The little joys.

WordPress, the Great Divide, and a build-less experience

Thu, 04 Jan 2024 05:06:00 GMT

I recently worked on a small WordPress project for a client and it felt like the 2000s/2010s again. Vanilla HTML, CSS, JavaScript, PHP, MariaDB, Advanced Custom Fields, and SFTP. NPM wasn't needed. A build step wasn't needed. In some ways, the "DX" in the lens of common workflows today wasn't great, but in other ways, it was amazing. And most importantly, all of that actually didn't matter as long as the end result for the user was good. There are many voices in the web industry that touch on this already, but I wanted to chip in with my own 2¢ here.

Broaching the Great Divide, again

While it's not strictly front-end development, building a fully custom WordPress theme got me thinking about topics that Chris Coyier wrote about back in 2019.

I could have decided to front-load the build process for this site with some JavaScript-based toolchains, Sass, TypeScript, and other goodies, but I deliberately decided against it. The client often works with other shops that specialize in managing a portfolio of websites. After being in contact with some of the stakeholders, it was clear that it's important to lower the barrier of entry for this project as much as possible, especially when I won't be the one maintaining it. As a result, everything on the front end was using vanilla, native technologies. HTML, CSS, and sprinkles of JavaScript.

It felt really good, and it's a testament to how powerful the foundational technologies are. It's also a reminder that the front-of-the-front end is just as important, if not more important, than back-of-the-front end. e.g. With this particular project, there was no back-of-the-front end.

Build-less CSS

I generally use vanilla CSS for most of the projects I touch nowadays, but I wanted to touch on a couple small moments of CSS joy during this project. One of my gut reactions to using a build-less setup was that separating stylesheets like in a Sass or CSS module project was not possible. But it absolutely is. <link>-ing individual stylesheets works perfectly especially in today's HTTP/2 world.

I structured top-level page fields for this project with ACF's (Advanced Custom Fields) Flexible Content field which I named "components." Editors can just pick which components they want to use for a page and in whatever order they like. I wrote the markup for each component in its own template part file and fired off a wp_enqueue_style() per each component's stylesheet in the theme's functions.php. This produced several <link> tags in the end markup, and it didn't require any build step whatsoever. Anything that needed to be shared across stylesheets was tucked away nicely in CSS variables.

(I thought about using WordPress's new block editor and creating a bunch of custom blocks, but I decided against it since that would raise the barrier to entry for any future developers. At the time of writing, every block requires its own node_modules/ and build process, and that's far too much of a headache to deal with.)

Build-less JavaScript

Only a handful of small JavaScript files were needed for this project. There was no need to use anything that required a build step. The most involved JavaScript file I wrote for this project was 23 lines long, and native browser APIs handled everything that I needed.

I wanted to make the website's behavior declarative in the markup as I've written before, so I used data-component attributes in the markup as hooks for each JavaScript file. Each file was structured something like this:

document.addEventListener('DOMContentLoaded', function () {
  const instances = document.querySelectorAll('[data-component="<component-name>"]');
  for (let instance of instances) {
    // ...
  }
});

For things like dynamic image galleries, I reached for dependencies via CDNs which helped me to continue avoiding a build step.

Deploying like the old days

Finally, I got to use an SFTP client again. This was thrilling. Yes, it's not very efficient and is prone to all sorts of human error, but it felt great. Deploying changes is really as easy as drag and drop and that's exactly what I did. I gave the ol' Filezilla another download and dragged a directory over to the production server. Magic.

Closing thoughts

This project was a breath of fresh air since most projects I work on nowadays require some kind of build step, whether that's through NPM or asset preprocessing, and this one didn't. It felt so freeing to write vanilla code and drag it into production. The big thing for me is that I didn't have to think as hard as I normally do for projects.

I'm not saying projects today need to be absolved of build steps or deployed via SFTP. There are very good reasons to not do either for many projects. But I do think that it's a great idea to always evaluate how much complexity is necessary for any project before a single line of code is written. Modern browsers are powerful, and as a result, vanilla HTML, CSS, and JavaScript are powerful. Not all projects are going to be managed by large teams.

Migrating Rails from Postgres to SQLite

Wed, 13 Dec 2023 06:51:00 GMT

I recently migrated a personal Rails project off of Postgres and Redis (for Sidekiq and caching) to SQLite (powered by Litestack). I've been running this app on Fly.io powered by a handful of Docker containers for several months, and it's been accumulating costs in the magnitude of medium American french fries every month. This has been, and remains to this day, a purely for-fun project, so I wanted to reduce costs as much as humanly possible. At the time of writing, Fly.io waives bills that are under the $5 USD mark, so I started brainstorming some ways of making this happen.

My initial thoughts were to perhaps rewrite the app with something like Nuxt or Next.js, deploy it to Netlify or Vercel, and use some NoSQL database. My thought was that if the app stays under 100k serverless function calls a month, I could probably safely stay in a free tier. I started toying with this idea, but quickly ditched it since finding a database provider in free tier land proved to be a fruitless endeavor. I also didn't like the idea of having to separate application hosting from where data was being persisted and Ruby is much more of a joy to work in than JavaScript/TypeScript.

SQLite has had a resurgence in popularity as of late, and to my delight, I discovered Litestack which is an open-source Ruby gem that packages up all data-related infrastructure in SQLite. For Rails, it integrates with Active Record, Active Support, Active Job, and Active Cable which would remove my need for separate Postgres and Redis containers in my Fly.io infrastructure. After seeing how easy it looked to integrate into an existing project, I decided to give it a whirl.

Installation and revisiting the schema

Installing Litestack was pretty straightforward for a Rails project:

bundle add sqlite3
bundle add litestack
bin/rails generate litestack:install

Once the generator did its work, I then checked to see if I was able to load my existing schema into SQLite. Sadly, I wasn't able to.

Up till this point, I was using Postgres UUIDs as the primary key for all of my tables, so I needed to tweak the schema to use default integer primary keys. I also discovered that Active Record array columns aren't quite supported out-of-the-box, so something like:

t.string :my_array_column, default: [], array: true

...won't work with SQLite.

Since my previous migrations were all no longer compatible with SQLite and there were a handful of column types I needed to rethink, I decided to scrap all db/migrate/*.rb files and start with a brand new migration. I referenced db/schema.rb to scaffold out the bulk of what I needed, and started reading up on supported column types in SQLite.

As a replacement for array columns, turns out JSON types with a SQLite type constraint can be used:

t.json :my_array_column, default: []
t.check_constraint "json_type(my_array_column) = 'array'", name: "my_array_column_is_array"

So I went ahead and replaced all array types with this. I also had a handful of t.jsonb columns for Postgres, but replaced them with t.json for SQLite. It didn't take long before I was able to create a schema that was compatible with the new database and my existing models.

Refactoring caching usage

Prior to Litestack, I was making heavy use of Kredis for caching. Migrating away from Kredis APIs to supporting litecache was just a matter of switching to vanilla Rails APIs:

# Before
Kredis.flag("my_flag").mark(expires_in: 12.hours, force: false)
Kredis.flag("my_flag").marked?

# After
Rails.cache.write("my_flag", true, expires_in: 12.hours)
Rails.cache.read("my_flag").present?

To ensure that my test and development environments were being tested with Litestack, I also needed to declare litecache as the cache store in config/application.rb:

config.cache_store = :litecache

Once I got to this point, my test suite was green again, and I was a pretty happy camper.

Migrating production data

The last bit of the puzzle was migrating production data. Getting production Postgres data into a production SQLite database was a bit tricky since this process involved changing primary key types and column types. I'm also making use of Active Record encryption in some models. That meant I couldn't just export a SQL dump and import it into the schema.

So naturally, I exported each Postgres table into a CSV using the \copy command:

psql -c "\copy table_name to '/path/to/export.csv' delimiter ',' csv header;" postgres://user:password@host:port/db_name

This preps the data in a format where I can easily consume it with a Rake task and import it into the new database, but I still needed to handle encrypted columns. I had some trouble figuring this out. I would have thought that importing the serialized object would let Active Record decrypt at runtime, especially considering the active_record_encryption values in my config/credentials.yml.enc weren't touched.

Regrettably, I didn't end up deep-diving into the nitty-gritty of Active Record encryption to uncover the root cause. I instead ended up exporting the decrypted column values into these CSVs to use in my Rake task, which worked, and I was happy with that for the time being. (I would like to poke around Active Record to learn how encryption is implemented at some point.)

Part of the magic of SQLite is that the database is literally just a file. I ended up using a Rake task on my local machine to import the production data and then SCP'd the database to my production container's persisted volume.

SQLite is rock solid

After having migrated the app, I'm feeling pretty excited. Not only is the app still stable, but my production infrastructure is drastically simpler. I no longer have four containers for the app, Sidekiq, Postgres, and Redis. Instead, I just have one container with a persisted volume. It runs Rails and Litestack with a database, queue, and cache in three separate SQLite files on the volume. I'm able to run everything on a less powerful CPU, reduce RAM, and still have my app as snappy as before.

With projects like LiteFS and Litestream being actively worked on, the future of supporting Rails apps with SQLite replicas is looking promising. SQLite doesn't just work for smaller projects—it can scale.

For my current needs, SQLite perfectly fit the bill. It supports my for-fun project in a much cheaper way, simplifies the infrastructure, and if I have to, scaling it up bit by bit doesn't seem daunting at all.

Replacing ChromeOS with Linux on the 2017 Pixelbook (Eve)

Sat, 15 Jul 2023 03:37:00 GMT

I admit, I absolutely nerd sniped myself this week when I told myself I wanted to install Linux on my 2017 Pixelbook (Eve). This particular Pixelbook is, to this day, one of my favorite pieces of computer hardware. It's incredibly thin and I love how unique it is with its sleek white slate on the back.

Unfortunately, Google drew the Pixelbook on its Auto Update Expiration (AUE) list a while back, saying that after June 2024, the device will no longer receive OS updates. It's such a bummer since it still performs well with a lighter OS like ChromeOS, and I honestly could see myself still using the machine as my daily driver if the M2 MacBook Air didn't come around.

So naturally, I wanted to put Linux on it.

Not just use Linux through ChromeOS or Crostini, but completely replace ChromeOS with it. Chromebooks are generally known to be fairly closed devices since you can't boot from USB drives out of the box. No one thinks of a Chromebook when they're looking for their next Linux machine. Luckily, there are folks out there that have figured it out. Here are the steps that I followed for removing ChromeOS and installing Linux on the Pixelbook.

1. Enable developer mode on the device

First things first, we have to enable developer mode on the Chromebook to access things like Crosh (Chrome shell) which let us modify the system firmware.

Turn the Chromebook off.
Hold Esc + Refresh as you turn it back on.
Wait for a scary prompt that says ChromeOS is missing or damaged. Press Ctrl + D on this screen.
Follow steps to reboot the device. The rest of the steps is a standard ChromeOS installation process, so go through that as well.

2. Enable booting from USB

I stumbled upon mrchromebox.tech, which is run by someone called MrChromebox. After glancing at the updates on the site, I saw that there have been active posts since 2016 and the latest release was in May of this year. An active project was a very good sign. (The website has a ton of information that gets into the internals of Chromebooks, so check it out if you're so compelled.)

I then checked the supported devices page to see if the Pixelbook (2017, Eve) was listed, and to my delight, it was. After digging around various Linux-on-Chromebook articles, it seemed like modifying the device firmware was important to allow booting from a USB drive, so I clicked into the firmware utility script page where he outlines some commands that pull Bash scripts which are mirrored on GitHub.

From here, I cracked open a Crosh shell. Here's how to do that:

Ctrl + Alt + T to open a Crosh window.
Execute shell to jump into a proper shell from there.

I then executed the firmware utility script:

cd; curl -LO mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh

Luckily this script provides some nice step-by-steps in the CLI. I picked 1) Install/Update RW_LEGACY Firmware and picked further options that enabled boot-from-USB as the default device behavior.

3. Plug in the Linux USB drive

Presumably you have a USB drive with your preferred flavor of Linux on it already. If not, go do that. I ended up grabbing a copy of Elementary OS for this project and put it on an ancient 8 GB USB drive. Plug it into the Chromebook.

Now, reboot the device. You should see a scary screen that warns you about the device being in developer mode. Ignore it and press Ctrl + L to allow the device to boot from the USB drive. Wait until the device is able to successfully boot from the drive, but the rest of the way should be a standard Linux installation process!

The screen will be upside down on the Pixelbook, so flip your device around to get the orientation right or just use your finger to tap through the flow on the touchscreen.

4. Fix screen orientation and brightness (Pixelbook and Ubuntu-specific)

This step can be ignored if you're not on a Pixelbook and not using an Ubuntu-based distribution.

There is some further tweakage needed to fix the screen orientation and enable screen brightness adjustments on the Pixelbook on an Ubuntu-based distro. You've probably already noticed everything being upside down, but that can be fixed by navigating to the OS display settings and adjusting rotation config there.

To be able to adjust screen brightness (since by default it has everything at 100%), open terminal, and using your editor of choice, sudo edit the /etc/default/grub file. You'll need to make sure that the GRUB_CMDLINE_LINUX variable is set to the following:

GRUB_CMDLINE_LINUX="i915.enable_dpcd_backlight=1"

You can then apply these changes by running sudo update-grub and giving your device a restart. Make sure to always press Ctrl + L when seeing the scary developer mode screen again. You'll need to do this each time you reboot.

Live, laugh, love

And voila! The end-of-life'd Chromebook is now a healthy Linux machine with no end of life in sight. I always get excited when working with outdated tech because there's so much more that can be done with them than corporations lead us to believe. Installing Linux on these devices gives them so many more years of usage and saves a good deal of money. If you made it to the end of this article, then I commend you for making the choice of Linux-ifying your Chromebook.

I'm also happy to chat further with you over email or the fediverse.

How to: Selenium with Chrome extensions

Tue, 21 Mar 2023 05:12:00 GMT

When developers chat about browser automations, Selenium is one of those tools that’ll get mentioned in every conversation. It has native language bindings with C#, Ruby, Java, Python, and JavaScript, so it’s super flexible. This is an overview of how to use Selenium to automate Chrome extensions with JavaScript, but the concepts can be generalized to fit your browser and language of choice.

Setting up the project

First things first. Let’s fetch the selenium-webdriver NPM package.

$ npm install --save selenium-webdriver

Make sure you have the following installed on your system as well:

Google Chrome
Chromedriver (alternatively, you could also install the NPM package)

From there, we can set up a new Node.js script that will fire up a new Selenium Chrome instance.

// selenium.js (or anything you want to name this file)

(async () => {
  const { Builder } = require('selenium-webdriver');
  const chrome = require('selenium-webdriver/chrome');
  const driver = await new Builder().forBrowser('chrome').build();
})();

Starting Selenium Chrome with extensions

Now this is where things get interesting. There are multiple ways to add extensions to Selenium Chrome.

Method 1: Loading with a local directory

This is likely what most people need when automating using extensions. If you already have the local extension build on your machine, you can just use that. Let’s add that into the script.

(async () => {
  const { Builder } = require('selenium-webdriver');
  const chrome = require('selenium-webdriver/chrome');
  const options = new chrome.Options();  // <------
  options.addArguments('--load-extension=/path/to/extension/build');  // <------
  const driver = await new Builder().forBrowser('chrome').setChromeOptions(options).build();  // <------
})();

Method 2: Loading with a CRX file

CRX files are Chrome extension files. They are extensions bundled up into one file for nice portability. When you want to load in an extension that you aren’t actively developing, this might be the only way to do so. CRX files are obtainable using other extensions like the CRX Extractor/Downloader or online tools.

Once you have a CRX file, you can load it in like so:

(async () => {
  const { Builder } = require('selenium-webdriver');
  const chrome = require('selenium-webdriver/chrome');
  const options = new chrome.Options();
  options.addExtensions('/path/to/extension.crx'); // <------
  const driver = await new Builder().forBrowser('chrome').setChromeOptions(options).build();  // <------
})();

Interacting with extensions

If your extension has its own page that opens in a browser tab or as a pop-up, chances are your automation needs to interact with the associated DOM elements. The way to do this is to change Selenium’s currently active window to the extension’s. Selenium’s windows API lets us accomplish this.

Each window has an associated window ID, which is a set of randomized alphanumeric characters. You can get the current or full list of all windows in the browser session with a method call.

const currentWindowHandle = await driver.getWindowHandle(); // => This returns a `string`
const windowHandles = await driver.getAllWindowHandles(); // => This returns a `string[]`

And you can switch the currently active window like this:

await driver.switchTo().window(windowHandles[0]);

All driver calls are for the currently active window. That means we could write something like this, too:

// Store all window handles in a variable.
const windowHandles = await driver.getAllWindowHandles();
let windowHandleIndex = 0;

// Keep switching to the next window until we open one with a title value of
// "My Extension".
while (await driver.getTitle() !== 'My Extension') {
  windowHandleIndex++;
  const nextWindow = windowHandles[windowHandleIndex];
  await driver.switchTo().window(nextWindow);
}

// Make Selenium driver calls per usual.
await driver.findElement(By.xpath('//button[contains(text(), "Submit")]')).click();

Closing thoughts

As mentioned earlier in this post, these concepts can be applied to different browsers and languages. Loading local extensions for Firefox or Safari can be done in similar ways, and CRX files can be used for all Chromium-based browsers. (Looking at you, Microsoft Edge.)

Browser automations can really take us a long way as developers, and it’s nice knowing how to throw browser extensions into that mix. While we commonly use them for end-to-end testing, the use cases really can span anything we want.

I hope that this article proves useful to others out there, and keep building awesome software!

Our little universes

Sun, 29 Jan 2023 06:15:00 GMT

I’m currently writing this from the third floor of a creaky hotel in a small Japanese town where I spent a good chunk of my formative years. In the distance, I see some rolling hills peppered with trees that look like they could’ve been drawn by grade schoolers with dark green crayons. Thick, angry clouds are slowly migrating from north to south and a breathtakingly blue sky is staring down between them. Way back when, this used to be my entire universe.

Having bounced back and forth a lot between the US and Japan as a kid, I felt a lot of magic every time I visited Japan. There were revolving sushi bars, anime characters used in store ads, and extended family who I love very much. I took some time to catch a glimpse of my old elementary school where I made lifelong friends and solidified my grasp of the language. I’m reminiscing over how we used to run around outside in the playground and play baseball in sandy gravel as kids.

Spending time back in my second home town as a slightly jaded adult, I noticed that things seem so much less magical. This is probably because I understand much more now compared to when I was a kid, but it got me thinking about how everyone has this process of their universes expanding over time and that changes their lives forever. We’re just chugging along on this train of life collecting new experiences and those new experiences shape how we view everything.

There’s something kind of magical about this idea though. My grandpa is 90 this year. He isn’t in the best health at the moment, but is well enough to crack some jokes at the dinner table. My cousin has two kids. Those kids are my grandpa’s great-grandkids.

Great-grandkids. Bonkers.

On my trip to Japan this year, we have four generations of family members all having dinner together, all with different experiences, different world views, and different universes. All of our universes are still expanding. Colliding. It’s like a cosmic event.

I know I’m running this metaphor into the ground but it’s really making me appreciate time together, both in a familial and general sense. It helps me frame things in a way that makes judgment evaporate and empathy flood in.

We all have our little universes. That’s magical. Let’s make them collide beautifully.

Rubber bands

Mon, 02 Jan 2023 12:00:00 GMT

Back in middle school, my friend and I entered a science fair competition. The objective was for teams of 2 students to design, build, and use a catapult to launch a given object as far as possible. (I’m pretty sure it was a ping pong ball, but I don’t quite remember that detail.)

Every team got really fancy with it. They’d be making all these calculations with mathematical formulas, considering things like air resistance, how to maximize the amount of force produced to launch the object, and who knows what else. They consulted the science teachers, wrote things down on paper, and were being really productive.

Meanwhile, my friend and I just loved to launch stuff. The only reason we wanted to enter this thing was to make a propulsion device because we were middle schoolers and that sounded awesome. Looking around and seeing all these teams get so serious with this was honestly kind of anxiety-inducing. Were we not smart enough for this?

We ended up winning this competition.

Our solution? Three blocks of wood, some shoddily put together contraption that would hold a ball steady, and a ton of rubber bands.

I thought about this today because it was just so ridiculous. We didn’t think one second about any numbers or consulted any teachers. We just went, “Rubber bands should work because they launch things. Let’s just use as many as we can.” The school paper interviewed us after the competition and I felt bad we didn’t really have anything super science-y to say. Our big, beaming smiles were in our local paper later that month.

Sometimes, development can be like this. Not always, but sometimes. Most of the time, we should be thinking about things like:

Is it easy for others to understand this?
Is it an efficient use of resources?
How easy is it to make changes to this in the future?

But sometimes, just use rubber bands, which are already easy to understand, super accessible, and pretty easy to manipulate later.

Don’t over-engineer.

The Web pendulum

Fri, 16 Dec 2022 12:00:00 GMT

I think over the years, we’ve been noticing Web trends swinging back and forth in really broad strokes. Back in the 2000s, the rise and fall of skeuomorphism was really apparent. We ended up landing in the land of flat design by the 2010s and dare I say things are beginning to look a little less flat nowadays. Server-rendered applications became overshadowed by single page applications and back-of-the-front-end technologies. Now, we’re starting to see an influx of love for the server again (but on the edge).

At the moment, I’m particularly interested in two seemingly happening trends: privacy and decentralization. Twitter got bought out by Elon Musk and millions of people are signing up for Mastodon accounts across the fediverse. There are no sponsored ads or tracking in sight. They also are publishing more content on their RSS feeds again. 💛

There's a renaissance happening on the Web right now as some are saying, and I'm loving it. It’s the 2020s version of phpBB forums and decentralized protocols.

I’ve been categorizing these sorts of things as part of the Web pendulum in my head. I know the Web is still relatively young and it’s hard to say if these sorts of polarizing trends will continue to happen, but I hope they do. I think through the messiness of it all, we get to learn a lot. This leads to growth for this insane piece of technology called the Internet and it also lets us get a little better at being kind to each other.

Just a little.

Open source chats with Kasper Timm Hansen

Sun, 16 Oct 2022 12:00:00 GMT

Last week I attended the Rails SaaS Conference, which is a brand new conference revolving around Ruby on Rails and entrepreneurship. Despite writing Rails apps for a while now, I haven’t been very involved in the community, so I wanted to branch out a bit and meet the wider Rails community.

The conference was an incredible experience, but that’s not what I wanted to write about today. (Read Eric Berry’s wonderful write-up of the experience if you’re curious on that front!) I wanted to capture some nuggets of wisdom that Kasper Timm Hansen touched on while we chatted on a Hollywood rooftop.

For those who aren’t familiar, Kasper is a former Rails core member who has made major contributions to the framework. I ran into him while scanning around the second floor lobby for a bottle of water, where we greeted each other for the first time. He told me about his 11-hour flight from Denmark and I told him about my 30-minute Uber ride from home. We shared jokes about how I should craft an intricate travel story because I'm a local. (I didn’t end up doing this.) He’s super personable and extremely humble.

Later during the day, I asked him what he’d recommend to someone like me who has aspirations to eventually contribute to Rails. What he said really stuck with me.

Read bits of the codebase at a time

This one was a very new idea to me. I used to have a preconception that in order to contribute to an open source project, a good place to start would be to browse its GitHub issues or something similar. Kasper suggested that reading little bits of the codebase at a time would be a good first step.

No one understands Rails 100%. There are tens of thousands of lines of code with new contributions all the time. Reading bits over time, whether through api.rubyonrails.org or source code, with the intent to understand will help someone like me get a foot in the door by accumulating some domain knowledge.

In Kasper's own words:

"I like to think of reading the layers of code as drilling into the ground, viewing the different sediments until you hit bedrock (and then you know this piece). Then picking a different spot to drill into, so you learn bit by bit, but enough that you have a solid understanding for one piece."

Reading leads to learning

Library code is very different from application code. Code that is kosher in a consumer-facing application might not fly very well in a library. There are many more nuanced considerations like:

What could the downstream impacts of this seemingly tiny change be?
How difficult might it be to maintain this change over time across different people?
There are deprecation cycles in libraries—you can't just yank things from them. Is this change as "correct" as possible so we mitigate the risk of deprecating in the future?
Is this change targeting too specific a use case to be included in a library?

Reading and learning small bits of the codebase over time will shed light on these things and many more. Kasper brought up a great point that this will probably expose features of Ruby that aren’t quite as common in the application world. Learning all of these things will eventually make you a better programmer in general.

Make learning the goal

Finally, this was a really great mindset shift that he proposed: dive into Rails with the goal of learning. If a contribution eventually results from it, great, but what’s more important is that community members are leveling up from delving into Rails.

I love this community mindset. Rails should be about enabling developers to quickly build maintainable software and its community is aiming to grow everyone into better programmers.

Learnings from Rails would absolutely be applicable in any other project, whether that’s another gem, another framework, or even another programming language. Not everything you learn in private app contexts is applicable to open source, but learnings from open source will almost always be applicable to private apps. In the long run, the value of that outweighs any number of issued PRs, whether accepted or rejected.

Closing thoughts

To sum it up: read little bits of code at a time, slowly gain understanding of a specific domain, and do it all with the intent of getting better. There are a lot of higher-level themes in these ideas like curiosity, empathy, and community, and I’m sure I’ll still be noodling on them for the foreseeable future.

I feel like my chats with Kasper has already helped change how I think about open source, and I hope they can do the same for you.

Thoughts on data

Sat, 10 Sep 2022 12:00:00 GMT

Over the past several years, I’ve been doing quite a bit of work with data. This was through setting up systems to collect data from various APIs or webhooks, transforming the data so it’s more usable, documenting changes, handling errors, etc. And I’ve noticed that this particular area has been the wild west, particularly in the context of teams. There aren’t a lot of “data best practices” floating around in popular tech reading.

This is, in no particular order, a collection of my thoughts around data and how we might better approach it when writing software.

Keep raw data

When you reach out to an API or process webhook payloads for chunks of data, keep everything in the exact format you received it. This could be in a Postgres jsonb column, a separate table, or a separate database entirely. The point is that you’re more likely than not going to need to revisit that raw data at some point whether it’s to correct discrepancies or help debug something. It’s much better to have records of the raw data than to have to collect all of it again.

Normalize that data

Having the raw data is great but don’t be using it directly in your app. Create tables with explicit columns that parse out the relevant bits if you’re using a relational database. Make it easy to understand. Set good indexes. Thinking through this is important if you want a performant and maintainable application.

Use background jobs

Data processing generally takes time, especially when dealing with large data sets. Queue them as background jobs. Stagger them to respect any API rate limits. Have retry mechanisms in place in case anything goes wrong.

Batch things wherever possible

Whenever you’re inserting/updating/upserting rows or documents, batch them. It makes a world of difference when you can do it in one query vs N+1.

Encrypt sensitive bits

Personally identifiable information (PII), credit card numbers, social security numbers, and things of that nature should never be stored unencrypted. If they’re present in the raw data, encrypt that too.

Get agreement on and document events

I use the term “events” loosely here, but a lot of teams like to have analytics data in a platform like Mixpanel, Segment, etc. The data that goes into these platforms need to be well-documented and most importantly have stakeholder alignment. It’s going to be a bad time if everyone is free-handing all sorts of event names with inconsistent payloads that fire at unexpected times.

Bring in your data team

If you have a data division at your org, bring someone in from their team. They’re going to have to access this data at some point too, and their role is entirely around data. Chances are they’re going to have really great suggestions on how to collect, structure, and analyze the data that you didn’t think about.

+918 -24,519

Fri, 02 Sep 2022 12:00:00 GMT

It’s been several months since I’ve last written a blog post so I was revisiting my site this week. I noticed there were some security alerts in GitHub so I decided to upgrade various dependencies to resolve them. To my surprise, this actually broke Remix’s router and resulted in exception explosions whenever I wanted to navigate to any page.

Normally, I’d be more than happy to start debugging what the heck was going on, but I just wasn’t having it that day. I wanted my site to be a joyful little codebase where I push some Markdown and pages get published. This was making it turn into a headache instead.

So I migrated my site back to Jekyll which resulted in 918 lines of code added and 24,519 removed. Now, just to clarify, this is not a post bashing Remix—Remix is a lovely framework. It was just staggering how much more code there was to look at and reason about.

For me at this moment in time, this migration sparked joy. The site is much easier to maintain, the HTML and CSS are valid, and there’s not a line of JavaScript in sight.

Accessing a previous session in NextAuth.js callbacks

Mon, 21 Feb 2022 12:00:00 GMT

Edit: February 22nd, 2022: Balázs Orbán, the lead maintainer of NextAuth, was kind enough to point out on Twitter that achieving this is much simpler by using the built-in getToken() function. Cheers for that! I've left the original article below.

I recently was working on a project that used NextAuth.js for its auth mechanism and needed to support account merging. e.g. If I’m already logged in via an email and password combination, I need to be able to “attach” an account from an OAuth service like Twitter or Discord to that main account.

For folks who use NextAuth, this should already be possible if you’re using the database session strategy, but it’s not quite as obvious if you’re using the JWT strategy. The objective is to have access to the previous session with an identifier you can use to reference a main account/user record. There is a GitHub discussion open to address this very thing, but this article outlines a way you can access previous session tokens in your currently installed version of NextAuth.

General strategy

In Next.js, we’re already able to access request cookies by referencing the req.cookies object provided by the NextApiRequest object in each API route. We can utilize this to reference the session cookie provided by NextAuth. We can configure NextAuth to use a custom session cookie name so we can always reference it without fear of the default name changing in future releases.

The next challenge here is that the session cookie is encoded for security reasons, so we need a way to reliably decode it on the back end. Luckily, we can do that by defining custom JWT encode and decode functions for NextAuth.

1. Get access to the `NextApiRequest` object

As a first step, let’s make sure our NextAuth API route is set up to have access to the request object. Most examples from NextAuth’s docs don’t include the request, so here’s one way to do it:

// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'

export default (req, res) => {
  return NextAuth(req, res, {
    // Your NextAuth config
  })
}

// For TypeScript folks, it'd look like this.
//
// pages/api/auth/[...nextauth].ts
import type { NextApiRequest, NextApiResponse } from 'next'
import NextAuth from 'next-auth'

export default (req: NextApiRequest, res: NextApiResponse) => {
  return NextAuth(req, res, {
    // Your NextAuth config
  }
})

2. Use a custom session cookie name

Next, let’s use a custom session cookie name so we can future-proof ourselves from referencing a default session cookie name in case it changes in future NextAuth releases. You can see specific option documentation here.

// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'

export default (req, res) => {
  let sessionTokenName = '<your session token name>'

  return NextAuth(req, res, {
    cookies: {
      sessionToken: {
        name: sessionTokenName,
        options: {
          httpOnly: true,
          sameSite: 'lax',
          path: '/',
          secure: true
        }
      }
    },

    // Rest of your NextAuth config
  })
}

3. Add custom JWT encode and decode functions

Now, let’s add custom JWT encode and decode functions so that we can prepare to properly decode the session token. I ended up using the jsonwebtoken package as suggested by NextAuth’s docs, so let’s install that.

# For Yarn users
yarn add jsonwebtoken

# For NPM users
npm install jsonwebtoken

We’ll define custom functions in a separate module.

// lib/jwt.js
import * as jwt from 'jsonwebtoken'

export function jwtEncode({ token, secret }) {
  return jwt.sign({ ...token }, secret, { algorithm: 'HS256' })
}

export function jwtDecode({ token, secret }) {
  return jwt.verify(token, secret, { algorithms: ['HS256'] })
}

And use them in the NextAuth route. Generate a NEXTAUTH_SECRET environment variable if you haven’t done so already in your setup.

// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'
import { jwtEncode, jwtDecode } from '../../lib/jwt'

export default (req, res) => {
  let sessionTokenName = '<your session token name>'

  return NextAuth(req, res, {
    jwt: {
      secret: process.env.NEXTAUTH_SECRET,
      encode: jwtEncode,
      decode: jwtDecode
    },

    // Rest of your NextAuth config
  })
}

4. Decode the session token

Now we have all the piping in place to reference the decoded session token! This will obviously depend on your particular use case, but here’s an example of how to do it in the jwt callback.

// pages/api/auth/[...nextauth].js
import NextAuth from 'next-auth'
import { jwtEncode, jwtDecode } from '../../lib/jwt'

export default (req, res) => {
  let sessionTokenName = '<your session token name>'

  return NextAuth(req, res, {
    callbacks: {
      jwt: ({ token }) => {
        let secret = process.env.NEXTAUTH_SECRET
        let sessionToken = req.cookies[sessionTokenName]
        let decodedSession = jwtDecode({ token: sessionToken, secret })

        // Use `decodedSession` here! Look up a user or account
        // record, persist current session data, etc.
      }
    },

    // Rest of your NextAuth config
  })
}

Wrapping up

Keep tabs on the relevant GitHub discussion to follow any official releases that might make this article obsolete, but I hope this serves as a helpful reference in the meantime for anyone looking to accomplish account merging or something similar using NextAuth.

Replace a relational database with DynamoDB in Rails

Sun, 24 Oct 2021 12:00:00 GMT

I recently was working on an already existing Rails project where using Amazon DynamoDB made more sense than a relational database. While I won't get into the nitty-gritty of DynamoDB, what's relevant for this blog post is that it's a NoSQL database without an out-of-the-box Active Record adapter.

This meant a couple things:

We needed a Ruby ORM that supported DynamoDB.
Active Record must be removed from the project to avoid having to maintain a relational database in the project's cloud infrastructure.

This was a bit more involved than I first thought, so here are the steps I went through to successfully replace a Rails project's relational database with DynamoDB.

1. Install Dynamoid

Julie Kent's article on using DynamoDB in Rails has a great overview of an ORM called Dynamoid which feels really close to Active Record. This is an excellent choice for interfacing with DynamoDB, and adding it to a bundle is as easy as:

# Gemfile

# ...
gem 'aws-sdk'
# ...

Now, configuring Dynamoid can be done in a few ways. The way I opted for was to maintain as much of the "Rails way" as possible, which involves having local database tables as well as a test suite. Running DynamoDB locally can be done by running an executable .jar file or via Docker. Since I wanted to avoid the overhead of sorting out all Java runtime dependencies, I picked Docker.

2. Dockerize the project

I ended up Dockerizing this project by adding a Dockerfile and docker-compose.yml—the first to define an image and the second to orchestrate multiple containers.

# Dockerfile.
#
# Swap Ruby version to applicable one for your project.
FROM ruby:2.7.4

# Install Yarn.
RUN apt-get update && apt-get install -y npm && npm install -g yarn

# Setup working directory.
RUN mkdir -p /var/my-project-name
WORKDIR /var/my-project-name

# Setup dependencies. Split into separate step to utilize Docker cache.
COPY Gemfile* /var/my-project-name/
RUN bundle install
COPY yarn.lock /var/my-project-name/
RUN bin/yarn install

# Copy project files.
COPY . /var/my-project-name

# Command to boot server.
#
# 1. Prevent "Rails server already running" errors on runs.
# 2. Ensure proper DynamoDB tables exist.
# 3. Start Rails server on 0.0.0.0.
CMD rm -rf tmp/pids/server.pid && bin/rake dynamoid:create_tables && bin/rails server -b '0.0.0.0'

# docker-compose.yml
#
# Ref: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.DownloadingAndRunning.html

version: '3.8'

services:
  dynamodb-local:
    image: 'amazon/dynamodb-local:latest'
    working_dir: '/home/dynamodblocal'
    volumes:
      - './docker/dynamodb:/home/dynamodblocal/data'
    ports:
      - '8000:8000'
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath ./data'

  rails-app:
    build: .
    container_name: rails-app
    depends_on:
      - 'dynamodb-local'
    links:
      - 'dynamodb-local'
    volumes:
      - '.:/var/my-project-name'   # Mirror working directory in Dockerfile
    ports:
      - '3000:3000'

    # These environment variables can be left as-is. The DynamoDB container
    # doesn't need valid keys to work, it just needs them to exist.
    environment:
      AWS_ACCESS_KEY_ID: 'DUMMYIDEXAMPLE'
      AWS_SECRET_ACCESS_KEY: 'DUMMYEXAMPLEKEY'
      REGION: 'us-west-2'

3. Configure Dynamoid

First thing is to make sure our environments are referencing the proper DynamoDB tables. We'll modify our environment config.

# config/environments/development.rb

# ...
Dynamoid.configure do |config|
  # Point to local DynamoDB server.
  config.endpoint = 'http://dynamodb-local:8000'

  # Use passed REGION from docker-compose.yml.
  config.region = ENV['REGION']
end
# ...

# config/environments/production.rb

# ...
Dynamoid.configure do |config|
  # If you have a more advanced AWS infrastructure setup that uses assumed
  # roles, etc., then setting the access key and secret key aren't
  # necessary here.
  config.access_key = ENV['AWS_ACCESS_KEY_ID']
  config.secret_key = ENV['AWS_SECRET_ACCESS_KEY']
  config.region = ENV['REGION']
end
# ...

# config/environments/test.rb

# ...
Dynamoid.configure do |config|
  # Essentially the same as the development environment except with an
  # explicit namespace so we don't have development and test DynamoDB table
  # names clashing with each other.
  config.namespace = "#{Rails.application.railtie_name}_#{Rails.env}"
  config.endpoint = 'http://dynamodb-local:8000'
  config.region = ENV['REGION']
end
# ...

4. Migrate models

Luckily, Dynamoid provides a very easy way to migrate our existing Active Record models to it. We just need to break inheritance chains so we stop using ApplicationRecord and/or ActiveRecord::Base and then include Dynamoid::Document in our model classes.

An example model might look like:

# app/models/user.rb

class User
  include Dynamoid::Document

  field :name,  :string
  field :email, :string
  field :phone, :string
  field :age,   :integer
end

Since DynamoDB is a NoSQL database, migrations won't be applicable in our Rails project anymore, and model schemas are defined directly in model definitions.

5. Remove Active Record

Depending on your situation, this step may not be necessary, but in my case it was. The first thing to do is to modify your config/application.rb.

# config/application.rb

# ...

# Replace your `require "rails/all"` line with this.
#
# Pick the frameworks you want:
require "active_model/railtie"
require "active_job/railtie"
# require "active_record/railtie"
# require "active_storage/engine"
require "action_controller/railtie"
require "action_mailer/railtie"
# require "action_mailbox/engine"
# require "action_text/engine"
require "action_view/railtie"
require "action_cable/engine"
require "sprockets/railtie"
require "rails/test_unit/railtie"

# ...

Active Record, Active Storage, Action Mailbox, and Action Text are all commented out from the require statements because they all use Active Record. As a follow-up, we need to remove references to all of these libraries.

First, comment out any line that references any of the removed libraries in your environment config files (config/environments/*). For instance:

# config.active_storage.service = :local
# config.active_record_migration_error = :page_load
# config.active_record.verbose_query_logs = true

Next, we won't need Active Storage in our front end bundle anymore, so let's remove that:

yarn remove @rails/activestorage

And we'll also remove references to that front end package. In app/javascript/packs/application.js, comment out any lines that reference ActiveStorage.

// import * as ActiveStorage from "@rails/activestorage"
// ActiveStorage.start()

And finally, remove the following files:

app/models/application_record.rb: Since we've already migrated our models to Dynamoid.
config/database.yml: Since we're not using Active Record adapters.
db/*: The whole directory. We won't need the schema, migrations, or seeds anymore since those were all Active Record.
test/fixtures/*: This one's only really applicable if you use Minitest and fixtures, but those operate using Active Record, so we don't need those anymore.

6. Configure test suite

The primary thing to configure here is getting the test suite to properly clean database tables for test runs. Whether you're using Minitest, RSpec, or something else, you'll want to modify the method that runs before every test run. In my case, it was Minitest, so it looked like this:

# test/test_helper.rb

# ...
class ActiveSupport::TestCase
  # Run some procedures before every test case in the suite.
  #
  # @return [void]
  def before_setup
    super

    # Reset DynamoDB tables.
    #
    # Ref: https://github.com/Dynamoid/dynamoid#test-environment
    Dynamoid.adapter.list_tables.each do |table|
      Dynamoid.adapter.delete_table(table) if table =~ /^#{Dynamoid::Config.namespace}/
    end
    Dynamoid.adapter.tables.clear
    Dynamoid.included_models.each { |m| m.create_table(sync: true) }
  end
end
# ...

...profit! 🎉

Now we should be able to simply run docker-compose up and our local application should be using DynamoDB tables without any trace of Active Record left!

I would like to note that for most Rails projects, using DynamoDB is probably not advisable. However for cases where it actually makes sense, I hope this post can serve as a good reference.

Adding a Cypress test suite to your full stack Next.js app

Wed, 18 Aug 2021 12:00:00 GMT

Next.js is undoubtedly a powerful way to build React apps. With its recent addition of API routes, it can actually serve as a full stack toolkit to build web applications.

Recently, I started helping out with a full stack Next.js app (database and all) and wanted to add end-to-end integration tests. Cypress was the natural framework to reach for, and I was surprised to find that there weren't very many guides out there for adding it to Next.js apps. Specifically, there weren't very many guides for adding Cypress to Next.js apps that interact with databases.

This post is my stab at one of those guides.

Installing the packages

First off, we need to add the necessary package to run Cypress:

yarn add cypress --dev

We'll also add a handy package called start-server-and-test which will be used to automate booting up and tearing down the app when the test suite runs:

yarn add start-server-and-test --dev

And finally, we'll add a package called dotenv-flow which lets us easily manage environment variables in development and test environments:

yarn add dotenv-flow --dev

Creating the test database

We'll want to create a separate test database so we don't clobber development databases with test data. This will heavily vary depending on your use case, but the general steps should be more or less the same:

Create a new local test database and user.
Keep its database connection string in .env.test.local which will automatically be used in test environments thanks to dotenv-flow.
Use the connection string to connect to and interact with your database in your app.

Example for PostgreSQL

$ createdb my_app_test
$ psql my_app_test
psql_test=# create user YOUR_USERNAME with password 'YOUR_PASSWORD';
psql_test=# grant all privileges on database my_app_test to YOUR_USERNAME;

DATABASE_URL="postgresql://YOUR_USERNAME:YOUR_PASSWORD@localhost:5432/my_app_test"

Adding the scripts

Now let's add some scripts to package.json to automate running Cypress in a test environment.

{
  "scripts": {
    "dev:test": "next dev -p 3001",
    "cy:open-only": "cypress open",
    "cy:run-only": "cypress run",
    "cy:open": "NODE_ENV=test dotenv-flow -- start-server-and-test dev:test 3001 cy:open-only",
    "cy:run": "NODE_ENV=test dotenv-flow -- start-server-and-test dev:test 3001 cy:run-only"
  }
}

A couple points of interest here:

We add a dev:test command that starts our Next.js app on port 3001. This is to avoid any port conflicts when, say, we want to run the test suite at the same time we have a development environment running.
We specifically set NODE_ENV=test when running the main Cypress commands to have dotenv-flow automatically read our .env.test.local file to grab the database connection string.
We have cy:open and cy:run to easily let us access the Cypress Electron app or just run in the command line.

Running Cypress for the first time

Now let's finally run Cypress. The first run will generate files in your project that will serve as the foundation of your suite.

yarn cy:open

If you haven't used Cypress before, this will open an Electron app that gives you a nice UI to configure and run your tests. At this point, you should see a new cypress/ directory in your project as well as a cypress.json. Let's tweak that cypress.json file to look like this:

{
  "baseUrl": "http://localhost:3001"
}

This is so Cypress automatically prepends any paths with that URL when we want to run cy.visit().

If you've made it this far, you're now ready to start writing your integration tests and running them locally, congrats! 🎉

Configuring CI

This is another step that will vary depending on your use case, but for the sake of example, let's set up a new workflow in GitHub Actions that will run our Cypress suite on every pull request.

Add a new workflow file at .github/workflows/e2e_tests.yml:

name: E2E tests (Cypress suite)
on: [pull_request]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: "Setup Postgres database"
        uses: harmon758/postgresql-action@v1
        with:
          postgresql version: "13"
          postgresql db: ${{ secrets.POSTGRES_DB }}
          postgresql user: ${{ secrets.POSTGRES_USER }}
          postgresql password: ${{ secrets.POSTGRES_PASSWORD }}
      - name: "Setup Yarn dependencies"
        uses: bahmutov/npm-install@v1
        with:
          install-command: yarn --frozen-lockfile
      - name: "Run migrations"
        run: yarn db:migrate
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
      - name: "Run Cypress"
        uses: cypress-io/github-action@v2
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}
        with:
          command: yarn cy:run

This example workflow makes a couple assumptions:

You have POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, and DATABASE_URL added to your GitHub repo's secrets.
You have a db:migrate script setup in package.json which migrates your database and sets up the correct schema for your project.

Now try opening a new PR and celebrate the fact that your test suite now runs on each PR. 🎉

Wrapping up

It took me a minute to piece together this particular configuration when I first went through it, so I hope this post can serve as a solid reference for anyone looking to setup end-to-end tests for their Next.js app. Special thanks to Ash Connolly's post on setting up Cypress in Next.js. I used his guide as a stepping stone to get to where this ended up.

And finally, feedback is welcome! Feel free to reach out for any comments, questions, or suggestions.

Happy coding.

Giving Ruby objects access to Rails view methods

Wed, 27 Jan 2021 12:00:00 GMT

I think most Rubyists can agree that POROs (Plain Old Ruby Objects) are incredibly useful. When done right, they're easy to understand, build, and use in applications.

In the Rails ecosystem, there are many classifications of POROs: services, presenters, query objects, value objects, and so on and so forth. Sometimes we want to give these POROs access to things our application can access at the view level—maybe we want a PORO to manage generating a set of asset or route paths for us.

Luckily, it's easy! We can use something called view_context.

class MyController < ApplicationController
  def index
    # Pass a `view_context` from the controller level into a PORO.
    poro = MyPoro.new(view_context)

    # ...
  end
end

class MyPoro
  def initialize(context)
    @context = context
  end

  # Now we have access to things like...
  def example
    # Image paths.
    @context.image_path("/some/path/here")
    @context.image_url("/some/path/here")

    # Routes.
    @context.root_path
    @context.users_path

    # Other things you have access to in a view.
    @context.controller_name
    @context.action_name
    # etc...
  end
end

Having the flexibility to access view-level methods in a PORO is powerful for obvious reasons and can help prevent unnecessary complexity inside of templates and partials.

2020 year in review

Tue, 29 Dec 2020 12:00:00 GMT

It goes without saying that this year was absolutely insane, but existential threats aside, this year did give me a decent number of things to be thankful about.

Professionally

I passed my 1 year mark at Litmus, a company whose product I've used in just about every previous role I've had. My coworkers are great human beings and I feel like I can continue to grow here. Without divulging a lot of details, I helped enhance some internal company software and served as tech lead for two newly formed teams. I also helped lead the committee that recently launched the company's engineering blog.
I'm now in year 4 of being fully remote. Most people in the industry have gone fully remote with the pandemic, but I'm thankful to have had a bit of a head start, since I know switching cold turkey can be rough. Companies being remote first really does make a difference as opposed to remote friendly, or as I like to call it, "tolerant."
I'm still rocking Ruby on Rails as my daily driver with sprinkles of Vue here and there—technologies that I enjoy working with.
I started flirting with Rust in my off time.
I went through Rebuilding Rails by Noah Gibbs, which covers the major components of Rails internals.
I've also started mentoring a couple people who were looking to break into the industry in engineering roles, and I'm elated that they both landed jobs.

Open source...ly

Chusaku, a Ruby gem I started in 2019, passed 10,000 downloads and received some lovely contributions from people much smarter than me. I'm encouraged to continue maintaining it not just for my own use, but for the folks who have adopted it into their workflows as well.
I helped review PRs for if me, a mental health app that I started contributing to back in 2018. Definitely intending to continue contributing to this project, since it's especially relevant today.
I got a couple PRs (#1418, #1431) merged for DevDocs, a developer documentation tool I use for just about everything on a daily basis. I actually wasn't aware it was open source until recently, so I was happy to contribute.

Personally

I moved to Los Angeles in the latter half of 2019 to help support family, so I'm in my second year of living here. I've always wanted to live in California at some point in my life, and it's been an adventure so far. Thankful for the friends I've made here. Thankful that my family is doing alright. Hoping the COVID situation gets under control soon.
I brought home the goodest doggo named Luna and she's helped raise my bar for base happiness. Being remote and raising a puppy should really be a package deal for all dog lovers.

Finally

I think it's going to be important going into 2021 with the mindset that we need to make progress happen. Whether it's something at our jobs or things like COVID-19, we can't just sit around hoping problems are going to magically go away.

Be the magic. Wear a mask. Fight racism. Write semantic HTML.

See you all next year.

Fixing overflow padding in Firefox

Tue, 15 Sep 2020 12:00:00 GMT

Hat tip to my coworker Dylan for deep-diving into this issue with me and digging up the logged bug.

Elements that scroll as its contents go beyond its given dimensions—this is a pretty common pattern in sites and apps. Unfortunately, it comes with a 9 year old bug in Firefox. It's reasonable to want padding within these scrolling elements to give your content some breathing room as you reach the end of the scroll. This bug causes the end padding to be completely ignored. Here is a pen to demonstrate.

Unfortunately, until this bug is fixed, we can't really solve this in a "correct" way. So here are some cross-browser methods to fix this issue.

Pseudo-element that provides the padding

This is an approach that inserts an ::after pseudo-element in the element that has overflow applied. You'd remove the end padding explicitly and move it into the pseudo-element.

<div class="box">
  <!-- Your content here. -->
</div><!-- .box -->

.box {
  /* These properties are dependent on the project design. */
  overflow: auto;
  max-height: 100px;
  padding: 1rem;

  /* Explicitly removing the end padding. */
  padding-bottom: 0;
}

.box::after {
  content: '';
  display: block;
  padding-bottom: 1rem; /* Should match `padding` value in parent. */
}

This works nicely as Firefox will render the end padding just fine and other browsers will render it the same. It's also fine to use something like height instead of padding-bottom in this example as well.

Adding a child element in markup with the padding

This is similar to the first method except that we are explicitly including an element in the markup with the necessary padding rather than using a pseudo-element.

<div class="box">
  <!-- Your content here. -->

  <div class="box__spacing"></div>
</div><!-- .box -->

.box {
  /* These properties are dependent on the project design. */
  overflow: auto;
  max-height: 100px;
  padding: 1rem;

  /* Explicitly removing the end padding. */
  padding-bottom: 0;
}

.box__spacing {
  display: block;
  padding-bottom: 1rem; /* Should match `padding` value in parent. */
}

Adding a child container element with the padding

Instead of having the parent element declare a padding, you can move it into a child container element.

<div class="box">
  <div class="box__child">
    <!-- Your content here. -->
  </div><!-- .box__child -->
</div><!-- .box -->

.box {
  /* These properties are dependent on the project design. */
  overflow: auto;
  max-height: 100px;

  /* Notice that this element has no padding anymore. */
}

.box__child {
  padding: 1rem; /* ...and that the child now has the padding. */
}

Closing thoughts

The general strategy here is to divert the spacing to another element other than the original. Depending on your project, there are very likely other ways of tackling this problem, but I hope these general strategies help point you in the right direction.

Also...

CSS is hard. It seems deceptively simple to pick up, but the real world bugs and issues that developers run into are unlike anything you'll see in other languages.

Lots of respect to the people who work on browsers and browser engines, and lots of respect to people who write CSS.

Write code for people, not machines

Thu, 13 Aug 2020 12:00:00 GMT

I was asked recently in the context of my career, "what would you have done differently if you could do things over again?"

I'm a believer that mistakes are the best opportunities to learn and grow from, so I wouldn't avoid making mistakes. But if I could go back in time and talk to my past self, I think I'd encourage a particular mindset earlier—write code for people, not machines.

At a certain point in my programming journey, I used to love being clever. "Wow, look how compact I can make my code," "I can encode this list of possible options in binary to save space," "I'm going to write it this way to just feel cool," etc.

Spoiler alert, that sucked because guess who that always comes back to bite in the end? Me.

Obviously, this makes things difficult for your team as well. People who've never seen my code before will scratch their heads, find that the original author was me, then ping me with questions. That's fine for a short period of time while the ideas were still relatively fresh in my mind, but fast forward a handful of years. Shit, I forgot.

There's really no room for ego in this industry. There's really no room for ego anywhere, for that matter. At the end of the day, yes, writing code is laying out instructions for computers, but who are you really writing for? Yourself and other human beings.

My teachers in the past always taught me to write like I'm writing so a 4th grader could understand it. The same thing applies to code. Does something prompt a double take? Rewrite it and supply a thoughtful comment. Is something just hard to look at since it's really clumped together? Make it neat and tidy and easy to process.

Write the code for people. We're all in this together.

HTML isn't an assembly language

Sun, 12 Jul 2020 12:00:00 GMT

Back in 2005–2006, validators were all the rage. Every website had a W3C HTML valid badge to let visitors know the authors of the site really knew their stuff. It was almost ludicrous to see a site without a validator badge, and my first instinct was to run their markup through the W3C validator.

As the Web matured and newer techniques to build things came out, the attitude towards the "correctness" of HTML shifted. HTML became the vessel to ship user experiences on the Web. Whether it was valid or not mattered less as long as the interactions worked.

I'm not trying to claim that I'm a Web historian or anything because I'm not, but I would be incredibly surprised if this shift in attitude didn't contribute to things like progressive enhancement and accessibility not getting the attention that it really deserves.

I have friends who are getting into web development today, and the material that they're taught skews heavily on the shiny things—React, GraphQL, serverless functions, and the like. While there's nothing wrong with that, I'd love to see the fundamentals become cool again. I'd love to see an emphasis on semantics, structure, and readability become cool again.

HTML is the primary medium of the Web, yes, and that means it is the common denominator when it comes to things like progressive enhancement and accessibility. HTML isn't an assembly language. Make your site/app make sense and work without CSS and JavaScript first, then begin to layer everything else in.

Now that's cool. Let's normalize that.

The software spectrum

Thu, 30 Apr 2020 12:00:00 GMT

Kudos to my coworker Dylan Smith for the chats recently that got me thinking about this.

There was a fantastic article written by Chris Coyier over at CSS-Tricks in 2019 called The Great Divide. In it, the problem of the term "front end developer" encompassing very distinct roles is described. This isn't just a semantic difference—it's a mindset difference as well.

In a product team for the Web, you're likely to have people that cover the responsibilities of what we've traditionally known as designers, front end developers, and back end developers. Will roles and titles fit snugly? Almost certainly no.

Those traditional role titles are even a bit misleading, since you and I would probably have slightly differing definitions of each. Just by starting to think through the various responsibilities and laying them out in a flat list, I get something like:

User research/data analysis
User flows/storyboarding
Wireframes/low-fidelity prototypes
High-fidelity prototypes
HTML/CSS implementation of prototypes
Accessibility, cross-browser support, animation, etc.
CSS methodologies/structure
JavaScript sprinkles/enhancements
Heavy JavaScript utilization
Front end frameworks
CSS-in-JS, code splitting, state management, etc.
Single-page applications/hybrid apps
API design
Serverless functions
Server side development
Server side frameworks
Database design/management
Infrastructure/DevOps

...and I'm still probably missing a million things in between.

The point is, there's a lot of stuff, and expectations for roles and corresponding responsibilities are getting blurrier and blurrier each day. People's skill sets may clump somewhere in this spectrum, but it's also important to recognize that skill sets could be scattered as well.

We've traditionally separated out these responsibilities in clear-cut places, but what happens when someone's core skills sit right in the middle of a cut? What happens when someone is excellent at both ends of the spectrum? What happens when someone wants to pursue an unorthodox skill set at work?

How can companies start supporting employees that don't fit the traditional mold? Should roles and titles be more ambiguous?

I don't have an answer to any of these, but I think it's certainly worth mulling over.

Delayed::Job for outbound emails in Rails

Fri, 20 Mar 2020 12:00:00 GMT

Let's say you run an online e-commerce platform. You want to send out a reminder email to new merchants to fill out their business profile because shoppers care about who they're buying from. In Rails, that's pretty straightforward:

MerchantMailer.profile_reminder(merchant.id).deliver_later \
  wait_until: 3.hours.from_now

But wait, we should make sure that the merchant doesn't already have their profile filled out when the reminder email is about to go out. Otherwise we'd be sending an annoying and not applicable email.

class MerchantMailer < ActionMailer::Base
  # Reminder to fill out business profile.
  #
  # @param {Integer} merchant_id - Merchant record ID
  # @return {ActionMailer::MessageDelivery} - Email to deliver
  def profile_reminder(merchant_id)
    return unless (merchant = Merchant.find_by(id: merchant_id))

    return if merchant.filled_out_business_profile?

    # ...
  end
end

Perfect! Or is it? This test fails:

RSpec.describe MerchantMailer do
  describe '#profile_reminder' do
    it "shouldn't run the method code until send time" do
      expect(Merchant).to_not receive(:find_by)

      MerchantMailer.profile_reminder(1).deliver_later \
        wait_until: 3.hours.from_now
    end
  end
end

Unfortunately this doesn't work because mailer methods are run at the time we queue the job, not at the time of job processing. Our reminder emails will still always get sent even if our merchants filled out their profiles.

Enter Delayed::Job

Delayed::Job is an excellent (and popular) gem that provides a bunch of tools for processing jobs. #delay is a method added to all objects by Delayed::Job that we can use here.

Instead of queueing up the reminder email, we can queue up a method that determines if the email should be sent. So in our controller or service object, we can add:

# Queues a reminder to fill out the given merchant's business
# profile if they haven't already.
#
# @param {Integer} merchant_id - Merchant record ID
# @return {void}
def send_profile_reminder(merchant_id)
  return unless (merchant = Merchant.find_by(id: merchant_id))

  return if merchant.filled_out_business_profile?

  MerchantMailer.profile_reminder(merchant).deliver_later
end

And replace our original line where we queued the mailer with:

delay(run_at: 3.hours.from_now).send_profile_reminder(merchant.id)

Now what's queued isn't the email itself, but send_profile_reminder, which will determine if an email should get queued at the time it's scheduled for.

Closing Thoughts

This is a very situational use of Delayed::Job. I used e-commerce just as an example, but this could apply to anything that warrants conditionals at the time of a queued job. Perhaps you want to email trial users about something, or maybe you want to check in with a patient about a medical condition. Whatever the use case, using #delay in this manner is something that can help prevent an otherwise disgruntling bug.

Concepts I needed to learn to setup a home server

Wed, 11 Mar 2020 12:00:00 GMT

I've always wanted to set up a home server, but my networking knowledge has always held me back. I've always been aware of things like DHCP and port forwarding but have never configured anything meaningful with them, so they remained somewhat of a mystery to me.

My goal here is pretty straightforward: configure a machine in my home so I can SSH into it over the Internet. I finally hunkered down and learned enough to accomplish this and was pleased to find this is actually very easy to do.

Here are the concepts that helped me get there.

LAN, WAN, and static IP addresses

LAN stands for local area network, and it's the network of devices connected to my home router. WAN stands for wide area network, and it's the network of households being serviced by my Internet service provider.

When I connect my server box to my home network, my router assigns it an IP address that looks something like 198.168.1.12. When that server box reconnects to the router from a restart or some kind of connectivity issue, the router assigns it an IP address that isn't necessarily the one it assigned earlier. This is called a dynamic IP address. DHCP (dynamic host configuration protocol) is what handles this process, but it's not crucial to really know anything more about it for setting up a basic home server.

A static IP address is, surprise surprise, one that the router will always assign a particular device whenever it connects to the network.

All I had to do to setup a static IP address for my machine was use my router's software. This is different on a router-by-router basis, but it was very straightforward in my case. Get into my router's admin screens, find a menu option for IP addresses, find the relevant device, and assign it a static IP.

Port forwarding

This was more or less the gate keeper concept for me previously in setting up a home server. What the heck is port forwarding?

When SSHing into my device, I'm essentially doing two things:

Pinging the IP address of my home network (this is my public IP via my WAN).
Pinging the static IP address of my device (via my LAN) with a specific port number (in the case of SSH, it's 22).

For step 2 to be successful, I have to configure my router to know which local IP address to "forward" the request to when an SSH login is attempted. Also, for security reasons, I don't want to just forward port 22 from my public IP to my device IP since bad peeps might want to spam SSH login attempts if they get ahold of my public IP.

This is, at its essence, what port forwarding does. It is a configuration at the router level that will forward requests from a public IP + port combination to a local IP + port combination.

Again, the setup for this was pretty straightforward. I jumped back into my router's admin screens, found a menu option for port forwarding, picked an obscure port number and pointed it to my device's static IP address at port 22.

SSH software

Finally, the last piece here was to setup software on my device to properly accept SSH login requests at port 22. This will vary depending on which OS is being used, but in my case, I was using Ubuntu Linux, so I installed the openssh-server package with:

sudo apt update && sudo apt install openssh-server

And now this computer was ready to allow username/password combinations for existing users for SSH logins. Allowing connections with SSH keys and disabling passwords is something that can be configured with most SSH packages as well.

..magic

That was...it! Now I'm able to bring around an iPad and write blog posts and code, which gives me a mild sorcerer complex, and it's wonderful. For extra kicks, you can add an A record with your DNS provider to point mahbox.mahdomain.com to your public IP.

Test-driven reviews

Sat, 09 Nov 2019 12:00:00 GMT

You've likely heard of test-driven development. It's a practice that involves writing automated tests before writing code that accomplishes the feature or objective you're working on. You want to write tests that fail at first and only pass when the implementation can be considered "complete". It's a very powerful way of approaching software development.

Over the past year or so, I've been more heavily involved in code reviews at my job. I've reviewed PRs that are anywhere between 3-line code changes to 70+ changed files. Code reviews can be done in a lot of different ways, and they are different from person to person.

In this post, I want to document a language-agnostic approach to code reviews that has helped me give meaningful feedback.

Review the Tests First

By reviewing the tests first, you can get solid context of what to expect in the application code. If you feel like you're still not sure what to be looking for after reviewing the tests, that's a great indication that the tests need to be rewritten. This is like the "red" of TDD except it's for understanding the test.

This is especially important for larger PRs (your team could try enforcing smaller PRs, but at some point, large PRs are somewhat unavoidable). Also, this is important regardless of test-driven reviews because it will be applicable whenever anybody reviews any test in your codebase.

Some mindsets I've found that really support this are:

1. Test the "What" and Not the "How"

This means writing tests that read, "in this particular scenario, this input should result in this output" rather than "in this particular scenario, some particular function or method should be called". The more tightly coupled your tests become with the application code, the less natural it becomes to read and it also harms the test suite's ability to be a safe guard when refactoring.

2. Clever Tests Are Not Better Tests

It's tempting to write control structures and various helpers into tests to make them easier to write, but 9 times out of 10, I recommend against it. This is because the "naive" way of writing a test is generally easiest to understand whenever anybody revisits the test.

In other words, write the tests as dead simple as possible. Hardcode expectations instead of generating them. Repeating an operation with slight variations multiple times? Hardcode them, don't use a loop.

3. Localize Tests As Much As Possible

By "localize," I mean keep all crucial context within the test as much as possible. If a different part of the file needs to be looked at to fully understand a test, that's a hindrance. If an entirely different file needs to be loaded to fully understand a test, that's definitely a hindrance.

The goal of localizing test context is to reduce the time from "open test file" to "understand test file" as much as possible. While DRY principles are important in the application code, they can become harmful in the test suite.

Closing Thoughts

Well-written and easy-to-understand tests are just as crucial to an application as the application code itself. It enables not just your team, but also you to better iterate on your project.

Code reviews are a great place to help evolve this sort of mindset in your team.

Chusaku, a controller annotation gem

Sat, 13 Jul 2019 12:00:00 GMT

I'm an avid user of Annotate, a lovely gem written by Cuong Tran that annotates various Rails project files with summaries of the database schema. Without flipping back and forth between models, factories, and schema.rb, the annotations allow me to see what columns are present in relevant tables at a quick glance.

Chusaku, which is a play on the Japanese word 註釈, is a Rails controller annotation gem that I wrote a couple months prior to scratch my own itch of wanting to see route info directly in controller files.

Take for example the following:

class TacosController < ApplicationController
  def create
    # ...
  end

  def destroy
    # ...
  end
end

We have a very simple controller that handles the creation and destruction ("nomming") of delicious tacos. However, just by looking at this file, I have no idea if these actions correspond to any routes in my Rails project.

With Chusaku, we can simply run:

bundle exec chusaku

And our file would then look something like:

class TacosController < ApplicationController
  # @route POST /make-myself-a-taco (create_taco)
  def create
    # ...
  end

  # @route DELETE /put-the-taco-in-my-tummy (eat_taco)
  def destroy
    # ...
  end
end

We can see the HTTP verb, path, and route name that corresponds to each action.

Strategy

As a programmer, I thought it would be fun to tackle this problem from scratch. How would I parse my controller files and annotate only the actions that have corresponding entries in my routes?

Step 1: Gather routes info from Rails

First, I needed to somehow parse a project's routes. The only way I knew how to quickly see a project's routes was with:

bin/rake routes

But parsing CLI output for the purpose of this project seemed awful. After a bit of digging, I found that Rails does expose its routes info in Ruby. This led to the creation of Chusaku::Routes.

Step 2: Parse controller files

While this step is fairly obvious, the details of it took me a second. I should open a file for reading, yes, but I also need to be able to tell if what I'm looking at corresponds with a route in Rails.

Using Chusaku::Routes, I know what routes are available to me, so how can I find relevant actions? Regular expressions. By extracting the name of an action, I can check to see if any route matches it.

Great.

But now what? I want to insert an annotation above the action, but what if there is already a comment that exists? What if an annotation already exists?

At this point, I decided that being able to categorize lines of a file into three buckets was necessary. The buckets are:

Action: a line that defines an action
Comment: line(s) that are purely comments
Code: anything else

This is how I pictured it in my head:

This led to the creation of Chusaku::Parser.

Step 3: Annotate

Finally, I just want to write annotations above actions in each controller file where applicable. Using both Chusaku::Routes and Chusaku::Parser, I was able to insert annotations where necessary and was also able to prevent edge cases where annotations already existed or was no longer needed.

This leads us to the main module, Chusaku.

Closing Thoughts

Writing Chusaku was incredibly fun and I intend to continue using it for my Rails projects. You can see the repo and associated test suite here. If you like the project, please consider starring it on GitHub, and if you see any problems, please file an issue or open a pull request!

Testing is for all of us

Sat, 20 Apr 2019 12:00:00 GMT

If you're a software engineer, regardless of if you studied CS in college, learned programming through the Internet, or went through a bootcamp, you've heard it time and time again.

Testing is important.

But why? It's easy to hear those words over and over, but not quite grasp the significance of them without being in the real world. This is my take on why I think testing, and more specifically automated testing, is so important.

Quality Assurance (QA)

Quality assurance is a multi-faceted discipline whose primary objective is to ensure that product(s) are meeting high standards. In software, some of the large buckets of QA are:

Functional QA: Does everything work properly?
Design QA: Does everything look right?
Stress Testing: Does it still run with high traffic?
Security: Is it difficult to compromise?

Automation can help in every one of these facets. Integration tests can be put in place to catch regressions, CI platforms can be configured to output screenshots in different screen sizes, and scripts can greatly increase the server load and/or look for common security exploits in an application.

Time and Confidence

In interest of time, there may be situations in which teams don't prioritize automated testing in order to get features out the door. This inevitably puts a lot of pressure on the team performing manual QA. If this trend continues over time, the company may prioritize hiring more and more manual QA staff, at which point it becomes more and more difficult to achieve satisfactory automated test coverage.

The problem here is that there is a compounding opportunity cost.

As a real-world example, the QA team that I work with can perform a full, manual regression checklist for an application in a full day. That checklist covers things like UI interactions, SMS and email notifications being sent out, etc. That same checklist, after it was all automated, takes less than 5 minutes.

Prior to automation, the QA team performed a full regression check before every release. Any defects were caught, logged, and assigned back to the engineering team. After automation, with continuous integration (CI) and continuous deployment (CD), any time the engineering team pushes code and something breaks, the team is notified and a deployment does not occur.

A well-maintained automated test suite enables the team to find bugs faster, gives back an incredible amount of time to help them focus on things they couldn't have before, and increases the confidence of the entire team. No matter how incredible someone is at manual QA, at the end of the day, they are human, and humans can miss things. Machines can be more consistent at finding defects.

A Function of Engineering

I think that it's crucial to have engineering teams write automated tests for the features they develop. They have the context necessary to fully automate test cases since they are in the code on a day-to-day basis. Things like unit tests and API tests would be incredibly difficult for an external team to write.

Furthermore, regardless of whether a team follows test-driven development or not, automated tests will help engineers catch defects in their code before it's released into the wild, and perhaps just as importantly, enables refactoring in confidence.

This leads me to believe that QA should be a function of engineering. At the end of the day, QA engineers are exactly that, engineers. Automated test suites need maintenance, just like any other piece of software. QA engineers are necessary to ensure the suite is well-oiled by optimizing reliability (fixing flaky tests), improving runtimes, and refactoring.

What About Manual QA?

Automated testing does not rule out manual QA by any means. It massively complements it. Because of the time it gives back to the team, QA staff can focus more on things like design QA* and discovering bugs through new edge cases rather than having users find them in the wild (and angrily reporting them).

*Some teams prefer to have their design teams perform design QA, and that makes perfect sense.

Closing Thoughts

Automated testing should absolutely be a priority in a software team. Increase developer productivity, save incredible amounts of time for QA staff, and instill confidence in the entire team that the software works and looks correctly, every time.

Reflections on a custom "Component"

Sun, 10 Mar 2019 12:00:00 GMT

This post is a collection of my thoughts, both good and bad, on defining a JavaScript pattern that I called "Component" prior to adopting React.

Background

In 2016, my interest in front end frameworks like React started growing, but I hadn't committed to learning one yet. My day-to-day was heavily in Ruby on Rails, and I was a big fan of CoffeeScript for its likeness to Ruby and its ES6-like features before tooling like Babel and Webpacker really took off.

I loved the idea of componentizing an application but was still married to the more traditional idea of separation of concerns, where markup, styles, and behavior should be separate. The spark to writing my "Component" was the question, "How can I maximize the reusability of JavaScript while isolating functionality like lego pieces?"

The Component Class

Before moving on, here's a slightly stripped down version of what the Component class looked like in a project that used jQuery:

# component.coffee

class Component
  # @param {String} name
  # @param {Array<String>} targets
  # @param {Function} functionality
  # @return {void}
  constructor: (name, targets = [], functionality) ->
    selector = "[data-component='#{name}']"

    $(selector).each ->
      config =
        element: this
        selector: selector

      # Register target selectors.
      targets.forEach (t) ->
        targetAttr = "data-#{name}-#{t}"
        targetName = $(config.element).attr(targetAttr)
        config[t] = "[data-#{name}-target='#{targetName}']"

      # Run passed function with config object.
      functionality(config)

At its core, it really isn't a lot of code, but it allows for a way to define reusable, isolated functionality in a way that is incorporated into markup purely through data attributes. In practice, it was very similar to using something like Atomic CSS.

An instance of Component takes three arguments:

name: A string that gets used to identify base elements that use this functionality.
targets: An array of strings that define other elements that are affected by this functionality.
functionality: A function that runs for every base element that uses this functionality.

Component in Action

An example usage of Component to be able to easily show/hide elements via an .is-active CSS class would be something like:

# toggler.coffee

new Component 'toggler', ['toggleable'], (c) ->
  $(c.element).on 'click', () ->
    $(c.toggleable).toggleClass('is-active')

This instance defines a new Component called toggler that toggles an .is-active CSS class on its toggleable target on click.

The function that we pass as an argument to the constructor can reference each instance of a toggler via c.element and can also reference each toggler's unique target via c.toggleable.

That's it. That's all the JS we need for this functionality. Now for the markup:

<button
  data-component="toggler"
  data-toggler-toggleable="toggleable-a"
>
  Show/Hide A
</button>

<button
  data-component="toggler"
  data-toggler-toggleable="toggleable-b"
>
  Show/Hide B
</button>

<div data-toggler-target="toggleable-a">
  <p>A: I can be shown or hidden!</p>
</div>

<div data-toggler-target="toggleable-b">
  <p>B: I can be shown or hidden!</p>
</div>

We create two <button> elements that will toggle different elements on click by giving them data-component="toggler" attributes. We know which elements will be toggled by each button via their data-toggler-toggleable attributes, which have unique values. Finally, we create two <div>s that are targets of each button, denoted by the data-toggler-target attribute and a unique value that matches with the data-toggler-toggleable attribute on the base element.

Obviously, the CSS also needs to be written, but assuming it is, we've successfully defined what a toggler is and we can sprinkle it throughout the application by just defining some data attributes.

Here's an accompanying pen:

The Good

This pattern allowed the team I was with at the time to write very modular pieces of functionality that were usable across multiple projects. We dropped in CoffeeScript files, attached some data attributes, and voila, things worked.

This was a huge win.

Not only did it reduce development time on individual projects, it created an opportunity for the team to define and maintain a library of functionality that could be tested in isolation and baked into a company project starter.

This also made it so it was possible to identify all DOM elements on a page that were being used for particular functionalities, which seemed like one step toward the right direction in a traditional separation of concerns mindset.

The Bad

The number one biggest problem with this pattern was that I neglected to write documentation.

One of the projects that Component was used in got passed off entirely to the client, who was building its own engineering team at the time. Unfortunately, the hand-off timeframe was criminally short, and I hadn't written any decent documentation or had enough time to bring the client team up-to-speed on the pattern.

Needless to say, in a fast-paced environment, the pattern just created a swamp of uncertainty and introduced bugs on bugs on bugs.

I felt an insiduous amount of guilt.

Additionally, while the pattern worked as intended internally, it did make the markup gain some serious weight. Parsing through mountains of data attributes is a strenuous process, and a new breed of bugs was created where attribute value typos had serious consequences.

Closing Thoughts

Overall, I'm glad I went through the motions of writing this pattern. Not only did it create real value for my team at the time, but it gave me some perspective and great empathy for the developers in the world that create tooling for other developers.

Moving forward, I want to be more considerate of how easily other developers can use something I write. An intuitive API as well as well-maintained documentation is just as important as the tool itself.

As a side note, when Stimulus was released by Basecamp, I felt much better about some of the design decisions I made when writing Component, since the concept of targets was extremely similar.

Getting into open source

Sat, 09 Feb 2019 12:00:00 GMT

These are my thoughts and experiences around getting involved in open source software through a project called if me. This is for anyone who has wanted to get into open source but hasn't yet.

Why Open Source?

I've been intrigued by open source for years. Some in the developer community attribute a lot of their learnings and successes to open source, and I use open source software on the daily. I've also always wondered what a software-building environment that isn't purely driven by profits looked like.

Curiosity was my main drive. I just never knew where to start.

Finding My First Open Source Project

I first determined a couple key factors I was looking for in a potential project to contribute to:

It must be software for good. In other words, I'm only interested if it's trying to better people's lives in an obvious way.
It must use the technologies I love. I could've looked for a project in a stack I'm not familiar with to learn it, but I was interested in developing a deeper knowledge for what I already knew and loved (Ruby on Rails).

Obviously, these are different for everybody, but knowing my priorities made finding a great fit easier.

I searched for various lists of open source projects with this criteria and ended up just browsing GitHub repositories by topic. if me was a project that was featured in GitHub's social impact collection that caught my eye immediately. Not only was it a Rails project, but it was tackling a meaningful issue: mental health.

At the time, the project's documentation encouraged interested contributors to reach out via email, so I sent one explaining my interest and willingness to contribute. The founder of the project, Julia Nguyen, responded promptly and added me to the organization's Slack. While having a Slack group wasn't 100% necessary, it has been an amazing tool to get to know the other contributors better outside of GitHub discussions.

First Contribution

My first contribution ended up actually not being code at all. It was design.

Julia laid out various areas I could start tackling as a first-time contributor. These were all documented as GitHub issues in the project repo as well. One of them was assisting with an app redesign, which in my mind affected all other contribution opportunities.

I expressed interest in starting the redesign efforts, got a thumbs up, and spent spare afternoons and evenings working on mockups. Once a rough direction started taking shape, I opened a new GitHub issue to share.

It was great collecting feedback from other contributors via Slack and GitHub to iterate on the design. Because open source software brings people of diverse backgrounds together, I was exposed to a lot of insights I wouldn't have thought of by myself in a silo or even in a company.

The design was eventually implemented by the community and is continually being iterated on.

The Community Is the Most Important Part

As I engaged more with the project, I realized that the community of contributors really defined the open source experience for me.

Julia is extremely welcoming as are all the other contributors. Discussions can include everything from helping people determine their first GitHub issue to chatting about how Neopets kick-started our careers.

if me has a culture of empowering contributors to lead initiatives. The implementation of my design corresponded with the adoption of React in the codebase, so I was encouraged to create GitHub issues for individual components and review pull requests for them. This taught me that contributing code isn't the only way to grow as an engineer -- reviewing contributions and communicating effectively is just as, if not more, impactful.

I eventually got around to contributing code to the project as well. Refactoring efforts were a large part of what I worked on so far, and it gave me insights into how large teams effectively architect and maintain codebases.

During this time, a team from Rails Girls Summer of Code got involved with contributing to the project. I had the chance to work with two incredibly talented individuals, Atibhi and Prateksha, from Bangalore, India through various pull requests and discussions. Helping them in their journey to gain more engineering experience alongside other mentors was invaluable experience for myself as well.

My most recent contributions involve reviewing Japanese translations, which is something that I've never had the opportunity to help with at a day job.

Closing Thoughts

Getting involved with open source was one of the best decisions I've made for my career. I've learned that open source is not just about contributing code -- filing issues, creating designs, reviewing contributions, mentoring others, being mentored, having discussions with incredible people, and being part of a community can all be a part of the open source experience as well.

There's really nothing stopping you from starting your open source journey if you're interested. Give it a shot sometime, and I bet it'll be full of pleasant surprises.

ES6 in Gulp projects

Tue, 29 Jan 2019 12:00:00 GMT

This post covers how to setup a Gulp project to use ES6 and also accounts for usage of libraries such as jQuery.

Update as of July 19th, 2019: Thanks to @regiscamimura for pointing out that the Rollup NPM package is now required for this process to work. The article has been updated to reflect that!

Preface

The front end development landscape is changing extremely quickly. React, Redux, Vue, Vuex, Webpack, and SPAs are just a few of the hot phrases you'll see today. However, many teams and individuals still use Gulp -- it is a tried and true build tool and sometimes from an operational standpoint, it makes sense for it to continue to be used.

Even if adopting React, Vue, or some other front end framework is not a viable option for some, adopting ES6 certainly is. ES6 is the next iteration of JavaScript that introduces many new features, and while not all browsers have it fully implemented, they are certainly on their way to do so.

I won't make any assumptions about your current setup, so this post will setup a Gulp configuration from scratch so that you can cherry-pick missing pieces and start writing ES6 in your projects today.

Setup NPM and Dependencies

If you haven't already installed Node and NPM on your system, do so before proceeding.

Let's setup NPM so you have access to all the packages we will be using.

npm init

Follow the prompts, and you'll have a package.json in your directory. Now let's install some development dependencies.

npm install --save-dev @babel/core gulp gulp-better-rollup rollup rollup-plugin-babel rollup-plugin-node-resolve rollup-plugin-commonjs

That seems like a mouthful, what did we just install?

@babel/core -- A tool that transpiles ES6 code into JavaScript that any browser will understand.
gulp -- Our build tool. :)
gulp-better-rollup -- A Gulp plugin that allows us to use Rollup, a module bundler that allows us to use ES6 imports and exports in our code.
rollup -- The module bundler referenced above.
rollup-plugin-babel -- A Rollup plugin that integrates Babel into the bundling process.
rollup-plugin-node-resolve -- A Rollup plugin that allows us to use third party modules in node_modules/.
rollup-plugin-commonjs -- A Rollup plugin that converts CommonJS modules to ES6 so we can import them without issues.

Configure Gulp

Install the Gulp command line tool if you haven't done so already:

npm install --global gulp-cli

Now let's create and configure our gulpfile.js.

const gulp = require('gulp');
const rollup = require('gulp-better-rollup');
const babel = require('rollup-plugin-babel');
const resolve = require('rollup-plugin-node-resolve');
const commonjs = require('rollup-plugin-commonjs');

gulp.task('scripts', () => {
  return gulp.src('js/*.js')
    .pipe(rollup({ plugins: [babel(), resolve(), commonjs()] }, 'umd'))
    .pipe(gulp.dest('dist/'));
});

This configuration defines a new Gulp task called scripts, which will run with gulp scripts. It looks in a directory called js/ for any .js files, runs Rollup against them, and outputs the result in a directory called dist/. You can change the gulp.src and gulp.dest to what's appropriate for your project.

We configure Rollup to use Babel, allow for importing third party modules from node_modules/, and allow importing any modules written in CommonJS. We specify an output format of umd, which is compatible with the most environments (browser, Node, etc.).

Go ahead and drop a JavaScript file in js/ and run gulp scripts. It'll transpile a resulting file in dist/, a good first step! Of course, you'll probably just want one JavaScript file in the root of the js/ directory and import the rest with ES6 syntax.

What If I Still Need To Use jQuery?

jQuery is still widely used and it could be too much of an effort to phase out of an existing system, especially if a million jQuery plugins are in play. If you can't abandon jQuery and/or also want to keep all front end dependencies managed through NPM (as opposed to CDNs or keeping them in the project repo), then read on.

Let's add jQuery as a project dependency.

npm install jquery

Now in a JavaScript file, we can use it like so:

import $ from 'jquery';

$(document).ready(() => {
  console.log('Look ma, no CDNs!');
});

That's great. However, when there are jQuery plugins that depend on a globally available jQuery object, things get weird. As an example, I'll use a plugin called fancyBox.

import $ from 'jquery';

// This looks in the `node_modules/` directory thanks to
// rollup-plugin-node-module. We can find the path to the minified
// JavaScript by manually looking in the `node_modules/` directories
// ourselves.
//
// We don't assign the import to any variable, since most jQuery
// plugins simply extend jQuery by adding new methods developers
// can use in their code. e.g. $('.my-element').myPluginMethod();
//
// Also, per ES6 imports, we can omit the `.js` at the end.
import '@fancyapps/fancybox/dist/jquery.fancybox.min';

If we run this through Gulp and load it on a web page, we get a JavaScript error:

ReferenceError: jQuery is not defined

Boo. Why?

A good first guess might be because we simply imported jQuery as a variable $, not as jQuery. We could try rewriting the first line, perhaps?

// This won't fix the error.
import jQuery from 'jquery';
import '@fancyapps/fancybox/dist/jquery.fancybox.min';

Unfortunately, this results in the same error. This is because jQuery plugins look for a globally defined jQuery object at runtime, and our transpiled files will always be protected from polluting the global scope (this is a good thing).

As a second stab, we could try this:

// This also won't fix the error.
import $ from 'jquery';
window.jQuery = $;
import '@fancyapps/fancybox/dist/jquery.fancybox.min';

Alas, same error. Why would assigning jQuery to the global scope not work either? This is because Rollup processes all imports first. This means that in our transpiled file, all of our imported modules are outputted before any of the JavaScript we write.

In this case, that means our window.jQuery = $; appears after our jQuery and fancyBox code.

With this knowledge, I propose this final solution:

// js/config/jqueryLoad.js
import $ from 'jquery';
window.$ = $;
window.jQuery = $;

// js/index.js
import './config/jqueryLoad';
import '@fancyapps/fancybox/dist/jquery.fancybox.min';

With this multifile approach, we're doing a couple things:

We delegate the importing of jQuery to a separate file jqueryLoad.js that also assigns $ and jQuery in the global scope.
We import our newly created config file before any plugins.

Now when Rollup transpiles our root JavaScript files, it will output our imported code first, meaning that the contents of jqueryLoad.js will appear before any of the jQuery plugin code.

You may now open your bottle of champagne.

Closing Thoughts

There's nothing wrong with using tools that aren't the latest and greatest, especially if there are organizational and operational reasons for it. At the same time, it's nice to have a little taste of the future as well.

I hope this can come in handy for some of you. Code on.

Vim, one year in

Sat, 26 Jan 2019 12:00:00 GMT

I started exclusively using Vim as my editor a little over a year ago.

This wasn't a decision I made lightly. I was heavily invested in the Atom editor ecosystem at the time, but was also transitioning into using a Chromebook as my primary machine. Linux apps support was not yet released, so I experimented with multiple ways of viably programming on Chrome OS.

I eventually committed to using Vim since it was an editor that is supported on virtually any environment. At the time, I figured I could program on a VPS on a Chromebook to stay true to having literally everything in the cloud. I was also always intrigued by Vim since I've read that it's a skill that you can develop over time, and productivity gets a huge boost as a result.

As a fallback, if I hated it, I could just run Ubuntu on my Chromebook and go back to my old ways.

Turns out I didn't hate one bit of it.

Shown here is what my current Vim setup looks like. It's technically Neovim, but I still count it as Vim, and I have Tmux in the mix as well.

I type around 120 WPM. When I have to stop and move a mouse, it really breaks my flow. It took me a couple days to get used to awkwardly navigating around with only my keyboard, but once I got somewhat of a grasp on that, I could already tell I'd be able to work faster than before.

What really got me, though, was when I discovered how to change everything within parantheses. With the help of a few keystrokes -- ci( -- I was able to change something like this:

best_flavor(ice_cream: 'chocolate chip cookie dough ice cream', bubble_tea: 'taro lychee fancy schmancy stuff')

...to this:

best_flavor(everything: 'vanilla')

Like everyone else, I was intimidated by what I thought were mountains of keyboard shortcuts to start using Vim even half effectively. To my surprise though, they really weren't that hard to remember at all.

Most key combinations in Vim are mnemonic. Take ci( from earlier as an example, it literally reads as "change in ()". Even the keys used to navigate correspond to English words, such as w for word and b for back. Vim commands really are like you're talking to your editor, and that makes it fun to use.

As far as functionality goes, I just had to spend a little time finessing my config and I had everything that I had in Atom and more. Vim has an incredibly rich plugin ecosystem, and the minor tweaks needed to make it look more like a modern editor were very easy. My .vimrc is open sourced on GitHub if you're curious!

The one bit that took me a while to fully comprehend was the concept of buffers. I've always seen Vim screenshots with multiple files open so I assumed it had tabs just like any other program.

Buffers are in memory. You can have the contents of a file loaded in it or it can be a blank slate. Each Vim session has one buffer per file you have open. This means that you can have multiple panes in Vim looking at the same file (this is useful for things like referencing sections of a file while you write in another section). You can cycle through buffers in any given pane.

Vim tabs, on the other hand, are just ways to organize panes. If I want a two column vertical split as one tab and a three row horizontal split in another, I can do that, and I can flip between them whenever.

Once I got that, I was much more comfortable in Vim land. Thanks to my friend Justin for constantly hounding me about using buffers.

Overall, I don't regret my decision to switch to Vim one bit. It feels liberating, and it's amazing to invest time in a tried-and-true piece of software that's just as old as I am.

Nowadays, I only have three apps open on my computer: a browser, Slack, and a terminal. If I ever need to SSH into servers to edit anything, I usually have my favorite editor available to me right on the server. To top it off, I work faster and more efficiently than before without a mouse slowing me down.

If anything changes, I'm sure I'll write about it, but I don't see that happening anytime soon.

Tidying my digital life

Thu, 24 Jan 2019 12:00:00 GMT

This post is about tidying up and Marie Kondo-fying my digital life. Because decluttering my mental space is just as important as decluttering my physical space.

Preface

I should start off by saying that I am and have always been a neat freak. My parents have told me that even as a kid, I used to obsess over keeping my toys neatly organized. This probably plays a huge role in my liking for refactoring entire code bases.

Keeping my digital life tidy has been something I've been working on over the past several years, and as someone who spends a majority of their days online, it has reduced unfathomable amounts of stress. No panicking over where certain files are, no digging through endless emails, and no sleepless nights wondering what services have my account information.

This is how I approach tidying my digital life.

My Cloud

I used to own external hard drives. I'd put all my files on them and keep them organized in directory structures that made sense at the time. It was convenient since I could hook it up to any computer and have access, no matter where I was.

Today, with services like Dropbox and Google Drive, I don't see a need for them anymore. Sure, there are security implications, but that doesn't outweigh knowing that even if all my devices broke, I still have access to my files. This is the same reason I use Authy over Google Authenticator.

I revisit my directory structures constantly, asking myself, "Will this reduce stress?" My general rules of thumb are:

Don't have too many files visible in a folder.
Don't have too many folders in one nesting level.
Keep everything as easy to understand as possible.

If I ever have trouble finding anything, that's a cue for me to reorganize.

I stream all my music, movies, and TV shows. I store all my photos in Google Photos. My cloud takes up less than 5GB of space, and it includes things like all my notes from college, the first site I ever built, and every PSD I created from way back in the day.

My Email

I use Gmail. I always archive my emails, I never delete. That means I have a lot of emails, but at least if there's important information I need to find in the future, it won't be deleted. If an email is actionable but I want to address it later, I snooze it (thanks Inbox, you will be missed).

I generally always maintain a zero inbox with no unread mail.

I used to manually categorize my emails but I stopped doing that -- it was way too much effort than it was worth. Companies like Google build sophisticated search algorithms for a reason. I use them pretty liberally.

I unsubscribe from everything. If I ever get a promotional email, I'll archive it, but you best believe I'm taking myself off their mailing list. This has made it so whenever I get an email notification, it's something I'll actually care about. This also made it so I don't hate emails, either.

My Digital Footprint

I keep track of all my online accounts. This is so I have a good overview of who has my data and where I can cut back to decrease that amount.

At first, it was a process to gather all this information. I jotted down all the services that I used on a regular basis, but the forgotten accounts took a bit of digging. Luckily, I keep all my account creation emails, so I was able to leverage that to bullet everything out. I'd imagine if I didn't have the emails, I'd have to use a service that checks a million apps for an account under my email address.

To my surprise I had over 150 accounts scattered around the Internet, which seemed bonkers to me. This is the equivalent of Marie Kondo's method of dumping all your clothes on your bed so you can wrap your head around just how much you own.

I immediately add to my list when I open a new account so that it's always up-to-date. I also constantly look for accounts to close. When I close an account, I make sure it's an explicit "delete account". If such an option is unavailable online, I call customer service and request it. If they're extra stingy about it, that should be a red flag, but generally if I'm courteous, they are too.

I track each service and list its status (open, closed, closing). I also tag services by category (e.g. communication, development, social network) and flag whether 2FA is enabled (I revisit my list to see where I can enable 2FA a lot, too). If something is marked as "closing" for too long and I know it's because of their support team being slow to respond, I severely question that account's service provider.

It's a Never-ending Journey

Getting to this point was a process for me, and it's a never-ending one at that. I'm always thinking about how to declutter and tidy whenever I'm using my devices. There's always a way to improve, and in turn, a way to destress and ultimately live a happier life.

Comments, questions, or suggestions? Always happy to discuss further via Twitter!

Managing WordPress with Composer

Wed, 23 Jan 2019 12:00:00 GMT

This post covers how to use Composer to offload WordPress core and plugin management to reduce your project's repo size.

Why Composer?

If you've ever built a website, chances are that you've built a WordPress site before. It's used by 32.9% of all websites as of January 2019 according to W3Techs.

And if you've ever built a WordPress site before, you'll know that the codebase is fairly, well, messy.

Composer is a dependency manager for PHP that will remedy that a bit. No need to push commits that read "Upgrade all plugins" or "Upgrade WordPress" anymore. No need to check in directories and directories of files you won't ever touch if you're just building a theme. Just have a config and lock file and you're ready to rock and roll.

Install Composer

First things first. Let's install Composer.

Linux users:

sudo apt install composer

macOS users:

brew install composer

From the root of your project, you can then run the following to setup your initial config file:

composer init

Answer "no" to the prompts that ask you to define dependencies interactively. We'll skip that step since a majority of WordPress-related packages aren't available through the official Composer registry.

You should end up with a composer.json that looks something like this (you can also manually create this file too, the composer init command just helps you through that process):

{
  "name": "<name>/<project name>",
  "authors": [
    {
      "name": "<your name>",
      "email": "<your email>"
    }
  ],
  "require": {}
}

Adding WordPress Packagist as a Repository

As mentioned a little earlier, the official Composer registry doesn't have most WordPress-related packages, so we'll have to use an alternate one. WordPress Packagist is the most widely used registry for WordPress, so let's use that.

To tell Composer to look there for packages, we need to add the following section to composer.json:

"repositories": [
  {
    "type": "composer",
    "url": "https://wpackagist.org"
  }
]

Now we have access to install any package from Packagist and WordPress Packagist!

Configuring Install Paths

By default, Composer will install packages in a vendor/ directory. While that may work for other PHP projects, that's obviously not where we want WordPress plugins, so we need to manually configure the install path ourselves.

WordPress plugins have a type of wordpress-plugin via WordPress Packagist, so we can tell Composer to install all wordpress-plugin package types to wp-content/plugins/ by adding this section:

"extra": {
  "installer-paths": {
    "wp-content/plugins/{$name}": ["type:wordpress-plugin"]
  }
}

Adding Public Plugins

WordPress Packagist works by scanning the official WordPress Subversion repository every hour, so anything that you can find through the admin UI, you'll be able to find in WordPress Packagist.

To add a plugin, find the plugin on wpackagist.org and add a line like the following in the "require" section of composer.json:

"wpackagist-plugin/<plugin name>": "*"

You can replace the * with a specific version number of the plugin as well -- using * will just tell Composer to fetch the latest version.

Once you've added all the plugins you want, run the install command and rejoice!

composer install

Adding Premium Plugins

Premium plugins are generally not available via the official WordPress plugin registry. Depending on the plugin creator, there may be specific documentation to add the plugin via Composer to your project.

If no such documentation exists though, there are still ways to have Composer manage your premium plugins.

The first is to register a plugin download link as a package. If you have a license for a plugin, chances are you have an account on their website, and you'll be able to locate a download link for the plugin.

In that case, you can add the following to composer.json under "repositories":

{
  "type": "package",
  "package": {
    "name": "<org name>/<plugin name>",
    "version": "dev-master",
    "type": "wordpress-plugin",
    "dist": {
      "type": "zip",
      "url": "<download link here>"
    }
  }
}

Then add this line to the "require" section:

"<org name>/<plugin name>": "dev-master"

Now when Composer looks through all the required packages and can't find <org name>/<plugin name> in Packagist and WordPress Packagist, it'll fall back to the package you manually registered.

We're defining the version as "dev-master" since most download links will give you the latest version of the plugin. If that's not the case, then feel free to swap it out for the appropriate version number. What's important is that the versions match in "require" and "repositories".

The second method is to self-host the premium plugin as a private repository. This should be more or less of a last resort since you'll be responsible for updating the private repository for new versions, but this will work nicely especially in teams that use starters across multiple different projects.

Create a new private repository with your service of choice and add the plugin files to it. We want to make this private so we don't expose the premium plugin files to the world -- it's premium for a reason.

Now create a new file called composer.json inside this repo. It should be in the following format:

{
  "name": "<your name>/<plugin name>",
  "description": "Self-hosted version of <plugin name>.",
  "license": "proprietary",
  "type": "wordpress-plugin",
  "require": {
    "composer/installers": "~1.0"
  }
}

<your name> should correspond to your account name on your service of choice. e.g. My username on GitHub is nshki so that would be what I use.

composer/installers is required here so that configs that install packages to custom paths can operate as expected.

Now in your WordPress repository, add the following under "repositories" in composer.json:

{
  "type": "vcs",
  "url": "git@<your service>:<your name>/<repo name>.git"
}

vcs stands for version control system. The url can just be the SSH string your service provides for your repo.

Now you can require that plugin in the familiar format (under "require"):

"<your name>/<repo name>": "dev-master"

Now run:

composer install

Composer should be pulling in your newly created private repo as a plugin in your project!

Have Composer Install WordPress

If you're like me and would want all dependencies to be managed by Composer for PHP projects, then read on.

On the homepage of WordPress Packagist, there's a small tid bit that refers to a couple resources for installing WordPress core itself using Composer. I'll be providing instructions for how to use johnpbloch/wordpress.

First, just add the following dependency under "require":

"johnpbloch/wordpress": "*"

You could run the install command right after, but you'll notice that WordPress gets downloaded into a directory called wordpress/ in the root project directory. Not what we want, assuming you want the root to correspond to the root of the WordPress site.

Now, it's important to note that by design, Composer will wipe out directories in favor of downloaded dependencies. This means that if packages weren't installed under vendor/ or WordPress under wordpress/, our entire project could be nuked.

This means that we need to write some custom scripts to reconcile this.

Luckily, Composer allows us to do just that all from within composer.json. Add the following to your config:

"scripts": {
  "post-install-cmd": [
    "if [ ! -f wp-load.php ]; then rm wordpress/composer.*; fi",
    "if [ ! -f wp-load.php ]; then rm -rf wordpress/wp-content/; fi",
    "if [ ! -f wp-load.php ]; then rm -rf wp-admin/; fi",
    "if [ ! -f wp-load.php ]; then rm -rf wp-includes/; fi",
    "if [ ! -f wp-load.php ]; then mv wp-content/ wordpress/; fi",
    "if [ -d wordpress ] && [ ! -f wp-load.php ]; then mv wordpress/* .; fi",
    "if [ -d wordpress ]; then rm -rf wordpress/; fi"
  ],
  "post-update-cmd": [
    "rm wordpress/composer.*",
    "rm -rf wordpress/wp-content/",
    "rm -rf wp-admin/",
    "rm -rf wp-includes/",
    "mv wp-content/ wordpress/",
    "mv wordpress/* .",
    "rm -rf wordpress/"
  ]
}

Ooooookay, slow down. Let's break this down.

post-install-cmd and post-update-cmd are hooks that are triggered after running composer install and composer update. You can read up on all the available hooks if you're interested.

Composer scripts allow us to run shell commands, and that's what we're doing here.

The general steps in English are as follows:

Remove Composer files from within the downloaded WordPress. This is to prevent our own from being overwritten.
Remove wp-content/ from within the downloaded WordPress since we want to use our own (and so we preserve things like uploads, etc.).
Remove wp-admin/ and wp-includes/ from our root directory to prevent "directory already exists" errors when we move files.
Move everything from wordpress/ into our root directory. Files get overwritten and updated.
Remove the wordpress/ directory.

You'll notice that the install hook has a bunch of conditionals that check for a file called wp-load.php. This is to prevent the install command from nuking any existing version of WordPress -- perhaps you updated it through the admin UI, for example. The file was arbitrary, the main objective was to look for something that indicates that WordPress already exists.

The update hook doesn't care about overwriting your existing WordPress core files since that's what it should do.

Now go ahead and install or update and profit!

composer install
composer update

Ignoring WordPress Core and Plugins in Git

One of the biggest points to using Composer was to remove all this extra fluff from our project repository, no? Let's do that.

If this was an existing project, you'll need to use git rm to remove all WordPress core and plugins from the repository. You can use git rm --cached to remove it from Git but keep the files.

Add the following to your .gitignore:

# Ignoring WordPress core files (but making sure to keep themes).
/wp-content/plugins/
/wp-content/uploads/
/wp-admin/
/wp-includes/
/index.php
/license.txt
/readme.html
/wp-activate.php
/wp-blog-header.php
/wp-comments-post.php
/wp-config-sample.php
/wp-cron.php
/wp-links-opml.php
/wp-load.php
/wp-login.php
/wp-mail.php
/wp-settings.php
/wp-signup.php
/wp-trackback.php
/xmlrpc.php

# Ignoring Composer directories.
/vendor

# Allowing these explicitly.
!/wp-config.php
!/wp-content/index.php
!/wp-content/themes/
!/wp-content/themes/**

Your repository should now be boiled down to just the essentials.

Closing Thoughts

Using Composer for WordPress is by no means necessary, but for someone like me who is used to using package managers like Bundler or Yarn, it's a huge boon to productivity and makes automation much easier down the line.

Deploying with Composer is quite easy as well. If you're managing your own servers, just install Composer and all you'll have to do is clone the repository and composer install.

If this setup works well for you or you have any questions, please reach out over Twitter!

Reviving the blog

Mon, 21 Jan 2019 12:00:00 GMT

For the past several years, I've been treating my website primarily as an online résumé of sorts -- I focused on making it flashy, telling my professional story, and selling myself.

Not to say those things aren't important, but I think my focus has been off the mark. I'm hoping that returning to blogging will help me organize my thoughts better and give me a better way to reflect on learnings. Publishing resourceful posts (hopefully) and giving employers a better picture of how I think and work are positive side effects.

"The single best thing I ever did for my career was start a blog on my own website." -- Brad Frost (@brad_frost)

Link to original tweet.

I spent a little time recycling illustrations from my previous site for this blog, and was able to write it in Gatsby fairly quickly. If you haven't tried Gatsby yet, I highly recommend it!

I was fairly proud of my previous site, however, so I decided to keep it alive on GitHub Pages. Would like to write about the process I went through to build that sometime.

Looking forward to writing more regularly as 2019 trucks forward.

Switching from a Mac to a Chromebook (as a web developer)

Sun, 26 Nov 2017 12:00:00 GMT

This is my experience switching from a 2014 Retina Macbook Pro to a Google Pixelbook. Doing this is by no means for everyone, but I wanted to share my findings for anyone toying with the idea.

Edit as of June 6th, 2018: I’ve experimented with two more ways of getting a development workflow on my Pixelbook and have updated the post to reflect them below.

Background

Ever since Apple announced their unibody aluminum MacBooks in 2008, I‘ve been a huge fan of the Mac.

Their attention to detail and tightly coupled hardware and software immediately wooed me into buying into their ecosystem. It was a blast into the future, especially considering I started off with roots in Windows 2000, Notepad++, and IE6.

The Mac introduced me to Unix, its sophisticated build tools, and the command line. I got spoiled by software like Homebrew, Sketch, and Pixelmator. As the years went by, I’ve always thought it was obvious that the Mac was the best platform for developers like me.

Today, that’s not the case.

To be clear, this post isn’t about bashing Apple. If someone were to ask me what computer they should buy if they wanted to get into development, I’d likely recommend a MacBook Pro.

This is more about my waning faith in the Apple ecosystem.

Something has been off since Steve Jobs’ untimely death. With the release of plastic iPhones, iPads with pens, and MacBooks with touchbars, I’ve been feeling Apple’s been steering further away from the original vision of all their products.

Product refreshes have been underwhelming to say the least, and their recent, seemingly poor design decisions on products such as the Magic Mouse — a device you can’t use as it charges — have really made me start looking elsewhere for an experience that just works.

Enter Google

Google has been competing with Apple for a while now, with the likes of Android, Google Apps, and Chrome. Their products are by no means perfect, but whether we like to admit it or not, a lot of us have already sold our souls to many of them. e.g. Gmail is the de facto standard for email and Google Docs is a go-to for any type of document collaboration.

This was the primary reason I switched from iOS to Android 3 years ago, and it’s one of the few reasons why I’m picking Chrome OS over macOS today.

Just this past October, Google announced the Pixelbook, a gorgeously made machine with top-notch specs, tablet and laptop modes, and a Wacom-powered pen. This was the first computer that got me to the same level of excitement as the unibody MacBook since 2008.

This got me seriously considering, what would happen if I replaced my MacBook Pro with a Pixelbook?

So I ended up ordering one.

Workflow

Email, calendar, word processing, spreadsheets, presentations, reminders, notes, and 95% of all my non-dev needs have been handled ubiquitously by Google Apps for years, so that was off my radar (not to mention the Pixelbook supports running Android apps).

I was really only concerned with two things: design software and development environment.

Turns out Figma is an excellent web-based design tool — its toolset closely mirrors Sketch with a few minor differences. After spending a couple weeks exclusively using Figma, I determined that I could live without Sketch and Pixelmator on the desktop.

The harder problem was development environment.

Again, turns out there are several options, though in the end I found only one to be completely satisfactory.

The first option I explored was using cloud IDEs. There are a handful of them out there: Cloud9 IDE, Codeanywhere, Codenvy, CodeTasty, and a few more. After trying all of them, I found Cloud9 to be the most robust and not-janky feeling IDE.

I tested Cloud9 by using the free tier exclusively for a pull request on a volunteer project using a Rails & React.js stack. My main gripes with Cloud9 were:

I had to implement a lot of workarounds in my development flow. Servers wouldn’t run without specifying $C9_HOSTNAME everywhere, PostgreSQL databases on Cloud9 didn’t support unicode by default, and only ports 8080, 8081, and 8082 were open.
It’s not very customizable. It ships with a classic and flat theme, but both pale in comparison to modern editors like Visual Studio Code or Atom.
Its future seemed unclear. It recently got acquired by Amazon, its favicon is still not Retina-ready in 2017, and its blog is not very active.

Although I could live with these issues, I didn’t want to have to sacrifice my development experience just so I could own a new and shiny Pixelbook.

There were a lot of great things about Cloud9 though, such as: autocompletion support, built-in terminal, robust keyboard shortcuts, and good syntax highlighting.

The second option was to install Termux and use a local Linux server without putting my computer in developer mode (here’s an excellent guide written by Kenneth White).

This had a lot of promise, but I ran into a one gamebreaker gripe: I didn’t have sudo access. This is just plain necessary for certain things. I tried installing a couple packages I regularly used but got blocked by permissions errors. I may revisit this again in the future, but I shelved this option for now.

The third option was to setup a VPS, ~~and this is what I'm sticking to as I write this~~. This seems like the correct option as a Chromebook user — to put my faith in the cloud and commit to using the cloud for all my computing needs.

Now, I could have put the Pixelbook in developer mode, installed Crouton, and run Linux from the device natively, but I didn’t want to deal with hardware incompatibility, losing Google Assistant, and making my device way less secure.

Instead, I setup a DigitalOcean droplet with a fresh install of Ubuntu 16.04, and everything worked as it should with none of the gripes listed above.

For my editor, I went all-in with Vim and have been very pleased. Thoughtbot’s write-ups and videos on Vim have been incredibly great resources.

Fast forward several months. The fourth option is giving in and using Crouton to run a Linux distro alongside Chrome OS.

Some time after publishing this article initially, I decided to finally give Crouton a try. Like I mentioned above, I expected a few cons to this approach: hardware incompatibilities, losing Google Assistant, and having a significantly less secure machine. I was in for a bit of a surprise.

There were reports of a faulty trackpad online, but I didn’t experience that at all with a local install of Ubuntu. The top row of the Pixelbook keyboard — with the exception of the escape key — unfortunately did not work, but I was able to make due.

The installation process itself was quite straightforward. I ended up using Ubuntu’s guide on installing Linux on a Chromebook, and was able to smoothly set the machine up with no problems. Enabling developer mode was a bit scary since you end up facing an intimidating screen about OS verification being off on each boot, but as long as I didn’t press the space bar which would completely wipe the machine, I was good.

Ubuntu works like...Ubuntu. There were no particularly unique snags. I quickly installed all my developer tools and configured an environment just as I would have on a Mac. You can even seamlessly switch between Chrome OS and Ubuntu by using the keyboard shortcut Ctrl+Alt+Shift+Back, which meant I didn’t lose Google Assistant or any other Chrome OS feature after all.

From a day-to-day standpoint, I believe that Crouton makes Chromebooks a completely viable option for developers. Though I’m not a security expert, many others online warn of having developer mode on as a security risk, so use this option with that in mind.

The fifth and most recently possible option is to use Chrome OS’s new Linux Apps feature, also known as Crostini.

At Google I/O 2018, Google announced being able to now run a Linux VM within Chrome OS. I heard some tid bits of this on the Crostini subreddit before this was officially announced, and have been completely on board with this since.

This feature is still under active development, but the Pixelbook (and a few other machines) can switch to the Chrome OS dev channel to begin using Linux apps now.

EDIT (September 26, 2018): Linux Apps are now available on the stable channel for Chrome OS, so this should be enable-able out of the box!

This takes the cake for me for my Chrome OS development setup. This is similar to having a Termux setup, except that the Linux environment allows sudo and is natively supported by the Chrome OS team. Furthermore, you don’t need developer mode enabled, so you get all your security and peace of mind back.

~~Since Linux is running in a VM, accessing web apps requires you to use the VM’s IP address or simply just penguin.linux.test, which is more convenient.~~ As of stable versions of Chrome OS in early 2019, accessing localhost now works as expected.

So far, I’ve run into no issues with my development environment or command line tools. I’m quite a happy camper.

Closing Thoughts

I’ve been really happy with my Pixelbook so far. I was able to consolidate my devices and put my money towards an ecosystem that I believe is only going to get better.

Some might ask, why not the Surface? To be honest, I seriously considered the Surface Book as well. I used exclusively Windows via Bootcamp for a week to get a hang for the new Linux subsystem, but kind of like the Cloud9 trial, there were too many hoops to jump through to get an ideal development environment.

Routing JavaScript in Rails

Tue, 17 Jun 2014 12:00:00 GMT

This post is inspired by Paul Irish’s original post on DOM-ready execution and also by my coworker Danny.

I’ve been working on JavaScript-heavy Rails projects lately, and it quickly became apparent that a sensible JavaScript architecture was needed to keep things in order. As I browsed through the repositories of other projects to see what others have done in the past, I found an interesting object called UTIL.

UTIL = {
  exec: function(controller, action) {
    var ns     = VAW,
        action = (action === undefined) ? "init" : action;

    if (controller !== "" && ns[controller] && typeof ns[controller][action] == "function") {
      ns[controller][action]();
    }
  },

  init: function() {
    var body       = document.body,
        controller = body.getAttribute("data-controller"),
        action     = body.getAttribute("data-action");

    UTIL.exec(controller, action);
  }
};

I was referred to an article written by Paul Irish from a few years ago, and was immediately intrigued. By tacking on data attributes on the body tag, you’re able to neatly “route” the execution of JavaScript using the UTIL object:

<body data-controller="<%= controller_name %>" data-action="<%= action_name %>">

var controllerName = {
  actionName: function() {
    // this code will only execute on controllerName#actionName!
  }
};

Genius.

I wanted to take it one step further.

This set up better organized JavaScript without the bloat of JavaScript frameworks, and because recently I’ve been pushing for components-based front end architectures, I wanted to incorporate this routing technique with modules.

Modules in JavaScript are essentially a set of namespaced, re-usable functions that define the behavior of app components (a modal, for example), like so:

var MyModal = {
  init: function() {
    // code...
  },

  show: function() {
    // code...
  },

  hide: function() {
    // code...
  }
};

While Paul Irish’s routing technique encourages “modules” to an extent, it does not directly translate into re-usable bundles of code, since it’s possible to still have to repeat yourself across multiple actions.

So, here’s my take on using modules with routing (in CoffeeScript). The javascripts/ directory should look like this:

javascripts/
|_ config/
|  |_ namespace.coffee
|  |_ router.coffee
|  |_ routes.coffee
|
|_ modules/
|_ vendor/
|_ application.js.coffee

The config/ directory will contain three files: namespace.coffee, routing.coffee, and router.coffee.

#===============================================================================
# namespace.coffee
#
# Defines a custom namespace for the application.
#===============================================================================

window.NS = {}

The namespace config file will simply define the primary namespace of the app. We’re assigning it to window so that it’s accessible globally. NS should be changed to the name of your app.

#===============================================================================
# router.coffee
#
# Routes execution of scripts based on controller-action pairs.
#===============================================================================

NS.router =

  # Run on document load. Gets controller and action of current page and
  # executes corresponding scripts.
  init: ->
    body       = document.body
    controller = body.getAttribute("data-controller")
    action     = body.getAttribute("data-action")
    this.exec(controller, action)

  # Executes a function in the application namespace.
  # @param {string} - controller
  #        {string} - action
  exec: (controller, action = "init") ->
    if NS[controller] && typeof NS[controller][action] == "function"
      NS[controller][action]()

# Initialize router
document.addEventListener "DOMContentLoaded", -> NS.router.init()
document.addEventListener "page:load",        -> NS.router.init()

This is a direct translation of Paul Irish’s UTIL object into CoffeeScript. I’m opting to use addEventListener to add DOM-ready events to make this architecture independent of jQuery. The page:load event is necessary only if you’re using Turbolinks.

#===============================================================================
# routes.coffee
#
# Defines custom routes for script execution.
#===============================================================================

NS.my_controller_name =
  my_action_name: ->
    NS.my_module_name.init()

Now, the routes file is where different modules are initialized on a per-action basis. This means that we can neatly separate modules into their own files without worrying about which actions it should be used on, then connect them using routes.coffee.

This has worked fairly well on the projects I’ve implemented this on.

routes.coffee can get cluttered rather quickly, however, and that is something to be improved upon in the future.

Comment, because people

Fri, 27 Dec 2013 12:00:00 GMT

"Good code doesn’t need comments, it should be self-documenting and easy to understand."

This is a quote from one of my former computer science professors in college. I’m referring to it here because, frankly, I completely disagree.

Comments don’t get as much attention as they deserve. They are the key to clear understanding of what code snippets are supposed to do. While code should be written to be easily understood, people approach different problems in different ways. What’s obvious to one person may not be obvious to another, and a lot of problems can be solved if there was a simple one-liner somewhere that explains the need for some conditional or assignment statement.

A lot of people, myself included, have often fallen into the trap of leaving comments as afterthoughts. This results in meaningless words that even the original commentator can have trouble figuring out. The tendency is to think, “I’ll finish figuring out the implementation before writing any comments,” when we should be figuring out the implementation in English before writing any code. Comments serve as a roadmap, both to the developer writing them and to the people reading them.

We’re only human. We forget, we misunderstand, we make mistakes. Comments can serve as our primary weapon against that. They spare our future selves countless hours of tracing and they let our co-workers flip straight to the same page we’re on. We can save everybody time by just writing comments.

Good code needs comments. Good code needs comments because people.

Nishiki Liu

Vibe check, November 2025

My ZSA layouts

Voyager

Layer 0: Main (Voyager)

Layer 1: Symbols (Voyager)

Layer 2: Media (Voyager)

Moonlander

Layer 0: Main (Moonlander)

Layer 1: Symbols (Moonlander)

Layer 2: Media (Moonlander)

Downloads

Vibe check, April 2025

Finding boosts

A moment of joy with CSS grid

WordPress, the Great Divide, and a build-less experience

Broaching the Great Divide, again

Build-less CSS

Build-less JavaScript

Deploying like the old days

Closing thoughts

Migrating Rails from Postgres to SQLite

Installation and revisiting the schema

Refactoring caching usage

Migrating production data

SQLite is rock solid

Replacing ChromeOS with Linux on the 2017 Pixelbook (Eve)

1. Enable developer mode on the device

2. Enable booting from USB

3. Plug in the Linux USB drive

4. Fix screen orientation and brightness (Pixelbook and Ubuntu-specific)

Live, laugh, love

How to: Selenium with Chrome extensions

Setting up the project

Starting Selenium Chrome with extensions

Method 1: Loading with a local directory

Method 2: Loading with a CRX file

Interacting with extensions

Closing thoughts

Our little universes

Rubber bands

The Web pendulum

Open source chats with Kasper Timm Hansen

Read bits of the codebase at a time

Reading leads to learning

Make learning the goal

Closing thoughts

Thoughts on data

Keep raw data

Normalize that data

Use background jobs

Batch things wherever possible

Encrypt sensitive bits

Get agreement on and document events

Bring in your data team

+918 -24,519

Accessing a previous session in NextAuth.js callbacks

General strategy

1. Get access to the NextApiRequest object

2. Use a custom session cookie name

3. Add custom JWT encode and decode functions

4. Decode the session token

Wrapping up

Replace a relational database with DynamoDB in Rails

1. Install Dynamoid

2. Dockerize the project

3. Configure Dynamoid

4. Migrate models

5. Remove Active Record

6. Configure test suite

...profit! 🎉

Adding a Cypress test suite to your full stack Next.js app

Installing the packages

Creating the test database

Example for PostgreSQL

Adding the scripts

Running Cypress for the first time

Configuring CI

Wrapping up

Giving Ruby objects access to Rails view methods

1. Get access to the `NextApiRequest` object