DEV Community: Andrea Stagi

Publish to NPM using GitHub Actions

Andrea Stagi — Wed, 25 Aug 2021 16:06:51 +0000

I recently needed to find a way to publish packages to NPM automatically and since all my projects are hosted on GitHub I thought why not using GitHub actions? In this article I explain how to do that in 3 simple steps!

👉🏻 Pssst... you can also check some real life examples:

Generate a new token on NPM

First of all you need to create a new NPM token that will be used to publish packages to NPM.

From NPM dashboard open main menu and select "Access token", then click on "Generate new token"

select "Automation" token to bypass two-factor authentication when publishing

then copy your token, it will be used as a GitHub secret as explained in the next section

Store your token as a GitHub secret

GitHub Actions can access your GitHub secrets, so that's the perfect place where to store your token!

Under "Settings" -> "Secrets" click on "New repository secret" and add your NPM Token your previously copied (in this example I use NPM_TOKEN label to identify it)

Now it's time to write some code and create a new action to publish your package!

Write your action

Create a new GitHub Action publish.yml inside your project under .github/workflows.



name: Publish to NPM
on:
  release:
    types: [created]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Node
        uses: actions/setup-node@v2
        with:
          node-version: '14.x'
          registry-url: 'https://registry.npmjs.org'
      - name: Install dependencies and build 🔧
        run: npm ci && npm run build
      - name: Publish package on NPM 📦
        run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

This action should run only when you create a new release on GitHub



on:
  release:
    types: [created]

The steps it executes are really clear:

Checkout code
Setup Node.js environment (using Node.js 14.x here)
Install dependencies and build your package (if needed)
Publish to NPM! As you can see this step uses our NPM_TOKEN secret to initialize NODE_AUTH_TOKEN env variable



  <span class="pi">-</span> <span class="na">name</span><span class="pi">:</span> <span class="s">Publish package to NPM 📦</span>
    <span class="na">run</span><span class="pi">:</span> <span class="s">npm publish</span>
    <span class="na">env</span><span class="pi">:</span>
      <span class="na">NODE_AUTH_TOKEN</span><span class="pi">:</span> <span class="s">${{ secrets.NPM_TOKEN }}</span>

Create a new release

In order to see your action running, you need to create a new release on GitHub.

After that your package will be successfully published to NPM 🎉

Oruga: the new kid on the block

Andrea Stagi — Wed, 03 Mar 2021 16:04:38 +0000

If you're working with Vue.js you know that here are a lot of UI component libraries orbiting around the Vue.js world like Vuetify, Buefy, BootstrapVue and so on. Rather than coding and styling buttons, cards, and layouts, you can use these libraries to get access to all the necessary UI elements for creating beautiful, content-rich applications. However sometimes you want to switch to your custom design or try another UI framework that doesn't provide any ready-to-use Vue.js component. In such cases you would like to have a set of naked UI components on which you can apply your style: here's where Oruga comes into play!

Say Hi to Oruga! 👋

Oruga is a new lightweight library of UI components for Vue.js (2.x and 3.x) without any CSS framework dependency. In fact, it doesn't depend on any specific style or CSS framework and it doesn't provide any grid system or CSS utility, it just offer a set of components that you can easily customize modifying your stylesheets or integrating it with a CSS framework. It also provides a default stylesheet containing only the essential rules to display Oruga components correctly such as display, position, z-index and other basic attributes.
Oruga wants you to focus only on UI/UX aspects of your application and be totally flexible to future changes without having to touch a line of JavaScript.

👉🏻 You can find useful resources and links at the end of the article!

Setup 🐛

Let's start a new project for Vue.js 2.x and install Oruga package (note that Oruga is available for Nuxt.js as well, see the documentation)

yarn add @oruga-ui/oruga

Then, import Oruga default stylesheet, the Config component and the Button component

import Vue from 'vue'
import {
  Config, Button
} from '@oruga-ui/oruga';

import '@oruga-ui/oruga/dist/oruga.css'

Vue.use(Button)

Config will be used for customization.

Customization

Customization is the core feature of Oruga. You can easily override existing components style appending one or more classes using the Config component. Each component has some class properties that you can define to extend classes of the target component. Each class property affects a specific part of the component as you can discover using the Class props inspector in Oruga documentation.

Suppose we want to style our Oruga components using a cool CSS framework like Nes.css to give our app a cool 90s style.

To install Nes.css run

yarn add nes.css

(add --ignore-engines to the command above if you're using Node.js > 10.x)

And import it in your project

import "nes.css/css/nes.min.css";

Let's start with a simple Button component from Oruga.

<o-button @click="search">Search</o-button>

Nes.css provides nes-btn class for buttons, so we can extend Oruga Button component using the Config object

Vue.use(Config, {
  button: {
    rootClass: 'nes-btn'
  }
}

When you instantiate a new Oruga Button, you'll have the class nes-btn automagically applied to your component, alongside default classes applied on that part of the component. If you wish to override default classes and use only your custom class, you can assign to rootClass an object, with the override attribute set to true.

Vue.use(Config, {
  button: {
    rootClass: {
      class: 'nes-btn',
      override: true
    }
  }
}

Using the Class props inspector we can easily find the class name to add a class when the button is disabled (in this case disabledClass), then we can extend our configuration overriding all the class props of o-button we need to customize

Vue.use(Config, {
  button: {
    override: true,
    rootClass: 'nes-btn',
    disabledClass: 'is-disabled'
  }
})

Result

Sometimes you may need more flexibility to extend classes and decide programmatically which class to apply to our component, especially when you have to deal with variant or position classes. Many Oruga components has some classes applied when certain properties change, like position and variant, on the other side Nes.css provides "variant" classes like is-success and is-warning and "position" classes like is-centered. For example, how can I apply the correct class in this case?

<o-button variant="warning">Warning!</o-button>

Follwing the Class prop inspector we can easily find that the Class prop we need to override is variantClass but its values are not fixed, it could be is-warning, is-error, is-success depending on variant value as you can see in the Suffixes column

Oruga provides an easy way to help us: you can extend classes using functions! A function will receive two parameters:

a suffix (that will receive for example waring, success, error in case of variants or centered, right.. in case of positions)
a context containing the context of the component instance.

To extend variantClass with Nes.css for Button we can simply do that

Vue.use(Config, {
  button: {
    rootClass: "nes-btn",
    variantClass: (suffix, context) => {
      return `is-${suffix}`
    }
  }
})

Result:

variantClass is determined by a function that will receive "warning" as suffix when variant property of o-button is "warning". Using a function we can instruct Oruga to apply to our Button components a class whose name is composed by "is-" followed by the suffix value, in this case the variant. Thanks to the context parameter, you can take more refined decisions like not applying a variant if the component is outlined (see an example here)

A Pokèmon finder with Oruga and Nes.css

Using Oruga and Nes.css I built a simple Pokèmon finder to search some statistics of my favourites Pokèmon taking advantage of the cool PokèAPI.

The app is really simple: it allows you to type Pokèmon name you want to find, press a button and then, through the API, get all the information you need and show them in a table. If the Pokèmon can't be found, the search input will turn red (variant="error") and an error message will be shown. You can play with the app on Netlify and browse the final code on GitHub

As you can see in the main.js file the final configuration for Oruga is really simple.

Useful resources

You can also play with other cool Oruga examples

Add custom icons to Font Awesome

Andrea Stagi — Tue, 17 Nov 2020 14:42:19 +0000

In one of my recent projects I used Font Awesome as icon set but I needed to add a new icon not included in the standard Font Awesome's library, the DuckDuckGo logo 🦆

After some research I discovered that Font Awesome allows you to add custom icons in addition to what's offered and in this tutorial I'll show you how to extend Font Awesome in 3 simple steps keeping your code clean.

1) First of all create a folder called myicons and add your icon definition inside a js file (fa-duckduckgo.js in my case)



export const faDuckDuckGo = {
  prefix: "fab",
  iconName: "duckduckgo",
  icon: [
    24,
    24,
    [],
    "e001",
    "M12 0C5.373 0 0 ... .616.484z"
  ]
};

prefix and iconName are respectively the icon group (fab -> Font Awesome brands in this case) and the icon name, so that you can render the icon in this way



<i class="fab fa-duckduckgo"></i>

the icon section contains the SVG viewbox (24, 24 in this case), the unicode point which represents this custom icon (e001) and the single-path SVG.

2) Create an index file myicons/index.js to export your custom icons



export { faDuckDuckGo } from "./fa-duckduckgo";

3) Install fontawesome-svg-core package



yarn add @fortawesome/fontawesome-svg-core

to make your custom icons available in Font Awesome.



import { library, dom } from "@fortawesome/fontawesome-svg-core";
import { faDuckDuckGo } from "./myicons";

library.add(faDuckDuckGo);

dom.watch();

In the code above your custom icons gets imported from the myicons module you created before and then added to Font Awesome's library. dom.watch method watches the DOM for any additional icons being added or modified.

Here you can play with the final demo!

Pssst... if you use TypeScript you need to use some types from fontawesome-svg-core as you can see in this example.

How to test Web Workers with Jest

Andrea Stagi — Tue, 20 Oct 2020 09:05:30 +0000

As you could read in Alex's article, Use Web Workers in your Vue.js Components for Max Performance, you can use Web Workers to maximize performance in your Vue.js app instead of running heavy tasks in the main thread which is UI-blocking. But how can we test Web Workers? Webpack-bundled Web Workers are not supported by Jest so we have to mock the worker in order to test it! Let's see how to do in 3 simple steps, starting from a simple Vue app to calculate the Fibonacci number, where fibonacci function is the heavy task performed by the Web worker (you can follow the code here)

First of all we need to isolate the main functionality of our worker, in this case is really straightforward because it's just our fibonacci function (src/fibonacci.js)



let fibonacci = (num) => {
  if (num <= 1) return 1;
  return fibonacci(num - 1) + fibonacci(num - 2);
}

export default fibonacci

and keep the worker minimal (src/fibonacci.worker.js):



import fibonacci from "./fibonacci";

self.onmessage = async function (e) {
  self.postMessage(fibonacci(e.data));
};

This way we can mock just the Web Worker part of our implementation (src/__mocks__/fibonacci.worker.js)



import fibonacci from "../fibonacci";

export default class fibonacciWorker {
  constructor() {
    // Note that `onmessage` should be overwritten by the code using the worker.
    this.onmessage = () => { };
  }

  postMessage(data) {
    this.onmessage({ data: fibonacci(data) });
  }
}

and easily test the main functionality



import { shallowMount } from '@vue/test-utils'
import App from '@/App.vue'

jest.mock("@/fibonacci.worker")

describe('Fibonacci App.vue', () => {
  it('should calculate Fibonacci number', async () => {
    const wrapper = shallowMount(App)
    await wrapper.find('input').setValue('10')
    await wrapper.find('button').trigger('click')
    expect(wrapper.find('.result').element.innerHTML).toBe('Result: 89')
  })
})

I created workerloader-jest-transformer to generalize this solution so that all workers are mocked at once. This Jest transformer helps you to test Web Workers loaded with Webpack worker-loader module in Jest. It's easy to use, install it with



yarn add workerloader-jest-transformer --dev

and add the tranformation rule to your Jest configuration:



transform: {
  "^.+\\.worker.[t|j]sx?$": "workerloader-jest-transformer"
}

This transformer is inspired by jsdom-worker and implements Web Worker API for JSDOM, so you can remove any mocking code as you can see here.

Workerloader-jest-transformer is highly experimental and code is available on Github, any contribution and advice would be greatly appreciated!

Testing a Nuxt.js application using WebdriverIO

Andrea Stagi — Tue, 14 Jul 2020 16:11:31 +0000

Recently WebdriverIO has been added in Nuxt.js create-nuxt-app scaffolding tool as a test framework option to provide end to end browser and mobile automation testing.

In this tutorial you'll learn how to test a Nuxt.js app with WebdriverIO following the Page Object pattern and set up Continuous Integration with TravisCI using WebdriverIO hooks.

Create a simple to-do list application

In this section we're going to create a very simple to-do list app: when users write inside the text field and press the "enter" key, a new item will be added to the list, then they can click on items to mark them as completed. You can play with the app here ✅.

👉🏻 Some parts of code are omitted for the sake of simplicity, check the complete code on Github.

Let's start! Create the app using create-nuxt-app scaffolding tool

npx create-nuxt-app todolist

And select WebdriverIO testing framework

? Testing framework:
  None
  Jest
  AVA
❯ WebdriverIO

Then create the store files inside store/todos folder

getters.js


export default {
  todos (state) {
    return state.list
  }
}

state.js

export default () => ({
  list: []
})

mutations.js

export default {
  add (state, { text }) {
    state.list.push({
      text,
      done: false
    })
  },

  toggle (state, todo) {
    todo.done = !todo.done
  }
}

And the TodoList component under components/TodoList.vue

<template>
  <ul class="todolist list-group">
    <li v-for="(todo, index) in todos" :key="index" class="todolist__item list-group-item" :class="{ done: todo.done }" @click="toggle(todo)">
      {{ todo.text }}
    </li>
    <li class="list-group-item">
      <input type="text" class="form-control" placeholder="What needs to be done?" @keydown.enter="addTodo">
    </li>
  </ul>
</template>

<script>
import { mapMutations, mapGetters } from 'vuex'

export default {
  computed: mapGetters({
    todos: 'todos/todos'
  }),
  methods: {
    addTodo (e) {
      const text = e.target.value
      if (text.trim()) {
        this.$store.commit('todos/add', { text })
      }
      e.target.value = ''
    },
    ...mapMutations({
      toggle: 'todos/toggle'
    })
  }
}
</script>

Render it inside pages/index.vue and your TodoList app is ready ✌🏻

<template>
  <div class="container-md">
    <h1 class="title">My List</h1>
    <todo-list />
  </div>
</template>

<script>
import TodoList from '~/components/TodoList.vue'

export default {
  components: {
    TodoList
  }
}
</script>

Write your tests using Page Object pattern

The goal of using Page Object pattern is to provide an additional layer of abstraction of any page information and use it in tests to refer to page elements. You should store all selectors and action methods that are unique for a certain page in a page object, so that you still can run your test after changes to the markup.

Using WebdriverIO our initial project structure comes with wdio.conf.js configuration file containing all the required info on how to execute WebdriverIO, such as test specs to run and capabilities (Chrome by default), and a test/e2e folder containing a test example (index.spec.js file under test/e2e/specs) and a page object (main.page.js file under test/e2e/pageObjects).

Inside index.spec.js you can find a simple test implemented using a page object. Edit this test to make it passes!

const TodoListPage = require('../pageObjects/main.page')

describe('Todolist', () => {
  it('should open correct app', () => {
    TodoListPage.open()
    expect(browser).toHaveTitle('todolist')
  })
})

👉🏻 To speed up tests execution during development run the dev server in another terminal executing yarn dev, we'll see later how to programmatically build and serve your Nuxt app for Continuous Integration.

To execute tests run

yarn test:e2e

Your application will be executed inside a new Chrome instance and your first test passes 🎉 You'll get a report like this

[Chrome 83.0.4103.116 darwin #0-0] Running: Chrome (v83.0.4103.116) on darwin
[Chrome 83.0.4103.116 darwin #0-0] Session ID: 03399e35-a11d-4305-87bc-3cea66ce42de
[Chrome 83.0.4103.116 darwin #0-0]
[Chrome 83.0.4103.116 darwin #0-0] Todolist
[Chrome 83.0.4103.116 darwin #0-0]    ✓ should open correct app
[Chrome 83.0.4103.116 darwin #0-0]
[Chrome 83.0.4103.116 darwin #0-0] 1 passing (1.7s)


Spec Files:  1 passed, 1 total (100% completed) in 00:00:03

Now it's time to get our hands dirty and test if our application really works as expected. To keep things simple I haven't created a new TodoListPage object inheriting from Page, but remember that you can do anything you want with page objects, they're normal classes. The first step is to write all important selectors that are required in our TodoListPage object as getter functions:

itemInput: input text field to insert items (use $(selector) for single element)
listItems: items inserted in the list (use $$(selector) for multiple elements).

class TodoListPage {
  get itemInput () { return $('input[type=text]') }
  get listItems () { return $$('.todolist__item') }

  open (path = '/') {
    browser.url(path)
  }
}

module.exports = new TodoListPage()

Then you can define further getters and action methods: listSize to retrieve the current list size and addListItem / addListItems methods to add one or more elements to the list

class TodoListPage {
  // ...
  get listSize () { return this.listItems.length }

  addListItem (item) {
    this.itemInput.setValue(`${item}\n`)
  }

  addListItems (items) {
    items.map((item) => {
      this.addListItem(item)
    })
  }
  // ...
}

Write another test that adds items to the list and checks if they're inserted correctly

describe('Todolist', () => {
  // ...
  it('should add items to the list correctly', () => {
    TodoListPage.open()
    TodoListPage.addListItems(['Milk', 'Apples', '1 Banana'])
    expect(TodoListPage.listSize).toEqual(3)
  })
  // ...
}

As you can see tests don't contain any CSS selector, everything is clean and easier to modify even in a rapidly developing web application context where page markup and design may change often. Following this pattern you can continue writing tests adding methods to the page object if needed: for example to test if an item is marked as completed when users click on it, you can inflate your page object with a method to check if an item at a specific position is completed (isItemCompletedAt) and another method to mark a specific item as completed (completeItemAt)

class TodoListPage {
  // ...
  isItemCompletedAt (position) {
    return this.listItems[position].getAttribute('class').includes('done')
  }

  completeItemAt (position) {
    this.listItems[position].click()
  }
  // ...
}

and then write the test

describe('Todolist', () => {
  // ...
  it('should complete items correctly', () => {
    TodoListPage.open()
    TodoListPage.addListItems(['Milk', 'Apples', '1 Banana', 'Meat'])
    expect(TodoListPage.isItemCompletedAt(2)).toBeFalsy()
    TodoListPage.completeItemAt(2)
    expect(TodoListPage.isItemCompletedAt(2)).toBeTruthy()
  })
  // ...
}

Build and serve your app for Continuous Integration

WebdriverIO provides several hooks to interfere with the test process in order to enhance it and to build services around it. To programmatically build and serve your Nuxt application in a Continuous Integration process you need to override onPrepare and onComplete hooks inside wdio.conf.js configuration file. Using Nuxt Builder you need to build and serve your app inside onPrepare hook and shut down the server inside onComplete hook. In the following code there's also a NUXT_ENV_CI environment variable to skip this process outside the Continuous Integration environment, keeping tests under development fast.

const path = require('path')
const nuxt = require('nuxt')

exports.config = {

  // ...

  async onPrepare (config, capabilities) {
    if (process.env.NUXT_ENV_CI !== 'true') {
      return
    }
    console.log('⛰  Setting up...')
    const rootDir = path.resolve(__dirname, '.')
    const nuxtConfig = {
      head: {
        title: 'todolist'
      },
      dev: false,
      rootDir,
      modules: ['bootstrap-vue/nuxt']
    }
    this.nuxtInstance = new nuxt.Nuxt(nuxtConfig)
    console.log('📦 Building your Nuxt.js project...')
    await new nuxt.Builder(this.nuxtInstance).build()
    await this.nuxtInstance.server.listen(3000, 'localhost')
    console.log('✨ Done!')
  },

  onComplete (exitCode, config, capabilities, results) {
    if (process.env.NUXT_ENV_CI !== 'true') {
      return
    }
    console.log('👋 Shutting down server...')
    this.nuxtInstance.close()
  }
}

To configure TravisCI for Continuous Integration you need to create .travis.yml configuration file, containing chrome addon, xvfb service and some scripts to make UI tests working.

dist: bionic

addons:
  chrome: stable

services:
  - xvfb

language: node_js
node_js: '12'

before_script:
  - fluxbox >/dev/null 2>&1 &
  - sleep 3

script:
  - NUXT_ENV_CI=$CI yarn test:e2e

In the script section yarn test:e2e is executed with NUXT_ENV_CI set to CI env variable value (CI is one of the default environment variables available to all builds and is set to true by default inside TravisCI).

👉🏻 If you need Continuous Deployment for your app see how to setup TravisCI to test, build and deploy your app on Netlify in 5 minutes.

Announcing JSON {BIN} IT! service to store your JSON files

Andrea Stagi — Wed, 24 Jun 2020 15:19:12 +0000

Since one of our favourite services to store JSON files went down (myjson.com), me and my pal @mino89 decided to write a new one by our own: that's how JSON {BIN} IT! was born 🦄

This service is ideal for hobbies projects, MVP and any other situation where you don't want to create a data storage. Using JSON {BIN} IT! is really straightforward, you can create a new JSON directly from the website or sending a POST request to the API endpoint

https://api.jsonbin.it/bins/

including the JSON you want to store in the body of the request.

{ "value" : 2000 }

The response will be something like

{ "bin" : "l088fgWQ" }

where bin is the id of your JSON that you can retrive sending a GET request to another API endpoint,

https://api.jsonbin.it/bins/:binid

{ "value" : 2000 }

The service is still in beta version, is open source (https://github.com/jsonbinit) and there are some good first issues in the repositories, any contribution or suggestion would be appreciated!

NuxtJS 2.13.0 has been released with Full Static Generation

Andrea Stagi — Fri, 19 Jun 2020 08:21:06 +0000

NuxtJS 2.13.0 is finally here and comes with a great feature we've been waiting for: full static generation 🎉 Before this release, it was possible to have full static support using nuxt-payload-extractor module as you can read here.

Starting from version 2.13.0 Nuxt.js has a crawler inside to detect every relative link and generate it. You can disable the crawler setting generate.crawler: false and still add dynamic routes by your own for performance reasons or to add extra routes that the crawler could not detect.

I've just updated my article How to build a Jamstack multi-language blog with Nuxt.js with full static generation support following these steps:

Remove nuxt-payload-extractor and all its references in nuxt.config.js and asyncData
Upgrade nuxt to 2.13.0
Add target: 'static' to nuxt.config.js
Add new scripts to package.json to export and serve the static site

{
  "scripts": {
    "export": "nuxt export",
    "serve": "nuxt serve",
    ...
  }

Run yarn build && yarn export instead of yarn generate

For more information about this awesome feature, please read Going Full Static from the official Nuxt.js blog.

Setup TravisCI to test, build and deploy your app on Netlify in 5 minutes

Andrea Stagi — Fri, 29 May 2020 16:34:23 +0000

In this tutorial you'll learn how to setup TravisCI to test and build a simple app (I'm using Vue.js here but feel free to use whatever you want!) and then deploy it on Netlify. TravisCI is a hosted, distributed continuous integration service used to build and test projects on GitHub. Netlify offers cloud hosting for static websites, providing continuous deployment, free SSL, serverless functions, and more... Read this article for more about Continuous Integration and Continuous Deployment with TravisCI and Netlify.

👉🏻 In this repository you'll find the final code.

Setup Netlify

Setting up your site with Netlify is really straightforward, click on New site from Git and follow the instructions. After this step, disable automatic builds in Netlify site dashboard under Build & Deploy > Continuous Deployment > Build settings. Without this option I suggest to run a separate instance of your site on Netlify to easily keep features like site preview on pull requests (check this pull request to see how it works). For example I have these two instances running for my sample app

Configure TravisCI

Builds on Travis CI can be configured through the build configuration stored in the file .travis.yml placed in the root of your project. To build, test and deploy a simple Vue app, the final .travis.yml file will look like this

language: node_js
node_js:
  - 12
cache:
  directories:
    - node_modules
script:
  - yarn test:unit
before_deploy:
  - npm install netlify-cli -g
  - yarn build
deploy:
  provider: script
  edge: true
  script: netlify deploy --dir=dist --prod
  on:
    branch: master

This configuration is easy to understand: first of all it instructs TravisCI to use Node.js 12 environment and run tests with yarn test:unit command as specified in the script section.
In the following section, before_deploy, TravisCI runs a complete build of your site (using yarn build in this case) and installs Netlify CLI to deploy the site later. Netlify CLI needs to know who you are and the target site you want to deploy.

Under Personal access tokens, select New access token.
Enter a description and select Generate token.
Copy the generated token to your clipboard (once you navigate from the page, the token cannot be seen again!) and add it to a NETLIFY_AUTH_TOKEN environment variable in TravisCI.

To set the target site to deploy

From the Netlify site dashboard, go to Settings > General > Site details > Site information, and copy the value for API ID.
Assign the API ID to a NETLIFY_SITE_ID environment variable in TravisCI.

In the last section, deploy, TravisCI uses Netlify CLI to deploy your site on Netlify in production mode, specifying the source folder (in this case dist generated by yarn build). By default, deployments will only happen on the master branch but you can overwrite this by using the branch option.

✨ Your CI/CD pipeline using TravisCI and Netlify is ready!

How to build a Jamstack multi-language blog with Nuxt.js

Andrea Stagi — Thu, 21 May 2020 23:32:05 +0000

Jamstack (Javascript, APIs and Markup Stack) is a terminology around the new way of making web projects where you don’t have to host your own backend that builds the site every time you serve it, instead it renders out a set of static pages at build time and deploys them to a content delivery network (CDN). This means better security, increased scalability and improved website performance.

In this tutorial you'll learn how to build a Jamstack multilanguage blog using Nuxt.js, a powerful Vue framework that supports SPA, SSR and statically generated renderings in conjunction with Strapi Headless CMS to store data and expose them to generate a static blog. To setup Strapi locally you can follow this guide otherwise you can use a read only instance running on our server at https://strapi.lotrek.net/.

👉🏻 You can find the complete code of this tutorial in this repository.

Backend structure

With Strapi I built a naive structure to support translations with a Post table containing elements linked with one or more TransPost elements that contain translations

       ____________                        ____________
      |    POST    |                      | TRANS_POST |
       ============                        ============
      | published  |                      | language   |
      | created_at | <--(1)-------(N)-->> | title      |
      |            |                      | content    |
      |            |                      | slug       |
       ============                        ============

You can play with it using GraphQL playground and explore the backend. Remember that the main focus of this tutorial is Nuxt.js, you can use any backend you want to generate the final static site. Backend repository is available here

Setup Nuxt.js project

Install Nuxt.js globally and create a new app called multilangblog

npx create-nuxt-app multilangblog

Remember to select axios option (you'll need it later) and add a UI framework such as Buefy.

Create a client to fetch posts

Install apollo-fetch client to fetch posts from the Strapi server (I used this old package to keep the client part as simple as possible, check @nuxtjs/apollo for a more structured and newer plugin)

yarn add apollo-fetch

and create index.js file under services folder to wrap all the queries. This client should implement 3 methods:

getAllPostsHead: fetches all the posts in a specific language, showing slug and title.
getAllPosts: fetches all the posts in a specific language, showing slug, title, content and the other posts slugs in other languages to get alternate urls.
getSinglePost: fetch a single post with a specific slug and language, showing all the attributes and posts in other languages.

import { createApolloFetch } from 'apollo-fetch'

export default class BlogClient {
  constructor () {
    this.apolloFetch = createApolloFetch({ uri: `${process.env.NUXT_ENV_BACKEND_URL}/graphql` })
  }

  getAllPostsHead (lang) {
    const allPostsQuery = `
      query AllPosts($lang: String!) {
        transPosts(where: {lang: $lang}) {
          slug
          title
        }
      }
    `
    return this.apolloFetch({
      query: allPostsQuery,
      variables: {
        lang
      }
    })
  }

  getAllPosts (lang) {
    const allPostsQuery = `
      query AllPosts($lang: String!) {
        transPosts(where: {lang: $lang}) {
          slug
          title
          content
          post {
            published
            transPosts(where: {lang_ne: $lang}) {
              slug
              lang
            }
          }
        }
      }
    `
    return this.apolloFetch({
      query: allPostsQuery,
      variables: {
        lang
      }
    })
  }

  getSinglePost (slug, lang) {
    const simplePostQuery = `
      query Post($slug: String!, $lang: String!) {
        transPosts(where: {slug : $slug, lang: $lang}) {
          slug
          title
          content
          post {
            published
            transPosts(where: {lang_ne: $lang}) {
              slug
              lang
            }
          }
        }
      }
    `
    return this.apolloFetch({
      query: simplePostQuery,
      variables: {
        slug,
        lang
      }
    })
  }
}

To make BlogClient available whenever you have access to the context (e.g. in asyncData function) create plugins/ctx-inject.js file

import BlogClient from '~/services'

export default ({ app }, inject) => {
  app.$blogClient = new BlogClient()
}

and add it to plugins in nuxt.config.js

export default {
  // ...
  plugins: ['~/plugins/ctx-inject.js']
}

Create the main views

The structure of this blog will be really simple, in the homepage (/) there'll be a list of posts with a link to read the article (/blog/<postslug>). Now that you can access the BlogClient instance from the context, start rewriting the HomePage component (pages/index.vue) to fetch blog posts in a special method called asyncData and render title and link for each post. asyncData receives the context as the first argument and your BlogClient instance is accessible at context.app.$blogClient

<template>
  <section class="section">
    <div class="is-mobile">
      <div v-for="post in posts" :key="post.slug">
        <h2>{{ post.title }}</h2>
        <nuxt-link :to="{name: 'blog-slug', params:{slug: post.slug}}">Read more...</nuxt-link>
      </div>
    </div>
  </section>
</template>

<script>
export default {
  name: 'HomePage',
  async asyncData ({ app }) {
    const postsData = await app.$blogClient.getAllPostsHead('en')
    return { posts: postsData.data.transPosts }
  },
  data () {
    return {
      posts: []
    }
  }
}
</script>

Add /blog/<postslug> route creating the component BlogPost (pages/blog/_slug.vue). Install Vue Markdown component to render the article correctly (yarn add vue-markdown)

<template>
  <section class="section">
    <div class="is-mobile">
      <h2>{{ post.title }}</h2>
      <vue-markdown>{{ post.content }}</vue-markdown>
    </div>
  </section>
</template>

<script>
export default {
  name: 'BlogPost',
  components: {
    'vue-markdown': VueMarkdown
  },
  async asyncData ({ app, route }) {
    const postsData = await app.$blogClient.getSinglePost(route.params.slug, 'en')
    return { post: postsData.data.transPosts[0] }
  },
  data () {
    return {
      post: null
    }
  }
}
</script>

Add i18n

To setup i18n install Nuxt i18n module

yarn add nuxt-i18n

Enable it in the module section of nuxt.config.js file

{
  modules: ['nuxt-i18n']
}

and setup i18n

const LOCALES = [
  {
    code: 'en',
    iso: 'en-US'
  },
  {
    code: 'es',
    iso: 'es-ES'
  },
  {
    code: 'it',
    iso: 'it-IT'
  }
]
const DEFAULT_LOCALE = 'en'

export default {
  // ...
  i18n: {
    locales: LOCALES,
    defaultLocale: DEFAULT_LOCALE,
    encodePaths: false,
    vueI18n: {
      fallbackLocale: DEFAULT_LOCALE,
      messages: {
        en: {
          readmore: 'Read more'
        },
        es: {
          readmore: 'Lee mas'
        },
        it: {
          readmore: 'Leggi di più'
        }
      }
    }
  }
  // ...
}

Now you can modify the HomePage component: in nuxt-link you should use localePath and render the translated label readmore using $t

<nuxt-link :to="localePath({name: 'blog-slug', params:{slug: post.slug}})">{{ $t('readmore') }}</nuxt-link>

In asyncData you can fetch the posts list using the store.$i18n attribute of context to get the current language.

// ....
async asyncData ({ app, store }) {
  const postsData = await app.$blogClient.getAllPostsHead(
    store.$i18n.locale
  )
  return { posts: postsData.data.transPosts }
},
// ....

Do the same in BlogPost component using route.params.slug to get the slug parameter

// ....
async asyncData ({ app, route, store }) {
  const postsData = await app.$blogClient.getSinglePost(
    route.params.slug, store.$i18n.locale
  )
  return { post: postsData.data.transPosts[0] }
},
// ....

It's time to create a component to switch the current language, LanguageSwitcher (components/LanguageSwitcher.vue)

<template>
  <b-navbar-dropdown :label="$i18n.locale">
    <nuxt-link v-for="locale in availableLocales" :key="locale.code" class="navbar-item" :to="switchLocalePath(locale.code)">
      {{ locale.code }}
    </nuxt-link>
  </b-navbar-dropdown>
</template>

<script>
export default {
  computed: {
    availableLocales () {
      return this.$i18n.locales.filter(locale => locale.code !== this.$i18n.locale)
    }
  }
}
</script>

and include it in layouts/default.vue to make it available in the navbar. This component calls switchLocalePath to get a link to the current page in another language. To make the language switcher working with dynamic routes you need to set the slug parameter in BlogPost component using store.dispatch

//...
async asyncData ({ app, route, store }) {
  const postsData = await app.$blogClient.getSinglePost(
    route.params.slug, store.$i18n.locale
  )
  await store.dispatch(
    'i18n/setRouteParams',
    Object.fromEntries(postsData.data.transPosts[0].post.transPosts.map(
      el => [el.lang, { slug: el.slug }])
    )
  )
  return { post: postsData.data.transPosts[0] }
},
//...

👉🏻 More on language switcher

Remember to set NUXT_ENV_BACKEND_URL environment variabile used by BlogClient with .env or directly (export NUXT_ENV_BACKEND_URL=https://strapi.lotrek.net) and launch the development server

yarn dev

Full static generation

👉🏻 Note that I wrote this article using Nuxt.js 2.12.0, then I upgraded the core to 2.13.0 to use full static generation, be sure to run the latest version. For more information please read Going Full Static from the official Nuxt.js blog and follow the changes in the repository.

To generate a full static version of this blog with Nuxt.js add target: 'static' to nuxt.config.js and run

nuxt build && nuxt export

(you can wrap nuxt export in the script section of package.json)

The final output is a list of generated routes inside dist folder

ℹ Generating output directory: dist/                                                                                       
ℹ Full static mode activated                                                                                               
ℹ Generating pages
✔ Generated /it/
✔ Generated /es/
✔ Generated /
ℹ Ready to run nuxt serve or deploy dist/ directory
✨  Done in 43.49s.

👉🏻 Starting from version 2.13.0 Nuxt.js uses a crawler to detect every relative link and generate it. You can disable the crawler setting generate.crawler: false and still add dynamic routes by your own for performance reasons (as in this case) or to add extra routes that the crawler could not detect.

To add dynamic routes manually you have to implement routes function under generate settings in nuxt.config.js and return a list of objects containing the route you want to generate and the payload containing the post.

import BlogClient from './services'

// ...

export default {
  // ...
  crawler: false,
  generate: {
    routes: async () => {
      const client = new BlogClient()
      let routes = []
      let postsData = []
      for (const locale of LOCALES) {
        postsData = await client.getAllPosts(locale.code)
        routes = routes.concat(postsData.data.transPosts.map((post) => {
          return {
            route: `${locale.code === DEFAULT_LOCALE ? '' : '/' + locale.code}/blog/${post.slug}`,
            payload: post
          }
        }))
      }
      return routes
    }
  }
  //...
}

Since payload is available in the context, you can refactor asyncData function in BlogPost component to get the specific post from context.payload

const getSinglePostFromContext = async ({ app, route, store, payload }) => {
  if (payload) {
    return payload
  }
  const postsData = await app.$blogClient.getSinglePost(
    route.params.slug, store.$i18n.locale
  )
  return postsData.data.transPosts[0]
}

export default {
  name: 'BlogPost',
  async asyncData (context) {
    const singlePost = await getSinglePostFromContext(context)
    await context.store.dispatch(
      'i18n/setRouteParams',
      Object.fromEntries(singlePost.post.transPosts.map(
        el => [el.lang, { slug: el.slug }])
      )
    )
    return { post: singlePost }
  },
  // ...
}

Run nuxt build && nuxt export again

ℹ Generating pages
✔ Generated /it/
✔ Generated /es/
✔ Generated /
✔ Generated /blog/hello-world
✔ Generated /it/blog/ciao-mondo
✔ Generated /es/blog/hola-mundo
ℹ Ready to run nuxt serve or deploy dist/ directory
✨  Done in 33.82s.

Now Nuxt.js is able to generate dynamic routes 🎉

You can test your static site installing using

nuxt serve

Sometimes you may need to configure a custom path for a dynamic route, for example you may want to keep /blog/:slug path for english, /artículos/:slug route for spanish and /articoli/:slug route for italian. Following nuxt-i18n documentation you have to specify these routes in i18n section of nuxt.config.js

i18n {
  // ...
  parsePages: false,
  pages: {
    'blog/_slug': {
      it: '/articoli/:slug',
      es: '/artículos/:slug',
      en: '/blog/:slug'
    }
  },
  // ...
}

To make these settings reusable both in i18n configuration and generate function, move custom routes in a separated file i18n.config.js

export default {
  pages: {
    'blog/_slug': {
      it: '/articoli/:slug',
      es: '/artículos/:slug',
      en: '/blog/:slug'
    }
  }
}

and import it in nuxt.config.js

import i18nConfig from './i18n.config'

// ...

export default {
  // ...
  i18n: {
    locales: LOCALES,
    defaultLocale: DEFAULT_LOCALE,
    parsePages: false,
    pages: i18nConfig.pages,
    encodePaths: false,
    vueI18n: {
      fallbackLocale: DEFAULT_LOCALE,
      // ...
    }
  },
  // ...

now you can rewrite generate function getting the correct path from the custom configuration

routes: async () => {
  const client = new BlogClient()
  let routes = []
  let postsData = []
  for (const locale of LOCALES) {
    postsData = await client.getAllPosts(locale.code)
    routes = routes.concat(postsData.data.transPosts.map((post) => {
      return {
        route: `${locale.code === DEFAULT_LOCALE ? '' : '/' + locale.code}${i18nConfig.pages['blog/_slug'][locale.code].replace(':slug', post.slug)}`,
        payload: post
      }
    }))
  }
  return routes
}

Build and export everything again and you'll get

ℹ Generating pages
✔ Generated /blog/hello-world
✔ Generated /it/articoli/ciao-mondo
✔ Generated /es/artículos/hola-mundo
✔ Generated /es/
✔ Generated /it/
✔ Generated /
ℹ Ready to run nuxt serve or deploy dist/ directory
✨  Done in 33.82s.

Your full static generated blog with custom paths is ready 🎉

You can do more

In this repository you can see the complete code of this tutorial, the result is deployed on Netlify CDN at https://eager-shockley-a415b7.netlify.app/. Netlify is one of my favourite services that provides cloud hosting for static websites, offering continuous deployment, free SSL, serverless functions, and more... The final code adds some missing features to the website, for example it adds authors support, uses some external components omitted here for simplicity and enables SEO option to the project to add metadata to pages (see SEO section in nuxt-18n documentation).

Another useful thing included in the final code is the sitemap, provided by the Nuxt.js Sitemap module. Sitemap is easy to setup because it takes the generate.routes value by default, so dynamic routes will be automagically included. The configurations is really straightforward, just add @nuxtjs/sitemap at the end of modules array section of your nuxt.config.js file

  {
    modules: [
      // ...
      '@nuxtjs/sitemap'
    ],
  }

and configure the sitemap section

export default {
  // ...
  sitemap: {
    hostname: BASE_URL,
    gzip: true,
    i18n: DEFAULT_LOCALE
  }
  // ...
}

Checkout the Nuxt Community organization on Github for more awesome modules and projects!

Happy coding! 💚

Cover image by Marco Verch (CC BY 2.0)

VitePress 📝💨 VuePress clone built on top of Vite

Andrea Stagi — Fri, 01 May 2020 12:27:35 +0000

13 hours ago Evan You announced VitePress, "the VuePress' little brother, built on top of vite".

https://t.co/6X2EPXfCml
— Evan You (@youyuxi) April 30, 2020

VitePress has a lot improvements over VuePress, as you can deduce from the name it uses vite under the hood which involves really faster hot updates and a blazing fast dev server because it doesn't require any compilation with Webpack as in VuePress (that's possible because vite intercepts requests to .vue files and compiles them on the fly, and it's instantly fast). VitePress uses Rollup internally reducing the time of static site building and generates lighter pages thanks to Vue 3 tree-shaking and Rollup code splitting. Here you can find the complete list of all the improvements made by VitePress.

Try it!

VitePress is in early WIP and requires Nodejs >= 12 (I use 12.16.3 LTS). Install VitePress in your project

npm install -D vitepress

And create a simple markdown file

echo '# Hello VitePress' > index.md

To run the dev server

npx vitepress

To run a complete build

npx vitepress build

The generated static site is in .vitepress/dist.

You can easily override the main theme creating theme folder inside .vitepress with two files, Layout.vue

<template>
  <div class="theme-container">
    <h1>{{ $site.title }}</h1>
    <p>{{ $site.description }}</p>
    <Content/>
  </div>
  <Debug/>
</template>

<style>
.theme-container {
  font-family: Arial, Helvetica, sans-serif;
  color: #2f495e;
}
a {
  color: #00c58e;
}
</style>

And index.js

import Layout from './Layout.vue'

export default {
  Layout,
  NotFound: () => 'custom 404',
  enhanceApp({ app, router, siteData }) {}
}

I made a repository to try VitePress and its upcoming features!

Happy coding 👨🏻‍💻

Rate limiting using Python and Redis

Andrea Stagi — Mon, 27 Apr 2020 15:54:11 +0000

Rate limiting is a mechanism that many developers may have to deal with at some point in their life. It’s useful for a variety of purposes like sharing access to limited resources or limit the number of requests made to an API endpoint and respond with a 429 status code.

Here we’ll explore some rate limiting algorithms using Python and Redis, starting from a naive approach and culminate at an advanced one called Generic Cell Rate Algorithm (GCRA).

In the following article we'll use redis-py to communicate with Redis (pip install redis). I suggest you to clone my repository from GitHub to make some experiments with rate limiting.

Time Bucketed

A first approach for rate limiting a number of requests within a period is to use a time-bucketed algorithm, where a counter (initially set to limit) and expiry time (period) are stored for each rate-key (something unique like username or IP address) and decremented on subsequent requests.

Using Python and Redis we can implement time-bucket logic in this way:

check if the rate-key key exists
if key doesn't exist, initialize it to the limit value (Redis SETNX) and an expiration time period (Redis EXPIRE)
decrement this value on each subsequent requests (Redis DECRBY)
the request is limited only when key value drops below zero
after the given period the key will automatically be deleted

from datetime import timedelta
from redis import Redis


def request_is_limited(r: Redis, key: str, limit: int, period: timedelta):
    if r.setnx(key, limit):
        r.expire(key, int(period.total_seconds()))
    bucket_val = r.get(key)
    if bucket_val and int(bucket_val) > 0:
        r.decrby(key, 1)
        return False
    return True

You can see this code in action simulating requests with a limit of 20 requests / 30 seconds (to keep things clear I wrapped the function in a module as you can see in my repository).

import redis
from datetime import timedelta
from ratelimit import time_bucketed


r = redis.Redis(host='localhost', port=6379, db=0)
requests = 25

for i in range(requests):
    if time_bucketed.request_is_limited(r, 'admin', 20, timedelta(seconds=30)):
        print ('🛑 Request is limited')
    else:
        print ('✅ Request is allowed')

Only the first 20 requests won't be limited, you have to wait 30 seconds before being allowed to make a new request again.

The downside to this approach is it actually enforces a limit to the number of requests a user can do within a period rather than a rate. This means that the entire quota can be exhausted immediately, resetting only after the period has expired.

Leaky bucket

There's an algorithm that can take care of rate limiting and produces a very smooth rate limiting effect: the leaky-bucket approach. The algorithm works similarly to an actual leaky bucket: you can pour water (requests) in the bucket up to a maximum capacity while some amount of water is escaping at a constant rate (usually implemented using a background process). If the amount of water entering the bucket is greater than the amount leaving through the leak, the bucket starts to fill and when the bucket is full new requests are limited.

Video: Leaky Bucket Traffic Shaping

We can skip over this for a more elegant approach that doesn't require a separate process to simulate a leak: the Generic Cell Rate Algorithm.

Generic Cell Rate Algorithm

Generic Cell Rate Algorithm (GCRA) comes from a communications technology called Asynchronous Transfer Mode (ATM) and was used in ATM network’s schedulers to delay or drop cells, small fixed size packets of data, that came in over their rate limit.

GCRA works by tracking remaining limit through a time called the Theoretical Arrival Time (TAT) on each request

tat = current_time + period

and limit the next request if the arrival time is less than the stored TAT. This works fine if rate = 1 request / period where each request is separated by period, anyway in the real world we usually have rate = limit / period. For example with rate = 10 requests / 60 seconds a user would be allowed to make 10 requests in the first 6 seconds, with rate = 1 request / 6 seconds the user would have to wait 6 seconds between requests.

To be able to bunch requests in a short period of time and support limit requests within period with limit > 1, each request should be separated by period / limit and the next Theoretical Arrival Time (new_tat) calculated in a different way than before. Indicating with t the time of the request arrival

new_tat = tat + period / limit if requests bunch (t <= tat)
new_tat = t + period / limit if requests don’t bunch (t > tat)

hence

new_tat = max(tat, t) + period / limit.

The request is limited if new_tat exceeds the current time plus the period, new_tat > t + period. With new_tat = tat + period / limit we have

tat + period / limit > t + period

Hence, we should limit requests only when

tat — t > period — period / limit

       period — period / limit
      <----------------------->
--|----------------------------|--->
  t                           TAT

In this case TAT should not be updated, because limited requests don’t have a theoretical arrival time.

Now it's time to unveil the final code!

from datetime import timedelta
from redis import Redis


def request_is_limited(r: Redis, key: str, limit: int, period: timedelta):
    period_in_seconds = int(period.total_seconds())
    t = r.time()[0]
    separation = round(period_in_seconds / limit)
    r.setnx(key, 0)
    tat = max(int(r.get(key)), t)
    if tat - t <= period_in_seconds - separation:
        new_tat = max(tat, t) + separation
        r.set(key, new_tat)
        return False
    return True

In this implementation we use Redis TIME because GCRA is dependent on time and it’s crucial to make sure that the current time is consistent between multiple deployments (clock drift between machines could lead to false positives).

In the following script you can see GCRA in action with rate = 10 requests / 60 seconds

import redis
from datetime import timedelta
from ratelimit import gcra


r = redis.Redis(host='localhost', port=6379, db=0)
requests = 10

for i in range(requests):
    if gcra.request_is_limited(r, 'admin', 10, timedelta(minutes=1)):
        print ('🛑 Request is limited')
    else:
        print ('✅ Request is allowed')

The first 10 requests are allowed by GCRA, but you need to wait at least 6 seconds to make another request. Try to run the script after some time to see how it works and try to change limit and period (e.g. limit=1 and period=timedelta(seconds=6) 😉).

To keep GCRA implementation clear, I avoided to add a lock between get and set calls, but it's needed in case of multiple requests with the same key at the same time. Using Lua-based lock we can simply add a lock as a context manager.

def request_is_limited(r: Redis, key: str, limit: int, period: timedelta):
    period_in_seconds = int(period.total_seconds())
    t = r.time()[0]
    separation = round(period_in_seconds / limit)
    r.setnx(key, 0)
    try:
        with r.lock('lock:' + key, blocking_timeout=5) as lock:
            tat = max(int(r.get(key)), t)
            if tat - t <= period_in_seconds - separation:
                new_tat = max(tat, t) + separation
                r.set(key, new_tat)
                return False
            return True
    except LockError:
        return True

Check the complete code on GitHub.

Cover photo by Scott Granneman (CC BY-SA 2.0)

Continuous Integration and Deployment with TravisCI and Netlify

Andrea Stagi — Fri, 17 Apr 2020 20:43:08 +0000

The Continuous Integration/Continuous Deployment (CI/CD) pipeline is an automated sequence of events that you would otherwise need to perform manually: previewing your in-development site, testing your new code and deploying it live! In this tutorial we'll learn how to build a simple Vue app and deploy it using CI/CD with Github, TravisCI and Netlify, providing backend functionalities with Netlify Functions!

TravisCI is a hosted, distributed continuous integration service used to build and test projects on GitHub.

Netlify offers cloud hosting for static websites, providing continuous deployment, free SSL, serverless functions, and more... We will use Netlify in conjunction with GitHub to deploy our site ever ytime we push new code.

Create the app

Let's start creating a simple Vue app to display our personal repositories hosted on Github. Check the code here, this is the final result:

Users can click on tiles to navigate to the selected repository or click "Load more" to fetch other repositories.

Create the project with Vue CLI selecting Unit Testing, Typescript and Linter/Formatter, and use Jest for testing

vue create github-netlify

Create a component Repository that renders a box with repository url, name and description

<template>
  <a :href="repository.html_url">
    <h2>{{repository.name}}</h2>
    <p>{{repository.description}}</p>
  </a>
</template>

<script lang="ts">
import { Component, Prop, Vue } from 'vue-property-decorator';

@Component
export default class Repository extends Vue {
  @Prop() private repository!: any;
}
</script>

In the main App component (App.vue) call the Github endpoint https://api.github.com/users/USERNAME/repos to fetch all the public repositories belonging to a specific user and render them using the Repository component. To make the app configurable, store the username in an environment variable and declare it in .env file as VUE_APP_GITHUB_USER=astagi. Both Netlify and Vue support .env file so we can use it to store all the environment variables we need during local development! (Remember to add .env to .gitignore)

The result of this API call is a paginated list of repositories, to support pages add a button to load more pages and use the query parameter page.

<template>
  <div id="app">
    <h1>My Github repositories</h1>
    <Repository v-for="repository of repositories" :key="repository.id" :repository="repository"/>
    <button v-on:click="fetchRepositories()" :disabled="!loadMoreEnabled">Load more</button>
  </div>
</template>

<script lang="ts">
import { Component, Vue } from 'vue-property-decorator';
import axios from 'axios';
import Repository from './components/Repository.vue';

@Component({
  components: {
    Repository,
  },
})
export default class App extends Vue {

  private repositories: any[] = [];
  private page = 1;
  private loadMoreEnabled = true;

  private mounted() {
    this.fetchRepositories();
  }

  public fetchRepositories() {
    this.loadMoreEnabled = false;
    axios.get(`https://api.github.com/users/${process.env.VUE_APP_GITHUB_USER}/repos?page=${this.page}`)
      .then((resp) => {
        this.repositories = this.repositories.concat(resp.data);
        this.page += 1;
      })
      .finally(() => {
        this.loadMoreEnabled = true;
      });
  }
}
</script>

We only need to test fetchRepositories method, mocking axios requests with some fixture (they're very long, you can see the fixtures here)!

import { shallowMount } from '@vue/test-utils';
import Vue from 'vue'
import App from '@/App.vue';
import reposResponses from '../__fixtures__/reposResponses';
import axios from 'axios'


jest.mock("axios");

(axios.get as jest.Mock).mockImplementation((url) => {
  switch (url) {
    case `https://api.github.com/users/${process.env.VUE_APP_GITHUB_USER}/repos?page=1`:
      return Promise.resolve({data : reposResponses.page1});
    case `https://api.github.com/users/${process.env.VUE_APP_GITHUB_USER}/repos?page=2`:
      return Promise.resolve({data : reposResponses.page2});
  }
});

describe('App.vue component', () => {
  let wrapper: any;
  beforeEach(() => {
    wrapper = shallowMount(App);
  });
  it('renders repositories on mount', async () => {
    await Vue.nextTick();
    expect(wrapper.findAll('repository-stub').length).toEqual(30);
  });
  it('fetches other repositories on load more', async () => {
    await Vue.nextTick();
    wrapper.vm.fetchRepositories();
    await Vue.nextTick();
    expect(wrapper.findAll('repository-stub').length).toEqual(60);
  });
});

To run tests, execute

yarn test:unit

In addition to tests we need to setup Code Coverage, a measurement of how many lines, branches, statements of our code are executed while the automated tests are running. Activate code coverage in jest.config.js

module.exports = {
  preset: '@vue/cli-plugin-unit-jest/presets/typescript-and-babel',
  collectCoverage: true,
  collectCoverageFrom: ["src/**/*.vue", "!**/node_modules/**"]
}

And run tests again to see Code Coverage in action!

➜  github-netlify (master) ✗ yarn test:unit
yarn run v1.19.2
$ vue-cli-service test:unit
 PASS  tests/unit/app.spec.ts
 PASS  tests/unit/lambda.spec.ts
-----------------|----------|----------|----------|----------|-------------------|
File             |  % Stmts | % Branch |  % Funcs |  % Lines | Uncovered Line #s |
-----------------|----------|----------|----------|----------|-------------------|
All files        |      100 |      100 |      100 |      100 |                   |
 src             |      100 |      100 |      100 |      100 |                   |
  App.vue        |      100 |      100 |      100 |      100 |                   |
 src/components  |      100 |      100 |      100 |      100 |                   |
  Repository.vue |      100 |      100 |      100 |      100 |                   |
-----------------|----------|----------|----------|----------|-------------------|

Test Suites: 2 passed, 2 total
Tests:       5 passed, 5 total
Snapshots:   0 total
Time:        6.878s

Remember to add coverage folder to .gitignore!

Add Continuous Integration with TravisCI

Now that our code has tests, coverage and the minimal functionalities ready, it's time to setup TravisCI for Continuous Integration! Activate TravisCI Github integration and Codecov on the repository and add .travis.yml file to configure how TravisCI will work

language: node_js
node_js:
  - 10
before_script:
  - yarn add codecov
script:
  - yarn test:unit
after_script:
  codecov

Every time we push code on the repository, TravisCI will install codecov package to communicate with Codecov (before_script) and run tests for you (script), sending coverage data to Codecov (after_script).

Add backend functionalities

Calling Github API directly from the component is not the best way to get all the repositories. As you can read from Github API docs there is a better API endpoint to get personal repositories with a higher rate limit, https://api.github.com/user/repos, but it needs an authentication token to work. Getting a new token from Github is easy, but it must be kept secret and can't be exposed in frontend code, so we need a backend server to communicate with Github. Fortunately with Netlify Functions you can run AWS's serverless Lambda functions to run server-side code without having a dedicated server or an AWS account, with function management handled directly within Netlify. For more info have a look at Netlify Functions documentation

Setting up a lambda function with Netlify is really easy: add a folder called lambda to the root of the project and a file getmyrepos.js where the function resides

const axios = require('axios');


exports.handler = function(event, context, callback) {
  let responseHeaders = {
    'Content-Type': 'application/json'
  };
  if (process.env.NETLIFY_DEV === 'true') {
    responseHeaders['Access-Control-Allow-Origin'] = '*';
  }
  axios.get(`https://api.github.com/user/repos?visibility=public&page=${event.queryStringParameters.page}`, {
      headers : {
        'Authorization': `token ${process.env.GITHUB_TOKEN}`
      }
    })
    .then((response)  => {
      callback(null, {
        statusCode: 200,
        body: JSON.stringify(response.data),
        headers: responseHeaders
      });
    })
    .catch((error) => {
      callback(null, {
        statusCode: error.response.status,
        body: JSON.stringify({'message' : error.response.data.message}),
        headers: responseHeaders
      });
    });
}

We just need to export a handler method where we communicate with the Github API endpoint using axios, adding our Github token (stored in the environment variable GITHUB_TOKEN) to the headers and then return the response using callback function provided by Netlify! We also need event.queryStringParameters object to get query parameters, in this case page. For more info see how to build serverless functions in Netlify with JavaScript.

To run lambda functions locally, install Netlify CLI

sudo npm install netlify-cli -g

And add netlify.toml file in the root of the project

[dev]
  command = "yarn serve"
  functions = "lambda"

This file contains the dev environment configuration: lambda functions are placed in lambda folder and the command to run frontend app is yarn serve. To run the entire app in dev mode add GITHUB_TOKEN to the .env file and launch

netlify dev

Our Vue app now runs at http://localhost:8080 and lambda function at http://localhost:34567/getmyrepos. It's time to modify the app code and tests to integrate lambda function in our app! First of all add Access-Control-Allow-Origin=* header to the function response when the app is running in dev mode (NETLIFY_DEV environment variable is 'true') because Vue app and lambda service are exposed on different ports

  // ...
    let responseHeaders = {
      'Content-Type': 'application/json'
    };
    if (process.env.NETLIFY_DEV === 'true') {
      responseHeaders['Access-Control-Allow-Origin'] = '*';
    }
  // ...

Setup a new environment variable VUE_APP_BACKEND_ENDPOINT=http://localhost:34567 to define our backend endpoint and change the url to fetch repositories in the App.vue component and tests

  // ...
  axios.get(`${process.env.VUE_APP_BACKEND_ENDPOINT}/getmyrepos?page=${this.page}`)
    .then((resp) => {
      this.repositories = this.repositories.concat(resp.data);
      this.page += 1;
    })
  // ...

// ...
(axios.get as jest.Mock).mockImplementation((url) => {
  switch (url) {
    case `${process.env.VUE_APP_BACKEND_ENDPOINT}/getmyrepos?page=1`:
      return Promise.resolve({data : reposResponses.page1});
    case `${process.env.VUE_APP_BACKEND_ENDPOINT}/getmyrepos?page=2`:
      return Promise.resolve({data : reposResponses.page2});
  }
});
// ...

Lambda functions are easy to test as well! Let's test our function adding lambda/getmyrepos.d.ts definition to support TypeScript.

export declare function handler(event: any, context: any, callback: any): any;

import reposResponses from '../__fixtures__/reposResponses';
import axios from 'axios';
import { handler } from '@/../lambda/getmyrepos';


jest.mock('axios');

(axios.get as jest.Mock).mockImplementation((url) => {
  switch (url) {
    case `https://api.github.com/user/repos?visibility=public&page=1`:
      return Promise.resolve({data : reposResponses.page1});
    case `https://api.github.com/user/repos?visibility=public&page=2`:
      let err: any = {}
      err.response = {
        status: 401,
        data: {
          message: 'Bad Credentials'
        }
      }
      return Promise.reject(err)
  }
});

describe('Lambda function getmyrepos', () => {
  it('renders repositories on call page 1', (done) => {
    const event = {
      queryStringParameters : {
        page : 1,
      },
    };
    handler(event, {}, (e: any, obj: any) => {
      expect(obj.statusCode).toEqual(200);
      expect(obj.body).toEqual(JSON.stringify(reposResponses.page1));
      done();
    });
  });
  it('shows message error if any', (done) => {
    const event = {
      queryStringParameters : {
        page : 2,
      },
    };
    handler(event, {}, (e: any, obj: any) => {
      expect(obj.statusCode).toEqual(401);
      expect(obj.body).toEqual(JSON.stringify({message: 'Bad Credentials'}));
      done();
    });
  });
  it('renders repositories with Access-Control-Allow-Origin * in dev mode', (done) => {
    process.env.NETLIFY_DEV = 'true';
    const event = {
      queryStringParameters : {
        page : 1,
      },
    };
    handler(event, {}, (e: any, obj: any) => {
      expect(obj.headers['Access-Control-Allow-Origin']).toEqual('*');
      done();
    });
  });
});

Remember to add "lambda/*.js" to collectCoverageFrom in jest.config.js.

Add Continuous Deployment with Netlify

It's time to publish our site with Netlify! After logging in, click New site from Git and add the repository.

You can configure production branch, build commands, functions directly on Netlify or add them to netlify.toml. The simplest way to configure a project for CD is using a protected branch called production and configure Netlify to start building and publishing only when a new commit gets pushed on this branch. In Advanced build settings under Settings -> Build & Deploy you have to set environment variables, for example the VUE_APP_BACKEND_ENDPOINT changes in production: /.netlify/functions.

You can also use netlify.toml file to configure the build settings

[build]
  base = "/"
  publish = "dist"
  command = "yarn build"
  functions = "lambda"

[dev]
  command = "yarn serve"

Check the documentation for more settings available in file-based configuration.

For every pull request you make, Netlify deploys a site preview, accessible directly from the PR details.

I love using this flow, I can check the entire site using the preview before merging to production, but there are alternative ways to configure Continuous Deployment! For example you can setup a custom CD flow triggering builds using a build hook or you can use a Netlify instance to preview our site and another instance made with Netlify Drop for production, where you can host a site just dropping files on Netlify. Then configure TravisCI to build and deploy our site after tests pass on a specific branch, configuring deployment to act only on that branch (this configuration requires a Netlify token, you can create one following this article).