Usar o TypeScript para Cloud Functions

Para desenvolvedores que preferem escrever funções no TypeScript, o Cloud Functions apresenta dois tipos de suporte:

  • Criar e configurar projetos do TypeScript para transcompilação automática na inicialização (firebase init functions).
  • Transcompilar a fonte do TypeScript existente para JavaScript no momento da implantação por um hook de pré-implantação.

Seguindo as instruções deste guia, você poderá migrar um projeto existente do JavaScript para o TypeScript e continuar implantando funções usando um hook de pré-implantação para transcompilar seu código-fonte. O TypeScript oferece muitos benefícios em comparação ao Vanilla JavaScript ao escrever funções. Alguns exemplos são:

  • O TypeScript é compatível com os recursos mais recentes do JavaScript, como dessincronizar/aguardar, o que simplifica o gerenciamento de promessas.
  • Um linter do Cloud Functions destaca os problemas comuns durante a codificação.
  • A segurança de tipo evita erros de tempo de execução nas funções implantadas.

Se você é iniciante no TypeScript, consulte TypeScript em 5 minutos.

Como inicializar um novo projeto do Cloud Functions com TypeScript

Executar firebase init functions em um novo diretório. A ferramenta oferece opções para criar o projeto com JavaScript ou TypeScript. Escolha TypeScript para ter como resultado a seguinte estrutura de projeto:

myproject
 +- functions/     # Directory containing all your functions code
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- tsconfig.json
      |
      +- .eslintrc.js # Optional file if you enabled ESLint
      +- tsconfig.dev.json # Optional file that references .eslintrc.js
      |
      +- src/     # Directory containing TypeScript source
      |   |
      |   +- index.ts  # main source file for your Cloud Functions code
      |
      +- lib/
          |
          +- index.js  # Built/transpiled JavaScript code
          |
          +- index.js.map # Source map for debugging

Depois que a inicialização for concluída, retire o comentário da amostra em index.ts e execute npm run serve para ver uma função "Hello World" em ação.

Usando um projeto existente do TypeScript

Se você já tiver um projeto doTypeScript, poderá adicionar um gancho de pré-implantação para garantir que o projeto seja transcompilado toda vez que você implantar seu código no Cloud Functions para Firebase. Você precisará de um arquivo tsconfig.json devidamente formado e um projeto do Firebase, além de realizar todas as modificações abaixo nas configurações do Firebase:

  1. Edite o package.json para adicionar um script de bash e criar seu projeto do TypeScript. Exemplo:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  2. Edite o firebase.json para adicionar um gancho de pré-implantação e executar o script de compilação. Exemplo:

     {
       "functions": {
         "predeploy": "npm --prefix functions run build",
       }
     }
    

Com essa configuração, um comando firebase deploy --only functions cria seu código do TypeScript e o implanta como funções.

Como migrar um projeto existente do JavaScript para o TypeScript

Caso você já tenha um projeto do Cloud Functions que foi inicializado e desenvolvido usando JavaScript, será possível migrá-lo para o TypeScript. Antes de iniciar, recomendamos que você crie um ponto de verificação git ou outro backup.

Para migrar um projeto existente do Cloud Functions em JavaScript, siga as seguintes etapas:

  1. Crie um ponto de verificação git e salve cópias dos arquivos de origem do JavaScript existentes.
  2. No diretório do projeto, execute o comando firebase init functions e selecione TypeScript quando aparecer a opção para informar a linguagem em que você escreverá as funções.
  3. Selecione Não quando aparecer uma mensagem perguntando se você quer substituir o arquivo package.json existente, a menos que não queira mantê-lo.
  4. Exclua index.ts no diretório functions/src e coloque seu código-fonte no lugar dele.
  5. No arquivo tsconfig.json criado na inicialização, defina as opções do compilador para permitir JavaScript: "allowJs": true.
  6. Copie o arquivo package.json salvo no diretório functions e edite-o para definir "main" como "lib/index.js".
  7. Ainda no arquivo package.json, adicione um script de compilação no TypeScript, como mostrado abaixo:

     {
       "name": "functions",
       "scripts": {
         "build": "npm run lint && tsc"
       }
     ...
    
  8. Adicione "typescript" como uma dependência dev executando npm install --save-dev typescript @typescript-eslint/eslint-plugin @typescript-eslint/parser.

  9. Para todas as dependências, execute npm install --save @types/<dependency>.

  10. Reescreva o código-fonte de .js para .ts conforme desejado.

Emular funções do TypeScript

Para testar localmente as funções do TypeScript, você pode usar as ferramentas de emulação descritas em Executar funções localmente. É importante compilar seu código antes de usar essas ferramentas. Portanto, execute npm run build dentro do diretório de funções antes de executar as funções firebase emulators:start ou firebase functions:shell. Como alternativa, execute npm run serve ou npm run shell como um atalho. Esses comandos executam a versão e exibem/iniciam o shell de funções.

Registros de funções para projetos do TypeScript

Durante o processo firebase deploy, o index.ts do seu projeto é transcompilado para index.js. Isso significa que o registro do Cloud Functions mostrará os números de linha do arquivo index.js e não do código que você escreveu. Para facilitar a localização dos caminhos e dos números de linha correspondentes no index.ts, o processo firebase deploy cria functions/lib/index.js.map. Use esse mapa de origem no seu ambiente de desenvolvimento integrado favorito ou com um módulo de nó.