Movendo de @nuxtjs/dotenv para configuração de tempo de execução

É hora de migrar do módulo @nuxtjs/dotenv para utilizar nossa nova configuração de tempo de execução que foi lançada com a versão 2.13 da Nuxt.

• O que são variáveis de ambiente
• Equívocos
• Porquê que nós precisamos do Webpack
• Como as variáveis de ambiente funcionam
• Introduzindo a configuração de tempo de execução da Nuxt
  • Os novos valores de configuração de tempo de execução são:
• Migrando de @nuxtjs/dotenv para a configuração de tempo de execução da Nuxt
• Migrando da propriedade env para a configuração de tempo de execução da Nuxt
• A propriedade env contra a configuração de tempo de execução
• Utilizando os teus valores de configuração
• Migrando os teus valores de configuração nos teus marcadores de script
• Migrando os teus valores de configuração nos teus modelos de marcação
• Suporte a Expansão e Interpolação
• Boas Práticas:
• O que fazer a seguir

O que são variáveis de ambiente

Em nossas aplicações de frontend, utilizamos APIs com frequência e integrações de terceiros que requerem que nós utilizemos dados de configuração que normalmente são fornecidas pelas variáveis de ambiente. Estas variáveis não devem ser expostas ao frontend visto que o ambiente do navegador é acessível por todos os visitantes. Ao invés disto, nós podemos guardar informação sensível, como chames e segredos, em ferramentas de integração continua protegidas por senha ou condutas de desdobramento. No entanto, quando estamos desenvolvendo aplicações localmente podemos não ter acesso às condutas de desdobramento e portanto precisamos de algum lugar para guardar estas variáveis de ambiente.

Equívocos

É muito fácil pensar que as tuas chaves secretas estão seguras ao colocá-las em algum lugar diferente o teu código-fonte tal como em um ficheiro .env, que fica muito fácil expor as tuas chaves secretas para pacotes no lado do cliente. Adicionar o teu ficheiro .env ao .gitignore significa que este ficheiro não será empurrado para teu controlo de versão e portanto não estará disponível para as pessoas olharem o que é importante se o teu repositório for público. No entanto, o ficheiro .env não é encriptado, e portanto colocar segredos em variáveis de ambiente na realidade não nos fornece um aumento em segurança e de fato ela só mantêm os dados sensíveis fora da vista. Uma opção de .env pode facilmente iludir programadores a exporem chaves secretas para pacotes no lado do cliente então sempre garanta que este ficheiro é adicionado ao teu ficheiro .gitignore.

Porquê que nós precisamos do Webpack

Aplicações isomorfas, de outro modo conhecidas como aplicações universais, precisam partilhar código entre ambos o servidor e o cliente. Babel é utilizada para compilar o nosso código JavaScript ES6 moderno para JavaScript ES5 assim ele pode funcionar em todas plataformas. Node.js que é um tempo de execução de JavaScript orientado a evento assíncrono que pode ser utilizado em computadores e servidores fora de um ambiente de navegador, utilize o sistema de módulo.

A utilização de módulos na Node.js é feita utilizando require, por exemplo require('lodash'). No entanto, o suporte do navegador para módulos continua incompleto e portanto precisamos ferramentas de empacotamento tais como Webpack para traduzir estes módulos para um código que os navegadores possam ler. Webpack basicamente torna o desenvolvimento no lado do cliente mais "parecida com a Node" com os mesmas semânticas do sistema de módulo. Isto significa que uma declaração require ou declaração import de ES6 resolverá da mesma maneira. E visto que as nossas aplicações não são apenas JavaScript mas também HTML, CSS e imagens que podemos exigir estas utilizando os carregadores da Webpack.

Como as variáveis de ambiente funcionam

No tempo de execução, a Node.js carrega as variáveis de ambiente automaticamente para process.env assim elas estão disponíveis para utilizar na tua aplicação. A referência às variáveis de ambiente são substituídas com o valor correto. Por exemplo, se tiveres uma chave API_SECRET com o valor de 'my-secret' então na tua aplicação onde tiveres utilizado process.env.API_SECRET esta seria substituída com o valor de 'my-secret'.

Os valores são lidos durante o tempo de construção e persistidos no pacote da Webpack. Portanto se mudarmos a nossa API_SECRET precisaremos reconstruir a nossa aplicação assim ela poderá ler o novo valor.

Introduzindo a configuração de tempo de execução da Nuxt

Nas versões da Nuxt acima 2.13 temos configuração de tempo de execução e suporte ao dotenv embutido fornecendo uma segurança melhor e desenvolvimento mais rápido! Duas novas opções são adicionadas ao ficheiro nuxt.config.js que permitirão a passagem da configuração de tempo de execução que está então acessível ao utilizar $config do contexto. Apesar da opção env, a configuração de tempo de execução é adicionada à carga (payload, em Inglês) da Nuxt assim não existe necessidade de reconstruir para atualizar a configuração de tempo de execução quando estiveres trabalhado em desenvolvimento ou com a interpretação no lado do servidor ou aplicações de página única. Ainda que para os sítios estáticos continuarás a precisar gerar novamente o teu sítio para ver estas mudanças.

export default {
  publicRuntimeConfig: {},
  privateRuntimeConfig: {}
}

Os novos valores de configuração de tempo de execução são:

• publicRuntimeConfig deve segurar todas as variáveis de ambiente que são públicas visto que estas serão expostas no frontend. Este poderia incluir por exemplo uma referência à tua URL pública.
• privateRuntimeConfig deve segurar todas as variáveis de ambiente que são privadas e que não devem ser expostas no frontend. Este poderia incluir por exemplo uma referência aos teus códigos secretos de API.

Migrando de @nuxtjs/dotenv para a configuração de tempo de execução da Nuxt

Se tiveres o módulo @nuxtjs/dotenv instalado então podes remover este módulo desinstalando-o e removendo-o da secção de módulos do teu ficheiro nuxt.config.js. Tu podes então migrar para configuração de tempo de execução da Nuxt adicionando as novas propriedades ao teu ficheiro nuxt.config.js. E então podes adicionar as tuas variáveis dos teus ficheiros .env as tuas propriedades de configuração de tempo de execução pública e privada assim a Nuxt consegue o acesso à estas variáveis em tempo de execução.

Se o teu ficheiro .env se parecer com algo como:

BASE_URL=https://v2.nuxt.com
API_SECRET=1234

Então migrando-a para a nova configuração de tempo de execução se pareceria com algo como:

export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL
  },
  privateRuntimeConfig: {
    apiSecret: process.env.API_SECRET
  }
}

Isto pode ser ainda mais simplificado utilizando um valor padrão no lugar de ter que manter o valor em ambas configuração de tempo de execução e ficheiro .env quando estiveres utilizando valores não sensíveis.

export default {
  publicRuntimeConfig: {
    baseURL: process.env.BASE_URL || 'https://v2.nuxt.com'
  }
}

Além disto pode ser uma substituição melhor para o .env.example e os valores padrão podem apontar para chaves e configurações de encenação.

export default {
  publicRuntimeConfig: {
    baseURL: process.env.NODE_ENV === 'production' ? 'https://v2.nuxt.com' : 'https://dev.nuxtjs.org'
  }
}

Migrando da propriedade env para a configuração de tempo de execução da Nuxt

Se tiveres as tuas variáveis de ambiente guardadas no teu ficheiro nuxt.config.js então podes migrar estas para utilizares as novas configurações de tempo de execução adicionando-as ao teu ficheiro nuxt.config.js.

Se as tuas variáveis de ambiente no teu nuxt.config.js se parecerem com algo como:

export default {
  env: {
    BASE_URL: 'https://v2.nuxt.com',
    API_SECRET: '1234'
  }
}

Então migrando-a para a nova configuração de tempo de execução se pareceria com algo como:

export default {
  publicRuntimeConfig: {
    baseURL: 'https://v2.nuxt.com'
  },
  privateRuntimeConfig: {
    apiSecret: process.env.API_SECRET
  }
}

A propriedade env contra a configuração de tempo de execução

Tu podes continuar a utilizar a propriedade env e ela ainda é útil para variáveis de ambiente que são exigidas no momento da construção mais do que no tempo de execução tal como NODE_ENV=staging ou VERSION=1.2.3. No entanto, para variáveis de ambiente de tempo de execução a configuração de tempo de execução é preferida visto que utilizar a propriedade env pode ser tão perigoso quanto utilizar o módulo dotenv incorretamente.

Utilizando os teus valores de configuração

Uma vez que tens guardado os teus valores em uma configuração de tempo de execução pública ou privada no teu ficheiro nuxt.config.js podes então acessar estes valores em qualquer lugar utilizando o contexto nas tuas páginas (pages), memória (store), componentes e extensões (plugins) utilizando this.$config ou context.$config.

<script>
  asyncData ({ $config: { baseURL } }) {
    const posts = await fetch(`${baseURL}/posts`)
      .then(res => res.json())
  }
</script>

E dentro do teus modelos de marcação (templates) podes acessá-lo diretamente utilizando {{ $config.* }}

<template>
  <p>Our Url is: {{ $config.baseURL}}</p>
</template>

Migrando os teus valores de configuração nos teus marcadores de script

Se já estiveres utilizando a variável de ambiente (env) nos teus marcadores de script tal como em dados assíncronos (async data)

async asyncData ({ env }) {

então podes só substituir env por $config quando estiveres passando o contexto. Cá também passamos a chave da configuração que queremos acessar. Neste caso baseURL.

async asyncData ({ $config: { baseURL } }) {

Então ao invés de utilizar env.apiURL

const posts = await fetch(`${env.baseURL}/posts`)

podes utilizar baseURL direto no teu código visto que já passamos este para a opção de configuração acima e portanto não temos que referenciar $config na nossa requisição.

const posts = await fetch(`${baseURL}/posts`)

Migrando os teus valores de configuração nos teus modelos de marcação

Se tiveres código que está utilizando as variáveis de ambiente podes migrar para utilizar a opção $config. Por exemplo se no teu código tinhas

<p>{{process.env.baseURL}}</p>

Podes mudar isto para utilizar $config no lugar

<p>{{$config.baseURL}}</p>

Suporte a Expansão e Interpolação

A expansão para configuração de tempo de execução só acontece se já houver uma chave.

API_SECRET=1234

export default {
  privateRuntimeConfig: {
    API_SECRET: ''
  }
}

A interpolação permite o encaixamento de variáveis de ambiente.

BASE_URL=/api
PUBLIC_URL=https://v2.nuxt.com

export default {
  privateRuntimeConfig: {
    baseURL: '${PUBLIC_URL}${BASE_URL}'
  }
}

Boas Práticas:

O que fazer a seguir