Go is really great in that respect. Go packages are a single binary and they’re installed based on how your Go tooling is set up.

Provided we have Go installed, when we run go help install in the command line, we can see where packages are installed:

usage: go install [build flags] [packages]

Install compiles and installs the packages named by the import paths.

Executables are installed in the directory named by the GOBIN environment variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH environment variable is not set. Executables in $GOROOT are installed in $GOROOT/bin or $GOTOOLDIR instead of $GOBIN.

So that’s pretty straight-forward. Let’s see where our packages are installed by trying the first command:

echo $GOPATH

If that returns blank, it’s not defined, so we can probably assume they’re going to be installed in ~/go/bin.

ls $HOME/go/bin

This should return a list of executable binaries installed using go install.

Installing a package with Go

A while back, I built a really simple CLI tool to assist me with testing deep links and statically generated sites that I built. This CLI tool static-server allows me to serve the entire contents of a directory as a static website.

As the instructions in the README say, I can install the latest version of the tool using Go with the following command:

go install github.com/tinacious/static-server@latest

Then, I can navigate to any static HTML website folder on my computer and serve it. Let’s assume I have the following directory somewhere:

test
├── index.html
└── style.css

I can run the following:

cd path/to/test
static-server

This will serve the contents of the directory on a random port.

Uninstalling a package installed with Go

Let’s say you’ve tried this tool and you absolutely hate it. You prefer to type out the long Python 3 command, or use an NPM package that depends on you having the correct Node.js runtime on your computer. Here’s how you can uninstall static-server.

which static-server

This should output the path to the binary. Simply delete it.

Or, if you’re feeling brave and want to do it in a single line:

rm $(which static-server)

This is the 3rd article in a series of posts about working with Open API to create generated API clients and documentation websites.

1. In the 1st post we went over what we can do with Open API spec files, e.g. generate API clients and documentation websites.

2. In the 2nd post we went over how we can create the Open API spec file from an API contract-first approach, using a hand-crafted approach to create the definition of the API, and then having teams build against that.

3. In this 3rd post, we’ll go over how we can annotate our code to support generating the Open API spec file, which means developers won’t have to touch any YAML or JSON files to write API definitions.

What does using annotations to generate an Open API spec look like?

Code can be annotated in a variety of ways to support generating an Open API spec file. This is supported to various degrees in different programming languages.

Java and Kotlin

Probably one of the best supported languages for doing it this way is Java (and Kotlin). The Open API tools were originally written in (and for) Java. And while they were probably amongst the first set of tools available for devs to leverage for this purpose, Java and languages interoperable with Java aren’t the only ones to have these tools. Before going onto those, I’ll share the approach that can be used in Kotlin and Java projects.

Using the starter Spring web project generated from this website, you can add this dependency:

implementation("org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0")

Assuming you want to make a simple todo list app, this could be the handler to retrieve all todos, accepting a query to filter if you want only completed or incomplete todos:

@RestController
@RequestMapping("/api/todos")
class TodoController {
    private val todos = mutableListOf<Todo>(
        Todo("Drink coffee", true),
        Todo("Write blog post about handcrafting bespoke artisanal Open API specs", true),
        Todo("Write blog post about creating Open API specs from code annotations", false),
    )

    @Operation(summary = "Gets all of your todos")
    @ApiResponses(
        value = [
            ApiResponse(responseCode = "200", description = "Success")
        ]
    )
    @GetMapping("", produces = [MediaType.APPLICATION_JSON_VALUE])
    @ResponseStatus(HttpStatus.OK)
    fun getTodos(
        @PathVariable @RequestParam(name = "is_completed", required = false) filterState: Boolean?
    ): List<Todo> {
        val response = todos
            .filter { todo ->
                if (filterState == null) return@filter true
                filterState == todo.isCompleted
            }

        return response
    }
}

And the Todo class itself would be annotated as well:

@Schema(description = "Pending or completed item")
data class Todo(
    @field:Schema(
        description = "The task that needs to be completed",
        example = "Wash car",
        type = "string"
    )
    val text: String,

    @field:Schema(
        description = "Completed state of the todo",
        type = "boolean"
    )
    val isCompleted: Boolean,
)

From these code snippets, you can see @Schema, @field:Schema, @Operation, @ApiResponses. The pattern here is generally there are annotations that map to the respective properties in the spec.

We can see that after it’s configured and we annotate the handler, we can get the information to show up in the Swagger UI tool.

There is of course other methods to support, e.g. post and put requests that accept a request body, and annotating those correctly.

TypeScript

In TypeScript, there’s a framework called Nest.js that is quite similar to Spring in that it’s also an object-oriented MVC framework. Nest can do something similar with the @nestjs/swagger library. Here’s an example controller for a stocks-related app:

import { Body, Controller, Get, Post } from '@nestjs/common';
import { ApiOperation, ApiResponse, ApiTags } from '@nestjs/swagger';
import { IsNotEmpty } from 'class-validator';
import { Stock } from './stock.entity';
import { StockService } from './stock.service';
import { StocksByNameRequest } from './stocks-by-name.dto';

@ApiTags('stocks')
@Controller('stock')
export class StockController {
  constructor(private stockService: StockService) {}

  @ApiOperation({
    summary: 'Get all available stock prices',
  })
  @ApiResponse({
    status: 200,
    description: 'List of stocks',
    type: [Stock],
  })
  @Get()
  async findAll(): Promise<Stock[]> {
    return this.stockService.findAll();
  }

  @ApiOperation({
    summary: 'Get stock prices by name',
  })
  @ApiResponse({
    status: 200,
    description: 'List of stocks',
    type: [Stock],
  })
  @Post()
  async findByNames(
    @Body() stocksByNameRequest: StocksByNameRequest,
  ): Promise<Stock[]> {
    const names = stocksByNameRequest.names;

    return this.stockService.bulkFindByName(names);
  }
}

// Requests

class StocksByNameRequest {
  @ApiProperty({
    description: 'List of stock tickers',
    example: ['AAPL', 'TSLA'],
  })
  @IsNotEmpty()
  names: string[];
}

You can see similar OpenAPI-related annotations, @ApiResponse, @ApiOperation, @ApiTags, @ApiProperty, and @IsNotEmpty, the last of which comes from the class-validator library which is used for object validation for request objects.

This also carries through to the Stock class:

import { ApiProperty } from '@nestjs/swagger';
import { Column, Entity, PrimaryGeneratedColumn } from 'typeorm';

@Entity({
  name: 'stocks',
})
export class Stock {
  @PrimaryGeneratedColumn()
  id: number;

  @ApiProperty({
    description: 'Stock ticker',
    example: 'AAPL',
  })
  @Column()
  name: string;

  @ApiProperty({
    description: 'Price in US dollars',
    example: 100,
  })
  @Column()
  price: number;
}

Again we can see a similar pattern in that it maps properties in the spec.

If we look at the output JavaScript, we can see that Swagger code does end up getting bundled with the dist files.

Go lang

This has also been attempted in Go lang using Go’s structure tags. Struct tags are commonly used in Go for mapping fields of a struct to other objects like database fields or JSON fields. Here’s a simple example of how struct tags are commonly used for JSON marshalling and unmarshalling:

var person *struct {
    Name    string `json:"name"`
    Address *struct {
        Street string `json:"street"`
        City   string `json:"city"`
    } `json:"address"`
}

There’s a project that aims to provide the same code generation abilities for Open API in Go that leverages these struct tags. The code looks like this:

type req struct {
    ID     string `path:"id" example:"XXX-XXXXX"`
    Locale string `query:"locale" pattern:"^[a-z]{2}-[A-Z]{2}$"`
    Title  string `json:"title"`
    Amount uint   `json:"amount"`
    Items  []struct {
        Count uint   `json:"count"`
        Name  string `json:"name"`
    } `json:"items"`
}

It also requires you to run lines of code in order to register objects into the Open API document. From the project’s documentation, we can see we need to execute quite a bit of code in order to generate the OpenAPI spec:

// Source: https://github.com/swaggest/openapi-go/tree/cdbf0a73418c416c59000778488f751a58f7cc54?tab=readme-ov-file#example
reflector := openapi3.Reflector{}
reflector.Spec = &openapi3.Spec{Openapi: "3.0.3"}
reflector.Spec.Info.
    WithTitle("Things API").
    WithVersion("1.2.3").
    WithDescription("Put something here")

type req struct {
    ID     string `path:"id" example:"XXX-XXXXX"`
    Locale string `query:"locale" pattern:"^[a-z]{2}-[A-Z]{2}$"`
    Title  string `json:"string"` // This looks like a typo and should be `json:"title"`
    Amount uint   `json:"amount"`
    Items  []struct {
        Count uint   `json:"count"`
        Name  string `json:"name"`
    } `json:"items"`
}

type resp struct {
    ID     string `json:"id" example:"XXX-XXXXX"`
    Amount uint   `json:"amount"`
    Items  []struct {
        Count uint   `json:"count"`
        Name  string `json:"name"`
    } `json:"items"`
    UpdatedAt time.Time `json:"updated_at"`
}

putOp, err := reflector.NewOperationContext(http.MethodPut, "/things/{id}")
handleError(err)

putOp.AddReqStructure(new(req))
putOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })
putOp.AddRespStructure(new([]resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusConflict })

reflector.AddOperation(putOp)

getOp, err := reflector.NewOperationContext(http.MethodGet, "/things/{id}")
handleError(err)

getOp.AddReqStructure(new(req))
getOp.AddRespStructure(new(resp), func(cu *openapi.ContentUnit) { cu.HTTPStatus = http.StatusOK })

reflector.AddOperation(getOp)

schema, err := reflector.Spec.MarshalYAML()
if err != nil {
    log.Fatal(err)
}

fmt.Println(string(schema))

This is quite a lot of code to write to support an OpenAPI spec but it supports the generation of the Open API spec YAML file.

Why (and why not) use annotations to generate the OpenAPI spec?

Let’s go over some of the reasons why you would or wouldn’t want to use this approach.

Why you may want to use this approach:

• The documentation is right near the code, so if you change the code, you may be more likely to update the documentation since it’s right there

Why you may not want to use this approach:

• Same reason: the documentation is right near the code. This could, arguably, muck up the code, in that it adds more you need to skim past when maintaining or debugging this code. It can be argued that maybe verbose documentation doesn’t belong there.

• You need to learn the abstraction layer of whatever library you’re using. This can be tedious and arguably not a valuable thing to learn and memorize. The initial learning curve can be higher than learning the spec outright since there are tools to help with code completion and validation of the schema file.

• Depending on the language (e.g. Go lang), you may end up writing and shipping a significant amount of extra code related to documenting the Open API spec when using this approach. You may even end up writing more in code than you would have in YAML. Depending on when the code runs and if it’s a compile time operation or a runtime operation, we may create bugs or crashes in the application.

There may be other reasons to prefer or not prefer this approach, but these are the ones I thought of immediately. If you have reasons you like or dislike this approach, feel free to drop a comment.

Summary

This is the 3rd article in a series of articles about working with Open API. In this post we looked at 3 programming languages where we can generate an Open API spec and sometimes Swagger UI documentation website by annotating code or also by writing lines of code inline. Depending on the language, this can result in a significant amount of code that needs to be written.

In part 1 we went over how to generate API clients in TypeScript and API Reference documentation websites.

In part 2 we went over hand-coding Open API spec files ourselves.

If you have anything to add to the discussion, feel free to leave a comment!

This article is the 2nd in a series of blog posts that discuss using Open API to help with API documentation and API client code generation.

In the previous article, we went over how we can generate documentation and API clients using existing Open API spec files. In this article, we’ll go over one way we can create this spec file, which will be the foundation for documentation and code generation.

The next 2 articles (this one and the next) will go over the 2 separate approaches I’m covering for creating an Open API spec file:

1. API contract-first, bespoke artisanal handcrafted Open API spec file

2. Generated Open API spec file

Why (and why not) API contract-first?

One approach to creating Open API spec files is to create the API contract and definition first and then build to the spec.

This is a great approach if you have multiple teams working on an API and you are building towards a common goal.

This approach only works if all teams are on board to doing it this way. If, say, one team is building out the front-end to an API contract, but the backend team is not adhering to the defined contract, then the front-end will not work, and the documentation is essentially useless.

There are some pros with this approach:

• API contract can be formalized up front, allowing back-end and front-end teams to respectively work in parallel on the software to support the back-end and front-end of the product

• API design is up front and centre, enabling API designers to optimize for the developer experience of the future API consumers

There are some cons with this approach:

• If you’re working in a setup where back-end and front-end teams do not collaborate, what can happen is that the front-end team builds towards an API contract they thought was finalized, meanwhile the backend team is building out an API that does not adhere to the contract. This would then require the front-end team to catch up on the API changes in order for their software to work, or the back-end team to revisit the API they implemented to respect the contract.

• Hand-coding these spec files can be tedious and prone to error if you do not have the right tools at your disposal to assist in validating your API schema and testing the documented endpoints

• Spec files are disconnected from the code and risk becoming out of date

In this blog post, covering the scenario where API contract changes are not adequately communicated is out of scope, but we will be going over the tools we can use to help make hand-coding Open API spec files an accurate and enjoyable process.

Optimizing for hand-coding nested JSON files

I will be blunt with this part and state that I prefer using the JSON format for Open API specs. I have not been a fan of YAML in general as I find it difficult to follow the indentation. I like my code braces.

In the below screenshot, I’ve got JSON and YML side-by-side for comparison.

In the above screenshot you may have noticed the rainbow-coloured JSON properties that change colours as the level of JSON is nested deeper. This is my custom Visual Studio Code theme called Tinacious Design. Since early 2020 I’ve had support for over 30 levels of JSON in my theme. This is probably excessive but I like it when working with Open API specs or other large, deeply nested JSON files.

I’m guessing there’s similar support for YML but I haven’t run into it.

If you’re using the Swagger Editor online, you may prefer YAML since they have better syntax highlighting support for it.

I prefer to use my own tools since I have access to the code in the same editor.

If you’re using your own tool, it would be a great idea to ensure you have the ability to preview your API. There are many extensions that have support for previews.

Another thing you’d definitely want is language support so that you can ensure you’re your spec is valid. There are also many extensions that claim to have language for Open API specs.

I ended up choosing one extension that did both. Please note that this appears to be an extension that is a very helpful suite of tools that wraps a commercial product. I did not use the paid features of this extension, only the free ones for editing and previewing my spec file.

The first screenshot above shows the OpenAPI preview with all elements collapsed using the Tinacious Design (dark) theme, while the second shows the OpenAPI preview with one of the elements expanded, using the Tinacious Design (High Contrast, Dark) theme. Both of those themes support colourizing for 30+ levels of nested JSON and are available in this extension.

Generating API types from the hand-coded Open API spec

There are many tools available for this task. After a quick Google search and looking over the documentation, I ended up going with openapicmd. While this was a good tool to generate all of the types into a single file, the API wasn’t readable enough for me to know at a quick glance how to use the same tool for implementing a generated client as discussed in the Part 1 blog post, so for that part I ended up choosing a different tool, heyapi/openapi-ts, which can do both in a straightforward way.

Here’s the command I used to generate the types from the spec file using openapicmd:

npx openapi typegen public/openapi.json > models/api-types/api-schema.d.ts

This outputs all the types to a single file.

Dogfooding the API types

One thing we can do to try to connect the API spec to the real code is using the types that end up being generated. For example, if you’re writing a Next.js or Express handler, you can do so in a way where you use the generated response types. Here’s a very naive example of that:

import { NextApiRequest, NextApiResponse } from 'next';
import { BaseResponse } from '../../utils/api/api-utils';
import { Environment } from '../../utils/Environment';
import { ResponseGetHealth } from '../../models/api-types/api-schema';

export default async function healthHandler(
  request: NextApiRequest,
  response: NextApiResponse<BaseResponse<ResponseGetHealth['data']>>
) {
  return response
    .status(200)
    .json({
      data: {
        version: Environment.getGitCommitHash() || 'unknown',
        openapi: 'https://tinaciousdesign.com/openapi.json'
      }
    })
}

It uses the generated type ResponseGetHealth:

export interface ResponseGetHealth {
  data: {
    /**
     * example:
     * 7ca91a975bfb85b940a290cd3116330ef9fbe6a9
     */
    version: string;
    /**
     * example:
     * https://tinaciousdesign.com/openapi.json
     */
    openapi: string;
  };
}

For example, if I delete the openapi property which is required by the spec, it’ll show an error:

Summary

This set of tools and approaches is one way we can create Open API specs to support generating API clients and documentation. This is a great approach for creating high-quality API documentation provided that all teams involved are willing to work towards creating and building against an agreed-upon API contract.

This is the 2nd post in a series of post. In the next one, we’ll be going over a different approach, which is code-first rather than API contract-first, in which documentation is generated from the code. Stay tuned for the next one!

This article starts a series of Open API-related blog posts.

OpenAPI, previously known as Swagger (a name still in use today for many of its tools), is a suite of tools that generate documentation and networking clients for various programming languages. It uses what’s called an Open API spec, which is versioned, and can be written in YAML and JSON (my preference being JSON).

The order of operations for these blog posts may be somewhat reversed, but in future posts I’ll get to how we can create these spec files in a couple of ways.

Options for generating documentation from an Open API spec YAML or JSON file

Generating documentation for an OpenAPI spec file is probably the easiest task out of all of these. There are many tools available for performing this operation, each with varying difficulties of time or money spent, here’s a few:

• Self-hosted options:

  • Docusaurus plugin

  • maybe VitePress soon

  • maybe Astro Starlight

  • Roll your own

• Hosted options:

  • Mintlify

  • Redocly

  • Hashnode Documentation (just launched recently)

As you can see, there’s no shortage of options. There’s probably countless options I’ve missed, so feel free to mention them in the comments.

I got an email recently about the new feature for Hashnode’s documentation generator, and since I already use the platform for my blog and think very highly of it, I thought I’d give it a try.

It was very easy to create a docs site and point it to my OpenAPI spec. The hard part was creating that spec properly so that I liked what I saw on the generated API Reference.

For this, I decided to document the API for my portfolio website Tinacious Design. The OpenAPI spec can be viewed here.

You can take a look at the generated documentation here: https://tinacious-design-api.hashnode.space

Here it is in dark mode:

And in light mode:

Docs Summary

While the final product of this isn’t particularly useful for anyone except myself, I wanted to build out another proof-of-concept OpenAPI documentation approach. Another, you say? Yes, I’ve already tried out one method, and so I tried out another. More to come in future blog posts. This is only part 1 of a multiple part series.

Generating OpenAPI clients in TypeScript

One of the benefits of using OpenAPI is that since the spec follows a consistent and detailed format for an API, it can be used to generate API clients to avoid time spent writing out the code manually, which can be time-consuming and is prone to human error.

typescript-axios-generator

When I was working with GrowthBook I built them a CLI tool for generating type-safe feature flags and interfacing with the REST API. While there are countless options for JavaScript and TypeScript client generation with varying degrees of satisfaction, for this implementation, I ended up using the typescript-axios-generator. This tool generated API clients which I ended up wrapping using the repository pattern, which helped me quickly build out commands to support all of the REST API endpoints following a simple pattern.

hey-api/openapi-ts

For my own API that I documented using Hashnode’s new tool as shown above, I decided to try another solution and went with hey-api/openapi-ts.

First, I downloaded the OpenAPI script and then used their CLI tool to generate API clients using the spec.

curl https://tinaciousdesign.com/openapi.json > tmp/openapi.json
npx @hey-api/openapi-ts -i tmp/openapi.json -o src/api/client -c @hey-api/client-fetch

In the above script, I use curl to make a network request and send the output into a file at tmp/openapi.json, where tmp is a directory configured to be ignored by version control in my project.

After saving the spec to a file, I then run the openapi-ts CLI tool to generate a client and have it output to src/api/client which is the directory I’ve chosen for this task. Passing -c with a value configures which client we want to generate, in this case a networking client that uses the browser native fetch.

This generates multiple files, but the ones I care about most for my implementation are the services.gen.ts file and the supporting types.gen.ts file, which respectively contain the generated services I can use to call all the endpoints and supporting types.

For my proof-of-concept implementation, I decided to use React. The generator is framework-agnostic, so you can use any framework (or lack thereof) that you prefer. My implementation code looks like this:

// App.tsx

import { useEffect, useState } from "react";
import { portfolioGet } from "./api/services.gen";
import { PortfolioItem } from "./api/types.gen";
import "./styles.css";

export default function App() {
  const [isLoading, setIsLoading] = useState(false);
  const [items, setItems] = useState<PortfolioItem[]>([]);

  useEffect(() => {
    setIsLoading(true);

    portfolioGet()
      .then(({ data }) => {
        setItems(data.data);
      })
      .catch((err) => {
        // todo: handle error
      })
      .finally(() => {
        setIsLoading(false);
      });
  }, []);

  return (
    <>
      {/* View template-related code */}
    </>
  );
}

In order for this to work, I also needed to do some very minor bootstrapping in the index file, which requires setting the base URL for the client:

// index.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { client } from "./api/services.gen";

const rootElement = document.getElementById("root")!;
const root = ReactDOM.createRoot(rootElement);

// Initialize OpenAPI client
client.setConfig({
  baseUrl: "https://tinaciousdesign.com/api",
});

root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Arguably this OpenAPI client bootstrapping code could’ve gone elsewhere but putting it here makes the proof-of-concept quick to read.

The React proof-of-concept fetches all portfolio items and renders them in a 2-up to 4-up grid (depending on the screen size).

You can view this CodeSandbox here. The generated API files can be found in the api directory here.

API client-generation summary

We looked at how we can generate API clients in a couple of ways, and what example implementations could look like for 2 separate code generation approaches.

Summary

So that covers part 1 of this Open API series of blog tools. We went over how we can use an already-generated spec file to its full potential by generating documentation and API clients. Next, we’ll look at creating this spec file in 2 ways.

Stay tuned for more!

NewAppIJustDownloaded pasted from your clipboard

Sometimes it happens during a flow where it's possibly convenient and expected (e.g. you just copied a multi-factor auth code and it would be convenient if the app pasted it for you), and other times, it's when you open the app for the first time and it absolutely is not necessary.

Why am I seeing this warning?

You're seeing this warning because you're on Android version 13 or higher, and because "Show clipboard access" is enabled in your privacy settings. This privacy alert is enabled by default.

In the below screenshot, you can see where this setting can be toggled off if you'd rather not know about every time an app accesses your clipboard (not recommended, I like to leave it on):

It's important to note that this doesn't mean that prior to Android 13 apps couldn't read our clipboard, it just means they did it without us knowing about it.

Disabling clipboard read permissions

Currently, there doesn't appear to be a way to disable clipboard access via the Android Privacy settings as a regular Android user. I would love to be wrong about this, so if it is actually possible, please let me know in the comments.

You can, however, do it by remotely executing scripts via ADB shell, but this requires downloading the Android platform tools so you can have access to the adb executable. It also requires you to enable USB debugging on your Android device so you can access your device with these tools. I'm going to go over this here.

Installing the tools and preparing your device

Before you can disable apps from accessing your keyboard, you'll need to download the right tools and configure the device:

1. Install the Android platform tools

2. Enable USB debugging on your Android device

3. Execute the command adb devices in your terminal to make sure ADB can connect to your device

If you can run the following script:

adb devices

And you see something like this:

$ adb devices
List of devices attached
ABC123XYZ456 device

You're ready to proceed.

If there is an error executing the adb command, it's likely you don't have the tool installed, or it's not on your path (i.e. your command prompt doesn't know where to find it). If you see an error like this, this is the case:

command not found: adb

You'll need to install the Android platform tools somewhere accessible in your path.

If, however, you don't see that error and the list is empty, it's possible you haven't enabled USB debugging on your device. Here's some example output for that:

$ adb devices
List of devices attached

You'll need to enable USB debugging on your Android device.

Seeing which apps have clipboard read access

Once you've got the Android platform tools installed and you can run adb and see your device, you should be able to proceed.

Run the following script to see which apps have access to read your clipboard data:

#!/bin/bash

echo "";
echo "  👁️‍🗨️  The following apps have access to read your clipboard data";
echo "";
adb shell cmd appops query-op --user 0 READ_CLIPBOARD allow

You should see a list of package names that looks something like this:

  👁️‍🗨️  The following apps have access to read your clipboard data

com.google.android.as
com.google.android.apps.messaging
com.google.android.dialer
com.android.chrome
com.google.android.calendar
com.google.android.inputmethod.latin
com.google.android.gm
com.android.systemui

In the above snippet I've only listed some packages, but your list should be much more comprehensive and include apps you've downloaded. In that list, you should see the offending app.

If you don't know an app package name, just Google "app com.whatever.package.name" and see what comes up—one of the first hits should be the Google Play Store listing. Alternatively you could install this app I built called AboutApps that shows you all your installed apps, allowing you to search by package name (you’ll need to build it yourself). Here’s a screenshot of the app’s UI:

Are all these apps reading my clipboard?

Short answer: probably not. If you haven't seen the alert that says that they are, then we should be able to trust that they aren't since Android would tell us when they do. So why are they showing up in this list? It's likely that they are writing to the clipboard.

On my device, there are a lot of apps listed here, including apps I've developed that I know first hand that don't read the clipboard. Apps appear to be listed even if they just write to your clipboard.

For example, one app I developed called Canned Replies (package name com.tinaciousdesign.cannedreplies) is a productivity tool that allows you to quickly copy messages so you can paste them wherever you need them. You enter your frequently-sent messages (canned replies) in the app, and you tap one when you're ready to send it. It gets copied to your clipboard when you tap it. In order to allow you to quickly paste it somewhere else, I need to copy it first. The app only writes to your clipboard but is still listed in this list as an app that reads your clipboard. You can safely revoke the app's access to reading your clipboard data (explained below) and it will still function since it does not read your clipboard data.

I suspect that accessing the ClipboardManager class or querying for context.getSystemService("clipboard") is enough to have it show up in this list. This is the relevant code that is making Canned Replies show up in the list:

fun copyText(text: String?, clipboardKey: String, context: Context) {
    val clipboardManager = context.getSystemService(Context.CLIPBOARD_SERVICE) as ClipboardManager
    val clipData = ClipData.newPlainText(clipboardKey, text)
    clipboardManager.setPrimaryClip(clipData)
}

Many apps need to query this service in order to copy data to your clipboard, which can happen when apps enable common functionality like the ability to copy content to your clipboard so you can share it more easily.

If an app is listed and they haven't been doing anything creepy, it's probably safe to ignore it. Alternatively, you can revoke its permissions (see below) and it should continue to behave as expected, which is the case with Canned Replies.

With Android 13+'s new clipboard read alerts as described here, you should be aware of which apps are accessing the clipboard anyway. If you're on Android 10+ you should be able to trust that apps will only be able to try to read your clipboard while they're foregrounded according to the privacy changes in Android 10 -> Limited access to clipboard data.

Revoking clipboard read access from an app manually

You can prevent one of the apps listed from accessing the clipboard by running the following command against the package. Let's say we want to prevent the Shopify Shop app from accessing our clipboard data, which is an app, from my experience, that reads your clipboard on startup, we can do so by running the following command:

adb shell cmd appops set com.shopify.arrive READ_CLIPBOARD ignore

We can also do that for LinkedIn (another app I've experienced this from):

adb shell cmd appops set com.linkedin.android READ_CLIPBOARD ignore

And TikTok (allegedly, according to people on the internet that are not myself as I have not installed this app to test it):

adb shell cmd appops set com.zhiliaoapp.musically READ_CLIPBOARD ignore

Revoking clipboard read access from an app with a script

If manually revoking packages one by one sounds tedious, you can do so with the following script, which prompts you to paste a list of app packages as input. When you’re done, press Ctrl+D to let it proceed.

#!/bin/bash

echo "";
echo '  🤷🏻‍♀️ Clipboard permissions before script:'
echo "";

adb shell cmd appops query-op --user 0 READ_CLIPBOARD allow

echo "";
echo '  💥 Paste a list of package names you would like to remove clipboard read permissions for and press Ctrl+D when done:'
echo "";

TARGET_APPS=()
while IFS= read -r line
do
  # Add each non-empty line to TARGET_APPS array
  [[ -n "\(line" ]] && TARGET_APPS+=("\)line")
done

for target_app in "${TARGET_APPS[@]}"
do
  echo "";
  echo "⏳ Attempting to remove READ_CLIPBOARD permissions from app: $target_app"
  adb shell cmd appops set $target_app READ_CLIPBOARD ignore
done

echo "";
echo '  ✅ Clipboard permissions after script:'
echo "";
adb shell cmd appops query-op --user 0 READ_CLIPBOARD allow

This produces the following output:

./clipboard_permissions_deny.sh

  🤷🏻‍♀️ Clipboard permissions before script:

# ...

  💥 Paste a list of package names you would like to remove clipboard read permissions for and press Ctrl+D when done:

com.shopify.arrive
com.linkedin.android
^D
⏳ Attempting to remove READ_CLIPBOARD permissions from app: com.shopify.arrive

⏳ Attempting to remove READ_CLIPBOARD permissions from app: com.linkedin.android

  ✅ Clipboard permissions after script:

# ...

What you can do as an Android developer

Are you developing for Android, and is your Android app currently warning users that it's reading their clipboard data? Are you using any libraries? If so, do you know if any of these libraries need to read the clipboard for their functionality? If so, one way you can avoid scaring your users is by warning them ahead of time before you attempt to access the clipboard data with getPrimaryClip(). If you don't know of any libraries you're using that require this functionality, it would be a good idea to look into why it's happening so that you don't lose the trust of your privacy-conscious users.

Get these scripts

You can get these scripts and any other Android-related privacy scripts I decide to add from this Github repository.

The Github repository will have up-to-date scripts while these ones inlined in the article might become out of date.

https://github.com/tinacious/android-privacy-scripts

git clone https://github.com/tinacious/android-privacy-scripts.git

Convert PDF to PNG files with magick

Convert a multi-page PDF file to PDFs with ImageMagick using the following command:

magick density -300 input.pdf -resize 30% outdir/output.png

You can adjust the density and resize values for your preferred file size and quality.

Combine PNG files to PDF in Finder

Select all output PNG files, right click, go to Quick Actions → Create PDF.

Improving this

Can this be done with just ImageMagick?

I did attempt the following command but the images were smaller than ideal.

cd outdir
magick *.png -scale 1311x1819 \
    -units PixelsPerInch \
    -density 300x300 output.pdf

Doing it all with ImageMagick would make this easier to script.

References

• https://stackoverflow.com/a/18863052

• https://imagemagick.org/discourse-server/viewtopic.php?t=26548

• https://www.imagemagick.org/discourse-server/viewtopic.php?t=35159

What is an Event Bus?

Event bus is a pattern that can be implemented in any programming language. An Event Bus is simply a class that implements this pattern.

In Android, there are libraries that have named themselves "EventBus," but it is not a library by default, it is a pattern that can be implemented quite easily without the use of any libraries.

The event bus approach and pattern is a tool that can be leveraged in an event-driven application. Event-driven applications are reactive and react to events as they occur.

One of the benefits of using the event bus pattern is to simplify your application architecture and decouple components that may need to know about each others' data. So, rather than injecting components into each other—which is not very scalable as your app grows—components can emit events and other components can subscribe to these events. This means that your components can instead depend on a shared EventBus class, to which they can publish and subscribe events, rather than on the components themselves that would be required to get this information.

When should I use an Event Bus?

You can use an Event Bus when you need to notify the rest of the app that something has happened, without worrying about all of the dependencies, the hierarchy of your app, or the lifecycles.

Some examples of events that may be appropriate to use the event bus pattern for:

• internet connection is lost or regained
• the user logs out of the app
• a long-running task has completed in the background and other components may want to be notified of this task completion
• data is updated in the background and other components may want to know when this data is updated so that they may re-fetch it

You can use events for pretty much anything but they may not make sense for everything.

When should I NOT use an Event Bus?

An Event Bus is not a one-stop solution—it is a tool that is useful in some cases but may not make sense in other cases.

If you have a view that, on mount, fetches data, and you want the view (fragment or activity) to be aware of this data once it's fetched, an event bus in Android is not the best approach for this. For this, I would instead recommend using MVVM (Model - View - View Model) architecture, and implementing a LiveData observable. With LiveData, you can observe changes to this data, so that this data (once changed) can be updated in the view.

The event bus pattern is not meant to replace Live Data and observables, but rather complement it. You can use both at the same time, if necessary. It is very valid to have both an event bus and live data observables in an application as they have different use cases and value.

A simple example EventBus implementation

EventBus class

The following example EventBus class uses Kotlin coroutine flows to provide events to subscribers. You can learn more about coroutines in Android here. Here is the example EventBus class:

import android.util.Log
import kotlinx.coroutines.flow.MutableSharedFlow
import kotlinx.coroutines.flow.asSharedFlow

class EventBus {
    private val _events = MutableSharedFlow<AppEvent>()
    val events = _events.asSharedFlow()

    suspend fun emitEvent(event: AppEvent) {
        Log.d(TAG, "Emitting event = $event")
        _events.emit(event)
    }

    companion object {
        private const val TAG = "EventBus"
    }
}

In the above code sample, AppEvent is a simple enum. This approach would keep your event bus simple. You may want to instead use a sealed class so you can pass data alongside this event, though I would probably limit the complexity of the event bus by just emitting simple events and having subscribers do what they want with that data. This may or may not be the simplest or most practical approach in your application, so consider your app's needs.

It is important to have a single instance of the event bus so that consumers are publishing and subscribing to the same event bus. In most cases, this EventBus would be provided as a singleton using your dependency injection framework of choice, like Koin or Dagger Hilt, both of which are out of scope for this article.

Publishing events

Publishers who want to publish events would call the emitEvent method with the desired event on the EventBus instance:

eventBus.emitEvent(AppEvent.CONNECTION_RECONNECTED)

Subscribing to events

Subscribers who want to listen to events would collect the emitted events on the flow. This implementation could look something like this:

eventBus.events
    .filter { it == AppEvent.CONNECTION_RECONNECTED }
    .collectLatest { handleReconnection() }

Caveats with the Event Bus approach

While an event bus is a useful tool, like anything, it can be abused. An application's state can quickly get out of hand if every component is using the event bus for everything. It could get to a point where events are being fired unexpectedly, causing unexpected side effects in your app.

Due to this, it may make sense to only use such an approach for events that need to be global in nature (e.g. network connection is dropped or connected, the user logs out, etc.), and stick to conventional MVVM architecture for most of your app's data.

Summary

In summary, the event bus pattern is a useful approach to reactive programming but is not a solution for everything. In most cases, LiveData observables may solve your problem, but in some cases you may want to leverage an event bus to react to events that are more global in nature as they occur.

This is the Android version. Built in native Android with Kotlin, I developed it as an opportunity to build something with some newer Android API's including LiveData, ViewPager2, and coroutines.

You can see the source code on Github or download the app on AppCenter.

Demo time

Steelseries offers their GameSense SDK which has a REST API you can use. This sounded simple enough, so I decided to create a dream for myself:

As a developer, when I push up code that breaks the build on CI, I want my keyboard to flash red

So now I had a new side project to waste my time on!

Here's a picture of the keyboard display showing a message for the build status. This one is for successful builds.

Here's a picture of the display when builds fail.

The function keys also flash either red or green, which you can sort of see in the demo video below.

This app leverages Codeship as the continuous integration service. I like Codeship for this purpose because it allows you to configure a web hook for the project and doesn't require you to modify any Yaml files in your source code to get this to work, you can just set it up in the dashboard without making a scene in your team's code. I initially looked at Github Actions and then Circle CI but neither of those had a setup as quick and easy as Codeship's.

I also used ngrok to create a local tunnel so that Codeship had a public URL to hit.

How the Steelseries GameSense SDK works

When you install the Engine software, a server is created on your machine. Steelseries keyboards listen for events on this port, e.g. localhost:<port>.

Steelseries also offers official SDK's for game engines like Unity. There was an unofficial Node.js client, which I tried first, but unfortunately it didn't run and threw a bunch of errors when implementing the example code, so I needed to build my own solution.

Demo time

If this sounds interesting, watch this demo to see it in action.

Get the code

If you like what you see, get the code on Github. The readme includes a tutorial on how you can set this up for yourself. Feel free to fork it. If you add any cool features, I'd love to see them!

I came across this problem again in a different app, and it was time to solve it the right way.

Saving to photos before Android 10

Before Android 10, you could save to photos by writing to the following directory:

Environment
  .getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES)

As of Android 10, this approach has been deprecated. You no longer have access to folders directly in this way. You could still use it for a little while though with the requestLegacyExternalStorage flag in your manifest, but this is a bandaid solution, and as soon as you upgrade your app to target Android 11, this will no longer work, which means you'll need to eventually overhaul your storage implementation. Targeting Android 11 will become mandatory in August 2021, giving developers about 1 year to migrate from the legacy storage implementation.

Share sheet for images

Sharing via the share sheet on Android is the easiest approach, and it's the one I outline in this blog post, but it's a cumbersome experience for some users.

On Pixel devices, Google Photos is the default photos program. When you want to see the photos on your device, you open Google Photos. There is no difference between Google Photos and your device photos anymore.

On other (non-Google) Android devices, this isn't the case, and many other device manufacturers have their own version of a gallery app. Unfortunately, some of these apps are not available as an option in the native share sheet when creating an image share intent. The OnePlus Gallery app, for example—which ships with One Plus devices—doesn't show up as an option to share to. This creates a cumbersome experience for these Android users who just want to save an image to their phone.

Problem: the go-to React Native plugin doesn't work on Android 10+

The React Native CameraRoll plugin, which works well enough for iOS, unfortunately doesn't work for recent Android versions. There are a few issues and/or pull requests open for this topic: #244, #219, #268, #248, #271 to name a few.

The problem I was solving was quite unique and had multiple layers: React Native app with an embedded web view, and the image is an export of an HTML5 canvas, which provides the image data as a base64 encoded string. To solve this problem on Android, I needed 2 separate plugins: the above-mentioned react-native-cameraroll plugin for iOS, as well as the React Native Share plugin to share with the native share sheet on Android since saving to photos didn't work. While this allowed me to get the image to the user to some degree, it wasn't the ideal solution for my needs.

Solution: Implement scoped storage for Android Q+ with legacy storage fallback

Because the React Native community didn't have a solution for my needs, I decided to develop one. While the react-native-cameraroll plugin sort of worked on iOS, it wasn't perfect—it would crash the app if the user had declined to share access to their photos.

I ended up developing the plugin I called React Native Save Base Sixty Four. The naming is unfortunately quite verbose but numbers in package names get marked as spam by NPM and prevent publishing.

The plugin I developed solves the following problems, which are limited in scope to an image that is in the format of an encoded base64 string.

On iOS:

• Enable iOS users to save a base64 image to their photos
• Allow the React Native app to handle the case that the iOS users decline to grant permissions to photos

On Android:

• Enable users on Android 10 and higher to save a base64 image to their photos on their device
• Enable users on Android 9 and older to save a base64 image to their photos on their device
• Allow the React Native app to handle the case that the user declines to grant permissions to photos

The plugin also allows user to share a base64 image via the native share sheet on both platforms, but if that's all you need to do, I would recommend you use the React Native Share plugin as it's more mature and is supported by the community and handles base64 strings perfectly. I added this functionality to my plugin because it was simple enough, and I could use the same plugin for both platforms and uninstall the other two from my project.

How to use this plugin

The full instructions can be found in the project readme, including instructions for how to modify your Android manifest and iOS Info.plist file, but here's a snippet. It uses the promises API, which can be implemented with a set of .then().catch() blocks or async await.

import SaveBase64Image from 'react-native-save-base-sixty-four';

// Save to device
//    with async await
try {
  const success = await SaveBase64Image.save(base64ImageString, options);
  if (!success) {
    // 😭 user did not grant permission
  }
} catch (error) {
  // 💥 there was a crash
}

//    with promises
SaveBase64Image
  .save(base64ImageString, options)
  .then((success) => {
    if (!success) {
      // 😭 user did not grant permission
    }
  })
  .catch((error) => {
    // 💥 there was a crash
  });

The linked readme also includes further instructions on how to implement permission checking on Android. Legacy versions of Android require you to prompt the user when you run the app, while Android 10+ does not because access is scoped to files you create. Older versions of Android will crash if you try to access something you don't have permission to access. This snippet is a handy utility function for React Native apps to check Android permissions. It depends on the react-native-device-info plugin. The example app in the plugin I developed has an example of how to implement the plugin with permission checking.

Implementing scoped storage for Android 10+

I have provided some links below in the Further reading section to specifics on implementing scoped storage. The TL;DR is as follows:

• Convert your base64 encoded string into a Bitmap. For this, you can use Android SDK classes Base64 and BitmapFactory to accomplish this task. Here is the source.
• Implement the ContentResolver API to create an output stream and pass the bitmap to that stream.

The full source code can be viewed on the Github page but most of it is in this file. The proof of concept app is available for download on AppCenter.

Gratitude 🙏

I must give a huge thank you to the team that built the bob tool for scaffolding React Native modules as it was a pleasure to work with and saved me a huge amount of time.

Further reading

• Content Resolver
• MediaStore guide

Environment
  .getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS)

The Canned Replies Android app used to use this deprecated API. As of Android 11, both importing and exporting features broke. 😬 This article will go through the solution I used to fix these bugs.

Why did Google deprecate get External Storage Public Directory?

In the Android documentation, Google mentions that access to the user's shared and external storage directories is deprecated as of API level 29 for privacy reasons.

What should I do instead?

The documentation makes a few suggestions as to which alternative API's to use instead. Some suggestions include MediaStore and getExternalFilesDir, which may not always be available.

You may, however, be able to get away with solving this problem with a much simpler approach by using the intent system.

Do users access these files?

Does your app read and write private files to disk, e.g. for caching reasons? Or will the user specifically be involved in the process?

If you are creating features like allowing the user to import or export their data using files, then you can do this with using the intent system. You don't actually need permissions to write to any storage directories and can do so via intents.

Using Intents to read and write files

You can uses the Intent API to read and write files in Android. This API implementation has 2 steps:

1. Creating your intent to perform an action, e.g. get a file
2. Handling the system's response to your intent, i.e. success and failure cases

This blog post will go through the example of reading and writing JSON files. This blog post code is written in Kotlin.

Reading files using Intents

To read files using Intents, we can prompt the user to pick files and then we can perform actions with those files.

This example will read a file of any type.

Creating our intent to read a file

First, we need to create an intent to read a file. We can attach this to a user action, for example, the tapping of a button or menu item. Once the user interacts with our view, we can execute requestImportIntent() which is implemented as follows:

private fun requestImportIntent() {
  val pickIntent = Intent(Intent.ACTION_GET_CONTENT)
  pickIntent.type = "*/*"
  startActivityForResult(pickIntent, INTENT_IMPORT_REQUEST)
}

The above code is creating an intent for ACTION_GET_CONTENT which allows the user to pick a file of any type.

Then, we start an activity for request with the request code stored in the INTENT_IMPORT_REQUEST, which is an Int value.

Once this intent activity is created, the user will be prompted to provide a file. This will allow the user to browse their file system and choose the file they want to provide.

Responding to our intent to read the file

To respond to this intent, we need to implement the override method onActivityResult. We can use the following code, which only cares about successful results, i.e. Activity.RESULT_OK:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (resultCode != Activity.RESULT_OK) {
      return
  }

  when (requestCode) {
    INTENT_IMPORT_REQUEST -> handleIntentImport(data)
  }
}

When the requestCode is for the intent we assigned to INTENT_IMPORT_REQUEST, then we should handle it. I've created a method handleIntentImport(data) which takes the nullable Intent data:

private fun handleIntentImport(intent: Intent?) {
  val importedData: Uri = intent?.data ?: return

  try {
    // Do things with imported data
  } catch (e: IOException) {
    e.printStackTrace()
  }
}

The above code allows us to read the data from the intent, which may be null. If it's null, we make an early return out of the function, otherwise we try to perform our actions on the file data.

Writing files using Intents

Similar to reading files with Intents, we can also write files with Intents. The following example will write a JSON file to the user's desired destination. It will allow the user to name the file.

Creating our intent to write a JSON file

We need to create an intent to write to a file. The following code will allow us to prompt the user to choose where they'd like the document we create to be written:

private fun requestExportIntent() {
  val intent = Intent(Intent.ACTION_CREATE_DOCUMENT)
  intent.addCategory(Intent.CATEGORY_OPENABLE)
  intent.type = "application/json"
  intent.putExtra(Intent.EXTRA_TITLE, generatedFileNameWithTimestamp)

  startActivityForResult(intent, INTENT_EXPORT_REQUEST)
}

In the above code, we first create an intent for ACTION_CREATE_DOCUMENT and specify that the category is openable. We need to add the category CATEGORY_OPENABLE in order to be able to have full control over the file via the ContentResolver API's.

Specifying the right type is required to ensure that the file has the right file extension. For example, to ensure we have the .json file extension, we need to set the type to application/json.

We can also provide a default file name. In this case, I'm using a generated file name with a timestamp. The user will be able to change this.

Next, the user will choose the location and the file name. Once they successfully create the file, we will be able to respond to the intent.

Responding to our intent to write the file

Similar to our read intent above, we will need to implement the override method onActivityResult. The following code has both the existing read intent code and the new code added:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)

  if (resultCode != Activity.RESULT_OK) {
      return
  }

  when (requestCode) {
    INTENT_IMPORT_REQUEST -> handleIntentImport(data) // old

    INTENT_EXPORT_REQUEST -> handleExportIntent(data) // new ✨
  }
}

Given that we get a successful export intent request (i.e. the user has chosen a directory and filename), we can handle that in our handleExportIntent method:

private fun handleExportIntent(intent: Intent?) {
  val uri = intent?.data ?: return

  val outputStream = contentResolver.openOutputStream(uri)
  val exportText = myStringifiedJsonData

  if (exportText == null || outputStream == null) {
    showExportFailureMessage()
    return
  }

  try {
    outputStream.write(exportText.toByteArray())
    outputStream.close()
    showExportSuccessMessage()
  } catch (e: Exception) {
    showExportFailureMessage()
    e.printStackTrace()
  }
}

We can now use the Content Resolver API's to write to this data URI using an output stream.

The example above of myStringifiedJsonData is just a serialized list of POJO's (Plain Old Java Objects). So I serialize the data as JSON, write it to the file, and close the output stream.

Benefits of using intents

• No permissions required
• User has full control over the files

No permissions required

What's great about using the intent system is that no extra permissions are required. You do not need access to read and write to storage if you are using intents.

If Google starts cracking down on permissions for Android like they did with the Chrome Web Store, we may find ourselves with more Play Store rejections for requesting permissions we may not need.

User has full control over the files

Unlike when working with getExternalStoragePublicDirectory, your users can choose where the file goes instead of you choosing a default directory. This is more user-friendly as it would allow the user to put it somewhere specific so they can retrieve it later.

Your users will also be able to name the file something sensible, while still allowing your app to provide a default file name.

Be intentional

Be intentional, spiritually and in an Android way. 🙏 In my opinion, the Intent experience is one of the best features of Android. Nowadays, Apple has caught up and offers something similar with iOS.

When using intents, you can use patterns that Android users are already familiar with instead of coming up with creative solutions to read and write to disk.

That said, intents will not work for all use cases, but if users are interacting with these files, it may be a better user experience to use intents rather than to write to specific directories that you choose.

By using a code generation tool like plop, you can avoid writing tedious boilerplate code and be productive right away. It's also great for maintaining consistency across the project and company.

Updated 4 Nov 2020: Added template for Vue 3 syntax.

Setup

Create a Vue project

To make sure you're set up to generate components using Plop, you'll need to have a Vue.js project. You can generate one with Vue CLI or with Nuxt.

Add Plop as a dependency

Run the following to add Plop as a dependency:

npm install --save-dev plop

Add an NPM script

Add a command to call plop from an NPM script, e.g.

{
  "name": "example-project",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "start": "nuxt-ts start",
    "plop": "plop"
  }
}

Create a Plopfile

Create a file named plopfile.js in the root of your project. Put the following code in it:

// plopfile.js
module.exports = function (plop) {
  plop.setGenerator('component', {
    description: 'Generates a Vue component',
    prompts: [
      {
        type: 'input',
        name: 'component',
        message: 'Component name, e.g. NatureBanner'
      }
    ],
    actions: [
      {
        type: 'add',
        path: 'components/{{pascalCase component}}/{{pascalCase component}}.vue',
        templateFile: 'plop-templates/component.hbs'
      }
    ]
  })
}

Create a plop template

You'll notice the above plopfile references a template file plop-templates/component.hbs. You will need to create this file.

Vue 2

<template>
  <div class="{{kebabCase component}}">{{pascalCase component}}</div>
</template>

<script lang="ts">
import Vue from 'vue'

export default Vue.extend({
  name: '{{pascalCase component}}',
  props: {}
})
</script>

<style lang="scss">
.{{kebabCase component}} {}
</style>

Vue 3

For Vue 3, we don't need to import or extend Vue:

<template>
  <div class="{{kebabCase component}}">{{pascalCase component}}</div>
</template>

<script lang="ts">
export default {
  name: '{{pascalCase component}}',
  props: {}
};
</script>

<style lang="scss">
.{{kebabCase component}} {}
</style>

These are the differences:

Above diffs generated with TextDiffer.

Note: If you're using Nuxt (or any project set up to use Prettier), you will likely need to disable the "helpful" Prettier JS formatting to avoid destroying your Handlebars file.

Once you've added all your files, your project should look something like this:

plop-vue-example/
├── package.json
├── plop-templates
│   └── component.hbs
└── plopfile.js

1 directory, 3 files

Run your script

Now all you need to do is run your script to generate a component:

npm run plop

You will be prompted for the component name. Enter it.

You should now have generated a component in the project's component directory:

components/
├── Logo.vue
├── NatureBanner
│   └── NatureBanner.vue
└── README.md

1 directory, 3 files

If you open the file, you should see a Vue component that uses Sass and TypeScript was generated.

<template>
  <div class="nature-banner">NatureBanner</div>
</template>

<script lang="ts">
import Vue from 'vue'

export default Vue.extend({
  name: 'NatureBanner',
  props: {}
})
</script>

<style lang="scss">
.nature-banner {}
</style>

You can see an example without Sass or TypeScript here.

Here's BEM's official website but keep reading for a brief overview.

BEM Basics

BEM takes a component-based approach to CSS development. It has some strict rules about inheritance and how to write your CSS selectors.

Rules for Inheritance

To follow BEM properly, you should not use inherited CSS styles in order to style your components.

Some CSS properties are inheritable like font- and table-related properties, but most are not (more info).

In order to follow this rule, you should set inherited properties explicitly, where applicable. So, for example, if you are building a card component but the whole card has a smaller font size, all text elements should have their font sizes specified explicitly rather than inheriting the smaller font size from the parent.

This rule exists in order to prevent bugs that can occur due to the cascading nature of CSS, i.e. when inheritable styles are added or removed.

Rules for Selectors

The most important rule is that you should not nest your selectors. The reason for not nesting your selectors is so that you do not have specificity wars.

What's a specificity war, you ask? Remember when you tried to apply a CSS style and it didn't work? And then you had to go digging in the dev console to find out why? Sometimes it was because you specified your style before the style that was applied, but more often than not it was because the style was declared with a combination of classes and HTML element selectors, which resulted in a higher level of specificity.

Some of the most popular CSS frameworks (like Twitter Bootstrap, Material UI, Semantic UI) have this problem, which is why it can be cumbersome to use them when working with an actual UI designer.

The following selector does not obey BEM for multiple reasons:

• because it nests selectors
• because it uses an element selector h2

Here's the bad stuff you should not copy:

/* bad */
.page h1 {
  font-size: 2.5rem;
}

.page h2 {
  font-size: 2rem;
}

The following is how you can do the same thing using BEM.

/* good */
.page__title {
  font-size: 2.5rem;
}

.page__subtitle {
  font-size: 2rem;
}

You'll notice some underscores there, more on that later. For this, see the Element section.

Following the selector rule in BEM means you can end up with more verbose HTML because it would require you to add a corresponding CSS class to everything you want to style. This can make tables more verbose, for example, but it means that in the event you need to have a table that's styled differently, you won't have to have any CSS specificity wars.

Anatomy of BEM

Essentially, the BEM syntax looks like this:

.block__element--modifier

B – Block

Blocks are the main component. If you've worked with React or Vue, you can break up your components the same way in your CSS.

You can also nest blocks inside of other blocks, if needed, but this is generally avoided.

A block can be as simple as a single HTML element, like a button, or it can be as complex as a set of them, like a card with an image, subtitle, excerpt, and a button.

Here is a simple block:

<button class="btn">
  Click me
</button>

Here is a more complex block, which could be a card view for a blog where a single card describes a single blog post:

<div class="card">
  <h3 class="card__title">
    How do I use BEM CSS?
  </h3>
  <div class="card__excerpt">
    BEM CSS stands for Block Element Modifier, which is a 
    CSS methodology to help you write maintainable CSS.
  </div>

  <a class="btn btn--secondary" href="/path/to/blog/post">
    Read More
  </a>
</div>

In the above example, the following are blocks:

• card
• btn

E – Element

A block can contain elements, but doesn't have to.

Though you can nest blocks inside of other blocks, you can only nest elements inside of blocks and you cannot nest elements inside of other elements. This is to maintain a flat CSS structure.

In the above card HTML, the following are elements:

• card__excerpt
• card__title

M – Modifiers

Modifiers are used to modify either blocks or elements. They are used to demonstrate state or variants.

They are used in addition to block and element classes, not in place of them.

Possible states:

• active
• disabled

Possible variants, e.g. for button variants:

• primary
• secondary
• small

In the above card HTML, the following are modifiers:

• btn--secondary

Here is how you would style buttons using BEM:

<button class="btn btn--primary">
  Click me!
</button>

<button class="btn btn--primary btn--disabled">
  Nope, can't touch this!
</button>

The modifier modifies only the relevant part that needs to be modified. If you had a button that was blue by default and grey when it was disabled, then you would only change the background colour:

.btn {
  padding: 10px 20px;
  font-size: 1rem;
}

.btn--primary {
  background: blue;
  color: white;
}

.btn--secondary {
  background: green;
  color: white;
}

.btn--disabled {
  background: grey;
  color: white;
}

Generally, I list my state modifiers after my theme modifiers. To avoid ambiguity or any specificity or inheritance issues, if a modifier needs to override another modifier, I will explicitly set all properties, e.g. background and color in this case.

Combining modifiers

Combining modifiers can be a bit tricky, and it seems like everyone on the internet has their own opinion for how to do this. Many of the posts I've found have produced barely-legible CSS.

Given that our primary button is blue, and our secondary button is green, let's assume that the designer said that the background for a disabled primary button should be dark blue, and the disabled secondary button should be dark green. Not only that, but disabled buttons should be at 50% opacity.

Here's an example mockup:

Option 1: Break the specificity rule

We can still keep the same HTML:

<button class="btn btn--primary btn--disabled">
  Nope!
</button>

As for the CSS, this is where it can get complicated. It may make sense to skip strict BEM rules and do something like this:

.btn--primary.btn--disabled {
  background: darkGreen;
  color: white;
  opacity: 0.5;
}

.btn--secondary.btn--disabled {
  background: darkGreen;
  color: white;
  opacity: 0.5;
}

This technically breaks the specificity rule, which means that the disabled- and variant-related classes are combined as a single selector, making them more specific than other selectors.

Option 2: Write a joined modifier

Instead of having a single --disabled modifier, you can have one for each variant you need to override.

The HTML could look like this:

<button class="btn btn--primary--disabled">
  Nope!
</button>

And the CSS like this:

.btn--primary {
  background: green;
  color: white;
}

.btn--primary--disabled {
  background: darkGreen;
  color: white;
  opacity: 0.5;
}

Doing this won't require you to break any rules, but it may add some complexity when writing your modifiers.

When you use only one modifier class for each style, you don't need to worry about the order that you declare your classes in the HTML. Unfortunately, with this approach, you'll need to remember which order your modifiers are written in, or duplicate the order.

That means you need to remember that you put --disabled after --primary, and not vice-versa, or you'll have to duplicate the CSS with the flipped version:

.btn--primary {
  background: green;
  color: white;
}

.btn--primary--disabled,
.btn--disabled--primary {
  background: darkGreen;
  color: white;
  opacity: 0.5;
}

That's not so bad with just 2 but if we added a third, you can see how this could exponentially get out of hand. This is why I, personally, would probably break the selector rule.

Example: Coffee Menu

Let's assume you have a coffee menu design that the designer gave you.

Here is an example of non-BEM HTML:

<!-- bad: does not follow BEM -->
<table>
  <thead>
    <tr>
      <th>Coffee</th>
      <th>Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Americano</td>
      <td>$3.50</td>
    </tr>
    <tr>
      <td>Long Black</td>
      <td>$3.50</td>
    </tr>
    <tr>
      <td>Latte</td>
      <td>$4.50</td>
    </tr>
    <tr>
      <td>Pour-over</td>
      <td>$6.00</td>
    </tr>
  </tbody>
</table>

With the non-BEM version, we could've styled the table like this, but it would've made assumptions about all tables. This is a common problem when using a CSS framework that provides a lot of opinionated styles for you:

/* bad */
table {
  border: 4px solid brown;
}

table th {
  font-weight: 700;
}

table td {
  padding: 8px;
  font-style: italic;
}

table td:last-child {
  font-weight: 700;
  font-style: normal; /* we need to override the default here 😞 */
}

The CSS is nice and short and this works perfectly fine if we have only one table style, but as soon as we have different table styles, things start to get crazy.

Also, it's not very legible why the styles are like that:

• why is the last child bold?
• why does the last child have their font style modified to normal, which is the default?

Here's the same example using BEM:

<!-- good -->
<table class="coffee-menu">
  <thead>
    <tr>
      <th class="coffee-menu__heading">Coffee</th>
      <th class="coffee-menu__heading">Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="coffee-menu__cell coffee-menu__cell--item">
        Americano
      </td>
      <td class="coffee-menu__cell coffee-menu__cell--price">
        $3.50
      </td>
    </tr>
    <tr>
      <td class="coffee-menu__cell coffee-menu__cell--item">
        Long Black
      </td>
      <td class="coffee-menu__cell coffee-menu__cell--price">
        $3.50
      </td>
    </tr>
    <tr>
      <td class="coffee-menu__cell coffee-menu__cell--item">
        Latte
      </td>
      <td class="coffee-menu__cell coffee-menu__cell--price">
        $4.50
      </td>
    </tr>
    <tr>
      <td class="coffee-menu__cell coffee-menu__cell--item">
        Pour-over
      </td>
      <td class="coffee-menu__cell coffee-menu__cell--price">
        $6.00
      </td>
    </tr>
  </tbody>
</table>

You'll notice that there's a lot more HTML due to all of the CSS classes that are applied. Each td has 2 classes, one as the base class and one as the modifier.

Here's how we would write the CSS of the BEM-friendly version:

.coffee-menu {
  border: 4px solid brown;
}

.coffee-menu__heading {
  font-weight: 700;
}

.coffee-menu__cell {
  padding: 8px;
}

.coffee-menu__cell--item {
  font-style: italic;
}

.coffee-menu__cell--price {
  font-weight: 700;
}

With the BEM-friendly example, we can read the CSS and understand it better. We can see that the price is bold, and the coffee menu item is italic. We don't have to refer to the HTML to see which element is the last child of the table.

So, while the HTML and CSS are more verbose, they provide more information, ultimately making both more legible.

We write code for people, not for computers. You'll thank yourself later as your projects grow.

Feature we need to build

I have a desktop application called TextDiffer which allows you to see the difference between two snippets of text. The app will hopefully be published soon and is currently awaiting for approval from the Mac AppStore. 🤞 Update it's available now.

The TextDiffer app has a button in the UI that says "Perform Diff" which will allow you to run the diff checker. As a user, I would like to access this action using a button in my macOS Touch Bar that says "Perform Diff."

In TextDiffer, I am also able to configure my UI theme between light and dark mode. Depending on the theme I've chosen, the "Perform Diff" button will be a different colour: orange for light mode, and purple for dark mode. As a user, I would like the colour of the "Perform Diff" button in my macOS Touch Bar to be the right colour depending on my theme.

Prerequisites

Before getting started, you will need to understand JavaScript and how to develop basic web apps using any (or no) framework or library.

You should also be familiar with Node.js.

Having a basic understanding of how Electron works helps too.

API's

For this exercise, we will only be using the standard Electron API's including TouchBar, IPC Main, and IPC Renderer.

IPC Basics

Let's go over some basics for interprocess communication in Electron.

Processes

There are two processes that we need to concern ourselves with. If you're familiar with Electron app development, or with developing native mobile apps, you are likely already familiar with these concepts:

• Main – the main process is the one that runs in Node.js. This is the layer that has access to the native desktop API's via corresponding Electron API's.

• Render – the web process. This is the one that runs in the client-side web app of your Electron application. This can be an app written in Vue, React, Angular, or simply vanilla JavaScript.

About message passing

In order for the main process to communicate with the render process, and vice-versa, these processes will need to send messages to each other.

Messages in Electron have two parts:

• the channel

• the message data

The channel is a string value and represents the name or topic of messages. Messages are sent on a channel. In this application, I have set up two separate channels:

• main-actions – the channel I use to send messages to the main process

• render-actions – the channel I use to send messages to the render process

Message passing uses an event-based/observables approach, allowing you to send messages with data to a channel, and to listen for messages and subscribe to a channel, and subsequently perform actions in response to messages you receive.

You can set up your channels as you like—one single channel, one channel per action, one channel per process where actions are shared, etc.

Though I am using two separate channels—one for each process—you may be able to use a single channel to communicate both ways. I have not tested this, but if you have, please let me know in the comments how it turned out!

Listening for messages

Electron allows you to listen for events on the main process via the ipcMain module.

// main.js
const { ipcMain } = require('electron');

ipcMain.on('main-actions', (event, data = {}) => {
  // Do things on the main process
})

Similarly, Electron allows you to listen for events on the render process via the ipcRenderer module.

// render.js
const { ipcRenderer } = window.require('electron');

ipcRenderer.on('render-actions', (event, data = {}) => {
  // Do things on the render process
})

Important: You may have noticed that I am using require differently for each of these processes. While the main process uses the standard Node.js require, the render process does things differently. This is because Electron requires that you use require on the window object in the render process. It's a good idea to check the existence of it ahead of time so that no exceptions are thrown—this is useful if you build your JavaScript app as a standalone web app initially and integrate it with Electron afterwards, in which case window.require would not be present in your standalone web app.

Structuring the message data

Messages you send can have any shape. The message data is the second argument in the callback. In my example code above, I've called that argument data and I've defaulted it to the empty object {}. Your data could just be a string if you wanted, or a number, or any value. I use an object so that I can pass multiple values if needed. I'm doing this because I will be sending multiple types of messages on each of these channels.

I like to structure my message data similar to how Redux actions are structured:

• each action has a type property which is a string that I can use to switch/case on

• additional properties are custom, based on the action

While a simpler action may just have a type property and no additional data, a more complex action would have a type property and whatever data is required to perform that action.

const performDiffAction = {
  type: 'performDiff'
}

const initTouchBarAction = {
  type: 'init_touch_bar',
  theme: 'dark'
}

There is no requirement as to what format your type property should follow. In Redux, the community as a whole is not unanimous between camelCase, snake_case, and SCREAMING_CASE, so feel free to use whichever you prefer.

So, given that my actions are shaped as above, my listeners could look something like this in the render process:

// render.js

ipcRenderer.on('render-actions', (event, data = {}) => {
  switch (data.type) {
    case 'performDiff':
      return window.globalPerformDiff();

    default:
      // no-op
  }
})

And something like this on the main process:

// main.js

ipcMain.on('main-actions', (event, data = {}) => {
  switch (data.type) {
    case 'init_touch_bar':
      return initTouchBarWithConfig({ theme: data.theme });

    default:
      // no-op
  }
})

Sending messages

While listening for messages on the main and render processes is quite similar, sending messages is slightly different.

I should also mention that there are limitations with the data that can be sent in a message.

Your message data must be serializable. Primitives work well for this case, e.g. strings, numbers, and JSON objects that consist only of primitives. Put simply, if you are passing an object, you should be able to run JSON.parse and JSON.stringify on your data and have it work reliably.

If your data is not serializable, you will encounter some errors. One error that you may see is Error: An object could not be cloned. This can occur if you try to pass a reference to a function as part of your message data. The reference cannot be saved and you will likely encounter an error. So, put simply, you cannot just send a message to the main process with a click handler and attach that to the Touch Bar button—this will not work, i.e. this would likely fail: { type: 'doSomething', onClick: doSomething }

We need to use message passing both ways in order to implement Touch Bar functionality end-to-end.

Render -> Main

This part will go over sending a message from the render process (the client-side web app) to the main process (the Node.js app with access to the native layer via Electron).

Let's say when my app initializes, I would like to initialize the Touch Bar with the dark theme. I am choosing to do this from the render process. Doing it from the render process adds an extra step of message passing, but it also gives me more flexibility.

I could have simply done it in the main process without going through the render process, but since I want to configure the style based on the user's UI theme, I need the user to tell me this (from the browser).

So, given that I'd like to send a message from the render process to the main process, the message could look something like this:

// render.js

function initTouchBarWithTheme() {
  const theme = localStorage.getItem('theme') || 'light';

  ipcRenderer.send('main-actions', {
    type: 'init_touch_bar',
    theme: theme
  })
}

The above code will result in the init_touch_bar message being sent from the browser to the Node.js process. This would be a good spot to implement the Touch Bar API, creating a button, and configuring the colour based on the theme sent from the render process.

Main -> Render

This part will go over sending a message from the main process (the Node.js app) to the render process (the web app running in the browser).

Given that the main process is where I need to be to interact with native API's, I would set up my Touch Bar and all of its buttons on the main process. But, considering my application is an Electron app and the bulk of my logic is happening in the UI, I would likely need any user interaction with that button to be propagated to the render process.

So far we've sent a message from the render process and included the theme, which tells us on the main process that we'll need to set the button to be a specific colour. Let's implement that instruction now.

Here is some basic code for creating a Touch Bar with a single button where the colour will change depending on the provided theme:

// main.js

function initTouchBar({ theme }) {
  const window = BrowserWindow.getFocusedWindow();

  const touchBar = new TouchBar({
    items: [
      new TouchBarButton({
        label: 'Perform Diff',
        backgroundColor: theme === 'light' ? '#FF9A49' : '#302AE6',
        click: () => {
          console.log('TODO!');
        },
      })
    ]
  });

  window.setTouchBar(touchBar);
}

The code above is enough code to get a Touch Bar with a single button that changes colour depending on the theme.

That's great and all, but the button won't do anything until we implement the click handler. In this case, clicking on this button should trigger a form submit in our render process. We won't go into detail about what that form submission does or how to implement it, we just need to trigger it, which we can do by clicking on the submit button. This will propagate the event and submit the form.

There is more than one way that we can tell the render process to execute JavaScript from the main process. The two ways I'll touch on both use the webContents API:

• Sending a message – That one is no surprise, given that's what this article is about. This is the approach I prefer.

• executeJavaScript API – An alternative approach that I do not prefer

So, before we get into how I would do it, let's briefly talk about the alternative (i.e. how I would not do it). The alternative way this can be done is without using message passing, and instead using the executeJavaScript API, which takes a string of JavaScript, and a callback with the result. If we used this approach, it means I could look up my DOM element and trigger a gesture (like a button click) and put that code right in the argument string.

While this API would be adequate for very simple tasks, it may not be ideal in the following cases:

• my application is using a framework like Angular, Vue, or React, as this would be outside of the framework code

• my code is relatively complex or comprehensive

I would not personally use this approach. The full range of support via this Electron wrapper is not predictable, may be unreliable, and will likely be quite difficult to debug if you have any issues. Users have experienced some limitations with this approach, at least in its earlier days.

I would prefer to leverage message passing here as well, and send a message from the main process to the render process, and then once I receive that message, execute my code. This is because I can send a very simple message with primitive data I am confident will arrive as intended, and just make sure I'm listening to this message in my web app. The code I execute is not contained in a string, which means I can write tests or execute it in other scenarios without duplicating it into the string argument of a function call.

Message passing from the main process to the render process is also done via the webContents API. I'm going to create the button click handler, which will send a message to the render process. This message will not have any additional data other than the type property.

// main.js

const onPerformDiff = () => {
  const window = BrowserWindow.getFocusedWindow();
  window.webContents.send('render-actions', { 
    type: 'performDiff' 
  });
};

Then, I'll attach it to the button I just made:

// main.js

function initTouchBar({ theme }) {
  const window = BrowserWindow.getFocusedWindow();

  const touchBar = new TouchBar({
    items: [
      new TouchBarButton({
        label: 'Perform Diff',
        backgroundColor: theme === 'light' ? '#FF9A49' : '#302AE6',
        click: onPerformDiff,
      })
    ]
  });

  window.setTouchBar(touchBar);
}

This means that once my orange (or purple) button is tapped on the Touch Bar, it will send the message { type: 'performDiff' } to the render process.

I can listen for that message on the render process and execute some JavaScript. A reminder of the listener we've already set up:

// render.js

ipcRenderer.on('render-actions', (event, data = {}) => {
  switch (data.type) {
    case 'performDiff':
      return window.globalPerformDiff();

    default:
      // no-op
  }
})

In this case, my app is a vanilla JavaScript app and I've saved a method globalPerformDiff to the window so I can easily access it:

// render.js

window.globalPerformDiff = () => {
  const button = document.getElementById('perform-diff-button');
  button.click();
};

I just need to trigger a click on the "Perform diff" button, which will propagate a form submission event, and my app will take care of the rest.

This is it! With everything we've gone over, you should be able to implement a Touch Bar button end-to-end.

I have put my Touch Bar initialization code in a separate method, initTouchBar, which in reality does more than this article covers. I am also calling it multiple times. Here are some examples of when I'm calling it:

• when my app loads

• when the user toggles between the light and dark UI themes

• when the user performs a diff, where I conditionally show and hide buttons depending on some settings

The IPC lifecycle in Electron, visualized

Now that you've seen the code, let's go over the lifecycle of the interprocess communication events for this feature.

1. from render: Send a message from the render process to the main process to create the Touch Bar for the specified UI theme

2. from main: Configure the button with the theme colour using the Electron TouchBar API

3. from main: Configure the button click handler of the above button to send a message to the render process using the Electron webContents API.

4. on main: User interacts with the Touch Bar button

5. from main: Send a message from the main process to the render process for the clicked button

6. from render: Perform an action based on the message and its data

Conclusion

And that's how I would implement a macOS Touch Bar feature in an Electron app.

Interprocess communication in Electron is useful for implementing any and all native desktop functionality end-to-end, like custom desktop notifications, interacting with the camera, or more. Check out the Electron documentation for a list of available API's.

I hope you've learned something here today. Let me know about your experiences with IPC in Electron, and your experience with Electron in general.

And feel free to check out TextDiffer once it's launched! 🚀🚢

Why did I switch from WordPress to Hashnode?

Currently, my portfolio website and blog are on WordPress. It's been really great for search engine optimization, and the experience with WP Engine has been almost flawless, but it's been a long time since I built it so everything I use to run it locally is broken: Vagrant, Scotchbox (LAMP stack), WP Distillery (Wordpress-flavoured LAMP), etc. It's no longer as quick as it used to be to make small changes.

I have been evaluating different blogging platforms. I considered Medium, but I am not a fan of the experience of landing on a Medium link and hitting a paywall, so I didn't want users to experience that if they find one of my posts. It also didn't have any ads injected, so that's great.

I also thought about using a headless CMS and a static site generator like Nuxt as I've had a great experience with it, but that would've taken a lot of dev time to build. I think that's something I would do for the rest of my site once I have more time.

Hashnode has a variety of features that I appreciate:

• Markdown editor
• Canonical link support so I can link to my original post if I wanted to
• Automated backups to a Github repository
• Custom domain linking
• Nice code syntax highlighting, with the bonus of embedding external services for code snippets

What's great is that these are all free, too. There's also a helpful community on Discord to get some help if needed.

Walkthrough for migrating from WordPress to Hashnode

Download post content

To begin the migration, you'll need to download your existing posts. By default these are in XML format. Since I don't really like working with XML, I used the plugin WP Import Export Lite to export my posts as JSON.

The resulting output was an array of objects that had the following shape.

{
  "ID": "463",
  "Title": "iTerm colour schemes",
  "Content": "Introducing 2 iTerm colour schemes [...]",
  "Excerpt": "iTerm colour schemes based off of my Visual Studio Code theme",
  "Date": "June 22, 2020",
  "Post Type": "post",
  "Permalink": "https:\/\/tinaciousdesign.com\/blog\/iterm-colour-schemes\/"
}

Download images

Next, you'll need to download all your images. There's more than one way you can approach it:

1. Download all of the images uploaded to your WordPress install
2. Programmatically process a JSON or XML export of the Media Library, which has links to the media

The first option is by far the easiest, so I went with that.

Images are stored in the ./wp-content/uploads directory by year and month.

wp-content/
└── uploads
    ├── 2019
    │   ├── 01
    │   ├── 02
    │   └── 03
    └── 2020
        ├── 01
        ├── 02
        └── 03

Your posts reference images like this:

https://example.com/wp-content/uploads/2020/08/filename.png

You can use an SFTP tool like Cyberduck or FileZilla to download this folder.

Upload images elsewhere

Update: This section is out of date. The service Fast no longer offers a free plan and Hashnode has its own CDN so I have been manually updating them in an effort to save on server costs.

That "elsewhere" I chose is Fast.io because it had a generous free plan that leverages a variety of storage options like Dropbox, Google Drive, OneDrive, etc. I can take advantage of one of those amazing storage services and link it to Fast.io. I chose Dropbox. After manually deleting some images that weren't used in the blog posts, I uploaded the entire contents of the downloaded ./wp-content/uploads directory to Dropbox.

Programmatically publish posts to Hashnode using their API

Hashnode has a GraphQL API. It's somewhat limited in functionality but has most of the basic features. There's a helpful blog post on how to use it.

Back-dating posts is not supported in the API so I needed to do this manually for each of my posts, which was tedious.

I've created a repository of the scripts I used to facilitate cleaning up and bulk uploading posts.

Conclusion

Overall, I was happy with my migration to Hashnode. It didn't take very long. Hashnode has a lot of features I look forward to using and I was happy to invest the time in migrating.

Setting up my custom domain was a bit painful compared to other services I've set up domains with, e.g. Heroku, Netlify, Github Pages, Amazon S3. I use Cloudflare, and eventually what worked was contacting support on Discord, disabling Cloudflare's default proxying behaviour, and waiting until the SSL certificate was re-generated. Within a day it was working, so the trouble was only a minor setback.

The authoring experience is nice, typographically. There's also support for a lot of different types of embeds. Showing code is pretty without any effort on my part, and their embeds support the services I use most (Codepen, Codesandbox).

Overall, migrating to Hashnode is a relatively low investment, low risk migration.

If you like the sound of this and want to migrate your WordPress blog to Hashnode, you can use some handy scripts I created.

Sorting criteria

The tool allows you to sort countries using the following criteria:

• total confirmed cases
• total new cases today
• total deaths
• total deaths today
• total recovered
• current active cases
• current cases in critical condition
• highest cases per 1 million population
• highest deaths per 1 million population

You can click or tap on the different buttons to sort the countries.

Search by country

The tool also makes it easy to search for COVID-19 stats for a specific country. You can type a country name in the search box to find that country. It filters the countries list by the provided search criteria. This uses the country name provided by the API.

Data

This tool couldn't have been made possible without the dated collected and shared by the open-source community:

• Postman COVID-19 API Resource Centre
• NovelCOVID API
  • Source code
  • API documentation

There's also lots of other data available, but that's the one I used.

Source code

The source code for this app that displays COVID-19 data by country is available on Codepen here. The web application is built using the following technologies:

• HTML
• SCSS
• React
• jQuery (Ajax)
• the above-mentioned API for COVID-19 data by country