frontend structure

Estrutura do frontend

Motivação

Usando como base projetos conceituados pela comunidade, como por exemplo o Bootstrap ou Angular, a estrutura de arquivos e diretórios que utilizamos se basea no isolamento por responsabilidade para agrupar determinada funcionalidade que necessita de vários arquivos para abranger todo seu conteúdo sem perder a objetividade.

Nomenclatura de arquivos

Os arquivos devem ser nomeados em kebab/dash-case, ou seja, todo em minúsculo separados por traço. Sempre preferir nomes em inglês, salvo o nome dos arquivos na pasta packages/mixdinternet/frontend/src/resources/views/html, pois eles serão as rotas que apresentaremos o preview do projeto aos clientes.

Exemplo: file-name.example

• Arquivos de imagens de background geralmente adicionamos o prefixo bg-
• Arquivos de ícones geralmente adicionamos o prefixo ic-

Diretório do desenvolvimento do frontend

Os arquivos de sass, javascript, imagens, fontes pertencentes ao frontend (e não ao Admix) estão localizados na pasta assets, dentro de resources na raiz do projeto.

├── fonts
│   └── arquivos fontes personalizadas
├── images
│   ├── icons
│   │   ├── favicon.ico
│   │   └── icones splashscreen pwa
│   ├── logo-amp.png
│   ├── logo-email.png
│   ├── logo.png
│   └── splash
│       └── arquivos splashscreen pwa
├── js
│   ├── bootstrap.js
│   ├── compress.js
│   ├── frontend.js
│   ├── spritemap.js
│   ├── spritemap.js.map
│   └── vendors
│       └── arquivos js de bibliotecas externas
├── sass
│   ├── _styles.scss
│   ├── bootstrap
│   │   ├── _bootstrap.scss
│   │   ├── _reboot.scss
│   │   └── _variables.scss
│   ├── frontend
│   │   ├── _fonts.scss
│   │   ├── _functions.scss
│   │   ├── _helpers.scss
│   │   ├── _mixins.scss
│   │   └── _variables.scss
│   ├── frontend.scss
│   ├── pages
│   └── vendors
│       ├── _hubspot-form.scss
│       ├── _infinite-scroll.scss
│       ├── _progressive-image.scss
│       ├── _slick.scss
│       └── _vendors.scss
└── svg

• fonts: Fontes personalizadas que precisaremos do arquivo baixado devem ser colocadas nesse diretório.
  Sempre procurar adicionar somente as fontes que o projeto irá usar para diminuir o tamanho do download do site, consequentemente melhorar o tempo de carregamento. Outro fator de melhoria de performance é dar preferência para os arquivos .woff/.woff2 pois são os novos formatos voltados pra web, mais compatíveis e mais leves.

• images: Arquivos .jpg/.jpeg, .png devem ser colocados aqui.

  • icons: Arquivos dos ícones de PWA e favicon.ico devem ser alterados aqui.

  • splash: Arquivos de splashscreen de PWA devem ser alterados aqui.

• js:

  • bootstrap.js: Arquivo usado para importar todos os .js (criados ou de bibliotecas externas) que serão utilizados no site. Após importar será gerado o frontend.js que será o arquivo que de fato o site utilizará, isso minimiza a quantidade de requisições ao servidor.

  • vendors: Arquivos de abstrações das bibliotecas externas, por exemplo, a atualização do slick ao redimensionar a tela, criamos uma função para isso, e essa é sua responsabilidade, então faz sentido isolarmos em um arquivo relacionado ao slick.

• sass:

  • _styles.scss: Se precisarmos definir alguma classe que faz sentido ser usada em todos os lugares, deve ser definida aqui.

  • bootstrap: Diretório responsável por toda manipulação do framework Bootstrap, seja aumentando ou removendo (resetando). A manipulação é feita da seguinte maneira:

    Se precisamos sobreescrever alguma variável do bootstrap, então procuramos o nome do arquivo original, criamos um arquivo dentro da pasta bootstrap com o mesmo nome e fazemos as alterações necessárias.
     
    Exemplo:
     
    Vamos alterar a variável de cor $primary, ela está no arquivo original do bootstrap bootstrap/variables, então no nosso diretório bootstrap criamos o mesmo arquivo variables, mantendo a conexão com o framework para facilitar a manutenção e debug de possíveis erros

    • _bootstrap.scss: Utilizado para sobreescrever estilos do bootstrap caso não consigamos alterá-lo através de variáveis.

    • _variables.scss: Utilizado para sobreescrever variáveis do bootstrap. Por exemplo alterar o azul primário do bootstrap, $primary: $bahama-blue.

  • frontend: Diretório responsável por abstrações, variáveis, fontes e estilos específicos do projeto ou caso faça sentido em outros projetos deixamos acoplado ao starter.

  • frontend.scss: Usado para importar e compilar todos os arquivos de SASS.  

    Deixamos somente esse arquivo sem o _ antes justamente para indicar ao SASS para somente importar os outros arquivos e compilar somente o frontend.scss

  • pages: Diretório responsável pelos arquivos SASS específicos das páginas.

    Como tudo será agrupado em um arquivo único (frontend.css), para isolar o código por página, adicionamos uma classe abraçando todo o arquivo com o nome da referida página.

  • vendors: Diretório responsável pela sobrescrita dos estilos das bibliotecas externas. Por exemplo:
    Se quisermos alterar o estilo do input do formulário da hubspot, .hs-input, criamos o arquivo _hubspot-form.scss e alteramos a mesma classe.

    Esse tipo de sobrescrita geralmente acontece quando não temos controle sobre os estilos aplicados. No caso da hubspot, o formulário é inserido por JS em tempo de execução, portanto, só conseguimos alterar o que ja existe.

• svg: Arquivos .svg devem ser colocados aqui.