Project Starter

Esse é um template para iniciar projetos. Há algumas coisas que você precisa fazer após criar seu repositório usando este template:

• Substituir project-starter, PROJECT_STARTER (e outras menções) pelo nome do seu projeto
• Editar src/main/resources/public/stylesheets/main.css conforme necessário (cores diferentes, fontes, etc.)
• Editar src/main/resources/public/javascript/main.js conforme necessário
• Editar src/main/jte/layout.kte conforme necessário para suportar a navegação do seu projeto

Adicionando uma nova página

Para adicionar uma nova página, você precisa editar alguns arquivos:

1. View

Adicione um novo template como src/main/jte/my-new-page.kte que usa o layout do projeto:

@template.layout(title = "Página", content = @`
    <section class="main-section-bg">
        <div class="px-4 pt-8 mx-auto max-w-screen-xl z-10 relative md:pt-16 text-center">
            <h1 class="mb-4 leading-none text-6xl text-gray-800 tracking-tight text-white md:text-8xl lg:text-8xl">Headline para a página</h1>
        </div>
    </section>
    @template.partials.content-section(content = @`
        <article class="format lg:format-lg">
            <p class="mb-3 text-3xl text-gray-800">Texto do primeiro paragrafo</p>
            <p class="text-gray-800 leading-relaxed mb-4">Texto do segundo paragrafo</p>
        </article>
    `)
`, metadata = @`
    <meta name="description" content="Meta descrição da página">
`)

2. Controller / Route

Como src/main/kotlin/br/ufpe/liber/controllers/IndexController.kt, ou outro se necessário:

@Get("/my-new-page")
fun index() = ok(templates.myNewPage()) // `myNewPage` é gerado automaticamente

3. Mudanças no layout

Se isso adiciona à navegação do seu projeto, você pode adicionar novos links à navbar no arquivo src/main/jte/layout.kte:

 <ul class="flex flex-col p-4 mt-4 font-medium md:space-x-8 md:flex-row md:mt-0">
     <li>
         @template.partials.navlink(path = "/", text = "Inicio", title = "Página inicial")
     </li>
+    <li>
+        @template.partials.navlink(path = "#", text = "Link #1", title = "Link #1")
+    </li>
 </ul>

4. Testes

Adicione alguns testes para a sua nova página / rota.

Tip

Se sua rota:

• Não recebe parâmetros
• Retorna HTML

Então ela será testada automaticamente pelos testes de acessibilidade.

Executar localmente

Para executar o projeto localmente, abra um terminal e execute:

./gradlew run

A aplicação ficará acessível em http://localhost:8080/.

Se você quiser recarregar a aplicação a cada alteração de código, execute o Gradle em modo contínuo:

./gradlew run -t

Simular ambiente de produção

O aplicativo é executado usando o nginx como proxy, em uma máquina com o Rocky Linux. Para simular este ambiente, você pode usar o Vagrant, que irá configurar todos os detalhes usando um único comando:

./gradlew clean vagrantUp

O servidor nginx ficará acessível em http://localhost:9080/, e a aplicação em http://localhost:9080/project-starter.

Para acessar a VM via SSH, execute:

vagrant ssh

Destruir / Reiniciar a VM Vagrant

Se a VM estiver executando, execute o seguinte comando para destruí-lo:

vagrant destroy --graceful --force

Requisitos

1. Java 21 (mais fácil de instalar com SDKMAN)
2. Node.js 20
3. Docker Desktop (se você quiser testar as imagens Docker)
4. Ktlint CLI (se você quiser executar inspeções de código localmente)
5. Gradle (se você não quiser usar o script ./gradlew)
6. Vagrant (se você quiser rodar o projeto usando uma VM)

Aspectos técnicos

O projeto é desenvolvido usando:

• Micronaut Framework
• Gradle
• Kotlin
• Tailwind CSS

Documentação de Micronaut

• Guia do usuário
• API Referência
• Referência de Configuração
• Guias sobre o Micronaut

Template Engine

O projeto usa JTE / KTE como template engine.

• Documentação do JTE
• Tutorial JTE

CI & CD

O projeto usa GitHub Actions para executar testes e outras validações descritas abaixo.

Inspeções de código

Para cada merge/push, e também para pull requests, existem ações do GitHub para executar ktlint, detekt, e DiKTat (experimental).

O ktlint está configurado para usar o estilo de código intellij_idea para que ele não entre em conflito com a ação de formatação de código da IntelliJ IDEA.

Há também uma integração com o Sonar Cloud: https://sonarcloud.io/project/overview?id=Liber-UFPE_project-starter.

Testes e Cobertura de Código

Usamos Kotest como framework de teste, e Kover como a ferramenta de cobertura de código. Ver também Micronaut Kotest integrações docs.

Tip

Veja a cobertura de código mais recente na página do projeto no SonarCloud.

Assets Pipeline

Para garantir que as páginas carreguem rapidamente, há um processamento dos assets estáticos (JavaScripts, CSS, imagens). O esbuild é usado em conjunto com alguns pacotes npm:

• sharp para gerar versões webp das images
• gzipper para gerar versões comprimidas (gzip, brotli, deflate)
• postcss para otimizar o uso do Tailwind CSS e manter apenas os estilos efetivamente usados.

Esse processamento é então integrado ao build principal da aplicação usando o Gradle Plugin for Node.

Tip

Dá para testar o processamento dos assets de maneira isolada executando diretamente node assets-pipeline.mjs.

Layout de Diretório de Projetos

O projeto segue o padrão Maven Standard Directory Layout para projetos Kotlin. As pastas principais são:

Diretório	Descrição
src/main	Pasta raiz para código de aplicação
src/main/jte	Pasta de templates JTE
src/main/kotlin	Código Kotlin da aplicação
src/main/resources	Configurações e outros recursos
src/main/resources/public	Web assets como imagens, javascript e arquivos css
src/test	Pasta raiz para código de teste
scripts	Pasta com scripts para deploy usando o Vagrant
github	Pasta raiz para configurações do GitHub
.github/workflows	GitHub Ações configuração