Crie PWAs com Vite: Um Guia Simples Passo a Passo para Iniciantes 📖
- Introdução
- Acesse e Teste 🌐
- Instale Localmente 🛠️
- Criação do Projeto com Vite 🚧
- Instalação do Plugin VitePWA ⚙️
- Adição de Requisitos Mínimos Para PWA
- Deploy da Sua PWA 🚀
Progressive Web Apps (PWAs) são páginas que podem ser instaladas diretamente do navegador, proporcionando experiências nativas sem a complexidade de lojas de aplicativos. Este repositório visa ensinar a criação delas.
-
Ao seguir o guia fornecido neste README, você poderá transformar qualquer projeto gerado com Vite em uma PWA totalmente funcional. No repositório, há um exemplo prático usando o aplicativo padrão de contador.
Esta aplicação está hospedada no GitHub Pages. Acesse Aqui.
É possível abrir no navegador, instalar no seu computador ou celular, realizar o teste do Lighthouse e ver que está tudo de acordo e pronto para ser uma PWA.
- Clonando o Repositório
git clone https://github.com/IgorFerreiraMoraes/Vite-PWA-Tutorial
cd Vite-PWA-Tutorial
- Instalando Dependências
npm install
- Visualizando o Resultado
npm run build
npm run preview
O Service Worker (SW) é criado ao construir a aplicação, por isso não funciona apenas com npm run dev.
- Para começar, execute o comando:
Ele inicia um novo projeto Vite na versão mais recente.
npm create vite@latest - Em seguida, siga as instruções para:
- Dar um nome ao projeto
- Definir um framework/biblioteca entre Vanilla, Vue, React, Svelte e outros
- Escolher entre JavaScript e TypeScript
- Instale as dependências
cd nome-do-projeto npm install
Instalação do Plugin VitePWA ⚙️
Este plugin gera o Web Manifest, que define como a aplicação aparece nos dispositivos, e o Service Worker, que permite tarefas em segundo plano.
-
Instale o plugin como dependência de desenvolvimento:
npm install -D vite-plugin-pwa -
Se o projeto foi gerado como vanilla, é necessário criar um arquivo
vite.config.js/vite.config.ts, conforme a linguagem escolhida, na pasta raíz. Caso contrário, apenas acesse o arquivo existente. -
No arquivo de configuração do Vite, é preciso o seguinte:
import { defineConfig } from 'vite'; import { VitePWA } from 'vite-plugin-pwa'; export default defineConfig({ plugins: [ VitePWA({ registerType: 'autoUpdate' }), ], });Se algum framework estiver sendo usado, haverá um import do seu plugin correspondente, que estará na lista de plugins. Mantenha a configuração inicial e adicione o VitePWA.
Sem esses ítens essenciais, os navegadores não reconhecerão a aplicação como PWA e não será possível instalá-la. Também preciso frizar que existem outras características que podem ser adicionadas a uma aplicação / página. Para saber mais, entre aqui.
-
A seção
<head>do arquivoindex.htmldeve conter os seguintes elementos:- Título
- Descrição
- Viewport
- Favicon
- Ícone para Apple Touch 180x180 (Pode ser o próprio favicon)
- Cor Tema
Por exemplo, um modelo de como ficaria o
<head>:<head> <meta charset="UTF-8" /> <title>Título da Aplicação</title> <meta name="description" content="Descrição da aplicação" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <link rel="icon" type="image/svg+xml" href="/vite.svg" /> <link rel="apple-touch-icon" href="/vite.svg" sizes="180x180" /> <meta name="theme-color" content="#ffffff" /> </head> -
O manifesto é um arquivo JSON que fornece as informações que o navegor precisa para instalar uma PWA. São elas:
- Nome
- Nome Curto
- Descrição
- Cor Tema (a mesma usada em
index.html) - Ícone com pelo menos 512x512px
O VitePWA gera o arquivo automaticamente no processo de
build. Para isso, inclua os novos parâmetros emvite.config.ts:VitePWA({ registerType: 'autoUpdate', includeAssets: ['vite.svg'], // ícones e imagens manifest: { name: 'Nome da Aplicação', short_name: 'Aplicação', description: 'Descrição da aplicação', theme_color: '#ffffff', icons: [ { src: '/vite.svg', sizes: 'any', // estou usando svg, então serve para qualquer tamanho type: 'image/svg+xml', purpose: 'any maskable', }, ], }, }), -
Uma aplicação PWA pode estar em diversos ambientes diferentes: Android, iOS, diferentes navegadores. Cada um desses tem tamanhos recomendados distintos para ícones e muitas vezes redimensionar as imagens não é o melhor caminho. Caso queira, existem geradores de assets para PWAs que criam ícones nos tamanhos certos.
Com isso, sua configuração mínima está pronta! Para testar, faça o seguinte:
npm run build
npm run preview
Ao abrir o localhost, você pode verificar que há um novo símbolo na barra, ele serve para instalar a aplicação.
Plataformas como Vercel e Netlify fazem o processo de build por conta própria. Já com o GitHub Pages, é necessário criar um novo branch com o diretório dist e defini-lo como origem nas configurações ou usar GitHub actions.