GraphQL no Front-end com Vue.js: Type Safety Automática com Codegen

A adoção do GraphQL no front-end traz benefícios quando combinada com ferramentas de geração de código. Neste artigo, vou compartilhar como implementamos GraphQL com Vue.js utilizando GraphQL Code Generator e Vue Apollo Composable , alcançando type safety completa e automaticamente.

O Problema da Tipagem Manual

Em aplicações tradicionais REST + TypeScript, é comum manter tipos duplicados:

Backend define os tipos
Frontend precisa recriar manualmente esses tipos
Mudanças no backend desativar atualização manual no front
Riscos de inconsistência e erros em tempo de execução

Uma Solução: GraphQL + Gerador de Código

GraphQL Code Generator transforma suas consultas e mutações em código TypeScript totalmente tipado, usando o esquema como fonte única da verdade .

Principais vantagens

1. Tipo de segurança de ponta a ponta

Tipos gerados automaticamente do backend ao frontend
Garantias em tempo de compilação
Autocomplete completo na IDE

2. Detecção Automática de Breaking Changes

Mudanças no esquema são bloqueadas instantaneamente
Erros de compilação quando tipos ficam desatualizados
Impossível usar campos que não foram solicitados na consulta

3. Produtividade Acelerada

Eliminação de trabalho manual de criar tipos
Foco no desenvolvimento da lógica de negócio
Composables prontos para uso com reatividade do Vue

4. Experiência do desenvolvedor superior

Documentação embutida na IDE
Validação em tempo real
Redução significativa de bugs

Configuração no Projeto

1. Configuração do Gerador de Código GraphQL

// codegen.ts 
import  type { CodegenConfig } from  '@graphql-codegen/cli'

const  config : CodegenConfig = { 
  overwrite : true , 
  schema : ` ${process.env.VITE_API_SERVICE_URL} /graphql` , 
  documents : [ 'src/graphql/**/*.gql' ], 
  generates : { 
    'src/generated/graphql.ts' : { 
      plugins : [ 
        'typescript' , 
        'typescript-operations' , 
        'typescript-vue-apollo'
       ], 
      config : { 
        withCompositionFunctions : true , 
        vueApolloComposableImportFrom : '@vue/apollo-composable' , 
        vueCompositionApiImportFrom : 'vue' , 
        skipTypename : true , 
        dedupeOperationSuffix : true , 
        documentMode : 'documentNode'
       } 
    } 
  } 
}

2. Definindo Consultas GraphQL

# src/graphql/queries/GetProducts.gql 
query GetProducts ( 
  $offset : Int ! 
  $limit : Int ! 
  $search : String 
  $category : String 
)  {
   getProducts ( 
    input :  { 
      offset :  $offset 
      limit :  $limit 
      search :  $search 
      category :  $category 
    } 
  )  {
     data {
       id 
      name 
      description 
      price 
      category 
      inStock 
      createdAt 
    }
     total 
  } 
}

3. Arquivo Gerado Automaticamente

O Code Generator cria tipos e composables prontos para uso:

// src/generated/graphql.ts (gerado automaticamente) 
export  type  GetProductsQueryVariables = Exact <{ 
  offset : Scalars [ 'Int' ][ 'input' ]; 
  limit : Scalars [ 'Int' ][ 'input' ]; 
  search?: InputMaybe < Scalars [ 'String' ][ 'input' ]>; 
  category?: InputMaybe < Scalars [ 'String' ][ 'input' ]>; 
}>;

export  type  GetProductsQuery = { 
  getProducts : { 
    data : Array <{ 
      id : string ; 
      name : string ; 
      description?: string | null ; 
      price : number ; 
      category : string ; 
      inStock : boolean ; 
      createdAt : string ; 
    }>; 
    total : number ; 
  }; 
}; 
export  function  useGetProductsQuery ( 
  variables: GetProductsQueryVariables | VueCompositionApi.Ref<GetProductsQueryVariables>, 
  options?: VueApolloComposable.UseQueryOptions<GetProductsQuery, GetProductsQueryVariables>
 ) { /* ... */ }

Usando no Componente Vue

Aqui está um exemplo real de como usar os elementos que podem ser compostos gerados:

< template > 
  < div > 
    < SearchInput  
      v-model = "searchTerm" 
      placeholder = "Buscar produtos..."
     /> 
    
    < LoadSpinner  v-if = "loading" /> 
    
    < ErrorMessage  
      v-if = "errorExist" 
      message = "Não foi possível carregar os produtos"
     /> 
    
    < ProductList  :products = "products" /> 
  </ div > 
</ template >

<script setup lang= "ts" > 
import { ref, computed } from  'vue' 
import { useGetProductsQuery } from  '@/generated/graphql' 
// Estado reativo 
const searchTerm = ref ( '' ) 
const products = ref ([]) 
const errorExist = ref ( false ) 
// Variáveis da query (reativas) 
const queryVariables = computed ( () => ({ 
  offset : 0 , 
  limit : 20 , 
  search : searchTerm.value , category 
  : ' electronics'
 })) 
// Composable gerado automaticamente com tipos completos 
const { loading, onResult, onError } = useGetProductsQuery ( 
  queryVariables, 
  { 
    fetchPolicy : ' cache - and-network' }
   ) 
// 
Handlers com tipos inferidos automaticamente onResult 
( ( result ) => {   // result.data é 
  totalmente tipado! products.value = result.data.getProducts.data.map ( produto => ({ id : produto. id , título : produto. nome , subtítulo : produto. descrição || 'Sem descrição' , preço : produto. preço , disponível : produto. em estoque   })) }) onError ( ( erro ) => {   erroExist. valor = true console . erro ( 'Erro ao carregar produtos:' , erro) }) </script>

Benefícios Autocomplete Inteligente

Ao acessar result.data.getProducts.data[0]., o IDE sugere apenas os campos que você solicita na consulta do GraphQL. Se tentar acessar um campo não solicitado, erro de compilação!

Refatoração Segura

Mudou o nome de um campo no backend? O TypeScript acusará erro em todos os lugares onde aquele campo é usado no front-end.

Validação de Variáveis

As variáveis da consulta são validadas no tempo de construção. Tipos errados ou campos obrigatórios faltando = erro antes mesmo de rodar o código.

Reatividade Nativa do Vue

Os composables gerados se integram perfeitamente à Composition API, suportando ref, computede toda a reatividade do Vue 3.

Fluxo de trabalho de desenvolvimento

Designer cria/atualiza uma consulta GraphQL em.gql
Roda o codegen :npm run codegen
Importar o composable gerado sem componente
TypeScript garante que tudo está correto
IDE oferece preenchimento automático completo

Mutações com Segurança de Tipo

O mesmo vale para mutações:

< script  setup  lang = "ts" > 
import { useCreateProductMutation } from '@/generated/graphql'

const { mutate : createProduct, loading, onDone } = useCreateProductMutation () 
const  handleSubmit = async ( formData ) => { 
  await  createProduct ({ 
    input : { name 
      : formData.name , price 
      : formData.price , // TypeScript valida todos os campos!     }   }) } onDone ( ( result ) => { // result totalmente tipado console.log ( ' Produto criado : ' , result.data.createProduct.id ) } ) </script>

Conclusão

A combinação de GraphQL + Code Generator + Vue Apollo Composable oferece:

✅ Zero esforço manual para manter tipos sincronizados
✅ Detecção automática de alterações quebradas
✅ Developer Experience superior com autocomplete total
✅ Type safety end-to-end do backend ao UI
✅ Integração perfeita com Vue 3 Composition API
✅ Menos bugs em produção

Se você usa GraphQL no front-end sem gerador de código, está perdendo uma das maiores vantagens da tecnologia. A produtividade e a segurança que essa pilha oferece transformam completamente o desenvolvimento de aplicações modernas.

Quer saber mais?

De 0 a 10, o quanto você recomendaria este artigo para um amigo?

Powered by: