A estrutura de frontend do Projeto Base USP utiliza um conjunto moderno de ferramentas para compilação e gerenciamento de assets (CSS e JavaScript).

• Vite: Um ferramental de frontend moderno e extremamente rápido que serve seus arquivos via ESM nativo durante o desenvolvimento e os agrupa para produção. Substitui o Laravel Mix/Webpack em projetos Laravel mais recentes.
• Tailwind CSS: Um framework CSS utility-first que permite construir interfaces customizadas rapidamente, compondo classes utilitárias diretamente no HTML.
• Alpine.js: Um framework JavaScript minimalista para adicionar comportamento interativo aos seus templates HTML com baixo custo. Frequentemente comparado a um "Tailwind para JavaScript".
• PostCSS: Ferramenta para transformar CSS com plugins JavaScript (usado pelo Tailwind e Autoprefixer).
• Autoprefixer: Plugin PostCSS que adiciona prefixos de fornecedores (-webkit-, -moz-, etc.) a regras CSS automaticamente.

O Vite é responsável por processar e compilar os arquivos CSS e JavaScript. Os comandos principais são executados via NPM:

• Desenvolvimento (npm run dev):

  • Inicia o servidor de desenvolvimento do Vite.
  • Monitora alterações nos arquivos resources/css/app.css e resources/js/app.js (e suas importações).
  • Fornece Hot Module Replacement (HMR): Atualizações de CSS e JS são injetadas no navegador sem a necessidade de recarregar a página, agilizando o desenvolvimento frontend.
  • Importante: Este comando DEVE rodar continuamente em um terminal separado enquanto você desenvolve.

  npm run dev

• Produção (npm run build):

  • Compila, otimiza e minifica os assets para o ambiente de produção.
  • Gera arquivos finais com hashes em seus nomes para cache busting.
  • Coloca os arquivos compilados na pasta public/build.
  • Este comando DEVE ser executado durante o processo de deploy da aplicação para produção.

  npm run build

• Arquivos Fonte:
  • resources/css/app.css: Ponto de entrada principal para CSS. Importa as diretivas base do Tailwind CSS (@tailwind base;, @tailwind components;, @tailwind utilities;). Adicione seus estilos customizados ou importe outros arquivos CSS aqui.
  • resources/js/app.js: Ponto de entrada principal para JavaScript. Importa bootstrap.js e inicializa o Alpine.js (Alpine.start()). Adicione seu código JS customizado ou importe outros módulos aqui.
  • resources/js/bootstrap.js: Configurações iniciais, como a configuração global do Axios (cliente HTTP para requisições AJAX).
• Arquivos de Configuração:
  • vite.config.js: Arquivo de configuração do Vite. Define os pontos de entrada (input) e ativa o plugin Laravel para integração com o backend.
  • tailwind.config.js: Arquivo de configuração do Tailwind CSS. Permite customizar o tema (cores, fontes, espaçamentos), adicionar plugins e definir quais arquivos (content) serão escaneados em busca de classes Tailwind.
  • postcss.config.js: Arquivo de configuração do PostCSS. Define os plugins a serem usados (Tailwind e Autoprefixer).

O tema visual principal da aplicação é fornecido pelo pacote uspdev/laravel-usp-theme.

• Layout Base: O layout principal da aplicação (resources/views/layouts/app.blade.php) estende o layout mestre do pacote (laravel-usp-theme::master), herdando a estrutura de menu, cabeçalho e rodapé padrão da USP.
• Inclusão dos Assets Compilados: O layout app.blade.php utiliza a diretiva Blade @vite(['resources/css/app.css', 'resources/js/app.js']) dentro das seções @section('styles') e @section('javascripts_bottom') (respectivamente, embora o JS costume ir no final) para incluir os assets processados pelo Vite. O plugin Laravel Vite cuida de gerar as tags <link> e <script> corretas, tanto em desenvolvimento (apontando para o servidor Vite) quanto em produção (apontando para os arquivos compilados em public/build).
• Conflitos de Estilo (Tailwind Preflight): Por padrão, o Tailwind CSS inclui um conjunto de estilos base chamado "Preflight" que reseta muitos estilos padrão do navegador para garantir consistência. No entanto, esses resets podem entrar em conflito com os estilos do laravel-usp-theme. Para evitar isso, o Preflight foi desabilitado na configuração do Tailwind:

  // tailwind.config.js
  export default {
      // ... outras configurações ...
      corePlugins: {
         preflight: false, // Impede que o Tailwind resete os estilos base
      }
  };

  Isso permite que os estilos do laravel-usp-theme prevaleçam, e você use as classes utilitárias do Tailwind para estilizações adicionais ou customizações pontuais sobre o tema base.

O Alpine.js é inicializado em resources/js/app.js. Você pode adicionar interatividade diretamente em seus arquivos Blade usando as diretivas do Alpine (x-data, x-show, x-on:click, etc.). Consulte a documentação do Alpine.js para mais detalhes.