DEV Community: Julian Krispel-Samsel

2021 is a great time to start freelancing 🚀

Julian Krispel-Samsel — Mon, 12 Jul 2021 10:43:33 +0000

DISCLAIMER: This is a little bit of a rant, albeit a positive one. I feel optimistic because this year has brought good things, now that I'm back to freelancing. I want to help others achieve the same successes because I am convinced it should be possible and accessible to others.

Software Engineering is booming 📈 and there's never been a better time to start freelancing.

When you are employed by someone, there are always limits, such as:

A holiday allowance. Don't tell me your company offers the unlimited variety because there is no such thing even if they say so 😉
A pay structure. Although these limits are increasing with the demand for software Engineers and are at an all time high - companies will limit how much they pay there employees. It's a necessity to running a business.
Your role. As an employee, unless you fill an executive role you will have little influence over the overall direction of the company. Your job will be defined by your role which comes with limits some of which will be spelled out in your onboarding, some will be unspoken and some boundaries will only be apparent when you push on them.

Of course as a company it's good practice to define these boundaries and as an employee it's helpful to have clear boundaries. For the self-employed none of them apply:

You can take as much holiday as you please, literally. Flip side is that you only get paid for your deliverables.
The price for well written software and good consultancy has no ceiling 💰 and therefore your possible annual salary has the potential to be whatever you make it. Think of the highest salary you know and I guarantee there will be someone who makes 2x that salary but spends half the time doing it.
As a company of one you have sole discretion over where to take it. I found this can be equally overwhelming and freeing.

Let this sink in. Let your dreams be a driver. The road will be long and hard but you can take my word for it - there is a box of highly valuable unicorn poo 🦄 at the end of the rainbow 🌈. I've seen it with my own eyes and recently I think I may be edging closer.

Finally, freelancing is not for everyone. I hope you feel encouraged to consider it, there is no shame in trying it out and going back to a full-time job if you feel it's too risky or too early in your career (as I did before).

Good luck out there and happy Monday! 🙏

PS: 📷 The cover picture is a lady blackbird from my garden, worm in mouth.

10 tips for building accessible (rich) text editors

Julian Krispel-Samsel — Fri, 11 Jun 2021 17:02:14 +0000

If you're building an app that features a rich text editor - you should make it as accessible as possible for screen-readers.

It's really not as hard as it sounds, so here's list of 10 recommendations for building accessible rich text editors. Although most points will be applicable to any kind of library you use, some of them are specific to react.js.

1. Test with an actual screen reader

If you have never used a screen reader, try one out on your app or any app with that has a rich text editor. I'd consider this blog-post a success even if you don't come back to finish reading it.

On OSX you already have one built in to your operating system: VoiceOver.
For Windows users there's nvda (free) which is also the most widely used.
Another popular screen reader is JAWS (not free).

All of the below recommendations become more obvious if you put yourself into your users shoes.

2. Avoid keyboard traps

Overriding default keyboard behaviour to implement features such as hotkeys or indenting text via tab is a common pattern seen in web-based rich-text editors and IDEs.

However, screen-reader users rely entirely on the keyboard to navigate your app, their browser and operating system. It is frustrating and hard to overcome if default keyboard functionality is prevented by an application. If you are implementing such features, check they don't collide with hotkeys that are already in use for the browsers or operating systems.

3. All interactive elements must be reachable via tab and/or arrow keys

Most rich text editing applications make use of menus and toolbars, dynamically positioned or fixed in place.

To ensure that elements are reachable via keyboard they need to be focusable. DOM elements such as button, input, select or textarea are focusable by default. If you're using an element that isn't considered interactive (such as a div) you are required to add a tabindex and a role attribute so that the screen reader knows how to interact with the element.

Consider how much work it is for a keyboard-only user (the mouse is mostly useless for a user with sight-issues) to navigate to these UI elements. This will depend on the position of the element in the DOM and how many other interactive elements are in between.

If you're building an editor with a floating toolbar (such as medium - which is completely inaccessible via tab keys btw) pay close attention to how a keyboard-only user can navigate to and from these buttons and toolbar components.

For complex usecases (if you have submenus or button groups) you should consider programmatically moving focus, more info on this here

4. Use alt text for your images and make them configurable

If you're rendering images in your editor, it is recommended you use an alt attribute to represent what the image contains to a screen reader.

However, for user submitted content it is too difficult to generate meaningful alt text automatically, that's why you should consider making the alt attribute configurable by the user. Here is what it looks like on medium.com:

5. Label your icon buttons

Most rich text editors make use of common icons for text formatting and layout.

These icons don't have textual meaning on their own, hence we need to tell the screen reader what they are by assigning the aria-label attribute like so:

<button aria-label="Bold" onClick={makeTextBold}>
  <MyIcon>
</button>

If you're not using the semantic button element, you need to assign the tabindex attribute (to make it tabbable) as well as the button role (to tell the screen reader that this is a button), see below:

<span
  aria-label="Bold"
  role="button"
  tabindex="0"
  onClick={makeTextBold}
>
  <MyIcon>
</span>

6. Use a linter with a11y support

To make it easier to stay on top of your apps accessibility, a linter can go a long way.

For react users, the a11y-jsx eslint plugin will make you aware of what attributes you're missing to make your web-app accessible. I cannot overstate how valuable this is especially for teams.

I recommend running your linter automatically (either as part of your CI or with a git hook).

7. Use an accessible component library

Using established component libraries will give you a leg-up on reaching a good accessibility baseline. Reach.ui, material ui and chakra are all react libraries that have decent accessibility defaults.

8. Think twice about whether you need collaborative editing

If your rich text editor has collaborative editing the content of a users document can change at the same time as you're editing it. The screen-reader needs to be notified that these updates occur, however these notifications must not be too noisy or distracting which can be a difficult balancing act.

Although there are no out of the box solutions for this, a good reference is googles "Live Edit's" feature, providing a list of edits made by other users.

Features such as this can be notoriously expensive to implement, test and maintain. My recommendation: Think twice about whether you actually need collaboration as part of your product before adding it to your roadmap.

9. Use a title attribute for iframes

Embedding content via iframes is a staple for rich text editors these days. To make this accessible for screen readers you should use the title attribute to describe what the iframe contains.

10. Always use the `textbox` role

Most frameworks (draft.js, slate.js and prosemirror as well as others) render this by default, but it's always good to double check this!

Any rich text editor using the contentEditable attribute (which is pretty much every rich text editor) needs to use the "textbox" role, to tell the screen-reader that it will respond to input and editing commands.

Thanks for reading, this article was originally posted on my website, for more content like this have a look and feel free to reach out on twitter too.

How to embed youtube videos in rich text documents with slate.js

Julian Krispel-Samsel — Tue, 13 Apr 2021 09:03:38 +0000

Embedding media such as youtube or vimeo links in a rich text document is a very common feature in rich text editors.

In this post I'll go through a pattern that I see used across projects, which is to render embedded media in iframes. In this case it's a youtube video, but it could really be anything, like a tweet for example.

The finished example is available here

Okay, let's get started ⬇️

1. Setup

At the time of writing, I'm using slate version ^0.59.

If you don't have a react app already, please use create-react-app (or something similar) to get started. I always include typescript for my projects but this is entirely optional.

npx create-react-app my-awesome-editor --template typescript
cd my-awesome-editor

Add the dependencies slate, slate-react and slate-history to your React app.

yarn add slate slate-react slate-history

Now let's add the boilerplate for your editor component, importing all the right dependencies and handling onChange events.

import React, { useMemo, useState } from "react";
import { createEditor, Node } from "slate";
import { withHistory } from "slate-history";
import { Editable, ReactEditor, Slate, withReact } from "slate-react";

export function MyEditor()  {
  const editor = useMemo(() => withHistory(withReact(createEditor())), [])
  const [value, setValue] = useState<Node[]>([
    {
      children: [{
        text: ""
      }],
    },
  ]);

  return <Slate editor={editor} onChange={setValue} value={value}>
    <Editable placeholder="Write something..."/>
  </Slate>
}

2. Add a slate element for youtube embeds

One of the three fundamental building blocks of a slate document are Block Elements. In their simplest form Block Elements are lines of text (or paragraphs), but they can also be non-text elements. All block elements are derived from this shape:

{
  children: [{
    text: ''
  }]
}

To create our youtube element we add our own properties to this element. Youtube videos have id's, so we add a videoId alongside a type for clarity.

{
  type: 'youtube',
  videoId: 'CvZjupLir-8',
  children: [{
    text: ''
  }]
}

Update your default slate value to include this block. Next, we'll tackle rendering this element ⬇

3. Rendering embeddable elements

In order to render the iframe we need to define the aptly named renderElement prop of slate's Editable component like this:

<Editable
  renderElement={({ attributes, element, children }) => {
    if (element.type === 'youtube' && element.videoId != null) {
      return <div
        {...attributes}
        contentEditable={false}
      >
        <iframe
          src={`https://www.youtube.com/embed/${element.videoId}`}
          aria-label="Youtube video"
          frameBorder="0"
        ></iframe>
        {children}
      </div>
    } else {
      return <p {...attributes}>{children}</p>
    }
  }}
/>

If you've followed the steps so far, you should now see a youtube embed appear in your editor. Let's break down what's happening with our renderElement method as shown above.

In our renderElement method we check if the type of element is 'youtube' and if it is, we render our iframe. We construct the iframe src attribute by concatenating youtube's embed url with with the video id.
Our renderElement callback must always render the children prop as well as the element attributes which can be spread over a html element (Otherwise slate.js will error when you try to interact with the element).
If the element type isn't 'youtube' the renderElement prop renders a paragraph by default. Slate will use the renderElement method to render every element in your document.
For non-text elements, we need to add contentEditable={false} to prevent the browser from adding a cursor to our content.
Don't forget to add an aria-label or a title attribute to your iframe, otherwise screen-readers will not be able to make sense of it.

4. Treat `'youtube'` blocks as voids

By default slate assumes that every element has editable text. This is not the case for our youtube block.

To make sure slate behaves appropriately we need to override the editor.isVoid method like so:

editor.isVoid = (el) =>  el.type === 'video'

For completeness, here's the entire useMemo callback producing the editor prop for the Slate component:

const editor = useMemo(() => {
  const _editor = withHistory(withReact(createEditor()))
  _editor.isVoid = (el) => el.type === 'youtube'
  return _editor
}, [])

Now we're rendering and handling this block correctly, but how does a user actually add a youtube block?

5. Inserting youtube blocks

To insert an element - we use slate's Transforms library, in particular, the insertNodes method:

Transforms.insertNodes([{
  type: 'youtube',
  videoId,
  children: [{
    text: ''
  }]
}])

However we still need the user interaction for input. Let's add an onPaste prop to our Editable component for this.

<Editable
  onPaste={(event) => {
    const pastedText = event.clipboardData?.getData('text')?.trim()
    const youtubeRegex = /^(?:(?:https?:)?\/\/)?(?:(?:www|m)\.)?(?:(?:youtube\.com|youtu.be))(?:\/(?:[\w\-]+\?v=|embed\/|v\/)?)([\w\-]+)(?:\S+)?$/
    const matches = pastedText.match(youtubeRegex)
    if (matches != null) {
      // the first regex match will contain the entire url,
      // the second will contain the first capture group which is our video id
      const [_, videoId] = matches
      event.preventDefault()
      Transforms.insertNodes(editor, [{
        type: 'youtube',
        videoId,
        children: [{
          text: ''
        }]
      }])
    }
  }}
  renderElement={...}
/>

Let's break this down:

First we retrieve the text we pasted:

const pastedText = event.clipboardData?.getData('text')?.trim()

To test if our pasted url is a youtube url and to capture the id from the url we use a regex. It's not pretty but I prefer examples with as few dependencies as possible. If you do want something easier to read, you could use libraries like get-youtube-id for this purpose.

If the regex matches we call event.preventDefault() to prevent the pasted text from being inserted as text. Instead we insert a slate element of type 'youtube' and with a video id. Now we can embed youtube videos in our document by simply pasting the link, anywhere.

That's it, I hope you enjoyed this tutorial. If you have questions or an idea of what you'd like me to cover in my next tutorial, reach out on twitter - I'm always happy to hear from the community!

FYI this article was first posted on my website -> https://jkrsp.com/slate-js-youtube-embeds/

Validate your cloud function with 1 line of code

Julian Krispel-Samsel — Sat, 14 Nov 2020 12:23:38 +0000

typescript-is is a library which enables type checks at run-time! This is an incredible tool to validate input and make your code more type-safe 🎉.

Validating the input of cloud functions can be a challenging problem. Re-using your types to ensure that your input matches your type solves a big part of the validation problem. To do this with the typescript-is library, the only thing you need to do is to use the assertType method that typescript-is exports:

// 2. Use the `assertType` method to perform your runtime check
assertType<MyEvent>(input)

Above we use assertType to check whether our runtime object input matches our type MyEvent. If it doesn't match the MyEvent type, an error is thrown. typescript-is has a bunch of other methods such as is or strictEqual. If you'd like to throw the error yourself you could do this for example:

if (!is<MyEvent>(input)) {
  throw new Error('input does not match type')
}

That's pretty much all it takes to add a run-time type check of your cloud functions input (provided you are a typescript user 🙃). Whereas previously you might have reached for validation libraries such as joi or god-forbid, written your own validator, it's now just one line of code. What are you going to do with all this new-found time?

Below is the entirety of an AWS lambda function handler with this pattern applied:

import { Handler } from 'aws-lambda'
import { assertType } from 'typescript-is';

type MyEvent = {
  msg: string
}

async function handler<Handler>(event: MyEvent) {
  assertType<MyEvent>(event)
  return { msg: 'Hello World' }
}

exports.handler = handler

🚀

For a fully working example of this pattern including deployment scripts for AWS and compilation with webpack please have a look at this boilerplate I've put together.

👍

Thanks for reading, this post was originally published on my website.

s3-auto-sync - watch a folder and automatically sync it with an s3 bucket 🎉

Julian Krispel-Samsel — Sun, 08 Nov 2020 17:25:50 +0000

So I wrote this little cli tool that lets you upload files to an s3 bucket, as changes happen.

All you need to do is install it:

npm install s3-auto-sync -g

And use it like so:

s3-auto-sync -b my-bucket -d ./my-folder -r eu-east-1

Make sure you set the region that you're in, otherwise performance will be slow.

That's it, practically your own little dropbox 🚀

The npm package is here: https://www.npmjs.com/package/s3-auto-sync
And the github repo is here: https://github.com/juliankrispel/s3-auto-sync

If you have any suggestions for features or improvements, by all means open an issue or a pr 🙌

How to write terraform, but with typescript

Julian Krispel-Samsel — Sun, 08 Nov 2020 11:57:46 +0000

Ever wished you could just use typescript to write your infrastructure? You may or may not have heard about the release of the terraform cdk (short for cloud development kit). It's HashiCorps answer to the aws cdk. In the words of the projects readme:

CDK (Cloud Development Kit) for Terraform allows developers to use familiar programming languages to define cloud infrastructure and provision it through HashiCorp Terraform.

Let's try this out shall we?

To get the full developer experience, make sure you have typescript support installed for your IDE

Generating the boilerplate

Let's open our terminal and install install cdktf-cli:

npm install -g cdktf-cli

Next we'll initialize the project

mkdir hello-cdktf
cd hello-cdktf
cdktf init --template="typescript" --local

Answer the two configuration questions and the project boilerplate will be generated.

Now we should see a main.ts file with the following contents in our folder:

import { Construct } from 'constructs';
import { App, TerraformStack } from 'cdktf';

class MyStack extends TerraformStack {
  constructor(scope: Construct, name: string) {
    super(scope, name);

    // define resources here

  }
}

const app = new App();
new MyStack(app, 'hello-cdktf2');
app.synth();

Adding a provider package and importing modules from it

After generation finishes you'll see a message in the console listing instructions of what to do next. To add the prebuilt aws provider (which also gives us all the modules and types that we might want).

npm install -a @cdktf/provider-aws

Now you can import modules from @cdktf/provider-aws such as AwsProvider and others. We'll go for the AwsProvider, LambdaFunction and IamRole. Add this at the top of your file:

import { AwsProvider, LambdaFunction, IamRole } from '@cdktf/provider-aws';

and then create an AwsProvider in your stack:

new AwsProvider(this, 'aws', {
  region: 'eu-west-2'
})

Adding a lambda function to our stack

To create a lambda we need to define an IAM role at first. Boring, but made easier by autocomplete of cours. Anyway here's the default policy:

const roleForLambda = new IamRole(this, 'iam-role-for-lambda', {
  name: 'iam-role-for-lambda',
  assumeRolePolicy: JSON.stringify({
    "Version": "2012-10-17",
    "Statement": [
      {
        "Action": "sts:AssumeRole",
        "Principal": {
          "Service": "lambda.amazonaws.com"
        },
        "Effect": "Allow"
      }
    ]
  })
})

Now we can add a lambda function to the stack like this:

new LambdaFunction(this, 'hello-world', {
  filename: process.cwd() + 'hello-world.zip'
  functionName: 'hello-world',
  handler: 'index.handler',
  runtime: 'nodejs12.x',
  role: roleForLambda.arn,
})

You will need to zip your lambda function - which is usually a separate step before running terraform. For example sake, let's say you have a file in your project named hello-world.js:

export const handler = async function () {
  return { hello: world }
}

Then zip your lambda zip -r lambda.zip hello-world.js

Deploying your stack

Before you deploy don't forget need to have your aws credentials in your path.

Now that you have everything ready you can deploy your stack with cdktf deploy. This command will display an execution plan and ask you if you want to deploy. Press the Y and Enter key to deploy.

Any errors at this stage should be farely self-explanatory. If they don't make sense, google the error message - other people have likely run into the same problem.

If you're a terraform user and you've used the lambda_function module before, you'll notice that the configuration is exactly the same.

Ultimately, when you run cdktf synth cdktf compiles your javascript/typescript modules into terraforms alternative JSON configuration syntax.

This is an extremely powerful feature of terraform's design since it can be a compile target not just for javascript and typescript, but any kind of language. The open source community could add it's own language compilers.

Why not write one in rust? 😅

PS: The original version of this post was published on my website, if you liked this post, please consider having a look around.

Environments per pull-request with github actions and terraform

Julian Krispel-Samsel — Sat, 07 Nov 2020 17:11:28 +0000

Using Github Actions and terraform - this post will guide you through automating the lifecycle of per pull request environments on github.

As a sidenote, short-lived environments go by many names, some of these are: feature environments, ephemeral environments, review apps, on demand environments or temporary environments.

What are short lived environments?

Say you're on a team that works on multiple features simultaneously. There is a need to share the work with colleagues in Engineering, Product, Design or QA to collaborate, test and review. That's where short lived environments come in. Their lifecycle is tied to that of the project.

Why Infrastructure as Code?

Although terraform is my weapon of choice (material for an entirely new blogpost), there are plenty other tools out there (such as pulumi or cloudformation 😬).

The fact of the matter is - you should use IAC tools to maintain your sanity and this is especially true when it comes to managing short lived environments.

Although in this tutorial I am just provisioning an S3 bucket with terraform (for my blog), the same concepts can easily be mapped to any resources that terraform has modules for and there are plenty.

Pre-requisities

if you don't already have one yet, create an aws account.
make sure you add your aws credentials AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to your github repository secrets.

Github Actions to control the lifecycle of short lived environments.

We'll create 2 github actions to manage our environments. Github actions are basically YAML files that are located in .github/workflows/.

create_and_update_pr_env.yml - When a pull request is opened or updated, we want to create/update our infrastructure. terraform apply does both of that, simple!
destroy_pr_env.yml - When the pull request is closed, we need to destroy the environment to make sure we're not wasting resources (if we don't our AWS bill will be one nasty surprise).

Defining the infrastructure with terraform

For this tutorial, we're using the terraform configuration for this blog. At the time of writing, here's how this looks like:


provider "aws" {
  region = "eu-west-2"
}

terraform {
  backend "s3" {
    // make sure you'll replace the above
    // with a bucket name that fits
    bucket = "jkrsp-tf-state"
    region = "eu-west-2"
  }
}

variable "env_prefix" { }
variable "is_temp_env" {
  default = false
}

Wouldn't it be awesome if everyone got access to aws playground so we can get people involved and potentially excited about it 🎉

As you can see, we're using s3 as our terraform backend. We're also defining two variables here env_prefix and is_temp_env. Next up you can see the only resource defined for this website, which is the we use for hosting the blog. The env_prefix variable is what we use to specify our environment-specific resource so we can avoid naming collisions.

is_temp_env is there to differentiate between production and a temporary environments. For temporary environments, we want to set force_destroy to true, so that we can easily destroy a bucket resource via terraform. If this is set to false, destroying the bucket will fail unless it is empty (which is exactly the kind of safety we want for production but not for a temporary environment)

resource "aws_s3_bucket" "b" {
  bucket = "${var.env_prefix}jkrsp.com"
  acl    = "public-read"
  force_destroy = var.is_temp_env

  policy = <<POLICY
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::${var.env_prefix}jkrsp.com/*"
    }
  ]
}
  POLICY

  website {
    index_document = "index.html"
  }

  tags = {
    ManagedBy = "terraform"
  }
}

At last, we're using an output variable to feed the url for our bucket website back to our github action, we'll use this later to display a link in the pr.

output "website" {
  value = "http://${aws_s3_bucket.b.website_endpoint}"
}

Now that we have a basic terraform setup, let's create our actions...

Creating/updating an environment when a PR is opened

First let's create a an action yml file .github/workflows/create_and_update_pr_env.yml with the following contents:

on:
  pull_request:
    types: [reopened, opened, synchronize, edited]

This block defines which events trigger the action (there's a more comprehensive list on help.github.com), in this instance the action gets triggered when a pull request has been opened, reopened, synchronized or edited.

Next we'll define the name of the action, the image being used for the action and the environment variables:

name: Create PR Env
jobs:
  create_or_update_pr_env:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      BRANCH_NAME: ${{ github.head_ref }}
    steps:
      - ....

Github actions not unlike other CI tools are containerized - ubuntu-latest is our choice container image for this action. We've defined 3 variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY we need for deploying to AWS via terraform. Terraform will automatically pick those up. We'll use the BRANCH_NAME env variable as a prefix for naming our temporary environment.

We're using github actions context variables here, namely - secrets and github. Obviously the secrets variable refers to the github repo's secrets for your AWS secrets.

Next let's look at the actual steps:

First the build steps:

- name: Checkout
  uses: actions/checkout@v1
- name: Install Dependencies
  run: yarn
- name: Checkout
  uses: actions/checkout@v1
- name: Install Dependencies
  run: yarn
- name: Build Site
  run: yarn build

This is fairly standard, you'll always want to checkout your repository as a first step and install your dependencies. In this case I'm building a gatsby site, but this could just as well be any other app with a build step.

Once the site is built, we use terraform to orchestrate our deployment. Hashicorps' github actions for terraform let you easily add any terraform command as a step. For this action, we'll use 4 commands: init, plan, apply and output.

The trick to achieving environments per pull request is to have different state files per environment as well as different names for resources. This is where the BRANCH_NAME variable comes in.

When initializing terraform we can pass in a key for an s3 bucket specific to this environment, pay attention to the args parameter to see how we achieve this by prefixing our key config with the BRANCH_NAME variable.

- name: 'Terraform Init'
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'init'
    args: '-backend-config="key=${{ env.BRANCH_NAME }}.jkrsp.com.tfstate"'

Next we use terraform plan and pass in the BRANCH_NAME as a variable to parameterize our terraform config. Note that I also pass in a variable called is_temp_env - this I do because we want our temporary s3 resource to be deletable. Once we used plan we can follow up with apply.

- name: Terraform Plan
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'plan'
    args: '-var="is_temp_env=true" -var="env_prefix=${{ env.BRANCH_NAME }}." -out tf.plan'
- name: Terraform Apply
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'apply'
    args: 'tf.plan'

Next we use output to extract the website url of our s3 bucket. We'll come back to this in a bit, when we post the url of the temporary website as a comment on our pr. To output a single value we add our desired field name to args.

- name: Terraform Output
  id: terraform
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'output'
    args: 'website'

Next we deploy our build to our s3 bucket via the cli. Again, we use our BRANCH_NAME env variable to specify the bucket or the environment.

- name: sync to s3
  run: aws s3 sync public s3://${{ env.BRANCH_NAME }}.jkrsp.com

As a final step in our action, I'm using a little JavaScript program to add a comment to the pr including the website.

- run: node .github/actions/comment.js
  env:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    issue_number: ${{ github.event.pull_request.number }}
    repo: 'jkrsp'
    owner: ${{ github.repository_owner }}
    website_link: ${{ steps.terraform.outputs.tf_actions_output }}

The comment.js file is located in .github/actions/comment.js and looks like this:

As you can see passing in the parameters above will give the script all the variables it needs to post a comment.

const github = require('@actions/github');

async function run() {
  const { issue_number, github_token, owner, repo, website_link } = process.env

  const octokit = new github.GitHub(github_token);

  try {
    const { data } = await octokit.issues.createComment({
      owner,
      repo,
      issue_number,
      // We unfortunately need to use replace to get rid
      // of extraneous double quotes
      body: `[Review website here](${website_link.replace(/"/gs, '')})`
    });

    // for debugging, lets log the created comment
    console.log('created comment', data);
  } catch (err) {
    throw err
  }
}

run();

That's it. Having added this to your github repository should create your environment and display a link to the bucket website when you open a pr.

But how do we get rid of the environment once we're done reviewing and the pr is closed/merged?

That's where our second action comes in:

Destroying a short lived environment

First lets start of with the block that defines for which events our action gets triggered

on:
  pull_request:
    types: [closed]

Pretty self explanatory: This action gets triggered when a pull request has been closed.

Next up, like before - we name the action and the job and define our environment variables:

name: Destroy PR Env
jobs:
  destroy_pr_env:
    runs-on: ubuntu-latest
    env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      BRANCH_NAME: ${{ github.head_ref }}

Now to the steps. First we need to check out our repo again:

- name: Checkout
  uses: actions/checkout@v1
  with:
    ref: ${{ github.head_ref }}

Then we start initializing terraform, again we use the BRANCH_NAME to specify the bucket for our environment

- name: 'Terraform Init'
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'init'
    args: '-backend-config="key=${{ env.BRANCH_NAME }}.jkrsp.com.tfstate"'

Next we destroy the environment, passing in two variables - is_temp_env and env_prefix

- name: 'Terraform Destroy'
  uses: hashicorp/terraform-github-actions@master
  with:
    tf_actions_version: 0.12.13
    tf_actions_subcommand: 'destroy'
    args: '-var="is_temp_env=true" -var="env_prefix=${{ env.BRANCH_NAME }}."'

Finally, we comment on our pr again, to tell our colleagues that the environment has definitely been destroyed. Note how we pass in secrets.GITHUB_TOKEN - we need this token for any interaction with the github api.

- name: Tell PR that we have destroyed the thing
  uses: thollander/actions-comment-pull-request@master
  with:
    message: 'Temporary environment now destroyed'
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Right that's it. If you'd like to check out the workflows described in this blog post, please have a look a the repository for this blog.

The original version of this blog post is here.

✎ - Zettel - A library for building editors

Julian Krispel-Samsel — Fri, 18 Oct 2019 09:18:47 +0000

👋 Howdy DEV community!!!

I'm working on this library I call Zettel for building editors with React. So here you go.

Currently working on a pre-release, something that people can use in their apps, something that's documented and well tested.

The github repo is full of examples, the examples are also hosted on gh-pages, check it out and reach out if you like!

I've just created a slack channel for Zettel, here's the invite link

zettel.software