vite-plugin-viacep

Plugin Vite para consulta de CEP e pesquisa de endereco usando o Web Service ViaCEP.

Ele injeta o modulo virtual virtual:viacep, que pode ser usado em qualquer app Vite: Vue, React, Svelte, Vanilla ou outro framework.

Instalar

npm install vite-plugin-viacep

Configurar

import { defineConfig } from 'vite';
import viaCep from 'vite-plugin-viacep';

export default defineConfig({
  plugins: [
    viaCep()
  ]
});

Com proxy no servidor de desenvolvimento:

import { defineConfig } from 'vite';
import viaCep from 'vite-plugin-viacep';

export default defineConfig({
  plugins: [
    viaCep({
      devProxy: true,
      proxyPath: '/__viacep'
    })
  ]
});

Com devProxy: true, o modulo virtual usa /__viacep/... durante o dev server. Em producao, configure um endpoint equivalente no seu backend ou use o modo direto sem proxy.

Tipos do modulo virtual

Adicione em src/vite-env.d.ts:

/// <reference types="vite-plugin-viacep/dist/virtual" />

Uso

import { fetchCep, searchAddress, isValidCep, formatCep } from 'virtual:viacep';

if (isValidCep('01001000')) {
  const address = await fetchCep('01001000');
  console.log(address.logradouro, address.localidade, address.uf);
}

const results = await searchAddress({
  uf: 'RS',
  cidade: 'Porto Alegre',
  logradouro: 'Domingos Jose'
});

console.log(results.map((item) => `${formatCep(item.cep)} ${item.logradouro}`));

API

fetchCep(cep)

Consulta um CEP no formato de 8 digitos. Mascara como 01001-000 tambem funciona porque o plugin remove caracteres nao numericos antes de validar.

searchAddress({ uf, cidade, logradouro })

Pesquisa CEPs por endereco. Regras:

• uf: 2 letras.
• cidade: minimo de 3 caracteres.
• logradouro: minimo de 3 caracteres.
• O ViaCEP limita o retorno a 50 resultados.

Erros

As funcoes lancam ViaCepError com code:

• INVALID_CEP
• INVALID_ADDRESS
• NOT_FOUND
• REQUEST_FAILED

Build local

npm install
npm run typecheck
npm run build
npm pack --dry-run