Forem: Joshua Tzucker

Git SHA Badges - Know Which Commit is Live

Joshua Tzucker — Mon, 14 Dec 2020 17:47:58 +0000

Demo Repo

I've taken the approaches covered in this post and created a fully-functional demo repo to demonstrate them in action:

💾 github.com/joshuatz/git-sha-badges.

Intro

When building a project that lives in a Git repository and auto-deploys elsewhere, a common concern is how to be 100% absolutely sure that the live "deployed" version is up-to-date. If I go to the live, production application, how can I trust that what I am seeing is the latest pushed code in my repository?

Just because my CI/CD pipeline passed does not necessarily mean that the latest commit is live yet. Furthermore, if something goes bad, I want to be able to know at a glance exactly what code is live in production. A simple "pass / fail" badge cannot tell me that.

Close, but Not Good Enough

Many automated deploy systems provide a build status badge, but this doesn't tell us much:

Standard Netlify Status Badge:

Many apps also display in the deployed UI the current version string of the app (e.g. 1.8.2-beta.1.10), but this actually still leaves a lot of room for ambiguity; what if a developer used --force to override the head of the main branch? What if there have been commits added to the main branch, but no new release authored? Etc.

Instead of a version string, a nice alternative (or better yet, an addition) is to use the actual SHA of the latest commit as a status indicator. This makes it very easy to compare against the latest commit in version control, and verify that the correct set of changes are live.

Furthermore, no two commits can have the same SHA, even if --force has been used, so if I know the SHA that is "live", I know exactly what code is running, and can even quickly "checkout" that exact version of code in my local environment.

💡 Similar to how you can use git checkout {branch_name}, you can also use git checkout {SHA} to checkout your entire repo at that commit. It kind of feels like time travelling!

Methods for Creating SHA Badges

The general concept that we are going to employ is that our build step, which runs on every deploy, is now going to save the current SHA of the branch (aka the tip) in an accessible format that can be used for visual indicators.

Two easy approaches that build off this concept, and which I'll explore here, are JSON files and raw SVG files.

JSON File

The basic idea with the JSON file approach is that, at build time, we stash the value of the latest SHA in a shared JSON file. This makes it easy to reuse across our codebase, possibly even at runtime, and in a widely compatible format.

The JSON file approach is my favorite, for a couple of reasons:

It is easier than dealing with SVG string building, but can be combined with that approach easily (more details further below)
The JSON file can be re-used, and even imported into runtime code (assuming they share access)!
Usable by APIs and 3rd party services (including Shields.io for badges)

JSON File - Getting and Saving the SHA

The implementation of this task could be accomplished in an endless number of ways, and the best option probably depends on the specifics of your build environment, project type, and operating system.

For a generic example, here is how I how I have integrated this approach into a NodeJS based project, within a package.json file:

{
  "scripts": {
    "build-badge": "$NETLIFY && git rev-parse --short HEAD | xargs -I % printf '{\"sha\":\"%\"}' > ./static/build-info.json",
    "build": "(yarn run build-badge || true) && gatsby build"
  }
}

The most important thing about the above command is that it modifies our build command, which used to be just gatsby build, to include a step that saves the current SHA to a JSON file (./static/build-info.json). If you wanted to, you could replace a lot of the bash stuff with a NodeJS or python script that does the same thing.

If you want a breakdown of the above command, you can view it below

Show / Hide Details

To break this down further, the build-badge command is composed of:

$NETLIFY is an environmental variable that only exists within my build environment (Netlify servers).
- You could use any value that evaluates to true in your build system
- Or, if you always want this file generated regardless of local vs production, you could omit the whole $VARIABLE && part
git rev-parse --short HEAD
- This is a git command to get the short version of the last commit SHA
- You could use the full SHA instead; just omit --short
- If you are looking for a lot of nifty git commands like this one, here is a shameless plug to check out my Git Cheat Sheet (this command is on it!)
xargs -I % printf '{\"sha\":\"%\"}'
- Not going to get too much into this, but it is a fancy way of passing the SHA from the last section into a stringified JSON representation
> ./static/build-info.json
- Save the generated JSON string to a file. This could be any file, and it doesn't even necessarily need the .json extension
- You should make sure that whatever directory you save it to is going to be accessible after the build is complete, either internally and/or externally (hosted)

And I've changed my build command from gatsby build to (yarn run build-badge || true) && gatsby build:

This is an easy way to make sure that gatsby build, the true build command, always runs regardless of the success or failure of the build-badge command.

Again, as an alternative to a long bash command you could alternatively extract and save the SHA entirely in your favorite scripting language of choice (NodeJS, Python, etc.).

JSON File - Using the Stored SHA

As-is, once we have our JSON file, that alone is enough to be able to add badges or pull the SHA value into front-end code. For example, we can use the dynamic badge feature of Shields.io to easily get a SVG URL that displays our SHA. Something like:

<img src="https://img.shields.io/badge/dynamic/json?color=blue&label=Deployed%20SHA&query=sha&url=https%3A%2F%2Fgit-sha-badges.netlify.app%2Fbuild-info.json" alt="Deployed SHA" />

Notice the importance of:
 - query=sha
 - url=HOSTED_SITE/build-info.json

If you wanted to pull it into your code, in CommonJS, that is as easy as:

const buildInfo = require(`${BUILD_DIR}/build-info.json`);
console.log(buildInfo.sha);

SVG File

Rather than displaying your SHA in front-end code by pulling it in via AJAX or inside framework components (e.g. a React component), you could also pre-generate SVG badges at build time, with just a little bit of code.

The easiest approach is to have 99% of the SVG badge ready-to-go, stored as a string. You can use whatever method you prefer for designing your badge. The main thing to do is leave room for the SHA to be inserted at build time, as a <text></text> element inside the SVG.

At build time, you combine your SVG template string with the latest SHA (this is where it is handy to have that build-info.json already generated), and then write out the resulting string to an actual .svg file, which can be served.

You can checkout how I put this all together in build.js in my demo repo.

In pseudo code, this approach might look something like:

// Compose full SVG string
const svgStr = '<svg>' + svgTemplateStr + '<text>' + sha + '</text></svg>';
// Save to SVG
saveFile(svgStr, 'my-badge.svg');

And don't forget, you can get as fancy as you want with your generated SVGs 😄

Bonus: Github Commit Badges

If all you want is a badge that shows the current HEAD of a particular branch in Github (i.e. the most recent pushed commit) - you can actually do this entirely with just Shields.io and the public Github API (no credentials required).

Caveat: this requires that your repo is published as public

First, you need get the API endpoint that returns HEAD info, for your specific repo and branch combo. The syntax follows:

https://api.github.com/repos/{USER}/{REPO}/git/refs/heads/{BRANCH}

So, for example, to get the currently pushed tip for my main branch in my demo repo for this post (joshuatz/git-sha-badges), I can use api.github.com/repos/joshuatz/git-sha-badges/git/refs/heads/main.

If you try that URL, you will get a JSON response, including:

{
    // Other stuff
    "object": {
        "sha": "____",
        "type": "commit"
    }
}

Now, we can plug that endpoint directly into Shield's amazing dynamic badge generator, which accepts a JSON endpoint and lets us control badge settings through query string parameters. By tweaking the parameters, we can get an orange badge that displays the object.sha value in the endpoint:

API Endpoint:
  https://api.github.com/repos/joshuatz/git-sha-badges/git/refs/heads/main

Shield Badge Base Endpoint
  https://img.shields.io/badge/dynamic/json

Shield Badge URL (raw)
  https://img.shields.io/badge/dynamic/json?color=orange&label=Github SHA&query=object.sha&url=https://api.github.com/repos/joshuatz/git-sha-badges/git/refs/heads/main

Same URL, encoded:
  https://img.shields.io/badge/dynamic/json?color=orange&label=Github%20SHA&query=object.sha&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fjoshuatz%2Fgit-sha-badges%2Fgit%2Frefs%2Fheads%2Fmain

---

Final badge code

---

Markdown:
  ![Github SHA](https://img.shields.io/badge/dynamic/json?color=orange&label=Github%20SHA&query=object.sha&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fjoshuatz%2Fgit-sha-badges%2Fgit%2Frefs%2Fheads%2Fmain)

HTML
  <img src="https://img.shields.io/badge/dynamic/json?color=orange&label=Github%20SHA&query=object.sha&url=https%3A%2F%2Fapi.github.com%2Frepos%2Fjoshuatz%2Fgit-sha-badges%2Fgit%2Frefs%2Fheads%2Fmain" alt="Github SHA" />

And, here it is (this is a live badge!):

Wrap Up

I want to wrap up this post by pointing out that, although I gave some specific examples and code samples, the approaches throughout this post are fairly generic in nature and could be extended to solutions beyond just adding Git SHA badges.

For example, if you maintain several build and deploy targets (e.g. dev, test, staging-alpha, production, etc.), you could re-use most of the solutions through this post to add visual indicators to each environment that makes it clear what system you are looking at.

Hope this post helps someone out there! (And kudos to anyone that understands and appreciates what my fancy SVG example is referencing).

More About Me (Joshua Tzucker):

Generate a Perfectly-Sized Cover Image with Cloudinary

Joshua Tzucker — Thu, 14 May 2020 18:49:38 +0000

For those unfamiliar with Cloudinary, it is a cloud service that is focused on image serving, with unique features like transformations, responsive generation, and a speedy CDN for delivery. I have no affiliation with Cloudinary, other than being a fan of their service.

Introduction

One of the big changes in web development over the years has been a shift from "fixed" designs to "responsive". For example, where we used to define layouts or the display of assets with fixed units, we now try to use percentages or other ratio based approaches to adapt to any display size. This is something to be celebrated, and Cloudinary has an entire feature set built around this, but today I want to talk about when the opposite approach is needed.

We often have "cover images", "hero images", and/or images that we need for social media sharing sites, and these frequently have specific desired pixel sizes or aspect ratios. For example:

Dev.to cover image: 1000 x 420 (see Editor Guide)
Twitter: (depends) 16:9 (1.77:1), 2:1, 1200x628 (1.91:1)
Facebook feed: 1.91:1

Finding images that perfectly fit these aspect ratios is often difficult and time-consuming, and manually cropping and resizing existing images to fit, equally so.

What if there was a better way to generate the perfectly sized hero image, with any image as the input?...

Our Goal

So, here is our example goal. We want to produce a 1000 x 420 pixel (2.38:1) cover image for Dev.to, but do so automatically, with a method that accepts any image as the input. If the input aspect ratio does not match the desired output, then the input will be centered, and a blurred background based on the same input shown behind it.

Sample Input:

Sample goal output:

The cover image for this very post was created with the method outlined below! But, you'll see that later.

Building It With Cloudinary

I'm going to walk through how to build this with Cloudinary image transformations, using URL parameters alone. This makes it very easy to use anywhere, with any backend or frontend, since all we need is a URL.

Base Image: https://res.cloudinary.com/demo/image/upload/sample

When you see Bold and Italic text in the URL, that indicates what was added in the step.

Steps:

Start with the "Base Image": https://res.cloudinary.com/demo/image/upload/sample
- Added: sample
Use image to fill exact desired size
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420/sample
- Added: /c_fill,w_1000,h_420/
Since this is actually going to be the background, apply a blur effect and reduce opacity
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/sample
- Added: e_blur:1500,o_75
- Blur is on a scale from 1 to 2000
- Opacity is on a scale from 0 to 100 (100 being completely opaque)
Overlay the same image, but limit its size to the "canvas"
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420/sample
- Added: /l_sample,c_limit,w_1000,h_420/
- Notice how l_{uploadedId} is used to generate an image overlay layer.
Add a nice blurred border to our overlay
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420,e_outline:outer:2:100/sample
- Added: e_outline:outer:2:100
- You might notice that the border now pushes the overlay outside the canvas...
Prevent "overflow" caused by new border
- Adding a border to the overlay actually made it larger than the boundaries of the background (base image). We have two options to remedy this:
- Option A: Re-crop: Since adding a border to the overlay made it larger than the boundaries of the background, we can simply re-crop the output
  - https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420,e_outline:outer:2:100/c_crop,w_1000,h_420/sample
  - Added: /c_crop,w_1000,h_420/
  - If we wanted to re-crop just the overlay, we could use fl_layer_apply to prevent crop action from applying to the entire chain
- Option B: Use the no_overflow_flag
  - This is a super helpful flag to remember! From the docs:
    - > Prevents Cloudinary from extending the image canvas beyond the original dimensions when overlaying text and other images.
  - https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420,e_outline:outer:2:100,fl_no_overflow/sample
  - Added: fl_no_overflow

Final output, using option B:

Extras:

There is still more we can do with this!

Add compression
- To save some bytes, we can tell Cloudinary to serve as a compressed JPG with a quality of 80%
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420,e_outline:outer:2:100/c_crop,w_1000,h_420,q_80/sample
- For our sample image, this gives us a saving of approximately 50%!!!
Add overlay text
- We can add overlay text, such as the title of the post that our cover image is for
- https://res.cloudinary.com/demo/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_sample,c_limit,w_1000,h_420,e_outline:outer:2:100,fl_no_overflow/l_text:Roboto_100_normal_stroke_:Hero%20Image,co_rgb:FFFFFF,bo_8px_solid_black,g_south,y_30/sample
- stroke, and border (bo_) are used to provide an outline around the text

Wrap-Up

This might have seemed like a bunch of work, but don't forget; now that we have the transformation chain built, we can reuse it across an unlimited number of images, simply replacing {uploadedId} with our desired input:

const myCloudId = 'acb123';

// pretend `myImages` is an array of hundreds of image IDs
myImages.forEach(uploadedId => {
    const heroImage = `https://res.cloudinary.com/${myCloudId}/image/upload/c_fill,w_1000,h_420,e_blur:1500,o_75/l_${uploadedId},c_limit,w_1000,h_420,e_outline:outer:2:100,fl_no_overflow/${uploadedId}`;
    saveImage(heroImage);
});

In fact, here it is in action, working its magic across any input I give it (large GIF, give a second to load...):

Nice, right!?

We could also...

Save this as a Named Transformation
- Once we do this, reusing it becomes as easy as /image/upload/{transformationName}/{uploadedId}
Implement this via Cloudinary API
Integrate into any backend (WordPress, Gatsby, etc.) for dynamic meta image tags to serve to Twitter, FB / OpenGraph, etc.
... and many more things!

If this was interesting to you, I have a few other Cloudinary related projects that might be worth checking out:

Cloudinary Cheatsheet - WIP quick cheatsheet

Desktop Cloud Transform - Transform local images with Cloudinary, with easy drag-and-drop GUI

Cloudinary WYSIWYG - Visually build Cloudinary transformations with interactive canvas

More About Me:

Using Windows Task Scheduler to Automate NodeJS Scripts

Joshua Tzucker — Fri, 21 Feb 2020 21:28:37 +0000

This is a post about using Windows Task Scheduler to automate the execution of NodeJS scripts, and other NPM / Yarn based tasks. If you don't use Windows, this post is probably not for you (but feel free to read anyways 🤷‍♀️)

Why? 🤔

Tons of reasons! Maybe you are trying to emulate a production environment that has NodeJS scripts as scheduled CRON tasks. Or, for your own productivity or fun you want to script things to happen based on Window events.

For example, you could write a NodeJS script that talks to your project tracker of choice via API and stops any running timers when you lock your computer to take a break.

Why not just use `crontab` under WSL?

Good question! If you have WSL (Windows Subsystem for Linux) installed, and you only want to trigger actions based on time, then you should totally give crontab under WSL a shot!

Although there used to be issues with it (in past versions, WSL used to kill background tasks when you closed the console), I just gave it a shot, and had success. If there is interest, I might make a separate post about how to setup crontab under WSL.

However, Task Scheduler still has value as a separate tool, since more than just time can be used as a trigger; you can execute tasks based on computer unlocks, power events, and more. You can't do that with crontab.

How? 🤓

Steps:

Find where the binary / application you need to run is stored
- You can use where npm or where yarn from the command line to find the path
  - Example: My yarn path is C:\Program Files (x86)\Yarn\bin\yarn.cmd
Open Task Scheduler (search in programs, or WIN+R, taskschd.msc)
Start the task creation process by clicking on "Create Basic Task" or "Create Task" in the sidebar
Pick a trigger
- "On a Schedule" (like CRON)
- "At log on"
- Etc.
Add your Action: Action -> Start a Program
- "Program/script":
  - Here is where you plug in the path to the application you found in step 1
- "Add arguments" - You should put whatever you would put after npm or yarn normally.
  - If normally execute npm run myScheduledTask, you would want arguments to be run myScheduledTask
- If you are calling a scripts entry in a package.json file, you need to tell scheduler to run this where your package.json file is located.
  - If using Yarn, you can pass the working directory through args, with cwd.
  - Otherwise, use the start in (optional) field to specify the directory

If you are concerned about keeping track of the results of what ran, you can also capture the result of anything spit out to the console by using >> task_log.txt or something like that.

👩‍🍳 - You can combine actions and triggers

One nice feature of task scheduler that I did not notice immediately is that it does not have to be a 1:1 mapping of task-trigger-action.

For example, you can group ten different actions under a single task with a shared trigger.

✨ - You can use Git Bash for more advanced scripting

Instead of targeting NPM, Yarn, or Windows CMD, if you have Git Bash (comes packaged with Git for Windows), you can it as the target "Program/Script", and then execute a more advanced command that uses some bash tools. For example, a sample task that performs some backups for a project might look like:

"Program/Script": C:\Program Files\Git\git-bash.exe
"Add Arguments": cd C:/projects/my-proj && node prep-dirs.js && npm run backup >> backup_log.txt

💥 - `%1 is not a valid Win32 application`

If you see this error, you have probably selected the wrong application as the Program/Script to execute. For example, using /yarn instead of yarn.cmd will result in this error.

⚙ - Stop the Cmd window from popping up

If the black windows Command prompt window keeps popping up whenever your task runs, you need to change one of the basic settings:

Change security options to: Run whether user is logged on or not
- 🔐You will probably also want to check Do not store password

There is no harm in having it show up; but it might get annoying if your task is scheduled to run frequently.

⏰ - How to schedule more frequently than every 5 minutes

You might have already noticed that the smallest interval that shows up in the repeat task every duration picker, under trigger settings, is 5 minutes. Uh-oh!

Actually, this is an easy fix - you can actually type a custom interval in that box! So if you wanted an entry that was equivalent to a CRON of * * * * * (every minute), just type in the box 1 minute and set for a duration of to Indefinitely.

Here is what that looks like:

Comparison with CRON

Since this is likely to come up in the comments (I can already hear the annoying response; ''why don't you use a real operating system? lol!") - yes, Task Scheduler is not a perfect replacement for CRON on windows. But it is not really meant to be, and this post is not advocating as such either.

Plus, you can use crontab under WSL now (see my note under "why?").

Wrap Up

I hope this was helpful! This is a bit different from what I normally write about, but felt compelled to publish it as I had trouble finding existing resources on the topic.

5 Underrated Built-In VSCode Features

Joshua Tzucker — Thu, 02 Jan 2020 20:21:11 +0000

Intro

First, to get this out the way, this post is not a list of "top extensions you need to install". Although those lists are helpful (albeit a little "clickbaity"), and I love that VSCode has an extremely "healthy" ecosystem of extensions and plugins, I noticed few posts about the amazing stuff that is built-in to VSCode from the get-go, and that is what I want to talk about.

These are features of VSCode that are baked into the editor (no extensions or tooling to install), but I personally don't think are getting enough attention and could use a PSA.

#1: JavaScript Type Safety

Although the rest of the list is not really ordered, this definitely deserves a #1 spot, by a large margin. I'm not going to shove TypeScript or type-safe JS (what?!) down your throat, but I'd like to just point out how VSCode has a feature that allows you to get some of the benefits of type-safety, without needing to switch to TS files, transpiling / compiling, or requiring that other devs use TypeScript in order to use your codebase.

This is a wonderful half-way solution for those looking to introduce some type-safety into their JS code immediately, with minimal changes and setup.

I don't want to go too in-depth on this, as there are multiple guides on this out there, but I'll cover some "quickstart" basics:

Enabling JS Type Checking

There are multiple ways to enable type checking in JS files, but the easiest if you are looking to just try it out, is to add // @ts-check to the top of your file.

See the "Type Checking JavaScript" section of VSCode's "Working with JavaScript" docs for more details.

What does this get you?

If you don't want to do any extra work (such as annotating types or setting up configs), simply adding // @ts-check is a way to instantly get TypeScript powered type checking in VSCode.

For example, checkout this screenshot comparing a JS file without and with TS-checking on:

In the above example, the developer has forgotten that querySelectorAll does not return an array, it returns something special - a NodeList - which does not have the built in map() method that arrays have. With type checking on, the fatal error triggered by the use of map is caught in VSCode and flagged.

For those wondering, an easy way to convert from a NodeList to an array is to use Array.from: Array.from(document.querySelectorAll('a[href]'))

Annotating Types with JSDoc and Advanced Usage

The "power-user" part of this feature is the ability to use JSDoc comments to tell VSCode's TypeScript powered intellisense system about advanced types that are within your JS code. This TypeScript doc page - "Type Checking JavaScript Files" goes into depth on it, but for brevity, I'll just paste a cool example:

For even more advanced usage, there are some great resources out there, starting with my VSCode cheatsheet which has a whole section devoted to JSDoc powered type checking and intellisense 🙂. It also has a list of links to other helpful related resources.

#2: Making things easier for contributors

Spending time to streamline the process for other people to contribute code to your codebase might feel like a chore, but in the long-run it makes things better for everyone. The easier and more "mistake-proof" the process is for devs to contribute, the less likely it is that you will have to field duplicate questions, reject PRs for violating guidelines, and deal with unnecessary back and forth.

What you might be surprised to learn is that VSCode has some built-in features that help with this goal.

Recommended Extensions

One of them I actually learned about when I poked through Dev.to's own source code, as it was the first time I had seen it used - "Recommended Extensions". The way it works is that you add a special file - .vscode/extensions.json - to your project root, with a list of extensions that you want all contributors to be using (for example, Prettier), and VSCode will pick up on that and popup a recommendation to Devs to install them when they clone and open your repo.

You can find more details on how to use this in VSCode's workspace recommended extensions documentation.

Workspace tools and settings

Built-in to VSCode are multiple places where you can override user settings and craft per project configurations, both of which can make it easier for contributors to work in your codebase with VSCode.

For example, if you manage a mono-repo with distinct parts, you might want to take a look at "multi-root workspaces".

For overriding settings, such as default indent and spacing options, you can commit .vscode/settings.json to the root of your repo with the overrides, but be respectful of your contributors and don't override anything that you want them to be able to change.

#3: User-Defined Snippets

Although VSCode does not yet support advanced macros (without the use of an extension that is), did you know that it does already support advanced snippets? At first glance, these might seem like they can only insert basic blocks of text, but you can actually do some advanced things with them.

For example, here is a snippet that I quickly whipped up to convert a markdown style bullet list into Github styled checkbox list:

{
    "MD List to GH Checkbox": {
        "scope": "markdown",
        "prefix": "list-to-checkbox",
        "body": [
            "${TM_SELECTED_TEXT/^([\t ]*-) ?(.*)$/$1 [ ] $2/gm}"
        ],
        "description": "Transform MD list to MD checkbox list"
    }
}

Here it is working in action:

The main docs page for creating custom snippets is here.

#4: Reordering Imports Automatically

First, I would like to thank Ryan Chenkie, for this tweet that brought this to my attention:

Ryan Chenkie

@ryanchenkie

Just learned about the quick key in VS Code to remove unused imports and reorder used imports: Shift + Option + O.

Save yourself some time when you want to clean up imports 🙌

15:17 PM - 03 Dec 2019

For Windows users, that key combo is SHIFT + ALT + O, by default.

As a reply to that tweet pointed out, you can also have VSCode automatically do this, by configuring it in your settings.json file, like so:

{
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    }
}

#5: Ability to build a custom extension for yourself or your company

One of the best things about VSCode is how extensible it is, and how easy it is to build and test new extensions. Often when this is discussed, the focus is on really flashy and/or impressive extensions, but I want to remind everyone that extensions that solve a singular niche problem can be just as important, especially within certain organizations.

Within the discussion of "tooling", you should think if there is a custom extension that could be built for your company (or just yourself) that could improve your developer workflow, help convert legacy code, and/or interop between processes that are specific to your work. It might be easier than you think to build one, and as a bonus, is sure to impress others.

Wrap Up

I hope you found at least one of these items helpful! Thank you to the VSCode team and open-source contributors for building a revolutionary code editor!

Fixed URL Reverse-Proxy with Serverless (GCP) Functions and Ngrok

Joshua Tzucker — Tue, 03 Dec 2019 23:39:23 +0000

Background - Why might you need a reverse proxy?

Web development tooling has come a long way, and most frameworks and SDKs have made previewing your app as you work a breeze; often it is as simple as running something like npm start from your CLI. But an unexpected hurdle that many web developers hit, and can seem much more complicated, is "how do I use this outside of my local network?". Things like screen-sharing, screen recording, and VSCode's Live Share can solve this issue if all you need to do is show your localhost demo to your remote coworker. But if you need to actually expose your code to the outside world, those tools fall short.

For example, a very common scenario is trying to test a third-party service (Slack, Github, Twilio, etc.) that talks to your codebase, maybe through a webhook. In this scenario, you can't run the third party code locally (e.g. running all of Github's platform on your computer), and if you put something like "localhost:3001/webhook" as the webhook, that third party is going to be unable to reach the code running inside your local network (for good reason!).

How do we solve this?

Reverse-Proxies

The common solution to this issue is a reverse proxy combined with ssh tunneling. You have a public URL, which points to a public server, which uses a reverse proxy to hand-off the request to a different port and/or server, which in turn gets proxied / tunneled via a SSH tunnel between the server and our local development computer. This is much easier to show visually, so here is a simplistic diagram showing this:

There is a lot that goes into this solution. You need to run a public server, set up SSH support on it, have a domain name, DNS entries, SSL certificates; the list goes on and on. It's not all that complicated (here is a simple guide), but it is also not free or quick.

Quick, Simple, and *Free - Ngrok

Given the complexity of setting up a full reverse-proxy through a SSH pipeline, services have sprung up to simplify this for developers.

One of the most popular and easiest to use is Ngrok. With a single command, you can instantly get a public URL that you can use to access your localhost from anywhere - no public server or complicated setup necessary!

For example, to relay HTTP requests from outside your home network to your localhost on port 3001, you could use ngrok http 3001 and be up and running in seconds!

Ngrok basically takes the place of both the SSH tunnel setup (with its CLI client), and the public server with a reverse proxy - the second and third blocks in my diagram up above. It even comes with built-in tools, such as a dashboard, request inspector, and replay functionality.

Ngrok is also recommended by several well-known third-party platforms (Twilio, Github).

I am not affiliated with Ngrok in any way; I just think they have an impressive service.

The downside to Ngrok

Although Ngrok has a very generous free tier, one major restriction is that the public URLs that are generated are both random and not assigned - meaning that each time you start it up, you will get a different random subdomain, like https://df12f52a.ngrok.io. If you are trying to develop webhooks or something similar, this means that each time you need to restart Ngrok, you would have to login into your third-party platform, find the admin dashboard, and copy and paste your new Ngrok URL into the GUI. Or, if you are sharing URLs with coworkers, you would need to keep sending them updated URLs.

Ngrok does offer custom subdomains or personalized domains, but these come under the paid option, which starts at $5 a month. Not much, but this is basically the same price as running Ngrok or Nginx reverse proxy yourself on a paid server, like Digital Ocean.

My Solution - Add Another Proxy with Cloud Functions!

This is the kind of solution I am simultaneously both proud and ashamed of. Because I am cheap, and didn't feel like buying a paid Ngrok plan just to test webhooks a few times a year, or setting up a dedicated server for it, I started thinking of how I might use free, or very low cost workarounds. What I came up with is kind of silly, but it works - just add another proxy, with a fixed URL, in front of the changing Ngrok URL!

Let me elaborate. As I researched options, I noticed that cloud functions (Google Cloud Functions or AWS Lambda) were often the cheapest to use, in that they start at a scale of zero by design (they only run when requested). At first I was thinking of replacing Ngrok with them entirely, but this quickly was squashed; they are designed to execute quickly and exit, and would not work for maintaining a SSH tunnel connnection.

However, I realized two important things; cloud functions often get a semi-permanent PUBLIC url to invoke them, and they can handle both incoming and outbound requests. With this in mind, I realized I could setup a cloud function with a public URL, that simply proxies inbound requests to a re-configurable Ngrok address. Here is what that looks like:

In this scenario, my Cloud Function public URL stays static, even as the Ngrok address it points to changes!

The code required to build this is very simple too; it can be assembled with just a little NodeJS, Express, body-parser middleware, and, most important, http-proxy-middleware.

The only caveat here is that the cloud function has to be redeployed each time that the Ngrok URL changes. However, this is very easy to automate; in fact, I already have a command set up in my package.json, so if my Ngrok URL has changed, all I need to do to redeploy with the update is type npm run ngrok-deploy.

GCP

I ended up going with Google Cloud Platform to provide the serverless function that proxies requests. Their free tier includes 2 million (!!!) executions per month, plus 5GB of network traffic. This is WAY more than enough for some simple webhook testing.

You can find all my code here, which proxies inbound requests to a configurable destination: github.com/joshuatz/gcp-proxy-func.

Another cheap alternative

Besides the obvious routes of paying for a pro Ngrok plan or paying for a server to run your own reverse-proxy, there are some other alternatives I have yet to explore.

One option could be to wrap a reverse proxy in a container, and deploy it on a platform that supports "scale to zero" container scaling, and have it "wake up" on an SSH connection. Then, you would only have to pay for it while you are actively connected via the SSH tunnel and using it for developing.

This post first appeared on: https://joshuatz.com/posts/2019/using-google-cloud-functions-permanent-url-to-proxy-ngrok-requests/

Simple Intro to JWT Basics

Joshua Tzucker — Sat, 28 Sep 2019 17:30:11 +0000

If you have been put off learning about JWT (JSON Web Tokens) because they sound scary or complicated, I have good news; they really aren't. In this short simplistic guide, I'll walk through the basics of JWT, what makes them unique, and their strengths and shortcomings compared to other forms of authentication.

Intro - What is a JWT?

JSON Web Tokens, or JWTs, are a 'stateless' (more on this later) approach to authentication and session management, where the information about the auth or session (is user admin? Permissions? Etc.) can be stored within the token itself, rather than on the server.

Essentially, you can think of JWT as a container full of truths that the server has sent (these are called claims in JWT terms), and metadata about how these "truths" are stored (the algorithm and type).

In the most practical terms, a JWT can be represented as a single string, which you will see later.

Stateless? What does that mean?

JWTs are not always part of a stateless system, but the way they are composed lends them to that sort of setup.

With a typical non-JWT system, if you want to handle authentication and different permissions for different people, you usually use a combination of sessions and server-side storage - this would be your state. When a user logs in, you create a new session for them, with a unique ID, and to check permissions, you lookup their user ID against a permissions table and/or roles table. Each page that you load might require multiple DB lookups, to check for a valid session, then get roles, then get permissions, etc.

By contrast, with JWT, all the information about both the validity of the user (being logged in) and their role and/or permissions, is contained directly within the JWT string itself. The server, upon receiving an incoming JWT, simply has to verify that it is valid, but doesn't necessarily have to do any database lookups. This can make it stateless.

There are downsides to the this approach however, which will be discussed later.

Breaking it down further - the parts of a JWT

JWTs can seem overwhelming, so let's break them down part by part:

What do they actually look like?

First, you might be wondering what a JWT actually looks like. Well, the final string that is sent from the server to the client, to be stored in localStorage, sessionStorage, or a cookie, can look like this (real example):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiQm9iYnkgVGFibGVzIiwiaWF0IjoxNTE2MjM5MDIyLCJpc0FkbWluIjp0cnVlLCJwZXJtaXNzaW9ucyI6eyJ1c2Vyc01ha2UiOnRydWUsInVzZXJzQmFuIjp0cnVlLCJ1c2Vyc0RlbGV0ZSI6ZmFsc2V9fQ.HFRcI4qU2lyvDnXhO-cSTkhvhrTCyXv6f6wXSJKGbFk

Enlightening, huh? Well, it's a lot less scary once you find out this is all it is:

base64Url(header) + '.' + base64Url(payload) + '.' + base64Url(signature)

Let's break it down further...

The pieces

As you saw above, the JWT is made up of three major components, each of which is base64 encoded (with the web-safe variant, to avoid characters that could screw up a URL) before being joined together. Each of these components, except the signature, is also a JSON object before encoding, but more on that below:

Header:

The header is the part that contains the metadata about the JWT itself. At the bare minimum, this will contain the type of algorithm used to encrypt the signature, but sometimes also contains extra metadata, like the type of token itself (JWT).

Example:

{
  "alg": "HS256",
  "typ": "JWT"
}

In this example, the header is saying "Hey, I'm a token of type JWT, with an encryption algorithm of HS256!"

Payload:

The payload is really the most important part in terms of functionality, not security. The payload contains the claims (or truths as I previously called them), that the server is saying belong to whomever holds the JWT and can send it back to the server.

When the user sends the JWT back to the server, via a header, URL, cookie, etc., the server decodes the payload and can use it in thousands of ways; for example, by allowing the user to make a "delete" action because one of the claims is that they are an admin.

Example payload:

{
  "name": "Bobby Tables",
  "iat": 1516239022,
  "isAdmin": true,
  "permissions": {
     "usersMake": true,
     "usersBan": true,
     "usersDelete": false
  }
}

There are no mandatory key-pairs that your payload must have, although there are some that are standardized and common. For example, iat is a registered claim for issued at, and if included, must be a number representing the timestamp the JWT was issued. You should avoid conflicting with reserved/registered claim names. You can read more about them in the original spec, here.

Reminder: You should try to keep both keys and values short, since JWT is designed to be small.

Signature:

The signature of a JWT is the most important part when it comes to security. Essentially it is the value of the header + payload, put through a one-way encryption hashing function that uses a secret that ONLY the server or other trusted entities know.

If you base64 decode the value, it looks like gibberish, because it is a secure hash:

.T\#..Ú\¯.uá;ç.NHo.´ÂÉ{ú.¬.H..lY

The pseudo code to generate this hash, on the server, looks something like this:

HMACSHA256(
  base64Url(header) + "." +
  base64Url(payload),
  SECRET_KEY
);

The signature is a way for the server to, using its secret key**, validate that the JWT a user sends it is both valid, and created by itself or trusted creator.

(PS: The secret key I used throughout my examples here was krusty-krab-krabby-patty-secret-formula).

** = If using asymmetric encryption, you can use public key to validate. See "Signing Algorithms" subsection under "How is it secure?" section.

Breakdown summary - putting it back together

So, to summarize and show how these parts fit together once again, we are taking:

const header = {
  "alg": "HS256",
  "typ": "JWT"
};

const payload = {
  "name": "Bobby Tables",
  "iat": 1516239022,
  "isAdmin": true,
  "permissions": {
     "usersMake": true,
     "usersBan": true,
     "usersDelete": false
  }
};

...making a signature by using a one-way encryption algo...

// Pseudo code
const signature = hashHS256(header, payload).withSecret(SECRET_KEY);

...and finally joining the parts together into a single string, after base64'ing each part:

// Pseudo code
const jwtString = base64Url(header) + '.' + base64Url(payload) + '.' + base64Url(signature);

How is it secure?

The security mechanism of JWT rests in its signature component (outlined above). To break it down further, when a user sends a JWT back to the server, the way the server checks to make sure that the claims should be trusted, is by validating the signature through:

Take incoming header and payload
Add SECRET_KEY that only the server and validator(s) know**
Put header, payload, and secret, through one-way encryption hash
- This creates a server-generated signature
Check that the newly created signature matches the one sent in the JWT by the user
If they match, that proves that the JWT the user sent was indeed created with the same secret owned by the server!

Please note that the strength of the security is strongly linked to your secret key - use a suitably long key (to avoid brute force attempts) that is never shared.

Side note: In addition to validating signatures, servers often also validate JWTs by checking that they conform to the expected structure and standards. See this auth0 guide for details.

** = or public key, if using asymmetric encryption, see below.

Signing Algorithms

In these examples, I'm using HMAC, which is a symmetric algorithm, meaning that there is only one private key and no public key. In order for more than one party to be able to create or validate a JWT, they must have the secret key.

With an asymmetric algorithm, a secret key is still used to create tokens, but a public key can also be used to confirm validity. This means that another server could create the JWT, and your server could still validate it by checking against the public key, without needing to share the private/secret key. This method is often preferred because it is a way for multiple parties to be able to validate, while only those with the private key can actually create tokens.

I won't get any further into the details here, since this is supposed to be an intro, but you can read more here.

Downside to JWT: Logging users out / invalidating tokens

So far, JWTs seem like they have numerous benefits over stateful authentication methods, but something we have not yet discussed is logging users out, deleting users, or otherwise invalidating or revoking tokens.

The truth is, this is where JTWs fall short. In order to invalidate a JWT, you need to have some sort of database / stateful system, because what you end up doing is maintaining either a blacklist or a whitelist.

With a blacklist, whenever you want to invalidate a token, you would add it to the blacklist table, and whenever a user tries to use a JWT, you would always need to check that it is not on the blacklist.

With a whitelist, it is basically the same thing, but add every token to the whitelist as it is created, and remove it from the whitelist when invalidating. And every incoming JWT would only be accepted if it is on the whitelist.

If you have to use either of these approaches, in my opinion that is symptomatic of your needs not aligning with what JWTs can provide, and it might be time to rethink your websites architecture to see if there is not a better alternative.

Avoiding state: Auto-expiring sessions

A pretty common workaround for sites avoiding having to implement a stateful JWT system for logging out users is to just auto-expire tokens quickly.

For example, you could either put the creation time of the JWT inside of its own payload, and/or the planned expiration time. Then, when validating incoming JWTs, simply check if the expiration time is earlier or equal to the current time - if so, reject the JWT.

The problem with this is that it is still a bit of a stop-gap solution and can end up being more complicated than just using sessions in the first place. In order to not have users getting constantly logged out while actively using the site (annoying!), you would need to use auto-refreshing JWTs, probably through a service like Auth0's Refresh Tokens. This still doesn't allow for a manual log-out flow, unless you also introduce revoking as part of the refresh pattern.

Avoiding state: Lazy invalidation

Imagine that you need to substantially upgrade your user management system, and force everyone to switch. A workaround that is unfortunately suggested by a lot of devs online, but is less than ideal, is to... change your private key secret. If you do that, you immediately invalidate all JWTs in circulation and force everyone to login again, since the signature portion of everyones' JWTs will no longer match.

Note on complexity, vulnerabilities, and more:

There is still lots to JWT that I have not covered fully in this post (it's supposed to be an intro, in my excuse). The reality is that many developers use a third party service (aka a Federated Identity Management service), such as Auth0, to manage the majority of the JWT stack. This won't magically solve many of the issues I've outlined with JWT, but it will make working with them easier and abstract some of the complexity and security concerns.

Additional resources:

What	Type	Link
Wikipedia page - surprisingly dev focused	Wiki	Wiki En
RFC spec from IETF	Spec	RFC #7519
JWT Debugger, Libraries, & More	Playground & Quick Ref	jwt.io

PS: If you enjoyed how this guide was written, you might like some of my other cheatsheets and quick reference guides. I've been working on collecting and showcasing them here.

Coding a CSS Theme Switcher - So Many Options!

Joshua Tzucker — Wed, 04 Sep 2019 16:16:45 +0000

Intro and "What is theming?"
Options:
- Method A: CSS Custom Properties
  - Method A-1: Using specificity to modify variable inheritance
  - Method A-2: Reassigning variable values with Javascript
- Method B: Using SASS/SCSS
  - Method B-1: Themes as nested maps
  - Method B-2: Mixing dumping
  - Method B-3: Pulling CSS variables into SASS
- Method C: Mutating State (React, Vue, etc.)
- Method D: Crazy Old-School
Wrap up / Final Notes

Introduction:

Front-end web theming seems to be a current hot topic, and I have to admit that I felt the itch to jump on the bandwagon and add a dark theme to a Single-Page Application I’m working on. But where to get started? There are so many guides out there, and yet I couldn’t find many that I felt adequately talked about CSS theming in a generic way that covers many different approaches, rather than a tutorial that is essentially “copy and paste this into your code”.

So I set out to make one (this post), a guide that briefly discusses each of the many available options in a broad manner, with some short snippets of example code.

First though…

What is theming?

In this context, CSS theming or CSS theme switching refers to a set of shared styles (colors, etc) that are grouped as a theme, and being able to switch between themes instantly on a webpage or within a SPA, without refreshing the page.

A very simple example of a theme, that I use throughout this post, is as follows:

Dark theme:
- Primary Color: Black
- Secondary Color: White
Light Theme:
- Primary Color White
- Secondary Color: Black

Ok, now lets look at different options for implementation:

Method A: Using CSS custom properties / variables

This is fast becoming one of the most common current approach to implementing switchable themes, and uses a newer CSS feature called "Custom Properties", which are often referred to as "CSS variables". In short, CSS custom properties allow you to define a variable, such as "primaryColor", which can then be referenced in hundreds of other spots throughout your CSS.

This is crucial for theming, because it means that you can share a property among thousands of elements, and to change it, you just need to update that one variable value, rather than needing to individually update each element's CSS.

To get into the details of how to use CSS variables to deliver switchable CSS themes, let's break this method into a few different approaches:

Method A-1: Using specificity to change variable inheritance

Ok, long title, but I promise you that this method is actually pretty simple. In fact, this is one of the most common methods, and can be seen in current use across several major websites. Basically, you define the default theme as a set of variables, and then override the exact same variables through another block of CSS. The override will work because we will add something specific (class or attribute) to a top level node (like <body>) to trigger the more specific rule.

Here is some example CSS, without using custom properties:

body .myElement {
    background-color: white;
}
body.dark .myElement, body[data-theme="dark"] .myElement {
    background-color: black;
}

And here is the same output, but using CSS variables:

body {
    --primaryColor: white;
    --secondaryColor: black;
}
body .myElement {
    background-color: var(--primaryColor);
}
body.dark, body[data-theme="dark"] {
    --primaryColor: black;
    --secondaryColor: white;
}

Then you can simply toggle the class or attribute with JS, either directly with something like .setAttribute(‘data-theme’,’dark’), or with a reactive binding within something like React or Vue.

Here is a quick demo using setAttribute on <body> to switch themes:

You could technically do this without using CSS custom variables, but you end up with a lot of handcoding and repeating rules. For every rule/element that has different styling for a specific theme, you only have to write that block once if you are using variables, but if not, you have to write it 1 x as many themes as you have. Example below, where you can see that with three elements and three themes, the minimum number of CSS blocks without custom properties is 9 (3×3), whereas with variables, we only need 3 (one for each element):

Method A-2 Re-Assign variable values with JS

This method usually is used when you aren’t just theme switching, but also allowing for live theme property changing by the user, through something like a color picker. Let’s pretend that the user has just picked a new custom primary color for their theme, and they want to preview how it will look. Here is the initial CSS:

:root {
    --primaryColor: red;
    --secondaryColor: blue;
}

With just a little bit of JavaScript, we can easy modify any of these values. Here we go changing the primary color:

// This will target :root variables
document.querySelector(':root').style.setProperty('--primaryColor',newColor);
// Or, same thing...
document.documentElement.style.setProperty('--primaryColor',newColor);

You can take this a step further and easily implement theming logic to swap out entire themes and switch between multiple:

const themes = {
    light: {
        '--primaryColor': 'white',
        '--secondaryColor': 'black'
    },
    dark: {
        '--primaryColor': 'black',
        '--secondaryColor': 'white'
    },
    red: {
        '--primaryColor': 'red',
        '--secondaryColor': 'white'
    }
}
function activateTheme(theme){
    for (let prop in theme){
        document.querySelector(':root').style.setProperty(prop, theme[prop]);
    }
}
// Switch to the dark theme:
activateTheme(themes.dark);

Demo:

By default, when you change a CSS property via Javascript, the change is not persisted when the user reloads the page. To save their changes to a theme, you have a bunch of different options, which is beyond the scope of this post. However, here are some generic options:

On value change, also AJAX to server and save with User data
- Then, when user logs in, send back theme data either as on-the-fly generated CSS, or JSON which gets parsed and mapped back to CSS custom vars
Persist theme to localStorage and map back on page load
- If you are using a state management system and storing the user's theme config there, this should be very easy to do with something like "redux-persist"
- You can also just inject a <style> tag into the page with overriding variable values; this is how dev.to is currently handling theming -- on page load, it injects a different set of variable values through a <style> tag, depending on the value of a localStorage value

Method B: Using SASS (Sass/Scss)

Technically, you could use Sass to accomplish both methods A & B, since Sass transpiles to CSS, and you could also just stick both methods, as CSS, into Sass, and it should be valid.

However, there are some Sass specific approaches for theme switching, which I’ve outlined below.

Sidenote: Throughout this post, my demos all use the SCSS style of Sass, but all of this should be possible with indented SASS; you would just need to reformat.

Method B-1: Themes as Nested Maps

One way to approach this in Sass is with nested maps. The inspiration for this code, and one of the best guides on this method is this post.

Nested maps in Sass resemble JSON, and allow nesting of key-pair maps that can hold any valid Sass value. This makes them a great way to hold multiple named themes, and sub-properties for each theme. Here are my two example themes as a nested map saved to $themes:

$themes: (
    'dark': (
        'primary': black,
        'secondary': white
    ),
    'light': (
        'primary': white,
        'secondary': black
    )
);

This by itself does not generate any CSS, so you have to write your own function/code to loop through your themes and generate the CSS you want. It is best to define re-usable helper functions to handle this, that use mixins:

/**
* Mixin to use to generate blocks for each theme
* Automatically takes @content
*/
$scopedTheme: null;
@mixin themeGen($allThemesMap: $themes) {
    @each $themeName, $themeMap in $allThemesMap {
        .theme-#{$themeName} & {
            // Creating a map that contains values specific to theme.
            // Global is necessary since in mixin
            $scopedTheme: () !global;
            @each $variableName, $variableValue in $themeMap {
                // Merge each key-value pair into the theme specific map
                $scopedTheme: map-merge($scopedTheme, ($variableName: $variableValue)) !global;
            }
            // The original content passed
            @content;
            // Unset
            $scopedTheme: null !global;
        }
    }
}
/**
* Function to call within themeGen mixin, to get value from the current theme in the iterator
*/
@function getThemeVal($themeVar){
    @return map-get($scopedTheme,$themeVar);
}

Finally, using this with an element:

/**
* Actually using theme values to generate CSS
*/
.myComponent {
    @include themeGen() {
        background-color: getThemeVal('primary');
        color: getThemeVal('secondary');
    }
}

Here is a demo showing the final CSS this can generate:

Technically, you could hand code the CSS that this generates (and some old-school devs do), but there is not a good reason to do so, and if anything, you are more likely to write error-ridden CSS.

A related, but slightly different approach (avoids global vars) can be found here. And here's another variation.

Method B-2: Simple Mixin "Dump"

This method is not as elegant as C-1, but less complicated. Essentially you dump a huge block of CSS into a mixin, which then repeats it, but with a named parent theme class.

@mixin scopeToTheme($themeName,$prop,$val){
    .#{$themeName} & {
        #{$prop}: #{$val}
    }
}

button {
  background-color: red;
  padding: 20px;
  margin-bottom: 4px;
  border-radius: 10px;
  @include scopeToTheme(
    'dark-theme',
    'background-color',
    'black'
  );
  @include scopeToTheme(
    'light-theme',
    'background-color',
    'white'
  )
}

And here is the CSS that this generated:

button {
  background-color: red;
  padding: 20px;
  margin-bottom: 4px;
  border-radius: 10px;
}
.dark-theme button {
  background-color: black;
}
.light-theme button {
  background-color: white;
}

Method B-3: CSS Custom Properties to Sass

I’m not sure I’ve seen this done anywhere, but an interesting approach could be to combine Method B with Sass by pulling the CSS variables into Sass. Like so – CSS:

:root {
    --primaryColor: red;
    --secondaryColor: blue;
}

Sass:

$primaryColor: var(--primaryColor);
$secondaryColor: var(--secondaryColor);

Method C: Mutating State

I won't get into the specific of how to code this out, but this is pretty easy to think about conceptually. In a reactive framework, you can hold CSS properties, such as colors, as part of state. Then, using a CSS-in-JS framework, or even just sticking state in inline css, you can plug the value from state into your scoped CSS.

React Demos:
- Simple inline style binding
- Styled components + ThemeProvider
React Native Web
- Inline style binding with "atomic" CSS classes
Vue Demos:
- Simple inline style binding

It looks like Twitter uses this method, with React Native Web.

Method D: Crazy Old-School

There are so many reasons not to do it this way, but I feel obligated to share this hackish idea anyways. If you really wanted to insist on using CSS, but not using any variables or touching of the <body> class or attributes, you could hand code different themes as completely separate CSS files. Like dark-theme.css and light-theme.css. Then, to switch the theme, you could use AJAX to pull in the new theme file. Or, if you wanted to support browsers without Javascript, you could even use server side code to change which theme gets included and force a page refresh.

As a side note, an effect of this approach is actually better utilization of bandwidth, since you are only sending what theme is needed.

Wrap-Up / Final Thoughts:

First, although this was an extensive look at theming options, it should not be considered fully comprehensive; there is an endless number of ways you can implement custom theming.

Second, if you have made it all the way through the post, you might still be wondering "well, which option is the best one?". The truth is that it really matters what your objective is. If your goal is to support as many browsers as possible and/or have functions within styling (like converting hex to RGBA and then darkening), then SASS is probably the way forward (Method B). Or, if you want to have the smallest CSS filesize and/or binding of CSS values to JS values, then CSS custom properties are likely the best fit (Method A and Method C, or Method B with special setup).

The short answer is use what fits best with the framework or existing structure of your site/SPA/App. And have fun theming!

This writeup was first published at: https://joshuatz.com/posts/2019/coding-a-css-theme-switcher-a-multitude-of-web-dev-options/

Github Language Stats Bar for a Pure Markdown Repo

Joshua Tzucker — Mon, 12 Aug 2019 18:38:40 +0000

If you have ever used Github, you have probably noticed the language details statistics bar (or “language breakdown bar”):

It doesn’t really have an impact on anything, but it can tell other devs at a glance what kind of tech is likely in your repo, and it does influence the search results when searching for a repo across Github.

Unfortunately, if you create a repo and fill it with nothing but markdown files (.md), the language breakdown bar will either not appear at all, or if you introduce some non-markdown files, it will only show those. What gives?

Both the problem and the solution are revealed with a little bit of background knowledge.

How is the language stats bar calculated?

Internally, Github uses a tool called Linguist to detect and classify code files. What you might not know though, is that Linguist also has a lot of rules for preventing a file from contributing towards statistics. A file is excluded from stats if it is classified as any of these:

Vendored-code
Generated-code
Documentation
Data
Prose

For details, see this section of the readme.

Why does Markdown not show up?

The first reason why Markdown does not show up is because it is immediately classified as “Prose”, which we know from above, is ignored when it comes to repo language statistics.

The second reason might or might not apply to you; filename and file structure. For example, if all your markdown files are named “readme.md” or are just in a folder called “Documentation”, they would be classified as “Documentation” and excluded. You can see this from the Regular Expressions patterns in the “documentation.yml” file.

Solution

It used to be that there was not a solution to this issue. However, over time, Github added "overrides" to Linguist, so now users can modify the default classification of files by overriding with git attributes (see issue #3964, which was solved by PR #3807, and example given in #3806).

How do we implement overrides? It is actually surprisingly pain-free.

First, create a ".gitattributes" file in the root of your repo. Then, use the standard git attributes syntax within that file to modify file attributes based on filename or pattern. Git Attributes are a way to assign specific, custom, and arbitrary attributes to specific files.

The linguist attributes you can override are:

linguist-documentation
linguist-langauge
linguist-vendored
linguist-generated
linguist-detectable

For example, here is a .gitattributes file where I have forced Github to count all Markdown files towards my language stats, except for readme.md:

# Linguist overrides
*.md linguist-detectable=true
README.md linguist-detectable=false
readme.md linguist-detectable=false

Technically, I believe toggling “linguist-detectable” should be all it takes to change whether or not a file is ignored, since it acts as a final override. If you wanted to be 100% sure that markdown is not excluded, you could also override any attribute that might prevent it from being recognized, like so:

*.md linguist-vendored=false
*.md linguist-generated=false
*.md linguist-documentation=false
*.md linguist-detectable=true

Final Notes:

Keep in mind that the solution found here is applicable towards many issues with Github stats; you can easily override any Linguist classifications with Git attributes.

Also, Pro Tip: You can easily check if your file patterns are correct in your .gitattributes file by using the "git check-attr" command. For example, to check the attributes of a markdown file with the filename "web-dev.md", in my folder "cheatsheets", I would use:

git check-attr -a cheatsheets/web-dev.md

Forem: Joshua Tzucker

Git SHA Badges - Know Which Commit is Live

Demo Repo

Intro

Close, but Not Good Enough

Methods for Creating SHA Badges

JSON File

JSON File - Getting and Saving the SHA

JSON File - Using the Stored SHA

SVG File

Bonus: Github Commit Badges

Wrap Up

More About Me (Joshua Tzucker):

Generate a Perfectly-Sized Cover Image with Cloudinary

Introduction

Our Goal

Building It With Cloudinary

Steps:

Extras:

Wrap-Up

Using Windows Task Scheduler to Automate NodeJS Scripts

Why? 🤔

Why not just use crontab under WSL?

How? 🤓

👩‍🍳 - You can combine actions and triggers

✨ - You can use Git Bash for more advanced scripting

💥 - %1 is not a valid Win32 application

⚙ - Stop the Cmd window from popping up

⏰ - How to schedule more frequently than every 5 minutes

Comparison with CRON

Wrap Up

5 Underrated *Built-In* VSCode Features

Intro

#1: JavaScript Type Safety

Enabling JS Type Checking

What does this get you?

Annotating Types with JSDoc and Advanced Usage

#2: Making things easier for contributors

Recommended Extensions

Workspace tools and settings

#3: User-Defined Snippets

#4: Reordering Imports Automatically

#5: Ability to build a custom extension for yourself or your company

Wrap Up

Fixed URL Reverse-Proxy with Serverless (GCP) Functions and Ngrok

Background - Why might you need a reverse proxy?

Reverse-Proxies

Quick, Simple, and *Free - Ngrok

The downside to Ngrok

My Solution - Add Another Proxy with Cloud Functions!

GCP

Another cheap alternative

Simple Intro to JWT Basics

Intro - What is a JWT?

Stateless? What does that mean?

Breaking it down further - the parts of a JWT

What do they actually look like?

The pieces

Header:

Payload:

Signature:

Breakdown summary - putting it back together

How is it secure?

Signing Algorithms

Downside to JWT: Logging users out / invalidating tokens

Avoiding state: Auto-expiring sessions

Avoiding state: Lazy invalidation

Note on complexity, vulnerabilities, and more:

Additional resources:

Coding a CSS Theme Switcher - So Many Options!

Table of Contents:

Introduction:

What is theming?

Method A: Using CSS custom properties / variables

Method A-1: Using specificity to change variable inheritance

Method A-2 Re-Assign variable values with JS

Method B: Using SASS (Sass/Scss)

Method B-1: Themes as Nested Maps

Method B-2: Simple Mixin "Dump"

Method B-3: CSS Custom Properties to Sass

Why not just use `crontab` under WSL?

💥 - `%1 is not a valid Win32 application`

5 Underrated Built-In VSCode Features