stedman.dev

Austin JavaScript Case Study

2022-12-08T02:30:13Z

Austin JavaScript (AustinJS) is a tech meetup organization with a proud history of involvement from local hackers to JavaScript industry giants. For over ten years, it’s provided timely and relevant JavaScript knowledge while serving as a key social network for the Austin web development community. If it has anything to do with JavaScript, it’s being talked about at AustinJS.

So it was always a bit ironic that JavaScript as a technology didn’t play a bigger role in the AustinJS website. Granted, a key consideration was performance on mobile devices and client-side JavaScript can degrade rendering speeds and battery life if not crafted properly. But even on the server-side, there wasn’t a contribution model in the Node world that quite fit AustinJS’s needs. This volunteer organization’s content management system needed to be simple, deployments needed to be effortless, and whatever was chosen needed to be free.

AustinJavaScript.com, circa 2013

The site was initially set up in 2010 on WordPress (PHP) and then moved to GitHub Pages and Jekyll (Ruby) in 2015. As a publishing platform, the GitHub Pages + Jekyll duo is a hard combination to beat. It’s rock-solid, easy to update (even with a mobile device), deployments are invisible, and it’s free.

But it’s not JavaScript. Worse, Jekyll runs on Ruby which is a challenging ecosystem for the uninitiated to set up locally. This impeded layout and design contributions, so not much evolved on the site beyond 2015.

AustinJavaScript.com, circa 2016

Fast-forward to 2020. The JavaScript community now has a wide variety of capable Jekyll alternatives. Better yet, the automated build and deploy process that Jekyll enjoys on GitHub Pages can be replicated with the recently released GitHub Actions.

It was time to rebuild AustinJS on JavaScript.

On this page: The prep > The pitch > The pivot > The launch > Conclusion

1. The prep

Before approaching the AustinJS organizers, I wanted to have a decent proof of concept to share. I figured I’d push some of the current content through a JavaScript engine, throw a fresh coat of paint on it, and see what folks thought.

Discovery

Before starting, I put on my project management hat and did some fieldwork. Their GitHub repo had been up for five years, so there was plenty of material to research:

Content: patterns of use (and evolutions in those patterns)
GitHub Pull Requests: issues that need to be addressed by code change
GitHub Issues: issues that need to be addressed
Templates/other code: comments, FIXMEs, and TODOs

Goals

After the research, my initial goals were simple:

maintain content parity (while the engine and the design might change, the content should remain the same)
keep all of Jekyll’s ease of use (e.g., YAML front matter for meta data, Markdown content, straightforward templating)
keep the lightweight and responsive static pages
keep GitHub Pages’ auto build and deploy functionality
improve the contributor experience (e.g., meetup posts, site templates)
improve the user experience with a visual design refresh
reduce dependencies (especially those requiring additional services and logins; Travis and Cloudflare, for example)

Proof of concept

Generator

Gatsby seemed like a solid JavaScript static site generator (SSG) choice. Based on ReactJS, it has tons of documentation, a good Jekyll migration path, and a supportive community.

Style

I also decided to give the CSS framework Bulma a shot as it is lightweight, flexible, and well-documented. For this community project, I figured that it’s also important to make design contribution as frictionless as possible. Bulma impressed me as hitting that sweet spot of capability and ease of use.

Content

Keeping Jekyll’s YAML front matter + Markdown content layout was never a question. It’s a tried and true system that’s been adopted by all the Jekyll alternatives. The home page, about page, etc. migrated without a hitch.

I took a closer look at the 100+ meetup posts from the past ten years. Details such as speaker names, bios, avatars, sponsor names, and venue locations in the Markdown could be standardized and moved up into the YAML front matter. This front matter data can then be used in the current page or elsewhere on the site. Standardizing the data format also makes linting and/or pre-flight field checks possible before allowing pull requests to be opened.

Thus, a typical original meetup (2020-02-16-meetup.md) file:

---
title: Absolute Unit Tests with Jest and Enzyme
author: kevin
layout: post
categories:
  - posts
  - meetups
when: 2020-02-18T19:30:00-06:00
---

{% assign speakr = 'Nick Gottschlich' %}
{% assign twiturl = 'https://twitter.com/nickgottschlich/' %}
{% assign huburl = 'https://github.com/nick-gottschlich/' %}
{% assign website = 'http://nickpgott.com' %}


Everything you wanted to know about testing React components with Jest and Enzyme! Learn what a unit test is, why its useful, and how to test things like: existence of react components, simulated clicks and other events, mocking data, snapshots and more!

### Our speaker

<div class="media-object speaker-bio">
  <a href="{{ twiturl }}">
    <img alt="{{ speakr }} @NickGottschlich on Twitter"
      src="https://pbs.twimg.com/profile_images/1029847332781740032/Gp54dk3Z_400x400.jpg" />
  </a>
  <div>
  <a href="{{ twiturl }}"><strong>{{ speakr }}</strong></a>, Software Engineer at Procore Technologies
  <p>
    Twitter: <a href="{{ twiturl }}">@NickGottschlich</a>
  </p>
  <p>
    Website: <a href="{{ website }}">http://nickpgott.com/</a>
  </p>
  <p>
    Github: <a href="{{ huburl }}">nick-gottschlich</a>
  </p>
  </div>
</div>

Make sure to thank our gracious host [Cloudflare][].

{% include give-em-the-business.html location='cloudflare' %}

Check back here or <a href="{{ site.twitter.url }}">follow us on Twitter</a>
for updates.

[cloudflare]: https://www.cloudflare.com/

…was transformed into the following concise post:

---
layout: meetup
title: Absolute Unit Tests with Jest and Enzyme
speakers:
  - name: Nick Gottschlich
    title: Software Engineer at Procore Technologies
    avatar: https://pbs.twimg.com/profile_images/1029847332781740032/Gp54dk3Z_400x400.jpg
    bio:
    email:
    homepage: http://nickpgott.com
    twitter: NickGottschlich
    github: nick-gottschlich
    linkedin:
sponsor: cloudflare
venue: cloudflare
after: lavaca
organizers:
  - lingram
  - astacy
---

Everything you wanted to know about testing React components with [Jest](https://jestjs.io/) and [Enzyme](https://enzymejs.github.io/enzyme/) Learn what a unit test is, why its useful, and how to test things like: existence of react components, simulated clicks and other events, mocking data, snapshots and more!

Note: To help contributors, I created a how to contribute to posts document that provides more details about each field. The mechanics of how it all works is a bit more involved and would be a great topic for another blog post.

You may have noticed that the when and categories fields were omitted in the new version above.

When

In Jekyll-land, the first part of the post file name (e.g., 2020-02-18-meetup.md) contains the publish date. AustinJS organizers were unable to use future publish dates because Jekyll throws an error. So organizers added the when front matter field to represent the meetup date in the future. Unfortunately they also used it for the meeting time as well. While analyzing past pull requests, I noticed all sorts of Daylight Saving Time snafus that required subsequent PRs to remedy.

Gatsby didn’t throw errors if file names had future dates so I was able to dispose of the when field. Oh, and since almost every one of the 100 or so meetups started at 7:30pm and ended at 9pm, I was able to hardwire that into the template as well.

2. The pitch

After wrangling Gatsby, Bulma, and a sample of content for a few days, I soon had a proof of concept to share with AustinJS leadership.

Aaron Stacey, long-time AustinJS organizer and developer of the second gen site, was pleased with the idea of it all but added that an MVP (minimal viable product) would include the following:

Deploy on push
Have a low page weight
Look good on mobile

Hooray! We agreed on goals. But then Aaron pointed out the page weight. My Gatsby-powered home page had ballooned to 30 times the size of the Jekyll-powered version. It now weighed-in at over 3GB. What the heck? Sure it was speedy on my desktop, but there were valid concerns about load times for mobile devices.

Gatsby hydrates the initial page after the static bits load and subsequent page loads are routed through ReactJS. So, as you can imagine, you’re getting a large upfront JS payload followed by smaller GraphQL data transfers to navigate additional pages. For a site that typically only experiences one page view per session (to view details about an upcoming meetup), it’s important to maintain a trim initial page weight.

Aaron kindly mentioned that Eleventy (11ty) might be a better fit.

3. The pivot

Changing horses from Gatsby to Eleventy was relatively uneventful. I quickly ported over the Bulma CSS and the posts with the newly standardized YAML front matter. Migrating the Gatsby guts was a bit more delicate but once on Eleventy, everything was gravy.

Note: The LiquidJS templating language used by Eleventy is a port of the very same Liquid language that Jekyll uses. Direct migrations from Jekyll to Eleventy are relatively seamless (with a few exceptions, of course).

Once I switched to Eleventy, things got even easier. Working with Eleventy is a joy. For the most part, things just make sense. The community is vibrant and ready to help when things don’t make so much sense.

GitHub Actions

While a JavaScript SSG is pretty exciting, this site needed to build and deploy whenever the master branch was updated. Jekyll did this out of the box and it meant that organizers could update meetup details from their mobile devices and see the changes live on the site within minutes.

GitHub Actions adds the ability to spin up a server to run builds, tests, deployments, etc. based on repo events such as pull requests or merges.

Setting up the AustinJS workflow was absolutely painless (see Make the Jump from Jekyll to JavaScript) and has been running like a tank ever since.

Enhancements

Once the basics were nailed down, there was time to add even more value.

home page: add an Austin skyline hero (to make a place connection) and a roll-call of past speakers/presentations (to make a people connection)
contributing page: add a page to help presenters, sponsors, hosts, and others get more involved
meetup posts: add videos and slide decks from past presentations
RSS feed
SSL/CI/CDN services: switch to GitHub and remove Cloudflare and Travis dependencies

AustinJavaScript.com, circa 2020

Goals review

I reviewed the goals one last time:

✅ maintain content parity
✅ keep all of Jekyll’s ease of use
✅ keep the lightweight and responsive static pages
✅ keep GitHub Pages’ auto build and deploys
✅ improve the contributor experience
✅ improve the user experience
✅ reduce dependencies

With all the boxes checked, it was time to launch.

4. The Launch

This launch called for the development branch to be merged into the main branch and then setting up the Actions workflow to automate future build/deployments. Simple tasks, but replacing engines while the old one still works is always a scary move. I pressed the buttons and hoped for the best.

I saw source code.

All that showed up on the AustinJS site was source code for the index page. Was there something I missed in an Eleventy config? Was something wrong with the Actions workflow?

Another hour of testing and research revealed that this repo didn’t have the same ability to deploy to gh-pages branch as my demo site. Huh? A bit more research revealed that <org_name>.github.io type repos can only deploy to master. There weren’t many options. Change the austinjavascript.github.io repo name or give up and return to Jekyll.

I got on a short call with Aaron and went through the options. We decided to rename the repo to austinjavascript.com and break the logjam. A few short moments later, the new site was live.

Conclusion

Since the launch, the site has run flawlessly. It builds a bit faster than the old Jekyll engine but you’d be hard-pressed to find any other deployment differences.

I set out to improve the AustinJS user/contributor experience and bury the cruel Ruby joke. With special thanks to Aaron Stacey and Kevin Kipp for their help, I believe I succeeded. At long last, Austin JavaScript can proudly say that, with regards to JavaScript, it is eating it’s own dog food.

Watching Sass in Eleventy

2022-12-08T02:30:13Z

I’ve been using node-sass in my 11ty workflow for awhile now but haven’t been able to get the --watch flag to work to my satisfaction. For instance, while Browsersync automatically refreshes the browser for content and template changes, it didn’t rebuild my Sass files and then refresh the browser.

Well, I finally had enough of the manual labor and found a Mathieu Huot solution that sorta worked for me. I made a few tweaks that I hope he doesn’t mind:

I don’t have a lot of Sass files to process and my render times were in the 125ms range. So I chose the simplicity of a synchronous process instead of a promise-based one. Bonus: I get to skip a dependency (fs-extra).
Rather than introduce an environment variable (e.g., dev) to toggle the start of this script (and prevent it running it in production), I look for the --watch process argument. It’s present when Eleventy is fired up in dev mode: node eleventy --serve --watch.

UPDATE (2020-09-15): I recently came across an Egghead tutorial on Sass compiling that may work better for you.

Let’s go

Make sure node-sass is installed.
```
npm install --save-dev node-sass
```

Open a new file, name it _includes/sass-watch.js, and drop in the following code.

const fs = require('fs');
const path = require('path');
const sass = require('node-sass');

/**
 * Render and save the Sass to CSS.
 * @param  {string}  sassPath     The Sass input path.
 * @param  {string}  cssFilePath  The CSS output file path.
 */
const buildCss = (sassPath, cssFilePath) => {
  // Render CSS from Sass source path.
  const rendered = sass.renderSync({ file: sassPath });
  // Save CSS to output path.
  fs.writeFile(cssFilePath, rendered.css.toString(), (writeErr) => {
    if (writeErr) throw writeErr;
    console.log(`CSS file saved: ${cssFilePath} (in ${rendered.stats.duration}ms)`);
  });
};

/**
 * Initialize and watch Sass for changes requiring a build.
 * @param  {string}  sassPath     The Sass input path.
 * @param  {string}  cssFilePath  The CSS output file path.
 */
module.exports = (sassPath, cssFilePath) => {
  // If CSS output directory doesn't already exist, make it.
  if (!fs.existsSync(path.dirname(cssFilePath))) {
    console.log(`Creating new CSS directory: ${path.dirname(cssFilePath)}/`);
    // Create output directory.
    fs.mkdir(path.dirname(cssFilePath), { recursive: true }, (mkdirErr) => {
      if (mkdirErr) throw mkdirErr;
      console.log('CSS directory created.');
    });
  }
  // Build CSS on startup.
  buildCss(sassPath, cssFilePath);
  // Watch for changes to Sass directory.
  fs.watch(path.dirname(sassPath), (evType, filename) => {
    console.log(`SCSS file changed: ${path.dirname(sassPath)}/${filename}`);
    // Rebuild the CSS.
    buildCss(sassPath, cssFilePath);
  });
};

Edit .eleventy.js so that it now includes the following sass-watch bits.

const sassWatch = require('./_includes/sass-watch');

module.exports = function (eleventyConfig) {
  // Run only when 11ty is in watch mode.
  if (process.argv.includes('--watch')) {
     // Watch Sass directory for updates.
    sassWatch('./src/_sass/_main.scss', './dist/css/main.css');
    // Refresh the browser when there are updates in the Sass directory.
    eleventyConfig.addWatchTarget('./src/_sass/');
  }
  ..
};

The config for the command line and VSCode is no different from the standard setup:

Command line: package.json start script:
```
"start": "eleventy --serve --watch"
```

VSCode: .vscode/launch.json script:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch 11ty",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["start"],
    }
  ]
}

Start Eleventy again via command line (npm start) or VSCode via the Debugger, all subsequent changes to Sass files should initiate an automatic build and the browser should refresh with the changes.

Conclusion

I sincerely hope there’s a better solution for kicking-off Sass builds on file change events. If you know of a better way, please reach out on Twitter @stedman.

Until then, I’ll be happily updating Sass and watching the changes show up in my browser.

Make the Jump from Jekyll to JavaScript

2022-12-08T02:30:13Z

With the recent addition of Actions to GitHub’s product lineup, we now have the ability to create a 100% Pure, Unfiltered™ JavaScript alternative to Jekyll (and Ruby) in GitHub Pages. This is a big deal. Really.

Back story

GitHub Pages, for the uninitiated, are public web pages automatically generated from your GitHub source files and freely hosted on github.io or your custom domain. There are no servers to provision and no databases to set up.

The automatic generation part is handled by Jekyll, a pretty sweet static site generator. It’s been around quite awhile, is battle tested, and is backed by a huge community. It’s also simple enough for beginners and yet powerful enough for advanced users. Unfortunately, customizing it requires running it locally and this is where things get sticky. Jekyll is based on Ruby. For casual users, Ruby is a challenge to set up and maintain—especially on Windows. Scaling is also an issue for Jekyll/Ruby as bigger builds are notorious for taking a long time to compile.

While there are plenty of competitive static site generators out there, the one piece that was missing was the integrated of build and deploy to GitHub’s web server. Pages+Jekyll took care of that build and deploy mumbo-jumbo for you, automagically. Just commit to the gh-pages branch and poof, your site is updated.

More recently, workarounds from Netlify and others have popped up. They handle build/deploy and offer additional features worth considering, but at the end of the day they are yet another dependency to maintain.

If only we could run a static site generator on Pages with all the hooks and privileges of Jekyll but with the ease-of-setup and performance provided by more modern alternatives.

Well, now you can. All the pieces have finally fallen into place.

UPDATE: If you’re working with GitHub user or organization sites, you can only publish from the master branch. This effectively prevents alternative GitHub Pages deployments such as the one described below for those types of sites.

What are user or organization sites? Those are the sites that publish from repos named <user>.github.io (or <organization>.github.io) and have URLs that look like https://<user>.github.io/.

All other repos are considered project sites. The deploy steps defined in this tutorial will work with those sites since they can publish from the gh-pages branch.

The build

This brief tutorial will cover the essentials of migrating from Jekyll to JavaScript. The following are required to get started:

GitHub account
NodeJS set up locally

Of course, it would also make sense to already have an existing Jekyll repo. If not, then create a new GitHub repo (public or private) with a README initialized. Follow the follow-up instructions to clone and set it up locally.

Set up the static site generator

It took awhile for someone to distill the essence of Jekyll into JavaScript. With Eleventy, Zach Leatherman (@zachleat) has really distilled, bottled, and shipped it. Oh, and did I mention that it’s fast? I’ll skip the rest of the sales pitch here and let the experts do the talking.

If you haven’t already guessed, I’m smitten with Eleventy. It’s that multi-purpose knife that fits just perfectly in your pocket and makes you smile every time you use it.

It also makes the transition from Jekyll to JavaScript almost completely seamless. So let’s roll with it.

Install and configure

Open a terminal and navigate to your repo.
If you don’t already have a package.json file in the root directory, then take this moment to initialize npm.
```
npm init
```
Install Eleventy as a devDependency.
```
npm install --save-dev @11ty/eleventy
```
To the site root, add an empty .nojekyll file to disable the default Jekyll build.
```
touch .nojekyll
```

Keeping things simple, we’ll assume a default Jekyll file structure.

..
├── _layouts
│   ├── default.html
├── assets
│   ├── css
│   ├── images
│   └── js
├── index.html
..

To the site root, add a .eleventy.js config file with the following contents. For more details, see the Eleventy configuration docs.

module.exports = (eleventyConfig) => {
  // Copy the "assets" directory to the compiled "_site" folder.
  eleventyConfig.addPassthroughCopy('assets');

  return {
    dir: {
      input: './',
      output: './_site',
      layouts: './_layouts',
    },
    templateFormats: [
      'html',
      'liquid',
      'md',
      'njk',
    ],
    pathPrefix: '/<repo_name>/', // omit this line if using custom domain
  };
};

Looking at the dir.output above, notice that we are maintaining parity with Jekyll’s deployment, using the ./_site directory for our compiled code.

Also note that, unless you’re using a custom domain, you’ll need to add a path prefix (/<repo_name>/) to the config options. This is because project sites are hosted on subdirectory URLs that look like https://<user>.github.io/<repo_name>/.

To the scripts section of package.json, add the following. We’ll need the build script for our deployment later.
```
  "scripts": {
    "clean": "rm -rf ./_site",
    "build": "npm run clean && eleventy",
    "start": "eleventy --serve --watch"
  },
```
- clean: empties out the deployment directory
- build: cleans the deploy directory and builds the site with Eleventy
- start: runs Eleventy in developer mode with live browser refreshes

The deployment

Now for the real magic sauce, GitHub Actions-style.

Set up a workflow

Open a browser to your GitHub repo and then select the Actions tab.
Tap on the New workflow button.
Tap on the Set up a workflow yourself button.
In the {repo_name}/.github/workflows/main.yml field, enter “eleventy_build.yml”.

Into the Edit new file textarea, cut and paste the following:

name: Eleventy Build

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
    - uses: actions/checkout@v2

    - name: Setup Node.js environment
      uses: actions/setup-[email protected]

    - name: Install packages
      run: npm ci

    - name: Run npm build
      run: npm run build

    - name: Deploy to gh-pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        publish_dir: ./_site

Tap the Start commit button.
Complete the Commit new file form and select Commit directly to the master branch.

The workflow script should be fairly self-descriptive. See that ${{ secrets.ACTIONS_DEPLOY_KEY }} line near the end of the workflow? We need to add deploy keys to GitHub before attempting a deployment.

Set up deployment keys

The following instructions were cribbed from a third-party GitHub Actions for GitHub Pages page. Please check that site for updates before proceeding as these instructions may have changed.

Generate a SSH key locally to use as your deploy key.

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
#   gh-pages.pub (public key)
#   gh-pages     (private key)

Open a browser to your repo and select the Settings tab.
Select Deploy keys from the left menu.
1. Tap the Add deploy key button.
2. In the Title field, enter “Public key of ACTIONS_DEPLOY_KEY”.
3. In the Key field, cut and paste the contents of your gh-pages.pub SSH key file made in step 1 above.
4. Check the Allow write access box.
5. Tap the Add key button.
Select Secrets from the left menu.
1. Tap the Add a new secret link.
2. In the Name field, enter “ACTIONS_DEPLOY_KEY”.
3. In the Value field, cut and paste the contents of your gh-pages SSH key file from step 1 above.
4. Tap the Add secret button.
IMPORTANT: Delete the local gh-pages keys at this point. You certainly do not want to add them to your version control (for all to see).
To initiate a deployment, commit/merge to the master branch. The first deploy will fail (because the gh-pages branch has not been created yet).
Go back to the Settings tab.
1. Scroll down to the GitHub Pages section.
2. From the Source options, select gh-pages branch.
Merge some more code into master to initiate another deploy.

Congrats. You’re done! From here on out, you should be able to trigger a fresh build and deploy by:

working/saving locally, committing, and pushing to origin master.
editing your code at github.com and saving to master.

Your updates will deploy to live in mere seconds. All of this takes place within the ecosystem that you version your code in. There are no additional dependencies, no additional accounts, nada. How cool is that?

The custom domain

GitHub provides project sites (e.g., https://<user>.github.io/<repo_name>/) that may suit you just fine. If, however, you want to use a custom domain (e.g., https://example.com/), there’s a bit more work involved.

Set up a custom domain

If you haven’t already set up an apex domain (e.g., example.com) for this repo, then you will need to add it. Follow the GitHub instructions for managing a custom domain.
The CNAME file created when you entered your domain in the Custom domain field (above) needs to be included in our distribution directory.
1. Open the gh-pages branch and copy the CNAME file.
2. Go back to the master branch and add that CNAME file to the source directory (in this case, the root directory).
3. Open the .eleventy.js config file and add the CNAME file to the list of pass-through copies.
```
..
  eleventyConfig.addPassthroughCopy('CNAME');
..
```
4. Save, commit, and push to origin.

Conclusion

For 12 years, GitHub teased us with a web hosting product that almost did everything we needed. We were grateful and we made due. Along the way, we came up with hacks and workarounds, employing one or more outside services to complete the task. But nothing quite combined source code versioning, flexible site generation, and web hosting in one elegant package.

With Eleventy and GitHub Actions, we now have it all.

stedman.dev

Austin JavaScript Case Study

1. The prep

Discovery

Goals

Proof of concept

Generator

Style

Content

When

Categories

2. The pitch

3. The pivot

GitHub Actions

Enhancements

Goals review

4. The Launch

Conclusion

Watching Sass in Eleventy

Let’s go

Conclusion

Make the Jump from Jekyll to JavaScript

Back story

The build

Set up the static site generator

Install and configure

The deployment

Set up a workflow

Set up deployment keys

The custom domain

Set up a custom domain

Conclusion