DEV Community: Welker Arantes Ferreira

Implementing OpenID Connect (OIDC) Authentication with Nuxt 3

Welker Arantes Ferreira — Mon, 30 Jan 2023 18:29:17 +0000

Intro

Recently i started migrating an application from Nuxt 2 to Nuxt 3, but when i faced the authentication part i got a little lost since there is still no official module for Nuxt 3. Moreover, when researching this topic i couldn't find much. So now that i have managed to overcome this challenge i decided to write a post explaining the step by step that i followed to implement the authentication flow. This tutorial includes:

The service class responsible for authenticating the user;
The Store responsible for storing the logged in user data in memory;
The service class responsible for communicating with the application back-end;
The middleware responsible for managing access to the application routes.

It is worth mentioning that here I am implementing an authentication flow that uses the authentication server as a Single Sign On tool, so the user will be redirected to a global authentication page and after being authenticated he will be redirected back to the application.

Requirements

To create a Nuxt 3 project you need to have a newer version of NodeJS installed, preferably version 16 or later. In addition, I recommend that if you are going to use VS Code as a code editor, install the Vue Language Features extension.

Creating the Nuxt 3 Project

Nuxt 3 comes with a CLI called Nuxi and it is through it that we will create the project with the command:

npx nuxi init nuxt-3-oidc

Then access the project folder and install the dependencies with the command:

npm install

To enable routing in nuxt 3 you need to create a directory called pages with at least one file index.vue inside. So let's create the application's home page:

// /pages/index.vue
<template>
  <div>
    <h3>Você está logado</h3>
    <NuxtLink to="logout">Sair</NuxtLink>
  </div>
</template>

In addition to creating the pages, in App.vue we need to use the NuxtPage component like this:

<template>
  <div>
    <NuxtPage />
  </div>
</template>

Now that we already have the base of the application working, let's implement the authentication class

Creating AuthService

To help us with the authentication flow, we are going to use the oidc-client-ts library, to install it run the following command:

npm install oidc-client-ts

Before implementing the service class, create a directory called services and inside it create the environment.ts file which will store the authentication settings:

// /services/environment.ts
export const environment = {
  production: false,
  authorityUrl: 'https://auth.papo-digital.net.br',
  clientId: 'papo-digital-app',
  clientSecret: 'blog-client',
  clientScope: 'openid profile posts',
  applicationUrl: 'https://api.papo-digital.net.br',
}

It is worth mentioning that this is not the most secure way to define the authentication settings. Here i am leaving in a file within the application just to make the example simpler, in a real application it is ideal to use environment variables.

Now, let's implement the AuthService:

// /services/auth-service.ts
import { User, UserManager, WebStorageStateStore } from 'oidc-client-ts'
import { environment } from './environment'

export default class AuthService {
  userManager: UserManager

  constructor() {
    const settings = {
      authority: environment.authorityUrl,
      client_id: environment.clientId,
      client_secret: environment.clientSecret,
      redirect_uri: `${window.location.origin}/auth`,
      silent_redirect_uri: `${window.location.origin}/silent-refresh`,
      post_logout_redirect_uri: `${window.location.origin}`,
      response_type: 'code',
      scope: environment.clientScope,
      userStore: new WebStorageStateStore(),
      loadUserInfo: true,
    }
    this.userManager = new UserManager(settings)
  }

  public signInRedirect() {
    return this.userManager.signinRedirect()
  }

  public signInCallback() {
    return this.userManager.signinCallback()
  }

  public renewToken(): Promise<void> {
    return this.userManager.signinSilentCallback()
  }

  public logout(): Promise<void> {
    return this.userManager.signoutRedirect()
  }

  public getUser(): Promise<User | null> {
    return this.userManager.getUser()
  }
}

In the constructor we mount the configuration object that is used in the initialization of the UserManager class, from the oidc-client-ts library. Explaining the methods better:

signInRedirect: This method redirects the user to the authentication server's login page
signInCallback: This method will be used in the auth.vue file that we will create later. It is responsible for receiving the tokens and user data after authentication
renewToken: This method will be used in the silent-refresh.vue file that we will create later. It is responsible for obtaining a new access_token when the user's token expires
logout: This method signals to the authentication server that the user is ending his session and redirects the user to the login page
getUser: This method allows access to the logged in user data stored in the storage of the oidc-client-ts library

Creating complementary pages of the authentication flow

Before we create the complementary pages, let's create a composable called useServices that will facilitate access to the service layer:

// /composables/useServices.ts
import AuthService from '@/services/auth-service'

export const useServices = () => {
  return {
    $auth: new AuthService(),
  }
}

Now that we have implemented the useServices, we need to create the complementary pages of the authentication flow that will use the AuthService methods. Let's start by creating the auth.vue page that will receive and store the user's data after authentication:

// /pages/auth.vue
<template>
  <h3>Carregando...</h3>
</template>

<script lang="ts" setup>
import { useServices } from '@/composables/useServices'

const services = useServices()
const router = useRouter()

const authenticateOidc = async () => {
  try {
    await services.$auth.signInCallback()
    router.push('/')
  } catch (error) {
    console.log(error)
  }
}

await authenticateOidc()
</script>

Next, let's create the logout.vue page:

// /pages/logout.vue
<template>
  <h3>Deslogando...</h3>
</template>

<script lang="ts" setup>
import { useServices } from '@/composables/useServices'
import { useAuth } from '@/stores/auth'

const services = useServices()
const authStore = useAuth()

const logOutOidc = async () => {
  try {
    authStore.clearUserSession()
    await services.$auth.logout()
  } catch (error) {
    console.log(error)
  }
}

await logOutOidc()
</script>

In the first line of the logOutOidc method we are calling a store method that doesn't exist yet, it will be implemented in the next topic.

Finally, we'll create the silent-refresh.vue page:

// /pages/silent-refresh.vue
<template>
  <h3>Carregando...</h3>
</template>

<script lang="ts" setup>
import { useServices } from '@/composables/useServices'

const services = useServices()
const router = useRouter()

const silentRefreshOidc = async () => {
  try {
    await services.$auth.renewToken()
    router.push('/')
  } catch (error) {
    console.log(error)
  }
}

await silentRefreshOidc()
</script>

Installing and configuring Pinia in Nuxt 3

now that we have the authentication service and the complementary pages let's configure the store, which will give us immediate access to the logged in user's data. In this case we are giving preference to Pinia instead of Vuex because the Nuxt documentation itself recommends that we use Pinia. Install it by running the command:

npm install pinia @pinia/nuxt

If there is any installation error you can add the dependencies manually, to do this just open the package.json file and in the dependencies section add these lines:

"dependencies": {
  "@pinia/nuxt": "^0.4.6",
  "pinia": "2.0.28"
}

After adding the dependencies, run the npm install command and wait until the installation is complete.

Next we need to register the Pinia module in the nuxt.config.ts file:

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

Now let's create the authStore that will allow us to transform localStorage data into reactive data:

// /stores/auth/index.ts
import { acceptHMRUpdate, defineStore } from 'pinia'
import { User } from 'oidc-client-ts'

export const useAuth = defineStore('auth', () => {
  const authUser = ref<User | null>(null)

  const access_token = computed(() => authUser.value?.access_token ?? '')

  const isLoggedIn = computed(() => !!authUser.value)

  const setUpUserCredentials = (user: User) => {
    authUser.value = user
  }

  const clearUserSession = () => {
    authUser.value = null
  }

  return {
    access_token,
    isLoggedIn,
    tenantId,
    setUpUserCredentials,
    clearUserSession,
  }
})

if (import.meta.hot) {
  import.meta.hot.accept(acceptHMRUpdate(useAuth, import.meta.hot))
}

Here is a valuable tip, the acceptHMRUpdate method enables Hot Module Replacement support in pinia allowing changes made to the Store code to be applied automatically without having to restart the application.

Configuring pages access control

The last part of the authentication flow consists of checking if the user is logged in before allowing him to access a certain page. To do this check we will create a middleware that will always be executed before rendering the application pages. In Nuxt 3 there are 3 ways to create a middleware, these are:

Inline: It is a function defined directly in the page where the middleware is used
Named: It is a .ts or .js file created in the middleware folder and needs to be invoked within the page that will be used
Global: It is a file created in the middleware folder similar to the named middleware, but this one has the .global suffix. Ex: user.global.ts

Here we will use the global middleware, because all pages require the user to be authenticated

// /middleware/auth.global.ts
import { User } from 'oidc-client-ts'
import { useAuth } from '@/stores/auth'
import { useSettings } from '@/stores/settings'

const authFlowRoutes = ['/auth', '/silent-refresh', '/logout']

export default defineNuxtRouteMiddleware(async (to, from) => {
  const authStore = useAuth()
  const services = useServices()
  const user = (await services.$auth.getUser()) as User

  if (!user && !authFlowRoutes.includes(to.path)) {
    services.$auth.signInRedirect()
  } else {
    authStore.setUpUserCredentials(user)
  }
})

Basically what is happening in this middleware is:

1 - If the user is not authenticated and is not accessing any complementary page of the authentication flow we redirect him to the login page (Single Sign On)
2 - If the user is logged in we pass his data to the store and let him access the requested page

Creating ApplicationService

To finish this tutorial we will implement the service class responsible for communicating with the back-end:

// /services/application-service.ts
import { environment } from './environment'

export default class ApplicationService {
  constructor(private readonly acessToken: string) {}

  getDefaultHeader() {
    return { Authorization: `Bearer ${this.acessToken}` }
  }

  async getPosts() {
    const headers = this.getDefaultHeader()

    const result = await $fetch(`${environment.applicationUrl}/v1/Posts/List`, {
      method: 'get',
      headers,
      query: { page: 1, size: 10 },
    })

    return result
  }
}

Here we receive in the constructor of the class the user's access_token that we store in the authStore and the getDefaultHeader method assembles the authentication header that will be sent in the requests. You may have noticed that we are not using Axios to make requests, but there is a reason. The Nuxt developers recommend that we use the Fetch API instead of axios in conjunction with Nuxt 3, they even provide a global method called $fetch that has a syntax very similar to Fetch API with the difference that this method works well in the Browser, in Nodejs and also in Web Workers, in other words it has good support for Server Side Rendering.

Now in order to use the ApplicationService in our pages we need to make a small adjustment in the composable useServices

// /composables/useServices.ts
...
import { useAuth } from "@/stores/auth";
import ApplicationService from "@/services/application-service";

export const useServices = () => {
  const authStore = useAuth();

  return {
    ...
    $application: new ApplicationService(
      authStore.access_token
    )
  };
};

Since the composables are executed within the context of Vue just like our pages and components, we can have access to the access_token stored in the authStore and thus pass it to the service class that communicates with the back-end. In addition, our middleware takes care of always saving the most updated token in the store, so when the authService executes the silent-refresh method the new token will already be saved in the store before the user accesses the requested page and that is why we access the service layer through this composable instead of instantiating the classes directly. Now we can access the methods of the ApplicationService class like this:

const services = useServices()
const posts = await services.$application.getPosts()

And thus we come to the end of this tutorial, I hope you enjoyed ;)

Edited

If interested, you can access the Github repository

Introdução ao Tailwind CSS - Do Zero ao Primeiro Projeto

Welker Arantes Ferreira — Wed, 23 Mar 2022 15:48:01 +0000

O Tailwind CSS vem ganhando bastante popularidade desde seu lançamento em Novembro de 2017. Desde então já foram geradas mais de 190 releases, além disso o projeto já conta com mais de 54 mil estrelas no GitHub. Mas apesar desta popularidade toda ainda existem muitos desenvolvedores que não sabem por onde começar. Se você é um destes desenvolvedores fique tranquilo, pois neste Post você aprenderá tudo que precisa para criar seu primeiro projeto com Tailwind CSS.

Introdução

Antes de colocarmos a mão na massa é importante entender o que é o Tailwind e qual é a filosofia por trás do framework, já que ele segue uma ideia bem diferente de outros frameworks CSS como o Bootstrap.

O que é Tailwind CSS?

O Tailwind é um framework CSS que segue a filosofia Utility First, ou seja, ao invés de ter componentes prontos como o Bootstrap ele te fornece várias classes utilitárias para que você mesmo construa seus componentes.

Diferenças entre Tailwind vs Bootstrap

Fazendo uma comparação entre as classes destes dois frameworks, é muito fácil perceber a diferença. Enquanto o Bootstrap tem classes como card, navbar e button que fornecem a estilização completa de um componente, o Tailwind tem classes como flex, flex-col, my-2, mx-2 onde cada classe representa mudanças bem menores na estilização de modo que combinando estas classes é possível construir layouts mais dinâmicos sem ter a necessidade de sobrescrever a estilização padrão do framework. Aliás, a ideia é que você nem precise escrever CSS.

Tailwind Playground

O Tailwind fornece um ambiente de playground para você se familiarizar com o framework sem ter que lidar com instalação ou configurações adicionais. Para acessar o playground acesse a página inicial do Tailwind, clique em Get Started e em seguida clique no link Playground localizado do lado esquerdo da tela.

Ao acessar o playground você perceberá que já existe algo criado, antes de apagar todo o conteúdo e começar a criar seus próprios layouts sinta-se a vontade para dar uma boa olhada nas classes que estão sendo utilizadas. Vale ressaltar que ao passar o cursor do mouse sobre as classes é possível ver as propriedades CSS que elas utilizam.

Criando um Balão de Notificação no Tailwind Playground

Agora que você já se familiarizou um pouco com o conceito de Utility First, vamos sair da teoria e ver na prática como construir um componente de notificação utilizando as classes do Tailwind. Para isso copie o código abaixo e cole no editor do playground:



<!-- container da página -->
<div class="w-screen h-screen bg-slate-100">
  <!-- balão de notificação -->
  <div class="p-4 max-w-sm mx-auto bg-white rounded-xl shadow-lg">
    <div>
      <h3 class="text-xl font-medium text-black">Notification</h3>
      <p class="text-slate-500">You have a new message!</p>
    </div>
  </div>
</div>

Se deu tudo certo você deve estar vendo algo como na imagem abaixo:

Na primeira div utilizei as classes w-screen e h-screen para ocupar toda a largura e altura disponíveis, em seguida utilizei a classe bg-slate-100 para aplicar uma cor de fundo.

Na segunda div utilizei a classe p-4 para aplicar um padding tando horizontal quanto vertical, a classe max-w-sm serve para limitar a largura do balão de notificação em 24rem, mx-auto aplica uma margem automática na horizontal centralizando o componente, bg-white muda a cor de fundo para branco, rounded-xl arredonda as bordas do componente e shadow-lg aplica um efeito de sombreamento.

No h3 eu utilizei a classe text-xl para aumentar o tamanho do texto, font-medium para dar mais destaque ao texto e text-black para mudar a cor do texto. No p eu utilizei a classe text-slate-500 para deixar o texto com uma cor mais clara.

Criando um projeto NuxtJS com Tailwind

Chegou o momento de criarmos um projeto real com Tailwind e fazermos algumas configurações customizadas.

Para criar um novo projeto NuxtJS abra seu terminal e digite o comando npx create-nuxt-app nome-do-projeto, assim que o CLI inicializar selecione as opções como na imagem abaixo:

Agora para instalar o Tailwind copie o código abaixo e cole no terminal:



npm install -D tailwindcss postcss@latest autoprefixer@latest @nuxt/postcss8

Em seguida execute o comando npx tailwindcss init para criar o arquivo tailwind.config.js

Abra o arquivo e edite a sessão content:



module.exports = {
  content: [
    './components/**/*.{js,vue,ts}',
    './layouts/**/*.vue',
    './pages/**/*.vue',
    './plugins/**/*.{js,ts}',
    './nuxt.config.{js,ts}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Abra o arquivo nuxt.config.js para habilitar o plugin postCSS e edite a sessão buildModules:



export default {
  buildModules: [
    '@nuxt/postcss8',
    // ...
  ],
}

Na sessão build adicione as seguintes configurações:



export default {
  build: {
    postcss: {
      plugins: {
        tailwindcss: {},
        autoprefixer: {},
      },
    },
  },
}

Crie um arquivo chamado main.css no caminho /assets/css/ e faça o import das camadas do Tailwind:



@tailwind base;
@tailwind components;
@tailwind utilities;

Por fim altere a sessão css do arquivo nuxt.config.js:



export default {
  css: ['@/assets/css/main.css'],
}

Com isso finalizamos a instalação do Tailwind no projeto. O próximo passo será customizar as configurações padrões do Tailwind para definirmos uma paleta de cores e a fonte do projeto.

Customizando o Tema Padrão do Tailwind

Alterando as configurações do arquivo tailwind.config.js é possível estender ou sobrescrever as definições padrão do Tailwind como cores, fontes e até mesmo os breakpoints de responsividade.

Adicionando Cores Personalizadas

Para adicionar novas cores ao Tailwind abra o arquivo tailwind.config.js e dentro da sessão extend adicione o código abaixo:



module.exports = {
  ...
  theme: {
    extend: {
      colors: {
        midnight: '#121063',
        metal: '#565584',
        'tahiti': {
          100: '#cffafe',
          200: '#a5f3fc',
          300: '#67e8f9',
          400: '#22d3ee',
          500: '#06b6d4',
          600: '#0891b2',
          700: '#0e7490',
          800: '#155e75',
          900: '#164e63',
        }
      }
    },
  }
}

As cores podem ser configuradas em formato de chave-valor como a cor midnight, ou em formato de objeto como a cor tahiti. A grande diferença é que o formato de objeto permite que sejam definidos vários tons para uma mesma cor, na prática significa que será possível utilizar a variação text-tahiti-500 por exemplo.

Adicionando Uma Nova Fonte

Para adicionar uma nova fonte é preciso fazer o download do arquivo da fonte e colocá-lo na pasta /assets/fonts. Em seguida abra o arquivo /assets/css/main.css e estenda a configuração de font-family na camada base do Tailwind como no exemplo abaixo:



@layer base {
  @font-face {
    font-family: 'Inter';
    src: url('../fonts/Inter-Regular.ttf') format('ttf');
    font-weight: 400;
    font-display: swap;
  }
}

Agora volte ao arquivo tailwind.config.js e adicione o código abaixo dentro da sessão extend:



module.exports = {
  ...
  theme: {
    extend: {
      ...
      fontFamily: {
        inter: 'Inter, sans-serif'
      }
    },
  },
  plugins: [],
}

Com isso podemos utilizar a classe font-inter para aplicar a fonte personalizada.

Dica Extra: Extensão Oficial para Visual Studio Code

A equipe do Tailwind desenvolveu uma extensão para o Visual Studio Code que habilita o recurso de auto complete das classes, além de exibir as propriedades CSS de cada classe quando passamos o cursor do mouse sobre elas da mesma forma que acontece no Tailwind Playground.

Para instalar a extensão acesse a guia de extensões do Visual Studio Code e pesquise por "Tailwind CSS IntelliSense" e instale a extensão exibida na imagem abaixo:

E assim chegamos ao fim deste tutorial, espero que você tenha gostado 😉

Comente aqui em baixo se você quer ver mais tutoriais sobre Tailwind 👇🏻👇🏻👇🏻

Fazendo deploy de sites Nuxt no Github Pages

Welker Arantes Ferreira — Tue, 26 Oct 2021 14:11:41 +0000

Introdução

Seja uma landing page, site pessoal ou até mesmo um portfólio, em todos estes casos o que você precisa é de um site estático. Neste tutorial eu vou mostrar como você pode publicar um site criado com Nuxtjs no Github Pages de uma forma bem fácil.

Criando o projeto

Para criar um novo projeto nuxt execute o comando abaixo no seu terminal:

npx create-nuxt-app nome-do-projeto

Assim que o CLI iniciar você pode selecionar as opções conforme desejar. Atente-se apenas à última etapa, que é referente à forma de renderização. Você deve selecionar a opção Static.

Configurando o Projeto

Para que seja possível publicar o projeto no Github Pages precisamos fazer algumas configurações. Primeiramente é preciso definir o "rootPath" da aplicação, para isso abra o arquivo nuxt.config.js e adicione esta linha de código:

router: { base: '/nome-do-projeto/' },

Substitua /nome-do-projeto/ pelo nome do repositório que você criou no Github. Caso ainda não tenha feito isso, crie um novo repositório e vincule-o ao seu projeto seguindo as instruções que o próprio Github te fornecerá.

Em seguida abra o arquivo package.json e adicione na lista de scripts o comando abaixo:

"scripts": {
  ...
  "deploy": "push-dir --dir=dist --branch=gh-pages --cleanup"
},

Por fim instale o pacote push-dir como dependência de desenvolvimento com o comando:

npm install push-dir --save-dev

Este pacote será responsável por pegar os arquivos compilados do site no diretório /dist e publicar no Github.

Configurando o Github Pages

Acesse o repositório que você criou no Github e crie um novo branch chamado gh-pages. Este branch será utilizado para armazenar os arquivos compilados do seu site.

Depois de criar o branch acesse a aba Settings, clique na opção Pages no menu lateral e na sessão Source selecione a branch gh-pages conforme descrito na imagem abaixo:

Fazendo o Deploy

Agora que você já configurou o projeto e o Github Pages, basta rodar estes comandos:

npm run generate

Este comando vai compilar o projeto e jogar os arquivos finais no diretório /dist. Caso você queira testar o resultado final antes de publicar o site é só rodar o comando npm start.

Agora para publicar o site execute este comando:

npm run deploy

Vale ressaltar que sempre que você fizer alterações no site será necessário executar os comandos npm run generate e npm run deploy para atualizar a versão publicada.

E assim chegamos ao fim deste tutorial, espero que tenha gostado ;)

Introdução a Testes Unitários com Jest e Vue Test Utils

Welker Arantes Ferreira — Sun, 24 Oct 2021 23:32:49 +0000

Introdução

A medida que evoluímos como desenvolvedores eventualmente chegará o momento de lidar com testes automatizados, é algo inevitável e que pode parecer bem intimidador a primeiro momento. Neste tutorial meu objetivo é te mostrar como você pode começar a testar seus componentes desde a configuração do projeto até a implementação de um componente de pesquisa.

Ferramentas Escolhidas

Neste tutorial utilizarei as libs Vue Test Utils e Jest para implementar os testes de unidade. Explicarei brevemente pra que serve cada lib antes de partirmos para o código:

Vue Test Utils

Este é o utilitário de testes oficial do Vuejs. Ele nos permite montar um componente em memória como se estivesse sendo renderizado no browser e a partir daí interagir com ele.

Jest

O Jest é um framework de testes para a linguagem Javascript desenvolvido pelo Facebook. Por ser escrito em Javascript ele funciona bem tanto no back-end com Nodejs quanto no front-end com frameworks como Vuejs, Angular e React. É o Jest que nos permite de fato testar a aplicação.

Criando o Projeto

Utilize o vue-cli para criar o projeto executando o comando abaixo:

vue create vue-tests

Selecione a primeira opção Default ([Vue 2, babel, eslint]) e pressione Enter.

Obs.: Caso queira, pode selecionar a opção Manually select features e então marcar a opção Unit Testing para adicionar automaticamente as ferramentas de teste ao seu projeto

Configurando Ferramentas de Teste

Se você adicionou o Jest na etapa anterior pode ignorar esta etapa do tutorial.

Seguindo as instruções de instalação da documentação só precisamos executar os comandos abaixo para instalar as ferramentas:

vue add unit-jest

npm install --save-dev @vue/test-utils

Agora precisamos criar um script dentro do arquivo package.json para manter o Jest executando e observando os testes unitários, para adicione o script abaixo no seu package.json:

"scripts": {
...
  "test:watch": "jest --verbose --watch"
}

Obs.: Caso ocorra erro EMFILE: too many open files ao executar os testes será necessário instalar o utilitário Watchman. Para fazer a instalação siga as instruções da documentação oficial.

Implementação inicial do projeto

Antes de começar a implementar os testes vamos criar o layout inicial do componente, assim garantimos que o visual do componente estará de acordo com o que planejamos. Este será um projeto bem simples onde implementaremos um input de pesquisa. Crie um novo diretório dentro de /components chamado search-input e dentro dele um arquivo index.vue com o código abaixo:

<template>
  <div class="input">
    <input type="text" placeholder="Pesquisar..." />

    <span class="input__clear">&times;</span>
  </div>
</template>

<script>
export default {

}
</script>

<style scoped>
.input {
  display: flex;
  width: 100%;
  position: relative;
}
.input input {
  width: 100%;
  padding: 8px 22px 8px 10px;
  font-size: 1rem;
  border: 1px solid #e3e3e3;
  background: #fafafa;
  border-radius: 6px;
  outline: none;
}
.input input:focus {
  border-color: rgb(109, 61, 255);
}

.input .input__clear {
  position: absolute;
  top: 6px;
  right: 6px;
  font-size: 18px;
  color: red;
}
.input .input__clear:hover {
  cursor: pointer;
}
</style>

Agora abra o arquivo App.js e substitua todo o código pelo código abaixo:

<template>
  <div id="app">
    <div class="component-box">
      <search-input />
    </div>
  </div>
</template>

<script>
import SearchInput from './components/search-input/index.vue'

export default {
  name: 'App',
  components: {
    SearchInput
  }
}
</script>

<style>
#app {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;

  width: 100%;
  height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
}

.component-box {
  width: 30%;
}
</style>

Agora rode a aplicação com o comando npm run serve e verifique se obteve um resultado semelhante ao da imagem abaixo:

Implementando os Testes

Agora finalmente podemos começar a implementar os testes a medida que implementamos as funcionalidades do componente. Para começar crie um diretório chamado __tests__ dentro do diretório search-input, destro deste novo diretório crie um arquivo chamado search-input.spec.js.

Para começar a implementação do primeiro teste copie o código abaixo e cole dentro do arquivo de teste:

import { mount } from '@vue/test-utils'
import SearchInput from '../index.vue'

describe('search-input - Unit', () => {
  it('should be a vue instance', () => {
    const wrapper = mount(SearchInput)

    expect(wrapper.vm).toBeDefined()
  })
})

precisamos importar o método mount de dentro da lib vue-test-utils, pois é ele que nos permite montar o componente e interagir com ele dentro dos testes. O describe define o início de uma nova suíte de testes. O método it define o primeiro teste da suíte. Na primeira linha do it utilizamos o mount para carregar o componente em memória e em seguida utilizamos o expect() do Jest para testar se o componente foi montado corretamente

Obs.: caso queira executar um teste isolado dentro de uma suíte de testes substitua o método it pelo fit

Para ver os testes rodando no seu terminal execute o comando abaixo:

npm run test:watch

Agora vamos voltar no App.vue e criar uma variável que será utilizada como v-model no componente search-input:

<template>
...
  <search-input v-model="search" />
</template>

<script>
...
data() {
    return {
      search: ''
    }
  }
</script>

Vamos alterar o componente para receber a prop que foi passada como v-model e uma computed property que será atualizada quando a prop for alterada e emitirá o evento de input sempre que algo for digitado no input:

<template>
  <div class="input">
    <input type="text" placeholder="Pesquisar..." v-model="searchQuery" />

    <span class="input__clear">&times;</span>
  </div>
</template>

<script>
export default {
  props: {
    value: {
      type: String,
      required: true
    }
  },
  computed: {
    searchQuery: {
      get() {
        return this.value
      },

      set(val) {
        this.$emit('input', val)
      }
    }
  }
}
</script>

Claro que o ideal é que se escreva os testes antes de fazer a implementação, porém quando estamos começando pode ser difícil alcançar este nível de abstração então neste tutorial farei a implementação antes dos testes para facilitar o entendimento.

Como declaramos uma prop que é obrigatória precisamos alterar o nosso primeiro teste para passar uma prop chamada value:

it('should be a vue instance', () => {
  const wrapper = mount(SearchInput,{
    propsData: {
      value: ''
    }
  })

  expect(wrapper.vm).toBeDefined()
})

Agora que temos parte da lógica do componente implementada vamos escrever mais testes. O próximo teste que vamos escrever será para verificar se o valor de searchQuery é alterado quando alteramos o valor da prop value:

it('should update searchQuery when prop value is changed', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    await wrapper.setProps({ value: 'test' })
    await wrapper.vm.$nextTick()

    expect(wrapper.vm.searchQuery).toEqual('test')
  })

Aqui utilizamos o método setProps para atualizar o valor da prop value e em seguida utilizamos o $nextTick para indicar que é preciso esperar até o próximo ciclo de vida para continuar a execução do teste.

O terceiro teste verificará se o evento de input é emitido quando algo é digitado no elemento input:

it('should emit input event when something is typed', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    const inputEl = wrapper.find('input[type="text"]')
    await inputEl.setValue('test')

    expect(wrapper.emitted().input).toBeTruthy()
    expect(wrapper.emitted().input[0]).toEqual(['test'])
  })

Neste teste utilizamos o método find para obter o elemento de input e então utilizamos o setValue para atribuir um valor ao elemento. Após preparar o cenário do teste utilizamos o método emitted para verificar se o evento de input foi disparado.

Agora que você já se familiarizou com a ideia de escrever testes unitários que tal começar a implementar os testes antes da funcionalidade?

Vamos criar um teste para verificar se o valor do input é limpo quando clicamos no ícone de X:

it('should clear input value when X icon is clicked', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    const clearBtn = wrapper.find('.input__clear')
    await clearBtn.trigger('click')

    expect(wrapper.emitted().input).toBeTruthy()
    expect(wrapper.emitted().input[0]).toEqual([''])
  })

Neste teste utilizamos o método find para acessar o botão de limpar e em seguida utilizamos o trigger para simular o evento de click no botão. Por último verificamos se o evento de input foi disparado com uma string vazia.

Obviamente o teste irá falhar já que não implementamos a funcionalidade. Para fazer o teste passar vamos implementar a funcionalidade de limpar o valor:

<template>
  ...
<span class="input__clear" @click="clearValue()">
  &times;
</span>
</template>

<script>
...
methods: {
  clearValue() {
    this.$emit('input', '')
  }
}
</script>

Conclusão

Se você chegou até aqui deve ter um resultado igual a este:

<template>
  <div class="input">
    <input type="text" placeholder="Pesquisar..." v-model="searchQuery" />

    <span class="input__clear" @click="clearValue()">&times;</span>
  </div>
</template>

<script>
export default {
  props: {
    value: {
      type: String,
      required: true
    }
  },
  computed: {
    searchQuery: {
      get() {
        return this.value
      },

      set(val) {
        this.$emit('input', val)
      }
    }
  },
  methods: {
    clearValue() {
      this.$emit('input', '')
    }
  }
}
</script>

<style scoped>
.input {
  display: flex;
  width: 100%;
  position: relative;
}
.input input {
  width: 100%;
  padding: 8px 22px 8px 10px;
  font-size: 1rem;
  border: 1px solid #e3e3e3;
  background: #fafafa;
  border-radius: 6px;
  outline: none;
}
.input input:focus {
  border-color: rgb(109, 61, 255);
}

.input .input__clear {
  position: absolute;
  top: 6px;
  right: 6px;
  font-size: 18px;
  color: red;
}
.input .input__clear:hover {
  cursor: pointer;
}
</style>

import { mount } from '@vue/test-utils'
import SearchInput from '../index.vue'

describe('search-input - Unit', () => {
  it('should be a vue instance', () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    expect(wrapper.vm).toBeDefined()
  })

  it('should update searchQuery when prop value is changed', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    await wrapper.setProps({ value: 'test' })
    await wrapper.vm.$nextTick()

    expect(wrapper.vm.searchQuery).toEqual('test')
  })

  it('should emit input event when something is typed', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    const inputEl = wrapper.find('input[type="text"]')
    await inputEl.setValue('test')

    expect(wrapper.emitted().input).toBeTruthy()
    expect(wrapper.emitted().input[0]).toEqual(['test'])
  })

  it('should clear input value when X icon is clicked', async () => {
    const wrapper = mount(SearchInput,{
      propsData: {
        value: ''
      }
    })

    const clearBtn = wrapper.find('.input__clear')
    await clearBtn.trigger('click')

    expect(wrapper.emitted().input).toBeTruthy()
    expect(wrapper.emitted().input[0]).toEqual([''])
  })
})

E assim chegamos ao fim deste tutorial, espero que tenha gostado ;)

Caso queira aprender mais sobre o Vue Test Utils pode dar uma conferida nos guias da própria documentação

Crie seu próprio tema para Visual Studio Code

Welker Arantes Ferreira — Mon, 17 May 2021 14:31:47 +0000

O Visual Studio Code acabou se tornando a principal ferramenta de trabalho de grande parte dos desenvolvedores, já que ele oferece um bom suporte para diversas linguagens de programação e pode ser customizado conforme o gosto de cada usuário graças às suas extensões. Sendo assim passamos horas olhando para nossos códigos e sem dúvida um bom tema de cores faz toda a diferença, então por que não criar seu próprio tema?

Neste artigo eu mostrarei passo a passo como criar e publicar um tema para o vscode.

Passo 0

Antes de colocarmos a mão na massa é necessário se cadastrar nos serviços que serão utilizados.

Theme Studio

O primeiro serviço que utilizaremos é o Theme Studio for VS Code. Esta ferramenta nos permitirá customizar as cores do vscode de forma visual. Para se cadastrar acesse este link

Azure DevOps

O Azure DevOps é um serviço fornecido pela Microsoft que contém todas as ferramentas para gestão de projetos de software, é possível gerenciar o código fonte, as sprints e até mesmo automatizar o deploy. Precisamos ter uma conta do Azure DevOps para que seja possível publicar nosso tema no marketplace do vscode. Dito isso, acesse este link e clique em start free para se cadastrar com uma conta microsoft ou start free with Github para usar sua conta do Github.

Visual Studio Marketplace

O último serviço que precisamos nos cadastrar é o Marketplace . Acesse este link para se cadastrar. Quando estiver preenchendo seus dados repare que será criado um publisher id, você precisará informá-lo na hora de publicar seu tema no marketplace.

Passo 1 - Preparação do ambiente

Agora que já criamos todas as contas necessárias, vamos instalar as ferramentas necessárias para a criação do tema. Primeiro vamos instalar as ferramentas para gerar o projeto base, então abra seu terminal e execute o comando abaixo:

npm install -g yo generator-code

Agora vamos instalar a ferramenta que nos permitirá publicar o tema no marketplace, para isso execute o comando abaixo:

npm install -g vsce

Passo 2 - Criando o tema base

Nesta etapa utilizaremos a ferramenta generator-code para criar toda a estrutura base do tema, para isso basta executar o seguinte comando no terminal:

yo code

Após executar o comando você deve ver no seu terminal algo parecido com a imagem abaixo:

Selecione New Color Theme e em seguida No, start fresh. Em seguida o assistente te perguntará algumas informações sobre o tema, preencha da seguinte forma:

What's the name of your extension? nome-do-tema
What's the identifier of your extension? nome-do-tema
What's the description of your extension? Breve descrição sobre o tema
What's the name of your theme shown to the user? Nome que será exibido para o usuário

Por último você precisa escolher se o seu tema será do tipo Dark ou do tipo Light. Agora é só esperar todos os arquivos serem gerados.

Passo 3 - customizando as cores

Finalmente chegamos na parte divertida, acesse o serviço Theme Studio, faça login e clique em Create new Theme. Você terá que escolher entre as opções Dark ou Light, aqui é importante selecionar a mesma opção que foi escolhida no passo anterior, em seguida clique em Create Theme. Agora você deve estar vendo uma tela como esta:

Na barra superior onde está escrito Untitled é exibido o nome do tema, clique sobre o nome para alterá-lo e coloque o nome que será exibido para o usuário. Do lado esquerdo existe um menu com 3 abas, sendo elas:

Colors: Nesta seção é onde customizamos os elementos principais como StatusBar, SideBar, Terminal, inputs e botões.
Editor: Nesta seção é onde customizamos as cores do editor de código em si, os balões de sugestões.
Syntax: Nesta seção é onde customizamos as cores do código como variáveis, classes, palavras chaves e strings.

Quando terminar as estilizações basta clicar no botão Save Theme localizado no canto superior direito.

Após fazer as customizações de cores e salvar o tema você será redirecionado para a página Your Themes.

Passo 4 - Preparando o tema para ser publicado

Agora que já finalizamos a personalização das cores, precisamos repassar estas configurações para o nosso tema base. Para isso acesse o Theme Studio, clique em Your Themes, passe o mouse sobre o tema que foi criado e clique no botão de download como exibido na imagem abaixo:

Abra a pasta do tema base no vscode e substitua o conteúdo do arquivo themes/color-theme.json pelo conteúdo do arquivo json que foi baixado. Para testar o tema antes de publicar pressione F5, isso iniciará o debug e abrirá uma nova janela do vscode com o tema aplicado.
Além do arquivo de cores podemos configurar também o ícone e cor de background que será exibido no marketplace. Estas configurações são feitas no arquivo package.json, a imagem abaixo mostra as opções disponíveis:

Outro arquivo importante é o README.md. Este arquivo funciona como a página inicial do seu tema, o conteúdo dele será exibido tanto no marketplace do vscode, quanto dentro do próprio vscode na aba de extensões.

Obs.: Vale lembrar que para exibir imagens neste arquivo é preciso hospedá-las em algum servidor com https

Passo 5 - Publicando o tema

Finalmente podemos publicar nosso tema. Para fazer isso acesse o Azure DevOps, clique no ícone de usuário e acesse a opção personal access token.

Clique em New Token e preencha o formulário conforme a imagem abaixo:

Ao clicar em create será gerado um novo token. Copie este token e salve em um lugar seguro, pois não será exibido novamente

Agora vá para o terminal, acesse o diretório do tema e execute o comando abaixo:

vsce login <publisher name>

Lembrando que Publisher Name é o seu Publisher ID que foi gerado no passo 0. Ao executar este comando o vsce pedirá o seu token, copie e cole o token que foi gerado no Azure DevOps. Em seguida execute o comando abaixo:

vsce publish

Pronto!!!
Se tudo correu bem você já poderá ver seu tema no marketplace e instalá-lo no vscode.

Dica Extra

O Theme Studio facilita bastante a customização das cores, mas pode ser que você queira definir configurações mais específicas. Neste caso o ideal é fazer o seguinte:

Pressione as teclas Ctrl + Shift + P (cmd + Shift + P se estiver usando Mac OS), e selecione a opção Developer: Inspect editor tokens and scopes como mostra a imagem abaixo.

Assim será possível saber o "escopo" a ser customizado, como os nomes de variáveis por exemplo. Copie o scope exibido

Em seguida abra o arquivo themes/color-theme.json e dentro da seção tokenColors procure pelo scope que você copiou para alterá-lo e, caso não exista é só criar um bloco de código como na imagem abaixo:

Explicando o bloco de código

name: É uma descrição que ajuda a identificar o bloco, pode nomear como preferir
scope: Aqui é onde deve ser informado o scope que você inspecionou
settings: Aqui é onde de fato fazemos a customização, podemos alterar a cor da fonte, a família da fonte e colocar o texto como negrito ou itálico
settings > foreground: Entenda foreground como cor da fonte

Referências

Theme Studio FAQ

Visual Studio Code - Create a new Color Theme

Visual Studio Code - Publishing Extensions

Criando documentos PDF com ReactJS

Welker Arantes Ferreira — Mon, 03 Aug 2020 00:06:08 +0000

Em aplicações empresariais é muito comum a necessidade de criar documentos em PDF, seja para exibir dados de um relatório ou mesmo para exportar informações exibidas em tela. Neste artigo irei mostrar como criar documentos PDF utilizando React e a biblioteca PdfMake.

Iniciando o projeto

Inicie um novo projeto react utilizando o comando:
yarn create react-app app-react-pdf
Caso você não tenha o Yarn instalado pode iniciar o projeto com o seguinte comando:
npx create-react-app app-react-pdf
Por fim adicione a biblioteca PdfMake ao projeto com o comando:
yarn add pdfmake
ou caso não esteja utilizando yarn utilize o seguinte comando:
npm install pdfmake —save
Como o foco principal deste artigo é a criação de documentos em PDF vou criar uma tela inicial bem simples, apenas com um botão para gerar o relatório.
O arquivo app.js ficou assim:



import React from 'react';
import logo from './logo.svg';
import './App.css';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Criando documentos PDF com ReactJS
        </p>        
      </header>
      <section className="App-body">
        <button className="btn">
          Visualizar documento
        </button>
      </section>
    </div>
  );
}

export default App;

Segue abaixo as regras de estilização definidas no arquivo app.css:



.App {
  text-align: center;
}
.App-logo {
  height: 40vmin;
  pointer-events: none;
}
.App-header {
  background-color: #282c34;
  min-height: 60vh;
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  font-size: calc(10px + 2vmin);
  color: white;
}
.App-body {
  height: 15vh;
  width: 100%;
  display: flex;
  justify-content: center;
  align-items: center;
}
.btn {
  padding: 10px 16px;
  font-size: 14px;
  background-color: transparent;
  border: 1px solid #61dafb;
  border-radius: 6px;
  color: #61dafb;
  font-weight: bold;
  transition: ease-in 0.3s;
}
.btn:hover {
  background-color: #61dafb;
  color: #fff;
  cursor: pointer;
}

Agora que já temos a base da nossa aplicação, podemos iniciar a criação do relatório. Primeiramente vamos criar um arquivo que servirá como fonte de dados.
Na pasta src crie um arquivo chamado data.js e cole o conteúdo abaixo dentro do arquivo:



export const data = [
  {
    nome: "Mousepad",
    qtdEstoque: 4,
    qtdVendido: 10,
  },
  {
    nome: "Teclado",
    qtdEstoque: 8,
    qtdVendido: 12,
  },
  {
    nome: "Monitor",
    qtdEstoque: 2,
    qtdVendido: 14,
  },
  {
    nome: "Mouse",
    qtdEstoque: 15,
    qtdVendido: 32,
  }  
];

No início do arquivo App.js importe a biblioteca PdfMake e o arquivo data.js que acabamos de criar



import React from 'react';
import logo from './logo.svg';
import './App.css';

import pdfMake from "pdfmake/build/pdfmake";
import pdfFonts from "pdfmake/build/vfs_fonts";
import { data } from './data';
pdfMake.vfs = pdfFonts.pdfMake.vfs;

Importe o arquivo Impressao.js que será criado posteriormente contendo o layout do relatório



import { Impressao } from './impressao';

No arquivo App.js crie a função que irá abrir o documento PDF em uma nova guia



const visualizarImpressao = () => {
    const classeImpressao = new Impressao(data);
    const documento = classeImpressao.gerarDocumento();
    pdfMake.createPdf(documento).open({}, window.open('', '_blank'));
  }

Agora chame a função no evento de clique do botão



<button className="btn" onClick={visualizarImpressao}>
  Visualizar documento
</button>

Implementando o documento PDF

O PdfMake utiliza a sintaxe de object literals para construir o layout dos documentos, e sua estrutura é dividida em 4 partes, sendo elas header, content, footer e styles.
Além disso possui um conjunto de elementos como Tabelas, parágrafos e listas, sendo que é possível estilizá-los passando as propriedades inline ou definindo-as dentro da propriedade styles.

Segue abaixo o código da classe de impressão:




export class Impressao {

  constructor(dadosParaImpressao) {
    this.dadosParaImpressao = dadosParaImpressao;
  }  

  async PreparaDocumento() {
    const corpoDocumento = this.CriaCorpoDocumento();
    const documento = this.GerarDocumento(corpoDocumento);
    return documento;
  }

  CriaCorpoDocumento() {
    const header = [
      { text: 'Nome Produto', bold: true, fontSize: 9, margin: [0, 4, 0, 0] },
      { text: 'Qtd. Estoque', bold: true, fontSize: 9, margin: [0, 4, 0, 0] },
      { text: 'Qtd. Vendido', bold: true, fontSize: 9, margin: [0, 4, 0, 0] },
    ];
    const body = this.dadosParaImpressao.map((prod) => {
      return [
        { text: prod.nome, fontSize: 8 },
        { text: prod.qtdEstoque, fontSize: 8 },
        { text: prod.qtdVendido, fontSize: 8 },
      ];
    });

    const lineHeader = [
      {
        text:
          '__________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________',
        alignment: 'center',
        fontSize: 5,
        colSpan: 3,
      },
      {},
      {},
    ];

    let content = [header, lineHeader];
    content = [...content, ...body];
    return content;
  }

  GerarDocumento(corpoDocumento) {
    const documento = {
      pageSize: 'A4',
      pageMargins: [14, 53, 14, 48],
      header: function () {
        return {
            margin: [14, 12, 14, 0],
            layout: 'noBorders',
            table: {
              widths: ['*'],
              body: [                             
                [
                  { text: 'RELATÓRIO DE VENDAS', style: 'reportName' }
                ]              
              ],
            },
          };
      },
    content: [
      {
            layout: 'noBorders',
            table: {              
              headerRows: 1,
              widths: [ '*', 55, 55 ],

              body: corpoDocumento
            }
          },
    ],
    footer(currentPage, pageCount) {
          return {
            layout: 'noBorders',
            margin: [14, 0, 14, 22],
            table: {
              widths: ['auto'],
              body: [
                [
                  {
                    text:
                      '_________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________________',
                    alignment: 'center',
                    fontSize: 5,
                  },
                ],
                [
                  [
                    {
                      text: `Página ${currentPage.toString()} de ${pageCount}`,
                      fontSize: 7,
                      alignment: 'right',
                      /* horizontal, vertical */
                      margin: [3, 0],
                    },
                    {
                      text: '© Lojinha de TI',
                      fontSize: 7,
                      alignment: 'center',
                    },
                  ],
                ],
              ],
            },
          };
        },
    styles: {
      reportName: {
        fontSize: 9,
        bold: true,
        alignment: 'center',
        margin: [0, 4, 0, 0],
      }
    },

  };
    return documento;
  }
}

O método PreparaDocumento chama o CriaCorpoDocumento que irá iterar os dados do arquivo data.js e devolverá o conteúdo da seção content do documento.

No método GerarDocumento é definido o layout do relatório. Na primeira linha é definido o tamanho da página na propriedade pageSaze. Em seguida definimos as configurações de margem do documento. A propriedade pageMargins é muito importante, pois é ela que determina o tamanho disponível para o header e o footer, já que a altura do header vai de 0 até a quantidade de margem do topo e com o footer é a mesma coisa.

A propriedade content contém uma tabela e seu conteúdo sãos os dados gerados pelo método CriaCorpoDocumento. Na propriedade footer foi declarada uma função que recebe a página atual e a quantidade de páginas. A função do footer retorna uma tabela em que a primeira linha contém um text com vários _ para criar uma linha bem sutil, e na segunda linha foram utilizados os parâmetros recebidos pela função para exibir um contador de páginas.

Se você chegou até aqui, então seu relatório em PDF deve ter ficado igual ao da imagem abaixo:

E assim concluímos este tutorial, espero que tenham gostado e até o próximo post.