DEV Community: Lewis Lloyd

Adding Vitest to Nuxt 3 ⚡ (2023)

Lewis Lloyd — Sun, 01 Jan 2023 23:43:38 +0000

Introduction

In this post, we'll introduce Vitest for blazing-fast unit tests in your Nuxt 3 project.

Testing

Unit tests are important for ensuring that your code is working correctly.

This is especially important when making changes to your code, as you can ensure that you haven't introduced any new bugs or problems to existing features. Or, at least to the extent that these features have been covered by tests.

Vitest

Vitest is a test runner based on Vite, an alternative module bundler to webpack which Nuxt 3 uses by default.

It's incredibly similar to Jest, and often considered a drop-in replacement for it.

Installation

Packages

Install the following dependencies:

# Vitest
yarn add --dev vitest jsdom @vitejs/plugin-vue

# Test utils
yarn add --dev @vue/test-utils @nuxt/test-utils

Configuration

Create your Vitest configuration file (vitest.config.js):

// vitest.config.js

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  test: {
    globals: true,
    environment: 'jsdom',
  },
})

ESLint integration

If you're using ESLint from earlier in the series, you should also add its Vitest plugin:

yarn add --dev eslint-plugin-vitest

Then, modify your .eslintrc.cjs file to add the plugin:

// .eslintrc.cjs

module.exports = {
  // ...
  plugins: ['vitest'],
  // ...
}

Scripts

Add the following script to your project:

// package.json

{
  // ...
  "scripts": {
    // ...
    "test": "vitest"
    // ...
  }
  // ...
}

Usage

Creating tests

At this point, you should use a learning resource such as Testing with Vitest to get started.

A test may look something like this:

// tests/HelloWorld.spec.ts
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'

import HelloWorld from '../components/HelloWorld.vue'

describe('HelloWorld', () => {
  it('is a Vue instance', () => {
    const wrapper = mount(HelloWorld)
    expect(wrapper.vm).toBeTruthy()
  })
})

Running tests

To run your unit tests, use yarn test.

$ yarn test

>>> yarn run v1.22.5
>>> $ vitest
>>>
>>>  DEV  v0.26.3 ~/Documents/GitHub/nuxt-app
>>>
>>>  ✓ tests/HelloWorld.spec.ts (1)
>>>
>>>  Test Files  1 passed (1)
>>>       Tests  1 passed (1)
>>>    Start at  23:19:54
>>>    Duration  1.78s (transform 538ms, setup 1ms, collect 154ms, tests 20ms)
>>>
>>>
>>>  PASS  Waiting for file changes...
>>>        press h to show help, press q to quit

All done!

Now you can start shipping new features in peace 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

Website: https://lloyd.cx/
Twitter: https://twitter.com/lloydtao/
GitHub: https://github.com/lloydtao/
LinkedIn: https://www.linkedin.com/in/lloydtao/

Adding Pinia to Nuxt 3 🍍 (2023)

Lewis Lloyd — Sun, 01 Jan 2023 23:42:55 +0000

Introduction

In this post, we'll introduce Pinia, a powerful package for managing your Nuxt app's state in a single place.

Whether you're new to state management solutions or experienced with libraries such as Vuex and Redux, Pinia is definitely worth checking out.

State management

If you've ever found yourself aimlessly trying to manage state through props and events, then the idea of a store may sound appealing:

Manage an app's state from a single, centralised store
Update and retrieve data through simple actions and getters
Subscribe to changes to achieve deep reactivity without much work

This helps to make changes to the app's state predictable and more consistent.

For example, we can store a counter, and then increment it from anywhere by using its store:

Pinia

Pinia is a state management library for Vue, with an officially-supported module for Nuxt 3 (@pinia/nuxt). It's also the recommended solution for Vue and Nuxt projects.

Don't just take it from me:

"Pinia is de facto Vuex 5!"

— Evan You, creator of Vue (source)

What makes it useful for Vue and Nuxt applications?

Deep reactivity by default
No explicit mutations (all changes are implicit mutations)
Analogous with Options API:
- Actions (equivalent of methods)
- Getters (equivalent of computed)

Installation

Official documentation for using Pinia with Nuxt can be found here.

Install the package:



yarn add @pinia/nuxt

Add the module to your Nuxt configuration:



// nuxt.config.ts

export default defineNuxtConfig({
  // ...
  modules: [
    // ...
    '@pinia/nuxt',
  ],
})

Creating a store

Stores are created in a stores/ directory, and defined by using Pinia's defineStore method.

In this example, we have created a store (useCounterStore) and given the store a name (counter). We have then defined our state property (count) with an initial value.



// stores/counter.ts

import { defineStore } from 'pinia'

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
})

It's as simple as that!

Using the store

Pinia offers a few ways to access the store and maintain reactivity.

1. Store instance

In your component's setup(), import the store's useStore() method.



// components/MyCounter.vue

import { useCounterStore } from '@/stores/counter'

export default defineComponent({
  setup() {
    return {
      store: useCounterStore(),
    }
  },
})

You can now access state through the store instance:



// components/MyCounter.vue

<template>
  <p>Counter: {{ store.count }}</p>
</template>

2. Computed properties

To write cleaner code, you may wish to grab specific properties. However, destructuring the store will break reactivity.

Instead, we can use a computed property to achieve reactivity:



// components/MyCounter.vue

export default defineComponent({
  setup() {
    const store = useCounterStore()

    // ❌ Bad (unreactive):
    const { count } = store

    // ✔️ Good:
    const count = computed(() => store.count)

    return { count }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ store.count }}</p>
</template>

3. Extract via storeToRefs()

You can destructure properties from the store while keeping reactivity through the use of storeToRefs().

This will create a ref for each reactive property.



// components/MyCounter.vue
import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/stores/counter'

export default defineComponent({
  setup() {
    const store = useCounterStore()

    // ❌ Bad (unreactive):
    const { count } = store

    // ✔️ Good:
    const { count } = storeToRefs(store)

    return { count }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ store.count }}</p>
</template>

Actions

Adding an action

Actions are the equivalent of methods in components, defined in the store's actions property.



// stores/counter.ts

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  actions: {
    increment() {
      this.count++
    },
  },
})

Using an action

In your component, extract the action from the store.



// components/MyCounter.vue

export default defineComponent({
  setup() {
    const store = useCounterStore()
    const { increment } = store
    const count = computed(() => store.count)
    return { increment, count }
  },
})

The action can easily be invoked, such as upon a button being clicked:



// components/MyCounter.vue

<template>
  <button type="button" @click="increment"></button>
</template>

Getters

Getters are the equivalent of computed in components, defined in the store's getters property.

Adding a getter

Pinia encourages the usage of the arrow function, using the state as the first parameter:



// stores/counter.ts

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
  }),
  getters: {
    getCount: (state) => state.count,
  },
  actions: {
    increment() {
      this.count++
    },
  },
})

Using a getter

Similarly to state properties, getters need to be accessed in a way that maintains reactivity.

For instance, you could access it through the store instance:



// components/MyCounter.vue

export default defineComponent({
  setup() {
    const store = useCounterStore()
    return { store }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ store.getCount }}</p>
</template>

Or, by using a computed property:



// components/MyCounter.vue

export default defineComponent({
  setup() {
    const store = useCounterStore()

    // ❌ Bad (unreactive):
    const { getCount } = store

    // ✔️ Good:
    const getCount = computed(() => store.getCount)

    return { getCount }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ getCount }}</p>
</template>

Or, by using storeToRefs():



// components/MyCounter.vue
import { storeToRefs } from 'pinia'
import { useCounterStore } from '@/stores/counter'

export default defineComponent({
  setup() {
    const store = useCounterStore()

    // ❌ Bad (unreactive):
    const { getCount } = store

    // ✔️ Good:
    const { getCount } = storeToRefs(store)

    return { getCount }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ getCount }}</p>
</template>

A complete component

Since we've discussed actions and getters separately, here is a code snippet that combines both in the style that I recommend:



// components/MyCounter.vue

import { useCounterStore } from '@/stores/counter'

export default defineComponent({
  setup() {
    const store = useCounterStore()
    const getCount = computed(() => store.getCount)
    const { increment } = store
    return { getCount, increment }
  },
})



// components/MyCounter.vue

<template>
  <p>Counter: {{ getCount }}</p>
  <button type="button" @click="increment">Increment</button>
</template>

This code has been implemented at lloydtao/nuxt-3-starter/:

How do you think your developer experience will be improved? 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

Website: https://lloyd.cx/
Twitter: https://twitter.com/lloydtao/
GitHub: https://github.com/lloydtao/
LinkedIn: https://www.linkedin.com/in/lloydtao/

Adding Tailwind CSS to Nuxt 3 🍃 (2023)

Lewis Lloyd — Sun, 01 Jan 2023 23:42:01 +0000

Introduction

In this post, we'll introduce Nuxt Tailwind, a package for the Tailwind CSS library.

Tailwind is a powerful tool for rapidly styling modern web applications.

Utility-first CSS

Utility-first CSS is a design approach that uses pre-defined classes to style HTML elements. We refer to these classes as utilities.

One of the main advantages of utility-first CSS is that it allows you to style elements quickly without coupling them to custom CSS through stylesheets. This approach can be difficult to maintain when an app grows bigger.

You may argue that this will lead to code repetition, but when combined with component-based web frameworks (e.g. React, Vue), repetition is minimised while still keeping elements decoupled from stylesheets.

Tailwind

Tailwind isn't just a fantastic way of writing CSS; it's also great to build with, due to a variety of development features:

Easy configuration of built-in utilities
Just-in-time compiler to avoid build times entirely
Many great plugins available (typography, forms, etc.)

Installation

Official documentation for using Tailwind with Nuxt can be found here.

Install the package:

yarn add --dev @nuxtjs/tailwindcss

Add the module to your Nuxt configuration:

// nuxt.config.ts

export default defineNuxtConfig({
  // ...
  modules: [
    // ...
    '@nuxtjs/tailwindcss',
  ],
})

And just like that, you can now start adding Tailwind classes to your Nuxt components!

Classes

To get started, add some of Tailwind's in-built utilities to an element's class attribute.

<template>
  <NuxtLink
    to="/"
    class="font-semibold text-gray-50 hover:text-gray-400 duration-100"
  >
    Home
  </NuxtLink>
</template>

New to Tailwind? Your best bet is to check out the Tailwind docs.

Configuration

Create a tailwind.config.js file at the root of your project to configure the default theme.

module.exports = {
  theme: {
    screens: {
      sm: '640px',
      md: '768px',
      lg: '1024px',
      xl: '1280px',
    },
    extend: {
      colors: {
        linkedin: {
          primary: '#0A66C2',
          lighter: '#378fe9',
          darker: '#004182',
        },
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
}

Viewer

Nuxt Tailwind exposes a /_tailwind/ route in development where your Tailwind configuration is rendered as a library.

May your web apps become colourful and flashy 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

Website: https://lloyd.cx/
Twitter: https://twitter.com/lloydtao/
GitHub: https://github.com/lloydtao/
LinkedIn: https://www.linkedin.com/in/lloydtao/

Adding ESLint and Prettier to Nuxt 3 ✨ (2024)

Lewis Lloyd — Sun, 01 Jan 2023 23:37:40 +0000

🎉 Update (April 2024): This tutorial now uses the @nuxt/eslint module.

Introduction

In this post, we'll introduce ESLint and Prettier for automatic code style formatting in your Nuxt 3 project.

ESLint is a linter that helps to enforce code quality through standards and patterns, such as flagging unused variables, disallowing globals, and requiring Error objects as Promise rejection reasons.
Prettier is a formatter that helps in tidying up documents, such as maximum line length, mixed spaces and tabs, keyword spacing, and comma style.

By using these tools together, we can spend more of our development time on our actual code, instead of nitpicking a file's indenting, casing and bracket placement.

Installation

Packages

Install the following dependencies:

# ESLint
yarn add --dev @nuxt/eslint eslint typescript

# Prettier
yarn add --dev eslint-plugin-prettier eslint-config-prettier prettier

Configuration

Add the @nuxt/eslint module to your Nuxt configuration:

// nuxt.config.ts

export default defineNuxtConfig({
  devtools: { enabled: true },
  modules: [
    // ...
    '@nuxt/eslint',
    // ...
  ],
})

Run yarn dev to generate an initial ESLint configuration file (eslint.config.mjs), which will look like this:

// eslint.config.mjs

import withNuxt from './.nuxt/eslint.config.mjs'

export default withNuxt()

If you already have a flat configuration file for ESLint that you would like to use, it can be passed as an argument to withNuxt().
You can explore more configuration options here: https://eslint.nuxt.com/packages/module

Scripts

Add the following scripts to your package.json file:

// package.json

{
  "scripts": {
    // ...
    "lint": "yarn lint:eslint && yarn lint:prettier",
    "lint:eslint": "eslint .",
    "lint:prettier": "prettier . --check",
    "lintfix": "eslint . --fix && prettier --write --list-different ."
    // ...
  }
}

Usage

To check for errors, use yarn lint. This won't effect any changes, and may be useful in a code review or CI pipeline.

$ yarn lint

>>> yarn run v1.22.5
>>> $ yarn lint:eslint && yarn lint:prettier
>>> $ eslint .
>>> $ prettier . --check
>>> Checking formatting...
>>> [warn] app.vue
>>> [warn] Code style issues found in the above file. Run Prettier to fix.
>>> error Command failed with exit code 1.
>>> info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
>>> error Command failed with exit code 1.
>>> info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

To fix errors, use yarn lintfix. This will save any formatting changes.

$ yarn lintfix

>>> yarn run v1.22.5
>>> $ prettier --write --list-different . && eslint . --fix
>>> app.vue
>>> Done in 2.59s.

After using yarn lintfix, invoking yarn lint should be successful.

$ yarn lint

>>> yarn run v1.22.5
>>> $ yarn lint:eslint && yarn lint:prettier
>>> $ eslint .
>>> $ prettier . --check
>>> Checking formatting...
>>> All matched files use Prettier code style!
>>> Done in 3.07s.

All done!

You can hopefully now avoid the nitpicking arguments 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

Website: https://lloyd.cx/
Twitter: https://twitter.com/lloydtao/
GitHub: https://github.com/lloydtao/
LinkedIn: https://www.linkedin.com/in/lloydtao/

Why do we love server-side rendering again? 🤯

Lewis Lloyd — Wed, 28 Dec 2022 13:44:26 +0000

Why is everybody talking about server-side rendering again?

In order to understand the current trends, let’s have a look at the history of rendering on the web.

History of web rendering

2000 - 2012

From 2000 to 2012, if you were interacting with a feature-rich web page, it was almost certainly dynamically rendered by a backend web server. The page would then be served to the client as a static HTML file.

Backend market share was dominated by PHP (1995) and Ruby (1996), with other contenders such as ASP.NET (2002) and Spring (2003) joining the scene over the years.

2012 - 2020

The following decade saw the prominent rise of the single-page application (SPA).

This method involves rendering HTML in the user's browser, aiming to provide a desktop-like experience. Popular SPA frameworks include AngularJS (2010), React (2013), Vue.js (2014) and Angular 2+ (2016).

Features such as JavaScript-based routing could control and maintain state across pages, though it had the downside of long initial load times and poor SEO. Performance issues were also prevalent due to the heavy nature of SPAs, especially on lighter clients such as mobile phones.

Even with the trade-offs, the SPA was beloved and adopted by stakeholders and developers alike, and marked a historic switch to client-side rendering (CSR).

This effectively popularised the term “server-side rendering”, which had never seen mainstream usage as there was no need to differentiate it from CSR.

The return of SSR

These developments in web rendering posed a key question:

Can we utilise the fast initial load times of SSR while keeping the interactivity and dynamicity of SPAs, all while keeping the application lightweight?

Client-side hydration

The current best practise is to serve a pre-rendered page to the client, and then add application state and interactivity through a process called hydration.

Since the page is initially rendered by the server, it benefits from a quick load time, and takes rendering load off of the client. In the hydration process, a JavaScript bundle will attach event listeners to the DOM and make it fully interactive. This bundle is comparatively small compared to an SPA, which further keeps the app light and performant.

React and Vue each have an SSR counterpart, known as Next.js (2016) and Nuxt.js (2016) respectively. The popularity of these tools began to rise in 2020.

Static site generation

If we restrict all dynamicity to hydrated components, we can take SSR a step further and pre-render the entire application. This is known as static site generation (SSG), and often used in JAMStack applications.

Advanced SSG tools may even collect and transform data as they build the application (e.g. Markdown, CSV, JSON). This makes it useful for content that changes infrequently, such as blogs and documentation, as further API calls do not need to be made by the client.

All-in-all, this removes the need for a web server. The files can be shipped to any static hosting provider (e.g. Amazon S3, GitHub Pages) and served through a CDN to benefit from even lower latency and load times.

The horseshoe

In summary, web rendering has jumped from fully server-side (~1995 to 2010) to fully client-side rendered (~2010 to 2016), and then settled somewhere around mainly server-side rendered with client-side rendering for interactivity (~2016 onwards).

So, while it has not necessarily fully horseshoed back to server-side rendering, we’ve definitely taken a tremendous leap in each direction.

Which other technologies do you think could make a comeback? 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

Website: https://lloyd.cx/
Twitter: https://twitter.com/lloydtao/
GitHub: https://github.com/lloydtao/
LinkedIn: https://www.linkedin.com/in/lloydtao/

1. Two Sum

Lewis Lloyd — Mon, 24 Oct 2022 13:32:08 +0000

Python

Solution walkthrough: https://twitter.com/lloydtao/status/1584288569622790145

🥇 Hash table - O(n)

Method: Take each number and check if its complement has been seen before. If not, add it to the list of known complements along with its index.

Time complexity: O(n)
Space complexity: O(n)

class Solution:
    def twoSum(self, nums: List[int], target: int) -> List[int]:
        """Take each number and check if its complement has been seen before. If not,
        add it to the list of known complements along with its index.

        Args:
            nums (List[int]): Input array of integers
            target (int): Target integer

        Returns:
            List[int]: Indices of the two integers that sum to target
        """
        # Initialise hash map to store known integers
        complements = {}
        # Iterate through the list
        for i in range(len(nums)):
            # Check if the current number's complement has been seen before
            complement = target - nums[i]
            if complement in complements:
                return [complements[complement], i]
            # Add the current number to the list of known complements
            complements[nums[i]] = i

🥈 Check pairs - O(n²)

Method: Take each pair of numbers and see if they add up to the target.

Time complexity: O(n²)
Space complexity: O(1)

class Solution:
    def twoSum(self, nums: List[int], target: int) -> List[int]:
        """Take each pair of numbers and see if they add up to the target.

        Args:
            nums (List[int]): Input array of integers
            target (int): Target integer

        Returns:
            List[int]: Indices of the two integers that sum to target
        """
        # Get length of input array
        n = len(nums)
        # Iterate over all pairs (i,j)
        for i in range(n):
            for j in range(i + 1, n):
                # Check if this pair equals the target
                if nums[i] + nums[j] == target:
                    return [i, j]

KeepChat - Managed Chat API with Adaptive Hate Speech Filtering

Lewis Lloyd — Tue, 09 Aug 2022 01:27:00 +0000

Project

KeepChat is an in-game chat service with superpowers, making the chat space friendly for everyone. Our vision is to keep chat safe and inclusive, without requiring constant attention from moderators.

At a high level, KeepChat consists of a three-tier architecture.

At the core of the system is the chat API, which handles the business logic of the chat rooms. This includes storing messages, processing new messages from users, and processing flags.

When a new message is processed, the chat API asks the training and screening API whether the message should be filtered. The AI responds with a True or False, and the backend will filter the message accordingly before storing it.

When a flag is processed, the chat API tells the AI to add the flagged message to its bank of harmful messages, and then re-train on this data. We envision expanding on this by requiring a certain number of flags or total user sociability score in order to add the message to the training data.

In order to demonstrate this functionality, a frontend consumer application communicates with the backend by using its chat endpoints.

This demonstrates the plug-and-play nature of the application; integrating KeepChat into an existing application is incredibly simple, as screening messages and re-training on flagged messages is built-in to the service.

Teamwork

By splitting the project into the architecture mentioned prior, we were able to divide our team effectively. This involved giving individual team members ownership over some part of the system, and then exposing each part through a REST API, which kept the system loosely coupled.

The end result was a high development velocity within the team.

We leveraged Git and GitHub in order to distribute code between team members. It's important to prevent code-breaking changes from being pushed in a time-critical project, as these can block an entire team while the bug is fixed.

Therefore, any code changes went through a pull request, and we leveraged GitHub Actions in order to run quick code quality checks before accepting a PR.

Results

We didn't bring home the bacon this time. Interestingly, the winner of our challenge also built a chat service with adaptive filtering, including the ability to re-train on reported messages.

However, they managed to deploy their system to Google Cloud Platform, and provided a link to use their application. Considering the product-focused nature of the hackathon, we should have aimed to put our application online.

Results aside, I would definitely call this weekend a success. We managed to effectively execute on an identical product scope to the challenge winners, which validates our project on both the technical and product level.

Go KeepChat!

Increasing Pull Request Velocity with Acceptance Criteria

Lewis Lloyd — Thu, 07 Oct 2021 14:59:12 +0000

Pull requests

In software engineering, a pull request is the process in which a contributor asks a repository owner to merge their changes into the main codebase.

The PR is important, as it acts as a crucial safety buffer when developing software. It gives a chance for both manual validation (e.g. code reviews) and automatic checks (e.g. unit tests) to take place, as well as discussions between the repository's maintainers.

Once the code has been approved, it can be assumed safe to merge in, and will eventually become part of the next release.

This safeguard should result in the main branch of code remaining in a production-ready state, all of the time.

Reviewing a PR

When looking at a pull request, the reviewer is addressing two concerns:

Is the code of a high quality?
Does this implementation satisfy the feature's requirements?

The first criterium is, for the most part, a matter of opinion. We can attempt to standardise code quality through the use of linters and code coverage tools, but the final say falls to the reviewer.

The second is much more significant. A failure to meet requirements may result in a bad product, which affects the user experience. In the interest of business objectives, this is something that we absolutely need to minimise.

For distributed software teams, this poses a unique challenge.

A lack of context

Typically, the reviewer of a pull request will not have had any involvement in the specification, design or implementation of the feature.

As a matter of fact, software teams may find it beneficial for the reviewer to be completely out-of-the-loop. Their opinion is more likely to be unbiased if they haven't contributed to the delivery of the work item.

This creates a problem. The reviewer needs to know what they're looking for, but they don't have much information. If they approve of an unsatisfactory implementation, is it really fair to blame them? The responsibility should clearly be elsewhere.

Context of what the implementation is needs to be communicated, so that a reviewer can conduct an unbiased review yet remain an effective gatekeeper.

Acceptance criteria

In our team, we have found success in writing manual acceptance criteria.

This is a formalised checklist, verified by a human, which is marked alongside a code review.

The checklist contains unambiguous steps to follow. This includes any required test data, as well as the expected result of the test.

Why has this been effective?

We can test the feature with much more clarity on which behaviours we're testing. This results in faster reviews.
We have certainty that satisfying the acceptance criteria will satisfy the work item's requirements. Unsatisfactory code is less likely to be released.
The responsibility of identifying (but not testing) behaviours falls on the contributor, who has the most context on what is being implemented.

Screenshots

For the sake of visibility, I like to supplement the review with screenshots at each test.

After all, the success of the review ties into the success of the implementation. So, the contributor may appreciate seeing their hard work validated!

Weaknesses

It's a good time to note that acceptance criteria aren't a fool-proof solution to code validation.

There is a requirement for the contributor to write a sensible checklist. This means covering the full scope of the feature, including edge cases, without having such a volume of tests that checking them becomes a laborious process.

Therefore, you should still endeavour to validate all behaviours of your code through unit and integration tests. The acceptance criteria can be thought of as the formalisation of a separate, equally-important process, and not as a replacement.

Work smarter, not harder. 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

DEV: https://dev.to/tao/
Twitter: https://twitter.com/LloydTao
GitHub: https://github.com/LloydTao
LinkedIn: https://www.linkedin.com/in/LloydTao/

Catch you around!

Design Validation

Lewis Lloyd — Mon, 03 May 2021 01:26:02 +0000

Introduction

Software teams have a broad range of skill levels.

This can be due to familiarity with the tools, a push for mentorship from engineering managers, or just general software engineering .

In short, we shouldn't expect, nor assume, a level playing field across the team.

In the journey to give team members independence, you may find running out-of-scope in implementation.

This can lead to a range of issues, including undesired functionality and conflict with other work items. Product owners put a lot of effort into keeping the backlog well-defined, and we need to stick to what's required!

Further, these issues will almost always be identified after implementation, when time and development costs have already been spent.

We need a way to keep our team members on the right path, while still promoting autonomy through asynchronous development practises.

Enriching the Agile Lifecycle

I've found that a good solution is the inclusion of just a single, extra step in the agile process.

You're probably familiar with the design document. Before implementation starts, the developer whips up an outline of how they intend for the work item to be to completed.

This is nicely expanded upon by reqexperts.com:

The Design Specification should state how the design will meet the requirements. Design is not a one-to-one response to requirements. Design requires discipline knowledge and integration of disciplines in most cases.

At this stage, a senior team member can approve of the documented strategy, before a week or two is spent on the implementation.

More often than not, a quick read will result in an all-clear. However, if there's an issue, then specific changes can be requested.

Of course, your organisation may implement agile in a different way.

What's valuable is the core idea of documenting and validating a feature's design before its implementation.

I've provided the template that I use, and an example of a completed document.

The Junior Agile Lifecycle

We've now identified this extra step.

Using this, we can outline our junior-friendly agile lifecycle.

Concept: Stakeholder discusses feature request with Product Owner.
Requirements: Product Owner documents feature requirements, and adds work item to backlog.
Design: Developer picks up work item, and documents their implementation strategy.
Design validation: Design document is reviewed and approved by Senior Developer.
Implementation: Developer implements work item based on documented design.
Evaluation: Feature branch is reviewed, tested and merged.

Hopefully, this results in a great, cohesive team!

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

DEV: https://dev.to/tao/
Twitter: https://twitter.com/LloydTao
GitHub: https://github.com/LloydTao
LinkedIn: https://www.linkedin.com/in/LloydTao/

Host React/Vue with Continuous Deployment, for Free!

Lewis Lloyd — Wed, 12 Aug 2020 21:36:13 +0000

Introduction

Have you ever built web applications that you’d love to show off online, but don’t want to spend hours configuring and deploying it?

Do you have a blog, splash page or series of portfolio showcase projects, but don’t want to pay money to host them for display?

This guide will show you fully-featured web projects, for free!

Here’s the solution.

I’ve created a collection of template repositories on GitHub that makes hosting and continuously deploying React and Vue projects free, automatic and incredibly simple.

Additionally, it’s super easy to plug in a custom domain, and I've included installation instructions including all of the required A and CNAME host records for your domain provider.

You can view the repositories here:

Each of these is hosted separately, for free:

How it Works

We’ll be taking advantage of GitHub Pages in order to host our sites.

Pages is a feature of GitHub that can serve static web files for a repository, typically for docs or a wiki. We’ll be using it to serve a compiled React/Vue project.

I should note here that this won’t host an app that relies on Node. You’ll need a proper web server for that.

Getting started

It can be set up in minutes, and has a few nice features out-of-the-box:

The repository contains a GitHub Actions workflow to automatically build and deploy any pushed changes. No messing around with external pipelines (i.e. Travis CI), and a private repo can still get ~2000 deployments per month.

The repository contains a CNAME file, along with easy instructions for pointing your domain to the site using your provider’s DNS host records.

The README also contains instructions for launching unlimited static sites, each to its own subdomain. You can now publish a blog, or separate out your portfolio’s projects into repos under the same domain, all for free.

All instructions are in the repository’s README, but let’s get started below!

Usage

Get started in minutes with these instructions:

Create a repository from this template (include all branches).
Rename your repository to <username>.github.io.
Make sure that GitHub Pages uses the build branch.

The branch can be selected at Settings -> Options -> GitHub Pages -> Source.

Architecture

This is real simple:

The master branch contains a React/Vue project.
The build branch will contain the compiled React/Vue application.
When you push to master, a GitHub Action compiles the updated project into build.

Development

Any commits pushed or merged into master will trigger the build action.

These changes will be reflected on your GitHub Pages site after around 60 seconds.

Domain Names

Apex Domain

First, set your domain name within the GitHub repository.

In the CNAME file, replace example.com with your domain.
This can also be done in Settings -> Options -> GitHub Pages -> Source.

Second, configure your DNS host records with your domain provider.

Create an A record for host "@" pointing to 185.199.108.153.
Create an A record for host "@" pointing to 185.199.109.153.
Create an A record for host "@" pointing to 185.199.110.153.
Create an A record for host "@" pointing to 185.199.111.153.

Subdomains

You can configure a subdomain, such as www.[example.com], in your DNS host records.

Create a CNAME record for host "www" pointing to <username>.github.io.

Infinite Hosting

The awesome power of this is that you can have a repository for each and every subdomain.

Create a repository from this template with any name (include all branches).
Enable GitHub Pages for it (Settings -> Options -> GitHub Pages -> Source).
In the CNAME file, replace example.com with your apex and subdomain (i.e. blog.[example.com]).
With your domain provider, create a CNAME record for host "[blog]" pointing to <username>.github.io.

This is how I achieved each of these, for free:

What's not to love? 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

DEV: https://dev.to/tao/
Twitter: https://twitter.com/LloydTao
GitHub: https://github.com/LloydTao
LinkedIn: https://www.linkedin.com/in/LloydTao/

Catch you around!

The Case for Comma-Leading Lists

Lewis Lloyd — Sat, 13 Jun 2020 17:57:36 +0000

Introduction

Comma-leading lists are an objectively better presentation style.

They make logical sense; the next value on the list is dependant on the comma, and so, they should be kept together.

The style may look alien at first, but give it a test drive and you'll be surprised at how quickly it starts to look normal.

For now, let's have a look at the benefits.

Justification

1. No Merge Conflicts

When adding a new value to a list with trailing commas, you're making 2 additions and 1 deletion.

This will give you a merge conflict just because someone else adds a value on a different branch.

By using the comma-leading style, you make 1 addition and 0 deletions.

These commits play ball with each other, without needing any conflict resolution.

"Ah, but I've used a dangling comma," you say? Allow me to continue.

2. Dangling Commas Bad

It's true that using a trailing comma after the final value will prevent conflicts, but it's dumb for two reasons.

1. Language Inconsistency

SQL doesn't support them.

The JSON standard and Pre-ES5 JavaScript don't support them.

It's better to stick to a style that works across more languages, especially for a multi-lingual codebase.

2. Redundant Logic

There's not a second element. It's unnecessary context, so why justify it?

And, if an interpreter ever decides to stick a None in there, good luck.

3. Better Presentation

Separating Context

With the comma-leading style, the logic stays on the left, and the data stays on the right.

This makes it quicker and easier to scan when looking through code.

It will also allow you to quickly identify logic errors, such as missing commas.

Saving Whitespace

When you indent after the opening bracket, you're adding extra columns of whitespace on the left-hand side.

Placing the commas on the left keeps the code neat and narrow. Neat!

Summary

Comma-leading lists are easier for source control, more compatible across languages, and much faster to read since they keep data separate from the list's logic.

Do the world a favour and switch to a better standard of data structure.

animals = [ "ant"
          , "bat"
          , "cat"
          , "dog"
          ]

What's not to love? 😉

Hey, guys! Thank you for reading. I hope that you enjoyed this.

Keep up to date with me:

DEV: https://dev.to/tao/
Twitter: https://twitter.com/LloydTao
GitHub: https://github.com/LloydTao
LinkedIn: https://www.linkedin.com/in/LloydTao/

Catch you around!

Your Intro to Stripe: Online Payments Processing

Lewis Lloyd — Fri, 05 Jun 2020 18:00:07 +0000

Introduction

Stripe is an online payments processor.

It's incredible useful for almost any internet commerce; from online stores to subscriptions, and from user-driven marketplaces to crowdfunding.

This guide will briefly overview Stripe and its API, and give examples on how to integrate it with Django.

If you're using a different framework, it should be easily adaptable!

Features

Stripe is elegant. It abstracts most of the payments process. You don't need to worry about passing card details around and processing it yourself.

Stripe is robust. It can send dummy payments with test cards before completing a purchase flow.

Stripe is secure. AES-256 encryption is built in, with decryption keys stored separately.

Stripe is compliant. This includes PCI, PSD2, SCA and SSAE18/SOC certifications.

Fees

Stripe Payments charge 1.4% + 20p for European cards and 2.9% + 20p for non-European cards.

Stripe Billing, used for recurring payments, charges 0.5%.

Extensions

Stripe has a host of additional features:

Stripe Connect - dedicated dashboard for sellers on your marketplace, with a monthly fee per account.
Stripe Radar - machine learning fraud protection.
Stripe Sigma - SQL-powered business reports, with dozens of templates.
Stripe Atlas - launch a start-up (LLC, bank account, stock issuing) for a one-time fee.

We'll be taking advantage of Stripe Checkout for quick and compliant integration.

Setting Up

Overview

Our tasks at hand are essentially:

Create a Stripe account, and grab your API keys.
Install the Stripe API for the backend (Python: $ pip install stripe).
Add Stripe to the frontend (we're using checkout.js).
We're done! View processed payments on your Stripe account.

Creating a Stripe Account

Head to https://dashboard.stripe.com/register to create an account.

Remember to verify your account.

Now, grab your API keys. You'll need both.

Installing the Stripe API

Let's set up the backend. This is where the private API key will live.

Project Setup

Make sure you've set up your project, virtual environment and requirements. Here's a Django guide.

Add Stripe to your requirements.txt for pip. You'll probably want the latest version.

Install your packages with pip install -r requirements.txt.

Stripe Setup

In the settings, make sure you've added Stripe to your INSTALLED_APPS and defined the keys.

...

INSTALLED_APPS = [
    ...
    'stripe',
]

...

STRIPE_PUBLISHABLE_KEY = 'pk_test_notmykeynotmykeynotmykeynotmykeynotmykeynotmykeynotmykey'

STRIPE_SECRET_KEY = 'sk_test_notmykeynotmykeynotmykeynotmykeynotmykeynotmykeynotmykey'

Once you've set up your project, import stripe and define stripe.api_key in your views.

import stripe

from django.conf import settings
from django.shortcuts import render

stripe.api_key = settings.STRIPE_SECRET_KEY


class ...

We can now get started with some views and templates!

Adding Stripe to the Frontend

Using Stripe Checkout, we can create a payment form (and handle it) incredibly quickly.

Product Page

We'll make a very simple view, with our API key added to the context.

class HomeView(TemplateView):
    template_name = 'index.html'

    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context['key'] = settings.STRIPE_PUBLISHABLE_KEY
        return context

Our template will be include a form, as well as a script based on checkout.js.

<h1>Purchase hat:</h1>
<form action="{% url 'payments-charge' %}" method="POST">
  {% csrf_token %}
  <script src="https://checkout.stripe.com/checkout.js" class="stripe-button"
          data-key="{{ key }}"
          data-description="You are purchasing: Hat."
          data-amount="100"
          data-currency="GBP"
          data-locale="auto">
  </script>
</form>

Stripe will validate the payment form. The result looks like:

Payment View

You'll need a view that uses stripe.Charge.create().

You'll notice that the values are hard-coded. You need to enforce them server-side, otherwise the client can just edit the values in the Stripe form.

class ChargeView(TemplateView):

    def post(self, request):
        charge = stripe.Charge.create(
            amount = 100,
            currency = 'gbp',
            description = 'Hat purchase.',
            source=request.POST['stripeToken']
        )
        return HttpResponse('charge.html')

As for the template, it doesn't need anything. All functionality is handled in the post.

<p>Thank you for your payment!</p>

You'll likely want to pass some context data in order to personalise it.

Demo

We can try out our form with a test card.

We can now see the payment on the dashboard.

Super easy, right? You can now begin to explore the big, wide world of internet commerce!

Summary

What We Covered

In this post, we had a look at:

Creating a Stripe account.
Getting our API keys.
Adding Stripe to our Django backend.
Creating views and templates for our frontend.
Handling the post request using stripe.Charge.create().
Viewing payments on the dashboard.

What We Missed

There's a whole bunch of stuff to do after payment.

How do I get the money? Receive payouts.
How do I react to a payment? Handle webhook events.
How do I send receipts? Send email receipts.
A payment was declined. Deal with declines.
My customer wants a refund. Issue refunds.
What about fraudulent payments? Manage disputes and fraud.

As well as the pages above, there's also API docs, such as the API: Refunds page.