Lighthouse provides a rich set of built-in audits but can also be extended to run your own custom audits. This can be extremely useful if you have your own specific checks that you want to perform on your site, such as checking all links to external sites have the rel="noopener" attribute or contain a specific class to visually indicate an external link etc.

In this article, we’re going to write a custom audit to check for the well known web accessibility issue of adding a click handler to a non-interactive element and not ensuring it’s accessible for keyboard and screen reader users. My article on Accessible JavaScript Click Handlers covers this web accessibility issue in more detail.

JavaScript modules for our custom audit

There are 3 JavaScript modules we’ll need to create for our custom audit.

1. Gatherer — Collects information about the page. There are many standard gathers built-in to Lighthouse, including the AnchorElements gatherer, but this doesn’t collect all the details we require so we’ll create our own.
2. Audit — Converts the gatherer data into a score and in our case, returns details to display for each element that has failed.
3. Config — Provides the configuration for Lighthouse to register and run our custom gatherer and audit.

The code for this article is available on GitHub and contains a test HTML page with a <div> element containing a click handler and no other web accessibility considerations. This is what we want our custom audit to catch.

<div id="inaccessibleDiv" class="btn btn-primary">
  This is an inaccessible div element with a click handler
</div>

This test page can be viewed locally via a static web server.

npm install
npm run serve

The command behind npm run serve is:

http-server ./test-site --port 8085 -o

Creating the custom gatherer

Within the folder gatherers, create a new JavaScript file non-interactive-click-handlers-gatherer.js.

const { Gatherer } = require('lighthouse');
const pageFunctions = require('lighthouse/lighthouse-core/lib/page-functions');

/* global getNodeDetails */

class NonInteractiveClickHandlersGatherer extends Gatherer {
  /**
   * @param {LH.Gatherer.PassContext} options
   * @param {LH.Gatherer.LoadData} loadData
   */
  async afterPass(options, loadData) {
    const driver = options.driver;

    const mainFn = () => {

      /**
       * Returns a boolean indicating if the element has an event listener for type
       * @param {HTMLElement} element
       * @param {string} type Event type e.g. 'click'
       * @returns {boolean}
       */
      function hasEventListener(element, type) {
        const eventListeners = getEventListeners(element);
        return !!eventListeners[type];
      }

      // The tag names of the non-interactive elements which we'll check
      const tagNamesToCheck = ['div', 'span'];
      const selector = tagNamesToCheck.join(', ');
      const elements = Array.from(document.querySelectorAll(selector));

      const failingElements = elements
        .filter(element => hasEventListener(element, 'click'))
        .filter(element => {
          // Assume that any keyboard related handlers are covering web
          // accessibility for keyboard users (this could be a false negative).
          const hasKeyHandler =
            hasEventListener(element, 'keydown') ||
            hasEventListener(element, 'keyup') ||
            hasEventListener(element, 'keypress');

          // Without the "tabindex" attribute, a non-interactive element won't be
          // able to receive focus. It's only recommended to use the value 0 which
          // means the element receives focus in the DOM order.
          const hasValidTabIndex = element.tabIndex === 0;

          const hasRoleAttribute = element.getAttribute('role');

          return !hasKeyHandler || !hasValidTabIndex || !hasRoleAttribute;
        });

      const elementSummaries = failingElements.map(element => ({
        // getNodeDetails is put into scope via the "deps" array
        tagName: element.tagName,
        node: getNodeDetails(element)
      }));

      /**
       * @return {LH.Gatherer.PhaseResult}
       */
      return elementSummaries;
    }

    return driver.executionContext.evaluate(mainFn, {
      args: [],
      deps: [
        pageFunctions.getElementsInDocumentString,
        pageFunctions.getNodeDetailsString,
      ]
    });
  }
}

module.exports = NonInteractiveClickHandlersGatherer;

The gatherer will look at each <div> and <span> element that has a click handler but doesn’t have any of the following:

• Keyboard event handlers
• The tabindex attribute with the value 0
• The role attribute

For each element that matches, we’ll build up an array of objects with the tag name and a LH.Artifacts.NodeDetails object. This LH.Artifacts.NodeDetails object will allow us to output the element HTML in the report later when we create our audit module. The array is the data returned from our custom gatherer.

Creating the custom audit

Within the folder audits, create a new JavaScript file non-interactive-click-handlers-audit.js.

const { Audit } = require('lighthouse');

class NonInteractiveClickHandlersAudit extends Audit {
  static get meta() {
    /**
     * @return {LH.Audit.Meta}
     */
    return {
      id: 'non-interactive-click-handlers',
      title: 'Checks that click handlers on non-interactive elements are fully accessible',
      failureTitle: 'One or more non-interactive elements has a click which is not fully accessible',
      description:
        `When click handlers are added to non-interactive elements like div and span,
         keyboard handling should be used to ensure the element is operable via the
         keyboard and the tabindex attribute used so the element can receive focus.
         The element should also be given a role to assist screen reader users.`,

      // The name of the built-in or custom gatherer class that provides data to this audit
      requiredArtifacts: ['NonInteractiveClickHandlersGatherer'],
    };
  }

  /**
   * @return {LH.Audit.ScoreOptions}
   */
  static get defaultOptions() {
    return {
      // See https://www.desmos.com/calculator/tsunbwqt3f
      p10: 0.5,
      median: 1
    };
  }

  /**
   * @param {LH.Artifacts} artifacts
   * @param {LH.Audit.Context} context
   */
  static audit(artifacts, context) {
    // Get the data / elements collected by the gatherer
    const elementSummaries = artifacts.NonInteractiveClickHandlersGatherer;

    const results = elementSummaries.map(element => ({
      node: Audit.makeNodeItem(element.node),
      tagName: element.tagName
    }));

    /** @type {LH.Audit.Details.Table['headings']} */
    const headings = [
      { key: 'tagName', itemType: 'text', text: 'Tag name' },
      { key: 'node', itemType: 'node', text: 'Failing element' }
    ];

    const score = Audit.computeLogNormalScore(
      { p10: context.options.p10, median: context.options.median },
      results.length
    );

    /**
     * @return {LH.Product}
     */
    return {
      score, // Number between 0 and 1
      numericValue: results.length,
      numericUnit: 'element',
      displayValue: `${results.length} elements`,
      details: Audit.makeTableDetails(headings, results),
    };
  }
}

module.exports = NonInteractiveClickHandlersAudit;

The audit module contains the property getter meta which returns a set of metadata about the audit. The property requiredArtifacts is populated with the names of the built-in or custom gatherer classes that the audit requires data from.

The audit method reads the data from our gatherer via the artifacts.NonInteractiveClickHandlersGatherer property. The gatherer array is then mapped to an array of objects with the tag name and a LH.Audit.Details.NodeValue object. The audit method also calculates the score for the audit (which is a number between 0 and 1) and returns this along with the mapped array and some heading details.

Creating the configuration

Create a new JavaScript file config.js.

module.exports = {
  // 1. Run your custom tests along with all the default Lighthouse tests
  extends: 'lighthouse:default',

  // 2. Add gatherer to the default Lighthouse load ('pass') of the page
  passes: [
    {
      passName: 'defaultPass',
      gatherers: [
        './gatherers/non-interactive-click-handlers-gatherer.js'
      ]
    }
  ],

  // 3. Add custom audit to the list of audits 'lighthouse:default' will run
  audits: [
    './audits/non-interactive-click-handlers-audit.js'
  ],

  // 4. Create a new 'Custom Audit' section in the default report for our results
  categories: {
    custom: {
      title: 'Custom',
      description: 'Custom audit for our checks on DOM element related issues',
      auditRefs: [
        // "weight" controls how multiple audits are averaged together
        { id: 'non-interactive-click-handlers', weight: 1 }
      ]
    }
  }
};

Running the custom audit

With the 3 JavaScript modules in place, we’re now ready to run the custom audit against our test HTML page.

npm run serve
npm run lighthouse

The command behind npm run lighthouse is:

lighthouse --config-path=config.js http://localhost:8085/ --output-path ./results.html --view

Once complete, you’ll see the new “Custom” section in the report which contains the failed element from the test HTML page.

The code for this article is available on GitHub

This article covers configuring Lighthouse CI to run against a website and uploading the results to a Lighthouse CI server Docker container running both locally and in Azure.

Lighthouse is a great tool for auditing your website on performance, web accessibility, PWA, SEO and more. By automating Lighthouse to run nightly or with each commit and by uploading the results to a Lighthouse CI server, you can track your scores over time, see trends and detect when recent changes have had a negative impact.

Configuring Lighthouse CI to audit your site

Lighthouse CI is designed to have it’s configuration files exist within your project’s Git repo, so when it runs, it can include the branch name and last commit details with each report. This is especially useful with reports uploaded to a Lighthouse CI server, as you can compare results for different commits to help track down when scores have changed.

Note: If you don’t use Git, Lighthouse CI can be configured for use without a Git repo.

In this article, I’m going to create a new Git repo for an empty project but if you have an existing project you want to audit, you can skip this first step.

Create a folder for the empty project and initialise a Git repo

mkdir my-website
cd my-website
git init --initial-branch=main

Create the folder lighthouse for the configuration files.

mkdir lighthouse
cd lighthouse

Create a new package.json.

npm init -y

Install @lhci/cli.

npm install --save-dev @lhci/cli

Create the configuration file lighthouserc.js with the following settings:

module.exports = {
  ci: {
    collect: {
      url: [
        'https://keepinguptodate.com/code-snippets/'
      ],
      numberOfRuns: 1, // Set low to speed up the test runs. Default is 3.
      headful: true, // Show the browser which is helpful when checking the config
      settings: {
        disableStorageReset: true, // Don't clear localStorage / IndexedDB / etc before loading the page
        preset: 'desktop'
      }
    },
    upload: {
      target: 'temporary-public-storage'
    }
  }
};

The url property should contain an array of URLs for the pages on your website that you want to audit.

The numberOfRuns has been set to 1 to speed up the runs but typically should be set to 3 or more. Lighthouse will use the median result which then accounts for some volatility in the results.

The upload target of temporary-public-storage means once run, Lighthouse CI will upload the results to a public temporary URL and output the URL in the console. Later, we’ll setup up a Lighthouse CI server to upload our results to.

If you created a new Git repo, we need to make an initial commit for Lighthouse to pickup when it runs.

git commit -m "Initial commit"

Now we can run Lighthouse CI

npx lhci autorun

As the setting headful is true, Lighthouse CI will launch a visible Chrome instance as it runs. When Lighthouse CI has finished, the URL of the report is logged to the console.

Running Lighthouse 1 time(s) on https://keepinguptodate.com/code-snippets/
Run #1...done.
Done running Lighthouse!

Uploading median LHR of https://keepinguptodate.com/code-snippets/...success!
Open the report at https://storage.googleapis.com/xxx/reports/yyy.report.html

The report can be viewed via the URL logged to the console. Alternatively, the report is available in the .lighthouseci folder created by Lighthouse. Note: This folder is cleared each time Lighthouse CI is run.

Authenticating before running Lighthouse audits

If your website has pages that are only available to authenticated users, a puppeteer script can be created to control Chrome (e.g. enter an email address and password and click a login button) before the Lighthouse audit is run.

Given the following login form:

<form action="#" method="post">  
  <h1>Login</h1>  
  
  <label for="email">Email</label>  
  <input id="email" name="email" autocomplete="username" type="email" required>  
  
  <label for="current-password">Password</label>  
  <input id="current-password" name="current-password" autocomplete="current-password"  
         type="password" minlength="8" required>  
  
  <button value="login">Login</button>  
</form>

This puppeteer script will enter an email address & password and click the login button.

const EMAIL = 'user@domain.com' // Could use process.env.EMAIL for env var
const PASSWORD = 'xxx' // Could use process.env.PASSWORD for env var

/*
 * @param {import('puppeteer').Browser} browser
 * @param { {url: string, options: LHCI.CollectCommand.Options} } context
 */
module.exports = async (browser, { url }) => {
  const page = await browser.newPage();
  await page.setViewport({ width: 1024, height: 600 });
  await page.goto(url);

  // This login script is run for every URL so check if the user is already authenticated and if so then
  // return early without doing anything.
  const userDropdownElement = await page.$('#userDropdown');

  if (userDropdownElement !== null) {
    await page.close();
    return;
  }

  // Enter the username and password and login
  const emailInput = await page.$('#email');
  await emailInput.type(EMAIL);

  const passwordInput = await page.$('#current-password');
  await passwordInput.type(PASSWORD);

  const loginButton = await page.$('button[value=login]');
  await loginButton.click();

  await page.waitForNavigation({ waitUntil: 'networkidle2' }) // No more then 2 network requests for half a second
  await page.close();
};

To use this script saved with the filename login-script.js, first we’ll need to install puppeteer.

npm install puppeteer --save-dev

And then update the Lighthouse CI configuration file lighthouserc.js to run this puppeteer script before each URL is audited.

module.exports = {  
  ci: {  
    collect: {
      ...
      puppeteerScript: 'login-script.js',  // Ensure there's an authenticated user before running Lighthouse
      puppeteerLaunchOptions: {  
        defaultViewport: null  
      },
      ... 
    }
  }  
};

Uploading results to a local Lighthouse CI server

We’re going to run the Lighthouse CI server in a Docker container so first ensure you have Docker Desktop. installed and running. The Lighthouse CI server image is available on Docker Hub.

Download the latest version of the Docker image.

docker pull patrickhulce/lhci-server

Create a Docker volume to store files that should be persisted. The Docker image uses SQLite for it’s database, which uses files stored on the filesystem, so using a volume ensures results are not lost when the container restarts.

docker volume create lhci-data

Now we can start an instance of the Lighthouse CI server on port 9001.

docker container run --publish 9001:9001 --mount source=lhci-data,target=/data --detach patrickhulce/lhci-server

Once the instance has started, navigate to http://localhost:9001/. where you should see the dashboard welcome page.

As detailed on the welcome page, we now need to create a project for our Lighthouse results to be uploaded to. We can use the Lighthouse CI wizard to walk us through these steps.

npx lhci wizard

Choose the option new-project, enter the server URL of http://localhost:9001/ and give the project a suitable name. The Lighthouse CI server will then output a build token and admin token. Keep these tokens safe as they will be needed later.

If you navigate to the Lighthouse CI server on http://localhost:9001/, you will now see the project listed.

With our Lighthouse CI server running and having created a project, we now need to update the lighthouserc.js configuration file so when we run Lighthouse CI, the results are uploaded to our server. Update the upload section as per below:

module.exports = {  
  ...
  upload: {  
    target: 'lhci',  
    serverBaseUrl: 'http://localhost:9001',  
    token: 'xxx' // The Lighthouse CI server build token for the project  
  }  
  ... 
};

And with that, when Lighthouse CI is next run, the results will be uploaded to the server.

npx lhci autorun

Saved LHR to http://localhost:9001
Done saving build results to Lighthouse CI
View build diff at http://localhost:9001/app/projects/mywebsite/compare/xxx

Navigate to http://localhost:9001/ and the project to see the results.

Note: If you receive the error Unexpected status code 422, Build already exists for hash while performing test runs of Lighthouse CI, you can create an empty commit to bypass this.

git commit --allow-empty -m "Lighthouse run"

Running a Lighthouse CI server in Azure

This part of the article covers running the Lighthouse CI server Docker image in Azure. As well as creating a web app to host the Docker image, we’ll also create a PostgreSQL database to store all the results.

Unfortunately, storage account file shares used with containers don’t support SQLite databases, so for this reason, we’re using a PostgreSQL database.

From Azure Portal, create a new resource of type “Azure Database for PostgreSQL”. Follow the wizard and select the compute and storage you require.

I chose the plan Single server & storage + compute of Basic 1 vCores, 5 GB storage. When prompted, enter a username and password for the PostgreSQL database.

Once the PostgreSQL database has been created, access the “Connection security” blade and enable Allow access to Azure services and disable Enforce SSL connection.

We’re ready to create the web app for the Lighthouse CI server. Create a new resource of type “Web App for Container”. Choose the operating system Linux, and the sku and size of F1, which is free. From the “Docker” tab, select an image source of Docker Hub and for the image and tag, enter patrickhulce/lhci-server. With those options in place, create the web app.

Once the web app has been created, we then need to configure it to connect to the PostgreSQL database. From the web app, access the “Configuration” blade and add the setting LHCI_STORAGE__SQL_CONNECTION_URL with the connection details in the following format.

postgresql://{user}%40{server}:{pass}@{server}.postgres.database.azure.com:5432/postgres

So for example.

user: bob
password: qwerty
server: mypostgres
postgresql://bob%40mypostgres:qwerty@mypostgres.postgres.database.azure.com:5432/postgres

Additionally, add the setting LHCI_STORAGE__SQL_DIALECT with the value postgres. As the Lighthouse CI server in the container is listening on port 9001, we need to configure the Azure web app to use this port, so add the application setting WEBSITES_PORT with the value 9001.

And with that, you should now be able to access the web app URL and see the Lighthouse CI server welcome page. From here, follow the same steps as earlier for configuring a local Lighthouse CI server but substitute the http://localhost:9001 server URL for the URL of the Azure web app.

Additional options for running Lighthouse CI

Lighthouse CI server also supports MySQL databases.

The server configuration settings to use a different database are documented here.

The format for the application settings in Azure should be all uppercase, dots replaced with 2 underscores, words separated by 1 underscore and settings prefixed with LHCI_. For example:

storage.sqlConnectionUrl => LHCI_STORAGE__SQL_CONNECTION_URL

More information on environment variables naming is documented here

Additional reading

Lighthouse CI server containers can also be run in Google Cloud Kubernetes.

Lighthouse CI can be integrated into your Continuous Integration process so it’s run after each commit.

Assertions can be used to ensure certain scores are met else Lighthouse CI returns an appropriate status code which could be used to fail builds.

While working on a large project, it can be very useful to keep on eye on key metrics about your codebase to see how your project is growing and review indicators that could mean you’re building up maintenance issues / technical debt.

SonarQube by SonarSource is a static analysis tool that supports 27 languages including JavaScript, TypeScript, HTML & CSS and can detect a range of issues in your codebase including bugs, code smells and security issues as well as provide traditional code metrics like lines of code and cyclometric complexity.

SonarQube additionally supports React JSX and Vue.js Single File Components (that use JavaScript, TypeScript in Vue.js SFCs will hopefully be supported soon.

SonarQube has several tiers available including a Community Edition which is free. This article covers running the Community Edition up in a Docker container and analysing a project to see the range of information SonarQube can provide.

Running the server

SonarQube consists of a server element that collates the statistics on your codebase and serves up reports as webpages as well as a scanner element that analyzes your projects code.

We’re going to run the server element of SonarQube in a Docker container so first ensure you have Docker Desktop installed and running.

Then download the latest version of the SonarQube Docker image.

docker pull sonarqube:latest

And start an instance on port 9000.

docker run -d --name sonarqube-instance -e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true -p 9000:9000 sonarqube

Once the instance has started, navigate to http://localhost:9000 where you’ll be asked to login and change the admin password. The default credentials are:

• Username: admin
• Password: admin

Then create a new project stackedit as we’ll be using the StackEdit source code as an example project to analyse.

Next, create a token with the name stackedit-token which acts as a secret for this project and will allow the scanner to import data for the project. Once generated, copy this token as we’ll be using it later.

Now that the server is running and a project created, it’s time to setup the scanner.

Running the scanner (on Windows)

First download the “vanilla” SonarScanner Windows 64-bit version ZIP file. In this article, we’re not interested in static analysis for any server-side code however there are other scanners available including those that target .NET, Jenkins and Azure DevOps.

Next, extract this ZIP file and place the extracted sonar-scanner-windows folder somewhere convenient on your file system. I moved the sonar-scanner-windows folder to C:\Program Files\sonar-scanner-windows.

In the sonar-scanner-windows\bin folder is the file sonar-scanner.bat which executes the scanner. We’ll add the bin folder to the PATH environment variable for this instance of the command prompt so we can run sonar-scanner from any folder.

set PATH=%PATH%;C:\Program Files\sonar-scanner-windows\bin

From another appropriate folder, download the full source code of StackEdit as the example project we’ll use to analyse.

cd \Temp
git clone https://github.com/benweet/stackedit.git
cd stackedit

Now we’re ready to run the scanner against the StackEdit source code. Run the following command ensuring you swap the token with the one you created via the SonarQube website earlier.

sonar-scanner.bat -D"sonar.projectKey=stackedit" -D"sonar.sources=." -D"sonar.host.url=http://localhost:9000" -D"sonar.login=your_token_here"

Leave the scanner to run and once complete, head back to http://localhost:9000 to see the results.

Excluding files

The command line parameters sonar.exclusions=xxx and sonar.inclusions=yyy can be used to tell the scanner what files to target.

If all the source files in your project are in the folder \src then the following additional command line parameter will limit the scanner to just this folder.

-D"sonar.inclusions=src/**/*.*"

If you have multiple dist folders at different levels within your project, all with minified assets to ignore, the following additional command line parameter will exclude these files from the scanner.

-D"sonar.exclusions=/**/dist/**/*.*"

By default, the scanner excludes node_modules folders with the default value for another parameter sonar.javascript.exclusions.

These parameters can also be provided to the scanner via a sonar-project.properties file in the root folder of the project you’re scanning as an alternative to using command line parameters.

This article covers creating a new .NET 5 ASP.NET Core website in Visual Studio 2019 for Mac and running this website from both Visual Studio and from a Docker image.

Before we start, the following prerequisites need to be installed:

• Visual Studio for Mac (with .NET 5 installed for old installs of VS)
• Docker Desktop on Mac

Create a new project and solution

Create a new “Web Application” project.

Use the target framework of “.NET 5” and “No Authentication”.

Name the project core5-website in a new solution core5-docker-playarea.

Now if you run the project from Visual Studio, after accepting any development certificate prompts displayed, your browser should load the “Welcome” page on the URL https://localhost:5001

The site is actually running in HTTP mode on port 5000 (http://localhost:5000) as well as HTTPS mode on port 5001 (https://localhost:5001). The website is configured to redirect HTTP requests to HTTPS via the HTTPS Redirection Middleware (UseHttpsRedirection) in Startup.cs.

We’ll make a change to the “Welcome” page to output the current time and to output (via an environment variable) whether the code is running in a container. Add the following code to the /Pages/Index.cshtml page:

@{
    ViewData["Title"] = "Home page";
    var runningInContainer = Environment.GetEnvironmentVariable("DOTNET_RUNNING_IN_CONTAINER") == "true";
}

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://docs.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>
    <p>Current time: @DateTime.Now.ToLongTimeString()</p>
    <p>Running in container: @runningInContainer</p>
</div>

Now when you run the site from Visual Studio, the “Welcome” page should display the time as well as detail that the website it’s not running in a container.

Create a Dockerfile file

We now want to take this .NET 5 ASP.NET Core website and run it up in Docker. The first step to do this is to create a Dockerfile file at the solution root to hold the commands needed to build a Docker image:

# First stage
FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build
WORKDIR /DockerSource

# Copy csproj and restore as distinct layers
COPY *.sln .
COPY core5-website/*.csproj ./core5-website/
RUN dotnet restore

# Copy everything else and build website
COPY core5-website/. ./core5-website/
WORKDIR /DockerSource/core5-website
RUN dotnet publish -c release -o /DockerOutput/Website --no-restore

# Final stage
FROM mcr.microsoft.com/dotnet/aspnet:5.0
WORKDIR /DockerOutput/Website
COPY --from=build /DockerOutput/Website ./
ENTRYPOINT ["dotnet", "core5-website.dll"]

These commands can look a bit cryptic so I’ll explain them individually.

FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build

Specifies the base image to use for our image. In our case, we’re using the .NET 5 SDK image provided by Microsoft. The SDK image is being used so we can compile the app but we’ll actually swap to the .NET 5 runtime base image later as this is smaller so will result in smaller output image.

WORKDIR /DockerSource

In the image we’re creating, change to the /DockerSource folder. WORKDIR will create this folder for us if it doesn’t exist.

COPY *.sln .
COPY core5-website/*.csproj ./core5-website/

Copy the solution file to the current image folder (/DockerSource) and copy the project file to the folder /DockerSource/core5-website in the image. COPY like WORKDIR will create a target folder if it doesn’t exist in the image.

RUN dotnet restore

Restore NuGet dependencies. In the previous step, we individually copied the solution and project files to form a separate layer to take advantage of Docker’s build cache. If neither of these files change then Docker knows dotnet restore will yield the same output so can safely bypass this command and use the built-in cache for the corresponding dotnet restore layer instead.

COPY core5-website/. ./core5-website/

Copy all the files from the core5-website project to the to the folder /DockerSource/core5-website in the image.

WORKDIR /DockerSource/core5-website
RUN dotnet publish -c release -o /DockerOutput/Website --no-restore

Swap to the /DockerSource/core5-website folder and compile the website with the output going to the /DockerOutput/Website folder in the image. The --no-restore option prevents the NuGet packages from being restored again as this was done previously in an earlier command.

FROM mcr.microsoft.com/dotnet/aspnet:5.0

Now we’ve compiled and published the website, use the .NET 5 ASP.NET Core runtime image provided by Microsoft as the base image (rather than the SDK image) to reduce the size of the final image created. The use of multiple FROM statements in the Dockerfile is known as a multi-stage build.

WORKDIR /DockerOutput/Website
COPY --from=build /DockerOutput/Website ./

Copy the artifacts from the previous stage of the multi-stage build.

ENTRYPOINT ["dotnet", "core5-website.dll"]

And the last command ENTRYPOINT takes an array of values with the first being the executable to run and the remaining values the arguments to use. When the container starts, the ENTRYPOINT command runs and starts the app.

Create and run the Docker image

Now we have our Dockerfile file in place, we can create our Docker image with the following command:

docker build --pull -t core5-website .

The --pull parameter ensures the latest upstream .NET 5 SDK and .NET 5 runtime images are used and the -t parameter provides the tag / name of the image.

With the Docker image created, we can run an instance of the image:

docker run --rm -it -p 8000:80 core5-website --name core5-website-app

The parameter -rm removes the container once it’s finished running, -it starts the container in interactive mode, -p 8080:80 exposes the port 80 of the container to port 8080 on the host and --name provides the name of the instance.

With the container now running, if you browse to http://localhost:8000 you should see the “Welcome” page and you should see that it details the app is running in a container.

The observant of you may be wondering why the ASP.NET Core app is running over HTTP on port 80 in the container instead of HTTPS on port 5001. Port 80 has been used because the base image from Microsoft contains the environment variable ASPNETCORE_URLS with the value http://+:80, which controls the port the app will listen on and the app is only running over HTTP as we haven’t configured a certificate for Docker to use.

Configuring a certificate to support HTTPS in Docker

The first step is to remove an existing self-signed certificate if there is one.

dotnet dev-certs https --check --verbose
dotnet dev-certs https --clean
dotnet dev-certs https --check --verbose

Now we’ll create a new certificate (with a password of your choosing) and check that the certificate was created successfully.

dotnet dev-certs https -ep ${HOME}/.aspnet/https/core5-website.pfx -p your_password_here
dotnet dev-certs https --trust
dotnet dev-certs https --check --verbose

And with that, we can start the container with some additional parameters to provide details of the certificate we just generated and to map port 443 of the container to port 8001 on the host.

docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORT=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="your_password_here" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/core5-website.pfx -v ${HOME}/.aspnet/https:/https/ core5-website

Now if you browse to http://localhost:8000, you will be redirected to the HTTPS version on https://localhost:8001 with the certificate we just generated being used.

If you are running on a different operating system other than macOS, the previous steps for HTTPS support are slightly different. Please refer to the Microsoft Hosting ASP.NET Core images with Docker over HTTPS page for more detail.

After recently seeing a few BEM class naming issues on a project I was working on, I looked for an online site that would check a CSS stylesheet for BEM naming issues. I couldn’t find one… and what with being on lockdown here in England and having a fair amount of free time on my hands, I thought I’d write one!

Introducing the BEM Class Names Checker — An online tool to check a CSS stylesheet for common BEM naming issues.

https://bem-class-names-checker.netlify.app/

As you make changes to the CSS stylesheet, in real-time any BEM class naming issues are displayed. I hope this online tool will help as a way of experimenting with BEM as well as validating existing stylesheets.

BEM (Block, Element, Modifier) is a methodology for naming CSS styles in a modular and maintainable manner. If you’ve worked on large websites, I’m sure you’ll have come across indecipherable class names and felt the pain of changing a style in one place and that breaking the styling elsewhere on something that seemingly isn’t related. These are issues that BEM will help you to avoid.

In this article, we’re going to use the example of a product card to explain BEM.

BEM relies solely on CSS class names to apply styles to HTML so there are no HTML tag or ID selectors. BEM class names can consist of 3 parts [block]__[element]--[modifier].

Block

A Block is a component part of a website that can exist in it’s own right. We’re using a product card as our example Block in this article. Other examples of a Block are a website header & footer, a login form and a check list.

Block names are in lowercase and each word is separated by a single dash (-) e.g. check-list and site-header.

When you can, try and name Blocks as generically as possible so they can naturally be reused. In this example, we have a product card but if you had other cards on your website that all follow a similar style and layout, it would be better to have a card Block that could be used for other cards like offer cards and latest product cards etc. For the purposes of this article, we’ll assume that the product card is highly specialised so a generic card Block has purposefully not been used.

Element

An Element is a child aspect of a Block that only exists within that Block. In our product card example, image, title, price and like-button are all examples of Elements within the product card Block.

Element class names all begin with the Block name followed by 2 underscores (__) and the Element name in lowercase with words separated by a dash e.g. product-card__title and site-header__logo-image.

Element common mistake 1 — Element chaining

One thing to note with Elements is they shouldn’t be chained. If we take the example of a shopping list, it has items and each item has a product image. At first glance, you may think the Block is shopping-list, Element 1 is item and Element 2 is product-image but this is wrong as there should only be one Element in the class name.

.shopping-list__item__product-image {
  ...
}

Instead, the product image should be thought of as an Element within the shopping-list Block and the class name named as such.

.shopping-list__product-image {
  ...
}

Element common mistake 2 — Element names based on style

Elements should be named based on the “type of thing being displayed” rather than the “styling to be applied”. With our product card, we have a title which is styled larger and in bold text but the Element should not be named based on it’s style.

.product-card__large-bold {
  ...
}

Some issues with this class name is by just reading it, it’s hard to know where it’s being used and hard to know where it can / should be re-used in future. Also, if this style was being used for the title, the price, the availability and other information in the product card, if a developer changed this class because they wanted a larger font for the title, they will actually increase the font size for all the other elements which may not be their intention.

.product-card__title {
  ...
}

Block vs Element

With our made up product card example, we’ve created the like-button Element within the product-card Block which implies that we only ever show like buttons in product cards. If that isn’t the case and like buttons can be shown elsewhere on the site, the like button should become it’s own standalone Block.

Modifier

A Modifier can be applied to either a Block or an Element and is used to adjust the default look or behaviour of the Block or Element. With our product card example, the Modifier liked exists and can be applied to both the product card Block and the like-button Element when a product has been liked.

Modifier class names are separated from the Block or Element by 2 dashes (--) and should be in lowercase and words separated by a dash e.g. product-card--unavailable and shopping-list__item--limited-stock.

Modifier classes should always be used in conjunction with original Block or Element class and just override the attributes to be different. It’s also possible to use multiple Modifier class names on the same HTML tag.

<button class="btn--primary">
    Download
</button>

<button class="btn btn--primary">
    Download
</button>

<button class="btn btn--primary btn--disabled">
    Download
</button>

What are the benefits of BEM?

So you’ve got your head around the slightly odd syntax of BEM (once you’ve seen it a few times, it does become very easy to read), and now you’re probably asking why would I use it? Here’s what I think are the clear benefits:

• Consistent naming of CSS selectors — With a large project being worked on by multiple developers, there’s often different levels of experience and different approaches to CSS. With BEM, every developer should very quickly be able to understand where each CSS class is used and understand how they should name new classes.
• Less unexpected broken styles — As BEM classes always target a Block, in theory, any style changes related to that block will not affect other Blocks.
• No class name clashes — With BEM, there shouldn’t be any class name collisions.
• Any HTML tags can be used — As BEM only uses class names and not tag or ID CSS selectors, we can use any HTML tags we see fit.
• HTML structure can change without everything breaking — As BEM classes are all discrete and not nested, the structure of our HTML can be however we like and it can be changed over time without breaking due to CSS cascading issues.
• Promotes modular, component based design — BEM pushes you to think about your site being composed of discrete areas which promotes abstraction and reuse.

Over the years, I’ve worked on many large web app projects with developers of varying levels of experience and often see the same web accessibility issues crop up. In this article, I detail the 5 most common web accessibility issues I’ve come across and offer solutions for them.

Are you making / have you made these mistakes in your projects?

1) Using An Input Without An Associated Label

Wrong - Using plain text next to the input

Username <input type="text" name="username">

The text “Username” is not associated with the <input> so when a screen reader announces the <input>, it won’t announce that it’s for entering a username. The <input> will be announced along the lines of “input, edit text” so a screen reader user would have no idea what this <input> is for or what to enter.

The text “Username” also won’t act as a click / touch target to set focus to the <input>.

Wrong - Using a label but not linking it to the input

<label>Username</label>  
<input type="text" name="username">  

When using a <label>, it must be associated to it’s corresponding <input>. This can be done either with the for attribute or by wrapping the <label> around the <input>. As neither of these approaches has been used here, the <label> is not associated to the <input>.

Also note that a <label> has a specific semantic meaning which is to provide a label for a corresponding <input>. A <label> must therefore not be used for any general text content that is not acting as a label for an <input>. I have seen <label> elements used just to visually make some general text bold which is wrong.

Wrong - Using a label with for attribute but the input id is missing / wrong

<label for="firstName">First name</label>  
<input type="text" name="firstName">

<label for="lastName">Last name</label>  
<input type="text" name="name" id="name">  

With the “First name”, the <input> doesn’t contain the id attribute and with the “Last name”, the input contains the id attribute but with the value name and not lastName. In both cases, the <label> is not correctly associated with it’s <input>.

Also note that attribute values are case-sensitive so a for="Username" attribute will not match an <input> with the attribute id="username".

Correct - Using a label and input with correct for & id attribute values

<label for="username">Username</label>  
<input type="text" name="username" id="username">  

Correct - Using a label wrapped around the input

<label>  
  Username
  <input type="text" name="username">
</label>  

Correct - Using the aria-labelledby attribute

<h2 id="resetHeading">Reset Password</h2>

<span id="resetUsername">Username</span>  
<input type="text" name="username" aria-labelledby="resetHeading resetUsername">  

If there are one or more existing elements that contain text suitable to act as a label for an <input>, the IDs of these elements can be referenced using the aria-labelledby attribute. In this example, the <input> will be announced along the lines of “reset password username, edit text”.

Providing the extra context of “reset password” may be extremely useful in some scenarios for example on a sign up page that consists a “Username” input in a section for creating a new account and a “Username” input in another section for resetting a forgotten password.

Correct - Using the aria-label attribute for a non-visual label

<input type="text" name="searchTerm" aria-label="Search">
<button type="submit">Search</button>

In some very specific cases, a visual label is not required for an <input> as the purpose of the <input> is clear from the surrounding content. In this example, for a fully sighted user, it’s clear what purpose the <input> serves due the “Search” button next to it. For screen reader users though, this visual connection cannot be made. The aria-label attribute can be used to provide a non-visual label for the search <input>.

Further reading on labels for user input

WCAG 2.1 (Level A) - 3.3.2 Labels or Instructions https://www.w3.org/WAI/WCAG21/quickref/#labels-or-instructions

2) Using An Icon Font Without Text Alternative

Icon fonts provide a convenient way to add scalable, styleable icons to a website (although now arguably SVG icons provide a better approach). The markup to display an icon is typically a <i> or <span> tag with a class applied to it which includes a :before or :after selector to output a specific Unicode character. This Unicode character happens to visually display an icon in the font file but a screen reader either won’t announce this character or will announce a literal description of the icon, neither of which is ideal.

With this in mind, let’s have a look at some common web accessibility issues when using an icon font.

Wrong - Icon with no text alternative

<button>
  <i class="fas fa-download"></i>
</button>

Wrong - Hiding text on small viewports

<style>  
  .download-text {
    display: none;
  }  
 
  @media screen and (min-width: 768px) {
    .download-text {
      display: inline;
    }
  }
</style>  

<button>
  <span class="download-text">Download</span>  
  <i class="fas fa-download"></i>
<button>

Correct - Icon with text alternative

<button>
  Download  
  <i class="fas fa-download" aria-hidden="true"></i>
<button> 

Note that the attribute aria-hidden="true" has been applied to the <i> to ensure the screen reader doesn’t announce the Unicode character.

Correct - Having text alternative still available when displayed text is hidden on small viewports

<style>  
  .download-text {
    display: none;
  }
 
  @media screen and (min-width: 768px) {
    .download-text {
      display: inline;
    }
  }
</style>  

<button>
  <span class="sr-only">Download</span>  
  <span class="download-text" aria-hidden="true">Download</span>
  <i class="fas fa-download" aria-hidden="true"></i>
</button>  

The class sr-only (screen reader only) has been applied to the first <span> which positions the text outside of the viewport so it can’t visually be seen but still exists in the DOM and is announced by a screen reader.

Both the text that is only displayed on larger viewports and the icon <i> tag have the attribute aria-hidden="true" so they are not announced by a screenreader.

Further reading on icon font accessibility

https://fontawesome.com/how-to-use/on-the-web/other-topics/accessibility

3) Adding A Click Handler To A Non-Interactive Element

Wrong - Adding click handlers to a div and span in React and Vue

<div onClick={this.addToBasket}>Add To Basket</div>  
  
<span @click="checkout">Checkout</span>  

Unlike a native <button> or <a>, a keyboard user can’t interact with and invoke click handlers on <div> or <span> elements and a screen reader user isn’t made aware that the <div> or <span> elements can be interacted with.

Correct - Use click handlers with interactive elements

<button onClick={this.addToBasket}>Add To Basket</button>  
  
<a href="#" @click="checkout">Checkout</a>  

Further reading on accessible JavaScript click handlers

https://keepinguptodate.com/pages/2019/04/accessible-javascript-click-handlers/

4) Not Using A Live Region For Important Information

With Progressive Web Apps, Single Page Applications and client-side rich webpages, the content on a webpage can change dynamically without the need for a full page reload. When content in part of a page is dynamically changed, a fully-sighted user can visually see these changes but a screen reader user is not aware of the changes.

Live regions provide a way to have dynamic content changes announced by screen readers.

Wrong - Important information will not be announced

<div>Your message has been sent</div>

<span>Unable to place order as you're offline<span>

Correct - live-region used to announce important information

<div aria-live="polite" role="status">
  Your message has been sent
</div>

<div aria-live="assertive">
  Unable to place order as you're offline
</div>   

Further reading on live regions

https://developers.google.com/web/fundamentals/accessibility/semantics-aria/hiding-and-updating-content#aria-live

5) Not Providing The href Attribute On An Anchor Tag

An anchor element should have a href attribute with a value to ensure the element can receive focus by a keyboard user and to ensure the link is announced correctly by screen readers.

Wrong - No href attribute

<a onClick={this.upload}>Upload</a>  

Wrong - Empty href attribute

<a href="" onClick={this.upload}>Upload</a>  

Correct - A href attribute with a value is provided

<a href="#" onClick={this.upload}>Upload</a>  

Knockout is a minimalist, mature and proven library for creating web applications. It isn’t as feature rich as some of the more modern libraries & frameworks but it does what it does well, primarily being binding HTML elements against a data model. Even in 2019, I believe Knockout has its place and is still used on some very large projects, including Microsoft’s Azure Portal.

As of v3.5.0 (released Feb 2019), Knockout has built-in TypeScript definitions. https://github.com/knockout/knockout/blob/master/build/types/knockout.d.ts

TypeScript provides a huge amount of benefits over JavaScript including type safety, improved IDE tooling and additional constructs like interfaces and enums. If you have an existing project that uses Knockout, you can move over to TypeScript now and start enjoying these benefits.

This article will start with covering using TypeScript and Knockout’s type definitions to create view models, components and bindings that are strongly typed. We’ll then cover creating a new project from scratch that uses webpack and Babel to transpile TypeScript down to JavaScript (ES5).

The code for this article is available on the GitHub repo: https://github.com/JonUK/knockout-typescript

Using strong types with Knockout

We’re going to create a Person class that will be used by a read-only and an editable component to display & allow editing of a person’s details.

Create the file src/models/person.ts.

import * as ko from 'knockout';  
import {
  Observable, ObservableArray, PureComputed
} from 'knockout';  
  
class Person {  
  firstName: Observable<string>;  
  lastName: Observable<string>;  
  favouriteFilms: ObservableArray<string>;  
  
  fullName: PureComputed<string> = ko.pureComputed(
    () => this.firstName() + ' ' + this.lastName());  
  
  constructor(firstName: string, lastName: string, favouriteFilms: string[] | null) {  
    this.firstName = ko.observable(firstName);  
    this.lastName = ko.observable(lastName);  
    this.favouriteFilms = ko.observableArray(favouriteFilms || []);  
  }  
}  
  
export default Person;

The types Observable, ObservableArray and Purecomputed have all been pulled in from knockout. First name is an Observable of type string so if you try to set the firstName observable to a null, a boolean, a number etc, you’ll receive a TypeScript error. Similarly, the PureComputed must always return a string and favouriteFilms can only contain an array of string.

Let’s now create the read-only component to show the person’s details. Create the file src/components/PersonReadOnly.ts.

import Person from '../models/person';  
import template from './PersonReadOnly.html';  
  
class PersonReadOnly {  
  person: Person;  
  
  constructor(params: { person: Person }) {  
    this.person = params.person;  
  }  
}  
  
// The default export returns the component details object to register with KO  
export default { viewModel: PersonReadOnly, template: template };

The template (which we’ll create next) is imported which will result in a HTML string being included in the webpack bundle.

Create the template src/components/PersonReadOnly.html for the read-only component.

<div>  
  
  <h2 class="h4 mt-4 mb-3">PersonReadOnly Component</h2>  
  
  <table class="table">  
    <thead>  
    <tr>  
      <th scope="col">Item</th>  
      <th scope="col">Value</th>  
    </tr>  
    </thead>  
    <tbody>  
    <tr>  
      <th scope="row">First name</th>  
      <td data-bind="text: person.firstName"></td>  
    </tr>  
    <tr>  
      <th scope="row">Last name</th>  
      <td data-bind="text: person.lastName"></td>  
    </tr>  
    <tr>  
      <th scope="row">Full name</th>  
      <td data-bind="text: person.fullName"></td>  
    </tr>  
    <tr>  
      <th scope="row">Favourite films</th>  
      <td data-bind="films: person.favouriteFilms"></td>  
    </tr>  
    </tbody>  
  </table>  
  
</div>

The first name observable, last name observable and full name computed are all bound using the built-in text binding. The favourite films observable array is however bound with a custom films binding which we’ll create next.

Create the file src/bindings/filmsBinding.ts.

import * as ko from 'knockout';
import { BindingHandler, ObservableArray } from 'knockout';

const filmsBinding = {
  init: (element: HTMLElement, valueAccessor: () => ObservableArray): void => {
    const valueUnwrapped = ko.unwrap(valueAccessor());
    const isPopulatedArray = Array.isArray(valueUnwrapped) && valueUnwrapped.length > 0;
    const text = isPopulatedArray ? valueUnwrapped.join(', ') : 'Unknown';
  
    element.textContent = text;
  }
} as BindingHandler;

export default filmsBinding;

Now we’ll create the editable component. Create the file src/components/PersonEditable.ts.

import Person from '../models/person';  
import template from './PersonEditable.html';  
  
class PersonReadOnly {  
  person: Person;  
  
  constructor(params: { person: Person }) {  
    this.person = params.person;  
  }  
}  
  
// The default export returns the component details object to register with KO  
export default { viewModel: PersonReadOnly, template: template };

And create the editable component template src/components/PersonEditable.html.

<div>  
  
  <h2 class="h4 mt-4 mb-3">PersonEditable Component</h2>  
  
  <form>  
    <div class="form-group">  
      <label for="firstName">First name</label>  
      <input data-bind="textInput: person.firstName"
        type="text" id="firstName" class="form-control">  
    </div>  
  
    <div class="form-group">  
      <label for="lastName">Last name</label>  
      <input data-bind="textInput: person.lastName"
        type="text" id="lastName" class="form-control">  
    </div>  
  
  </form>  
  
</div>

We can now reference and use these components in index.ts.

import * as ko from 'knockout';  
  
import Person from "./models/person";  
import PersonReadOnly from './components/PersonReadOnly';  
import PersonEditable from './components/PersonEditable';  
  
import filmsBinding from './bindings/filmsBinding';  
  
ko.components.register('person-read-only', PersonReadOnly);  
ko.components.register('person-editable', PersonEditable);  
  
ko.bindingHandlers.films = filmsBinding;  
  
class AppViewModel {  
  person: Person;  
  
  constructor() {  
  
    // These values are hard-coded but could come from a server API request with JSON response  
  this.person = new Person(  
      'Jon',  
      'Keeping',  
      ['The Matrix', 'The Shawshank Redemption', 'Upgrade']  
    )  
  }  
}  
  
  
ko.applyBindings(
  new AppViewModel(),
  document.getElementById('app'));

Here we’re importing and then registering the components and the custom binding. We’re also creating a instance of the Person class on the person property of AppViewModel. All that’s left to do now is update the webpack template to use these 2 components.

Update the <div id="app"> element in webpack-template/index.html to contain:

<div id="app">  
  
  <div class="row">  
    <div class="col-sm-12 col-lg-7">  
      <person-read-only params="person: person"></person-read-only>  
    </div>  
    <div class="col-sm-12 col-lg-5 pl-lg-5">  
      <person-editable params="person: person"></person-editable>  
    </div>  
  </div>  
  
</div>

Now when you run npm run serve and reload the browser you’ll see these strongly typed Knockout components in action.

The code for this article is available on the GitHub repo: https://github.com/JonUK/knockout-typescript

Using Knockout Validation with types

The package Knockout Validation is very popular with Knockout but unfortunately hasn’t been updated with the latest type definitions.

A GitHub pull request has been created to provide the latest types but at this time (April 2021), this pull request has yet to be merged.

For us, this means we’ll need to add a TypeScript type definition file to our project. Create the file src/knockout.validation.d.ts and copy the content from the GitHub pull request file knockout.validation.d.ts

With the TypeScript type definitions in place, we can install the actual package.

npm install --save knockout.validation

From our main entry point src/main.ts, include this package and configure it as required.

import * as ko from 'knockout';
require('knockout.validation');

...

ko.validation.init({
  errorElementClass: 'is-invalid',
  errorMessageClass: 'invalid-feedback',
  decorateInputElement: true
});

...

Within our components, we can now apply validation rules.

  name: Observable<string> = ko.observable('Bananas')
    .extend({ required: true });

  productCode: Observable<string> = ko.observable()
    .extend({
      required: true,
      minLength: 5,
      pattern: {
        message: 'Please enter letters and digits only',
        params: /^[A-Za-z0-9]*$/
      }
    })

  stockCount: Observable<number> = ko.observable()
    .extend({
      min: 1,
      max: 100
    })

Creating a new Knockout project with TypeScript support

Fire up your terminal / command prompt and let’s get stuck in!

Create a new folder for our project.

mkdir knockout-typescript
cd knockout-typescript

From within the new folder, initialize a new package.json.

npm init -y

Now we have our newly created package.json we can install Knockout and TypeScript.

npm install --save knockout
npm install --save-dev typescript

TypeScript is installed with the --save-dev argument to save it as a development dependency as it’s not needed in production.

Our project is going to use webpack to:

• Handle transpiling TypeScript to Javascript and bundling into a single file
• Generate a HTML page that includes a reference to the output bundle
• During development, provide a web server that supports live reloading

Let’s install webpack and the other related packages we’re going to use.

npm install --save-dev webpack webpack-cli webpack-dev-server html-webpack-plugin

We’ll use Babel (with webpack) to actually transpile our TypeScript to JavaScript which can then be run by web browsers. Let’s install Babel and other related packages.

npm install --save-dev @babel/core @babel/preset-env @babel/preset-typescript @babel/plugin-proposal-class-properties babel-loader

We’re going to use Knockout components with HTML templates and want these templates to be bundled up by webpack. The effect this will have is when the page loads, the component templates will be ready immediately without any additional calls to the server. We’ll use the webpack loader html-loader to include our HTML in the webpack bundle. npm install --save-dev html-loader

We now need to add the webpack configuration file webpack.config.js.

const path = require('path');  
const HtmlWebpackPlugin = require('html-webpack-plugin');  
  
module.exports = {  
  mode: 'development',  
  entry: {  
    app: './src/index.ts'  
  },  
  devtool: 'source-map', // Generate separate source map files  
  devServer: {  
    contentBase: './dist',  
    overlay: true // Show errors in overlay on the website  
  },  
  module: {  
    rules: [  
      {  
        test: /\.(js|ts)$/,  
        exclude: /node_modules/,  
        loader: 'babel-loader'  
      },  
      {  
        test: /\.html$/, // All Knockout.js component HTML templates  
        use: 'html-loader' // Adds the component templates to the bundle  
      }  
    ]  
  },  
  plugins: [  
    new HtmlWebpackPlugin({  
      template: './webpack-template/index.html'  
    }),  
  ],  
  resolve: {  
    extensions: ['.js', '.ts']  
  }  
};

This configuration file instructs webpack to use babel-loader to transpile TypeScript (and ES6+) files down to a JavaScript (ES5) bundle which is output to the dist folder. HTML files are also included in the bundle by html-loader. The app entry file src/index.ts and the webpack template HTML file webpack-template/index.html used to generate dist/index.html don’t exist yet so lets create these now.

Create the file src/index.ts.

alert('An alert from index.ts');

This is just some test code which will allow us to check everything is working correctly. Later we’ll add some real code here.

Create the file webpack-template/index.html.

<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="utf-8">  
  <meta name="viewport" content="width=device-width, initial-scale=1" />  
  <title>Knockout TypeScript</title>  
  
  <link  
  rel="stylesheet"  
  href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css"  
  integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm"  
  crossorigin="anonymous">  
  
</head>  
<body>  
  
<main class="container">  
  <h1 class="mt-4">Using TypeScript With Knockout</h1>  
  
  <!-- The element Knockout will bind to -->
  <div id="app">
  </div>
</main>  
  
</body>  
</html>

As well as the configuration file for webpack, we also need to add configuration files for Babel TypeScript.

Create the file Babel configuration file .babelrc.

{  
  "presets": [  
    "@babel/preset-env",  
    "@babel/typescript"  
  ],  
  "plugins": [  
    "@babel/proposal-class-properties"  
  ]  
}

Create the TypeScript configuration file tsconfig.json

{  
  "compilerOptions": {  
    /* Basic Options */  
    "target": "esnext", 
    "module": "commonjs",
    "allowJs": true, 
    "noEmit": true,
    "isolatedModules": true,
  
    /* Strict Type-Checking Options */
    "strict": true,
   
    /* Module Resolution Options */
    "moduleResolution": "node",
    "baseUrl": "./src",
  
    /* Advanced Options */ 
    "forceConsistentCasingInFileNames": true
  },  
  "include": ["src"]  
}

We’re almost ready to test our page out by running the webpack dev server. Just before we do that though, let’s update the scripts section in package.json to include a new entries for starting the webpack dev server and for performing a production build.

{
  ...
  "scripts": {  
    "serve": "webpack-dev-server --open",  
    "build": "webpack --mode production",  
  },
  ...
}

Good work! Now you can run npm run serve to start dev server and load the site. You should see the JavaScript alert that we added in index.ts.

The code for this article is available on the GitHub repo: https://github.com/JonUK/knockout-typescript

This article covers how to start using TypeScript modules in an existing project alongside JavaScript modules. If you have a large project, it may not be feasible to move to TypeScript all in one go. Gradually migrating provides more flexibility and allows you to, for example, use TypeScript just for new code or “upgrade” modules when there are changes to existing code.

TypeScript provides some huge benefits like types support, better IDE tooling and additional constructs like interfaces and enums so why not start making use of these now.

This articles assumes you’re using webpack with Babel to transpile ES6+ down to ES5. The code for this article is available on the GitHub repo: https://github.com/JonUK/javascript-with-typescript

Steps to configure TypeScript support

1. Install TypeScript:
   npm install --save-dev typescript

2. Install the Babel TypeScript preset along with class property support plugin:
   npm install --save-dev @babel/preset-typescript
npm install --save-dev @babel/plugin-proposal-class-properties

3. Edit .babelrc to include the new Babel preset and plugin:

{  
  "presets": [  
    ...
    "@babel/typescript"  
  ],  
  "plugins": [
    ...  
    "@babel/proposal-class-properties"  
  ]  
}

4. Update webpack.config so Babel additionally compiles TypeScript files:

...
{
  test: /\.(js|ts)$/,  
  exclude: /node_modules/,  
  loader: 'babel-loader'  
},
...

5. Update webpack.config to additionally resolve files with the .ts extension:

...
resolve: {  
  extensions: ['.js', '.ts'],
},
...

6. Create a tsconfig.json file to provide configuration for the TypeScript compiler:

{  
  "compilerOptions": {  
    /* Basic options */  
    "target": "esnext",
    "module": "commonjs",
    "allowJs": true,
    "noEmit": true, 
    "isolatedModules": true,
  
    /* Strict type-checking Options */
    "strict": true,
  
    /* Module resolution options */
    "moduleResolution": "node",
    "baseUrl": "./src",
  
    /* Advanced options */
    "forceConsistentCasingInFileNames": true
  },  
  "include": ["src"]  
}

Steps for ESLint support

7. Install the ESLint TypeScript parser and plugin:
   npm install --save-dev @typescript-eslint/parser
npm install --save-dev @typescript-eslint/eslint-plugin

8. Add an overrides section to .eslintrc to handle TypeScript files:

{
  ...
  "overrides": [
    {
      "extends": ["plugin:@typescript-eslint/recommended"],
      "files": ["*.ts"],
      "parser": "@typescript-eslint/parser",
      "parserOptions": {
        "project": "./tsconfig.json"
      },
      "plugins": [
        "@typescript-eslint"
      ],
      "rules": {
        "@typescript-eslint/no-inferrable-types": "off",
        "@typescript-eslint/no-explicit-any": "off",
        "@typescript-eslint/ban-ts-ignore": "warn",
        "@typescript-eslint/no-use-before-define": ["error", { "functions": false }],
        "no-invalid-this": "off"
      }
    }
  ]
  ...
}  

9. Update webpack.config so ESLint additionally checks TypeScript files:

...
{  
  enforce: 'pre',  
  test: /\.(js|ts)$/,  
  exclude: /node_modules/,  
  loader: 'eslint-loader',  
  options: {  
    emitError: true,  
    emitWarning: true,  
    failOnError: true  
  }  
},  
...

Using TypeScript modules (GitHub code example)

Having followed the steps above, you can now add TypeScript files in your project.

To see all this is action, I’ve created an example in GitHub for a simple webpage that calculates the character count, word count and longest word length for some text. The example uses webpack, Babel & ESLint along with Karma and Jasmine for unit tests.

The repository has two branches for before and after the TypeScript support changes:

JavaScript webpage GitHub branch before changes
https://github.com/JonUK/javascript-with-typescript/tree/01_javascript_only

JavaScript and TypeScript webpage branch
https://github.com/JonUK/javascript-with-typescript/tree/02_typescript_support

Review the TypeScript file src/wordCountCalculator.ts and it’s corresponding tests wordCountCalculator_test.js which are still in JavaScript.

Now go forth and add TypeScript support! 😄

When using Vuex with TypeScript, you typically use the @Getter decorator from the binding helpers package vuex-class. This is a more declarative approach over using this.$store.getters.*.

Vuex @Getter example

@Getter('books', { namespace: 'library' })
books!: Book[];

The getter above retrieves all books from the Vuex module library but what if you wanted to retrieve just a single book by it’s ID?

Method Style Getters

Vuex supports “method-style” getters which are getters that return a function with one or more parameters.

Vuex “method-style” getter example

...

const state: LibraryState = {
  books: []
};

export const getters: GetterTree<LibraryState, RootState> = {
  getBookById: (theState: LibraryState) => (id: string): Book | null => {
    const book = theState.books.find(item => item.id === id);
    return book || null;
  }
};

...

In this example, the getter returns another function which accepts the book id argument and performs a query on the array in state to find the item. With this “method-style” getter in place, we can now get a handle to it from within a component via the @Getter decorator as follows.

@Getter decorator with argument example

@Getter('getBookById', { namespace: 'library' })
getBookById!: (id: string) => Book;

The getBookById function can now be called with the book id parameter to retrieve a single book from state.

mounted hook and route param example

export default class BookDetails extends Vue {
  @Getter('getBookById', { namespace: 'library' })
  getBookById!: (id: string) => Book;

  book: Book | null = null;

  mounted(): void {
    const id = this.$route.params.id;
    this.book = this.getBookById(id);
  }
}

This article covers designing and developing a Weather App webpage using Responsive Web Design (RWD) techniques.

This article will cover creating wireframes for our page so we can visually see how the app will be laid out on different devices and then we’ll create some high-fidelity designs. Next we’ll develop the responsive webpage making use of CSS media queries to alter the layout and design to fit any device screen size from a mobile phone to a large desktop.

The code for this article is available on GitHub: https://github.com/JonUK/responsive-web-weather-app

A demo of the responsive Weather App webpage is hosted on Netlify: https://clever-cray-449315.netlify.com/

Project Brief

Before we start, let’s review the fictitious brief for our Weather App page so we have a clear idea of what we want to achieve.

Requirements

• Current weather conditions are displayed at a large size
• Weather conditions for the next 5 days are displayed
• Weather conditions at different times throughout the current day are displayed (if space available)
• The location of the weather conditions is displayed
• The page looks good on all devices from mobile phones through to large desktops
• Ideally no scrolling is required on mobile phones and tablets in portrait orientation

Creating Wireframes

A great starting point for a web page that is highly visual is to create wireframes. This is especially true for pages that need to work across different device sizes.

We’ll take a mobile first design approach where we create wireframes for a mobile phone and then work up to tablets and desktops. In many ways, a mobile phone is the hardest device to design for due to the limited space available so will force us to consider the essential features and content.

I created the wireframes using Adobe XD (a free version is available).

Mobile Phone — 375 x 667 pixels

Tablet — 768 x 1024 pixels

Desktop — 1920 x 1080 pixels

As you’ll notice, there are no colors or icons on the wireframes and they look very plain. That’s intentional and later we’ll come back and create high-fidelity designs. The purpose of these wireframes is to understand the layout and content for our page on different devices.

On a mobile phone, we won’t show the “Weather by hour” section as there’s not enough space (without introducing vertical scrolling) and we show a condensed version of the “Next 5 days” section.

On a tablet, we’ll move the “Current stats” section up and to the right the “Current temperature” section and we show a extended table version of the “Next 5 days” section.

On a desktop, we essentially have the same version as the tablet but with more spacing and some larger font sizes.

Although our wireframes have been created at typical mobile phone (375 x 667), tablet (768 x 1024) and desktop (1920 x 1080) sizes, these won’t necessarily be the breakpoints we’ll use to swap layouts. Later when we’re developing our page, we’ll review the breakpoints to use based on the space our content needs to show.

Creating High-Fidelity Designs

Now we understand the page layout for each device and we understand what content we want to show, we can move on to creating high-fidelity designs. These designs will let us explore exactly how we want to present the UI to our users.

A caveat to add at this point is that I’m a developer rather than designer, so I’ll give this my best shot!

Mobile Phone — 375 x 667 pixels

Tablet — 768 x 1024 pixels

I used the free 25 Outline Weather Icons from Emske.com which look fantastic and really help give a nice “clean” look.

Developing The Page Layout

Now we’ve created the wireframes and designs, we’re ready to get our hands dirty and start developing the Weather App page. As we’ve seen, there’s 2 main layouts we need to support.

Mobile And Tablet / Desktop Layouts

We’ll take a mobile first development approach to creating our web page which means we’ll initially create CSS just to support mobile phone devices and then add media queries to adjust these styles for larger devices.

Let’s start development with the HTML page. Create the HTML file index.html with the following content:

<!DOCTYPE html>  
<html lang="en">  
<head>  
  <meta charset="utf-8">  
  <meta name="viewport" content="width=device-width, initial-scale=1">  
  <title>Weather App</title>  
  <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600,700&display=swap" rel="stylesheet">  
  <link href="site.css" rel="stylesheet">  
</head>  
<body>  
  
<main class="main-container">  
  
  <div class="location-and-date">  
    A) Location and date  
  </div>  
  
  <div class="current-temperature">  
    B) Current temperature  
  </div>  
  
  <div class="current-stats">  
    C) Current stats  
  </div>  
  
  <div class="weather-by-hour">  
    D) Weather by hour  
  </div>  
  <div class="next-5-days">  
    E) Next 5 days  
  </div>  
  
</main>  
  
</body>  
</html>

Next create the file site.css with the following content:

* {  
  -webkit-font-smoothing: antialiased;  
  -moz-osx-font-smoothing: grayscale;  
  box-sizing: border-box;  
}

body {  
  margin: 16px;  
  font-size: 100%;  
  background-color: gray;
  font-family: 'Open Sans', sans-serif;
}  
  
.main-container {  
  display: flex;  
  flex-wrap: wrap;  
}  
  
.location-and-date {  
  width: 100%;  
  border: 3px solid blue;  
}  
  
.current-temperature {  
  width: 100%;  
  border: 3px solid yellow;  
}  
  
.current-stats {  
  width: 100%;  
  border: 3px solid red;  
}  
  
.weather-by-hour {  
  display: none;  
  width: 100%;  
  border: 3px solid blue;  
}  
  
.next-5-days {  
  width: 100%;  
  border: 3px solid yellow;  
}

We’re using flexbox on the <main> element via the use of the attribute display: flex; on the class main-container and this element is acting as the flexbox parent. Each flexbox child item (each <div> element) is set to a width of 100% and the items are allowed to wrap because of the parent’s attribute flex-wrap: wrap;. The end result is that each <div> element is displayed at full width one below the other which is what we want on a mobile phone device.

The “Weather by hour” section is hidden due to the attribute display: none;. As we saw in our designs, only on viewports larger than a mobile phone is this section displayed.

The HTML contains a <link> element to load the Google Fonts “Open Sans” font which we then apply to all elements via the body selector in the CSS.

Adjusting The Layout For A Tablet

We do want to show the “Weather by hour” section on a tablet device or any device larger than a tablet. A typical tablet in portrait orientation is 768 pixels wide so we’ll use a media query to apply different styles to the “Weather by hour” section when the screen is 768 pixels or greater.

Add the following CSS below the .weather-by-hour selector:

@media screen and (min-width: 768px) {  
  .weather-by-hour {  
    display: block;  
  }  
}

Now as you resize the browser wider and narrower than 768 pixels, the “Weather by hour” section will show and hide.

The other change we want on a tablet device or any device larger than a tablet is to show the “Current temperature” and “Current stats” sections next to each other. To achieve this, we’ll use another media query to set the width of the 2 <div> elements to 50% when the screen is 768 pixels or greater.

Add the following CSS under the .current-stats selector:

@media screen and (min-width: 768px) {  
  .current-temperature,  
  .current-stats {  
    width: 50%;  
  }  
}

To test how your webpage looks on different devices, most modern browsers have developer tools where you can view your site at different viewport sizes. You can read about how to do this with Chrome on the Google Developers website article Simulate Mobile Devices with Device Mode in Chrome DevTools.

Adjusting The Layout For A Desktop

On a desktop, we’ll increase the text size slightly and restrict the maximum width of the <main> element to 1120 pixels. Add the following CSS below the .main-container selector:

@media screen and (min-width: 1000px) {  
  .main-container {  
    width: 980px;  
    margin: 16px auto;
    font-size: 1.1em; 
  }  
}

By setting the width to 980 pixels and setting the left and right margins to auto ensures the <main> element is centered in the viewport when the screen is at or is wider than 1000 pixels. A 20 pixel (1000 - 980) tolerance has been used in case a browser scrollbar is being displayed.

Setting The Background Gradient

In our high-fidelity designs, we have a nice blue gradient background. To achieve this, we’ll apply a linear-gradient to the <body> element. As the blue gradient is quite dark, we’ll swap the foreground color to white so text is legible.

body {  
  margin: 16px;  
  font-size: 100%;  
  font-family: 'Open Sans', sans-serif;  
  color: white;  
  height: 100%;  
  background: linear-gradient(to bottom, rgb(43,50,178) 0%, rgb(20,136,204) 100%);  
  background-repeat: no-repeat;  
  background-attachment: fixed;  
}

Location And Date Section

The first section on the webpage we’ll tackle is the “Location And Date” section. In the HTML, swap the existing <div> with the class location-and-date with the following:

<div class="location-and-date">  
  <h1 class="location-and-date__location">London, UK</h1>  
  <div>Sunday 4th August</div>  
</div>

Then in the CSS, swap the location-and-date class style with the following:

.location-and-date {  
  width: 100%;  
}

.location-and-date__location {  
  margin: 0;  
  font-size: 2em;  
  font-weight: 600;  
}

To give our webpage some semantic meaning, we’ve used a level 1 heading for the location text and styled the text to the size and weight we require.

The CSS class names used follow a Block, Element, Modifier (BEM) naming approach to help isolate styles and make the CSS more maintainable. You can read more about BEM on the Smashing website article BEM For Beginners: Why You Need BEM.

Current Temperature Section

The current temperature section consists of a large weather icon, the temperature and a short summary (e.g. “Mostly Cloudy”). Let’s change the HTML to add these elements and then via CSS we’ll style them.

In index.html replace the <div> with the class current-temperature with the following:

<div class="current-temperature">  
  <div class="current-temperature__icon-container">  
    <img src="icons/mostly-sunny.svg" class="current-temperature__icon" alt="">  
  </div>  
  <div class="current-temperature__content-container">  
    <div class="current-temperature__value">21&deg;</div>  
    <div class="current-temperature__summary">Mostly Sunny</div>  
  </div>  
</div>

As the image is a visual representation of the short summary text, we don’t need this to be announced separately by a screen reader. We can safely add an alt attribute with an empty string so screens reader won’t announce anything for this image.

Next replace the existing current-temperature class and add the other new classes to site.css:

.current-temperature {  
  display: flex;  
  margin-top: 0.25em;  
  width: 100%;  
}  
  
.current-temperature__icon-container {  
  flex-grow: 1.25;  
  text-align: center;  
}  
  
.current-temperature__content-container {  
  flex-grow: 1;  
  text-align: center;  
}  
  
.current-temperature__icon {  
  width: 10.5em;  
}  
  
.current-temperature__value {  
  font-size: 5.25em;  
  font-weight: 300;  
}  
  
.current-temperature__summary {  
  margin-top: -0.5em;  
  margin-left: -0.6em;  
  font-size: 1.125em;  
}

The <div> with the class current-temperature is now acting as a flexbox child of the <main> element as well as a flexbox parent for the <div> elements with the classes current-temperature__icon-container and current-temperature__content-container.

The 2 child container <divs> have a flex-grow attribute which controls how much space they will take up as the available width increases. The current-temperature__icon-container has a grow factor of 1.25 so will take up slightly more width than the current-temperature__content-container which has a grow factor of 1.

Some custom margins have been added to the temperature summary text to pull the text up closer to the temperature value text and to help align the text horizontally.

Screenshot On A Mobile Phone

Well done! You’ve made some great progress. Come back soon for part 2 where we’ll develop the rest of sections of the webpage including the “Next 5 days” section which will involve some much more advanced responsive techniques.

The code for this article is available on GitHub: https://github.com/JonUK/responsive-web-weather-app

This article covers creating a blog from scratch using the Node.js powered static site generator Eleventy (aka 11ty). Eleventy is a relatively new project that came out in 2018 and is quickly gaining traction. It’s up to an impressive 5,000 stars on GitHub already. Eleventy keeps things simple and as you’ll see, really enables you to quickly create a fully functional site.

The blog we’ll create will contain a homepage with excerpts from our posts that can be clicked on to read the full post. Once we have our blog up and running, adding new posts will be as simple as adding new Markdown files. Eleventy will take care of generating HTML pages seamlessly for us as well as updating the homepage.

The code for this article is available on GitHub:
https://github.com/JonUK/eleventy-blog

A demo of the blog is hosted on Netlify:
https://dazzling-almeida-ca0492.netlify.com/

Creating the project

Create the folder eleventy-blog for our project and then within this folder, create a new package.json.

mkdir eleventy-blog
cd eleventy-blog
npm init

When the npm init command is run, you will be asked a series of questions which can all be answered with the default values.

With the package.json file in place, we can now install Eleventy locally as a development dependency.

npm install @11ty/eleventy --save-dev

Note that the package is within the scope @11ty. Another completely different npm package exists with the name eleventy.

Now let’s create the Markdown file About.md for the about page on our blog.

# About This Blog 
  
This is my special place on the big World Wide Web

And with these steps alone, we are ready to have Eleventy generate our first HTML page. Run npx eleventy.

npx eleventy
 
Writing _site/About/index.html from ./About.md.
Processed 1 file in 0.26 seconds

You should now have a new folder _site created for you by Eleventy which contains the folder About and inside this folder, the HTML file index.html.

<h1>About This Blog</h1> 
<p>This is my special place on big World Wide Web</p>

When Eleventy finds a template content file like a Markdown file, it generates an index.html under a folder named the same as the original filename but without the file extension. E.g. the file Pages\Help.md will result in index.html being created under the folder _site\Pages\Help.

The default output folder is _site and the default input folder is the root directory. These can be configured via an .eleventy.js config file in the root directory. Later in this article, we’ll create this file but for other reasons. You can read more about configuration in the official documentation.

Serving up the site

Having Eleventy generate the HTML for our blog posts is great but while we’re developing and adding content, we really want to run a web server so we can see our pages in the browser and even better than that, have the browser update whenever we make changes. Well guess what… Eleventy has got this covered!

First we’ll add some script entries to our package.json for the different Eleventy commands we’re going to use.

...
"scripts": {
  "build": "npx eleventy",
  "serve": "npx eleventy --serve",
  "debug": "DEBUG=* npx eleventy"
},
...

Next we’ll create a basic layout file that will contain HTML markup to wrap around the HTML that Eleventy generates for each Markdown file. The layout file will ensure that the final output is valid HTML with <html> and <body> tags. The layout file will also contain standard elements we’d like on every page such as a header and footer.

Create the folder _includes and within this folder create the file base-layout.njk with the following content.

<!DOCTYPE html> 
<html lang="en"> 
<head> 
  <meta charset="utf-8"> 
  <meta name="viewport" content="width=device-width, initial-scale=1" /> 
  <title>Eleventy Blog</title> 
</head> 
<body> 
  <header>
    Site Header
    <a href="/About">About</a>
  </header> 
  <main> 
    {{ content | safe }}
  </main> 
  <footer>Site Footer</footer> 
</body> 
</html>

Layouts are searched for in the “includes folder”, which is _includes by default. This can be configured to another location if required.

A .njk file is a Nunjucks template that can contain, among other things, loops, conditional logic, special formatting and variable handling. With the line {{ content | safe }}, the template will take the HTML generated from the Markdown file and combine this into the HTML generated for the layout template. The | safe part runs a filter that ensures the HTML from the Markdown is not escaped. You can learn more about Nunjucks on the official site

To use this layout, we need to add some front matter metadata at the top of our About.md file.

--- 
layout: base-layout.njk 
--- 
# About this blog 
  
This is my special place on the big World Wide Web

We can now start the local web server with hot-reloading via the following command.

npm run serve

Going to http://localhost:8080/About in a browser (your port may vary) shows our first page in all it’s glory!

If you change the Markdown file or the layout template, Eleventy will generate the new HTML and update the browser almost immediately. Similarly, if you create a new Markdown file, Eleventy will detect this and automatically generate a new HTML file.

Creating the homepage

What we’d like on our homepage is to list the recent blog posts we’ve added to our site. Let’s first create some dummy blog post Markdown files so we have some content to show. In a new folder posts\2019 create the files blog-post-1.md and blog-post-2.md with following content.

blog-post-1.md

---
layout: base-layout.njk 
title: This Is My First Ever Post
date: 2019-05-30
tags: ['post']
---
This is the first post on my blog.
 
Eleventy is super fresh init.

blog-post-2.md

---
layout: base-layout.njk 
title: How To Get Rich Quick
date: 2019-06-01
tags: ['post']
---
Buy the latest and greatest cryptocurrency that no-one has heard of.
 
## Legal Stuff
We do not accept any liability for any loss or damage.

Note that each blog post is using the base-layout.njk Nunjucks template and the title for each blog article is in the front matter metadata.

We’ll now create an index.njk Nunjucks template for the homepage of our site. Create index.njk in the root directory with the following content.

---
layout: base-layout.njk
pagination:
  data: collections.post
  size: 10
  reverse: true
  alias: posts
---
{% for post in posts %}
  <article>
    <h1>
      <a href="{{ post.url | url }}">{{ post.data.title }}</a>
    </h1>
    {{ post.date }}
  </article>
{% endfor %}

Each of our blog articles has the tag of post assigned to it in the front matter metadata. Eleventy provides a collection for each tag that’s been assigned, so we can access all our blog posts via the collection collections.post. The pagination metadata specifies that the variable posts will be available in the template and will contain the last 10 blog posts. In the template, we’re then iterating through each post and outputting a link to the post and outputting the date.

Looking at the homepage, the date isn’t formatted in a particularly nice way and should be formatted to be easier to read. Eleventy has no in-built mechanism for formatting dates, so we’ll create our own “filter” to handle this. We’re going to use the npm package “moment” to handle date formatting so let get that installed.

npm install moment --save-dev

We’ll then create the Eleventy configuration file .eleventy.js where we’ll add some date filters.

const moment = require('moment');
 
moment.locale('en');
 
module.exports = function (eleventyConfig) {
 
  eleventyConfig.addFilter('dateIso', date => {
    return moment(date).toISOString();
  });
 
  eleventyConfig.addFilter('dateReadable', date => {
    return moment(date).utc().format('LL'); // E.g. May 31, 2019
  });
};

This will make the filters dateIso and dateReadable available for us to use within our Nunjucks templates. We’ll use both of these date formats as we’re going to output a <time> element which uses the ISO format to assist with search engines understanding the date.

Update index.njk to use the new filters.

...
<time datetime="{{ post.date | dateIso }}">{{ post.date | dateReadable }}</time>
...

This results in our dates being much more readable.

Displaying excerpts on the homepage

When people view the homepage of our blog, we’d like to entice them to read a post by displaying the first part of it for them to see. As of Eleventy v0.9.0, the gray-matter npm package that Eleventy uses to parse front matter can be configured to use an excerpt separator which makes an excerpt available in your template as page.excerpt.

https://www.11ty.dev/docs/data-frontmatter-customize/#example-parse-excerpts-from-content

For the purposes of this article, we’re not going to use that approach and we’re going to take full control of excerpt handling ourselves via a “shortcode”. Add the following function at the very bottom of .eleventy.js (after the module.exports function).

function extractExcerpt(article) {
  if (!article.hasOwnProperty('templateContent')) {
    console.warn('Failed to extract excerpt: Document has no property "templateContent".');
    return null;
  }
 
  let excerpt = null;
  const content = article.templateContent;
 
  // The start and end separators to try and match to extract the excerpt
  const separatorsList = [
    { start: '<!-- Excerpt Start -->', end: '<!-- Excerpt End -->' },
    { start: '<p>', end: '</p>' }
  ];
 
  separatorsList.some(separators => {
    const startPosition = content.indexOf(separators.start);
    const endPosition = content.indexOf(separators.end);
 
    if (startPosition !== -1 && endPosition !== -1) {
      excerpt = content.substring(startPosition + separators.start.length, endPosition).trim();
      return true; // Exit out of array loop on first match
    }
  });
 
  return excerpt;
}

Then from within the module.exports function, register the excerpt “shortcode” with Eleventy.

eleventyConfig.addShortcode('excerpt', article => extractExcerpt(article));

This “shortcode” will take the HTML output from each article and return just the content between the HTML comments <!-- Excerpt Start --> and <!-- Excerpt End -->. If these comments aren’t found, it will instead return the content in the first paragraph.

Update the blog post Markdown files to wrap the <!-- Excerpt Start --> and <!-- Excerpt End --> HTML comments around the content you want to show as the excerpt for each post on the homepage. For example:

<!-- Excerpt Start -->
This is included on the homepage.
<!-- Excerpt End -->
 
This will not be on the homepage.

Now we just need to use the excerpt “shortcode” in the index.njk homepage template. We’ll also add a “Read more” link at the bottom of each excerpt.

...
<time datetime="{{ post.date | dateIso }}">{{ post.date | dateReadable }}</time>

{% excerpt post %}

<a href="{{ post.url | url }}"
   aria-label="Read more on {{ post.data.title }}">Read more</a>
...

The blog is starting to take shape nicely.

Blog post nested layout template

If we look at each of our blog posts, they don’t display the title or the date available in their front matter metadata. We can easily solve this by creating a nested layout template for use with blog post Markdown files. Create a new layout template post-layout.njk in the folder _includes with the following content.

---
layout: base-layout.njk
---
<article>
  <h1>{{ title }}</h1> 
  <time datetime="{{ date | dateIso }}">{{ date | dateReadable }}</time> 
  {{ content | safe }}
</article>

This will output the post title and date for each post. This layout template itself uses base-layout.njk layout, so it’s a nested layout template. To use this layout template, update the front matter metadata in each blog post Markdown file to layout: post-layout.njk.

Congratulations, you’ve got yourself a blog setup where adding new posts and having the homepage update is as simple as creating a new Markdown file.

Show me the code!

The code for this article is available on GitHub:
https://github.com/JonUK/eleventy-blog

The latest version of the code in master has a few additional changes to use Google Fonts and use a CSS file to smarten the site up.

A demo of the blog is hosted on Netlify:
https://dazzling-almeida-ca0492.netlify.com/

Some missing metadata on your site could be the cause of not being able to import your story into medium.com.

For the last few hours, I’ve been pulling my hair out trying to understand why the Import Tool on medium.com wasn’t working for an article on my blog.

After much trial and error, it turned out that adding the Open Graph protocol metadata og:type resolved my issue.

The fix

The changes I made were to first register the Open Graph prefix of og: by adding the prefix attribute to my <html> tag.

<html lang="en" prefix="og: http://ogp.me/ns#">

Then within the <head> tag, I ensured the og:type metadata was set along with og:title and og:description.

<meta property="og:type" content="article">
<meta property="og:title" content="...">
<meta property="og:description" content="...">

After these changes, the Import Tool worked fine. I hope this information might help prevent someone else from the same headache I’ve had with this issue!

Other known causes

If you have a web page that uses client-side JavaScript to generate your markdown and content, it’s unlikely the Import Tool will work on your page.

I recently faced an issue where the MIME type for a .mp4 file was being returned from an Azure Web App as application/octet-stream and not the video/mp4 I was seeing locally.

Code

var filename = "test.mp4";
var mimeType = MimeMapping.GetMimeMapping(filename);

Output

Locally:  video/mp4
In Azure: application/octet-stream

What’s going on?!

After some head scratching as to how a static class with a static method could return different results given the same inputs, I decided to dig into the source code.

In the file MimeMapping.cs, you can see mappings of file extension to MIME type but there’s no mapping for .mp4 files.

// MimeMapping.cs around line 246
AddMapping(".mp2", "video/mpeg");
AddMapping(".mp3", "audio/mpeg");
AddMapping(".mpa", "video/mpeg");
AddMapping(".mpe", "video/mpeg");

How was video/mp4 being returned locally for an .mp4 file extension then? The answer lies further down in the code in the file MimeMapping.cs.

// MimeMapping.cs around line 448
// This can provide mappings from the actual applicationHost.config file in IIS7 integrated mode
private sealed class MimeMappingDictionaryIntegrated : MimeMappingDictionaryBase {
	private readonly IntPtr _applicationContext;

	public MimeMappingDictionaryIntegrated(IntPtr applicationContext) {
		_applicationContext = applicationContext;
	}

	protected override void PopulateMappings() {
		IntPtr mimeMapCollection = IntPtr.Zero;
		try {
			int result;
			int mimeMapCount;

			// Read the collection
			result = UnsafeIISMethods.MgdGetMimeMapCollection(IntPtr.Zero, _applicationContext, out mimeMapCollection, out mimeMapCount);
            ...

The class MimeMappingDictionaryIntegrated can provide mappings based on IIS configuration. If MimeMapping is hosted within an ASP.NET application, the internal method SetIntegratedApplicationContext is called and additional MIME type mappings from the IIS configuration are available.

On my local machine, the IIS Express root configuration file applicationhost.config in the folder C:\Program Files (x86)\IIS Express (location can vary) contains the following:

<mimeMap fileExtension=".mp4" mimeType="video/mp4" />

Bingo! That explains why locally the .mp4 extension is mapped to video/mp4. It appears the default Azure Web App configuration does not include this mapping and therefore the default MIME type of application/octet-stream is returned instead.

Let’s have a look at a couple of solutions to resolve this issue of missing MIME type mappings.

Solution 1 — Add a MIME mapping in web.config

The first solution is to add the MIME type mapping for the extension .mp4 to your project’s web.config.

<configuration>
  <system.webServer>
    <staticContent>
      <remove fileExtension=".mp4" />
      <mimeMap fileExtension=".mp4" mimeType="video/mp4" />
    </staticContent>
  </system.webServer>
</configuration>

Solution 2 — Use a different MIME type mappings source

The GitHub project MimeTypeMap provides a much more extensive mapping of file extensions to MIME types (which includes .mp4). The code is packaged up and available via the NuGet package MimeTypeMap.List .

The Internet is a fantastic medium where people can share information, knowledge… and cute cat photos freely and inclusively. HTML is one of the key technologies for the World Wide Web and when used correctly, largely ensures content is accessible to all. Unfortunately, with the rush to create sophisticated JavaScript rich web pages, the fundamentals of good semantic markup are often overlooked to the detriment of web accessibility.

One way to drastically exclude users from your site is to add JavaScript click handlers to non-interactive elements such as <div> and <span> tags.

When is a button not a button?

Can you spot the difference between the two “buttons” below?

To a fully-sighted mouse or touch device user, these “buttons” would appear to function and look the same. For keyboard users or users of assistive technology though, it’s a very different story.

Let’s review these “buttons” as a keyboard user and a screen reader user.

The difference between the “buttons” is one is a native <button> while the other is a <div> tag. Unlike a native <button>, a keyboard user can’t interact with and invoke the click handler on the inaccessible <div> “button” and a screen reader user isn’t made aware that the inaccessible “button” is an element that could be interacted with.

Clearly, the simple fix for the inaccessible button is to swap the <div> for a <button> and job done… but this blog article would be a very short if we left it there! Instead, let’s explore the differences between these “buttons” further and see how we can replicate native <button> behaviour with a <div> element to highlight what using the correct semantic markup gives us out of the box.

Focusable element

The tab key allows a keyboard user to move focus through all the interactive elements on your page. Our <div> button is not focusable though, so let’s resolve that by adding the tabindex attribute.

<div class="btn" tabindex="0">Download</div>

By setting the tabindex to 0, we’re telling the browser that the element can receive focus and should do so in the same order it appears in the DOM, as a user tabs though all the interactive elements.

Web browsers provide a standard focus indicator in the form of an outline / focus ring around the focused element. The outline can be styled differently as required to match the design of your site but the outline should never just be removed.

button:focus {
  outline: 2px dashed red;
}

An element’s tabindex can be set to a positive integer which means the DOM order is ignored for the element. The browser will initially move focus through the elements with a tabindex greater than 0 (in the order of lowest tabindex to highest) before then moving focus through all the other interactive elements in DOM order. In general though, using tabindex to define an explicit tab order is not recommended.

Keyboard interaction

A keyboard user can now tab and set focus on the <div> button but they still can’t operate the button. With a native <button> element, when the button has focus, both Space and Enter keys will trigger the click event handler. To replicate this behaviour on our <div> button, we’ll need to add an event listener to onkeypress to determine if Space or Enter was pressed and if so manually trigger the click handler.

const button = document.getElementById('divButton');

button.addEventListener('click', () => {
  alert('Time to start downloading');
});

button.addEventListener('keydown', (event) => {
  if (event.code === 'Space' || event.code === 'Enter') {
    button.click();
  }
});

Screen readers

We’ll now turn our focus to the differences between a native <button> and our <div> button for screen reader users. When the native button received focus, it was announced with “Download, Button”. The screen reader announcing the word “Button” gives a visually impaired user more context to know the type of control that has focus and therefore to know it can be interacted with. The reason the screen reader announced the word “Button” is because a native button intrinsically has the attribute role of button. If we apply this attribute to our <div> button then the screen reader will announce in the same manner.

<div class="btn" tabindex="0" role="button">Download</div>

Note that adding the role of button just affects how an element appears to a screen reader. We still need to make the <div> focusable and react to keyboard events as detailed above.

Now that our <div> button is focusable, reacts to keyboard events and is announced correctly by screen readers, we have successfully replicated a native <button>.

Accessibility checking

There are a number of tools available to help check your site for common accessibility issues. Unfortunately, none of the tools I tried (including the axe Chrome extension and Google’s Lighthouse identified the <div> “button” as an accessibility issue. I suspect this is due to them not evaluating for JavaScript related web accessibility issues.

Automated accessibility tools can be very useful but, as evidenced here, should be considered a part of your wider strategy around checking for accessibility issues. Arguably, one of the best checks you can perform is to unplug your mouse, turn off your screen and with the keyboard and a screen reader, ensure you are able to perceive and interact with your pages.

Summary

In almost all cases, click handlers should be applied to natively interactive elements like <button> and <a>. Only in exceptional cases should you consider adding click handlers to non-interactive elements and if you do go down this road, ensure you cover accessibility.