Skip to content

Estrutura do Projeto

🔍 Preview

Se você vai criar um novo tema de Checkout, entender a estrutura do projeto é essencial.

A boa notícia é que a Uappi já entrega o repositório com estrutura padronizada, organizada e pronta para escalar.

Neste guia você vai entender:

  • O que não deve ser alterado
  • Onde você realmente vai trabalhar
  • Como organizamos componentes e responsabilidades
  • Quais são os padrões recomendados pela plataforma

    • 📁 Estrutura na raiz do projeto

    Na raiz ficam arquivos e pastas responsáveis por configuração, padronização e build.

    ⚠️ Atenção

    Em geral, não é necessário alterar nada aqui.

    🔒 .husky

    Utilizado para controle de qualidade antes dos commits.

    Ele executa validações como:

  • Lint
  • Tipagem
  • Padronização

    • ⚠️ Atenção

    Não deve ser alterado.

    Garante que todos os projetos mantenham o mesmo padrão.

    ⚙️ .vscode

    Contém configurações recomendadas para o VS Code:

  • Formatação
  • Regras de lint
  • Padronização de ambiente

    • Evita que cada desenvolvedor configure manualmente.

    ⚠️ Atenção

    Não deve ser alterado.

    🌎 Variáveis de ambiente

    As principais variáveis são:

    1VITE_API_BASE_URL=
    2VITE_BASE=
    🔹 VITE_API_BASE_URL Define o domínio da API da loja.

    ✔ Já vem configurada pela Uappi ✔ Pode ser customizada caso necessário

    🔹 VITE_BASE Define base de build.

    ⚠️ Atenção

    Não deve ser alterado.

    🧹 Prettier, ESLint e EditorConfig

    Arquivos responsáveis por:

  • Padronização de código
  • Organização visual
  • Evitar falhas no deploy
  • Garantir legibilidade entre projetos

    • Já configurados conforme padrão da plataforma.

    ⚠️ Atenção

    Não deve ser alterado.

    ⚡ vite.config.ts

    Este é o arquivo mais importante da camada de build.

    Aqui são definidas configurações como:

  • Proxy
  • Base
  • Configuração de build
  • Plugins
  • Ambiente de execução

    • ⚠️ Atenção

    A Uappi já entrega esse arquivo configurado para funcionar corretamente no servidor.

    Não altere configurações como:

  • proxy
  • build
  • base

    • A menos que seja extremamente necessário e com alinhamento técnico.

    📦 Pasta src — Onde você realmente trabalha

    Aqui acontece toda a experiência do cliente final.

    Se tiver dúvidas sobre conceitos do Vue 3, consulte a documentação oficial: Clique aqui

    🎨 assets

    Arquivos globais do projeto:

  • Estilos
  • Fonts
  • Recursos reutilizáveis por todo o projeto (Global)

    • Usado para elementos que impactam o projeto inteiro.

    🧩 components

    Aqui organizamos os componentes por níveis de contexto.

    Esse é o padrão recomendado pela Uappi (mas você pode adaptar se necessário).

    🔹 1. Page (nível de página) Componentes específicos de uma página.

    Ex:

  • Signin
  • Signup
  • Address

    • 🔹 2. Common Componentes reutilizados em múltiplos contextos.

    Já possuem estilização definida.

    🔹 3. UI Componentes micro e genéricos.

  • Sem estilização forte
  • Sem contexto específico
  • Funcionam como biblioteca interna

    • Ex:

  • Button
  • Input
  • Select
  • Accordions

    • 🔹 4. Layout Define estruturas globais como:

  • Header
  • Footer
  • Estrutura base

    • Normalmente existe apenas um layout:

    DefaultLayout

    Mas é possível criar outros.

    Exemplo:

  • Layout de login sem header/footer

    • 📁 Organização recomendada de um componente

    Exemplo: componente da Home chamado MainBanner

    1Home/
    2 └── ProductsAndResume/
    3      ├── ProductsAndResume.vue
    4      ├── styles.scoped.css
    5      ├── styles.css
    6      ├── types.ts
    7      └── img/

    A ideia dessa organização é isolar completamente o contexto do componente, facilitando manutenção, reutilização em outro projeto, leitura e escalabilidade.

    🧩 ProductsAndResume.vue

    Este é o arquivo principal do componente.

    Aqui ficam:

  • Template (HTML)
  • Script (lógica funcional)
  • Importações
  • Conexões com composables ou stores

    • É o coração do componente.

    🎨 styles.scoped.css

    CSS com escopo exclusivo do componente.

    ✔ Afeta apenas o MainBanner ✔ Evita vazamento de estilos ✔ É a forma recomendada pela plataforma

    Sempre que possível, prefira utilizar scoped.

    ⚠️ styles.css

    CSS sem escopo.

    Ele pode:

  • Afetar outras partes do projeto
  • Gerar conflitos inesperados
  • Criar vazamento de estilos

    • Por isso: 🚨 Deve ser usado com cuidado 🚨 Apenas em cenários muito específicos 🚨 Pouco recomendado

    🧠 types.ts

    Arquivo responsável por toda tipagem relacionada ao componente.

    Exemplos:

  • Tipagem de props
  • Tipagem de emit
  • Interfaces internas
  • Tipos auxiliares usados por componente que consumir ProductsAndResume

    • ✅ Boa prática da plataforma

    Centralizar a tipagem dentro do contexto do componente.

    Evite colocar essas tipagens na pasta global ts, porque:

  • Elas pertencem apenas a este componente
  • Perdem contexto quando isoladas
  • Dificultam manutenção futura

    • ℹ️ Informação

    Regra prática: se o tipo só faz sentido quando o componente está presente, ele deve estar aqui.

    🖼️ img/

    Imagens utilizadas exclusivamente pelo componente.

    Isso garante:

  • Organização
  • Facilidade de manutenção
  • Evita misturar assets globais com assets locais

    • Se a imagem for reutilizada em várias partes do projeto, mova para assets.

    🧠 Filosofia dessa organização

    Cada componente é quase um micro-projeto isolado.

    Ele possui:

  • Estrutura
  • Estilo
  • Tipagem
  • Recursos próprios

    • Isso melhora:

  • Escalabilidade
  • Legibilidade
  • Manutenção em longo prazo
  • Reutilização fácil em outros projetos

    • 🔄 composables

    Funções reutilizáveis específicas deste projeto.

    Objetivo:

  • Evitar Ctrl + C / Ctrl + V
  • Centralizar lógica importante
  • Melhorar reutilização

    • Exemplos:

  • Formatadores de dinheiro
  • Formatadores de data

    • 🧠 core

    Aqui ficam funções utilitárias criadas pela plataforma.

  • Independente de cliente
  • Independente de nicho
  • Reutilizável em qualquer projeto Vue 3 da Uappi
  • Não é necessário alterar
  • Apenas utilizar

    • Evita instalar libs desnecessárias.

    🧱 layouts

    Define estruturas globais das páginas.

    Exemplo comum:

  • Default layout (header + footer)

    • Caso necessário, você pode criar novos layouts.

    Exemplo:

  • Página de login sem elementos externos
  • Página especial com estrutura diferente

    • Criando um novo Layout: aprenda como criar um novo layout passo a passo

    🗺️ router

    Responsável por:

  • Configuração de rotas
  • Definição das páginas
  • Organização da navegação

    • As rotas já vêm com estrutura clássica de e-commerce, mas podem ser adaptadas conforme necessidade do projeto.

    🗃️ stores

    Responsável pelo gerenciamento de estado da aplicação.

    Utilizamos o padrão recomendado pelo Vue 3 (Pinia).

    Ele permite:

  • Centralizar estados globais
  • Compartilhar dados entre componentes
  • Manter previsibilidade

    • 📖 Consulte a documentação oficial

    📄 template

    Pasta utilizada para armazenar HTMLs que serão enviados para a plataforma.

    Exemplos:

  • Layouts de e-mail
  • Descrições personalizadas
  • Templates dinâmicos

    • Objetivo:

  • Servir como backup
  • Evitar perda de dados caso o cliente remova algo no painel
  • Evitar perda de dados em Golives

    • 🧾 ts

    Por padrão da plataforma, aqui ficam tipagens globais reutilizáveis.

    Geralmente:

  • Pouca tipagem
  • Tipos que fogem do contexto de um componente específico

ℹ️ Informação

Tipagem específica de componente deve ficar dentro do próprio componente (types.ts).

🏁 Próximo passo

Agora que você entende a estrutura do projeto é hora de aprofundar um pouco mais.

Customização de Interfaces: criando uma nova camada de layout

Tracking e SEO: eventos GA4 usando public-sdk Tracking e SEO: dados estruturados e boas práticas

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;