template-next — Next.js Portfolio Template

SHA-256: 1f8a2e7b89375e4329fc9fb111cbed1b836fa3bdee620a0ae30058e0c6b72407

2026-10-12T13:53:24.754Z

# Next.js Template Project

Template base para iniciar rapidamente projetos **Next.js**. Já vem com PWA (Serwist), styled-components, TypeScript estrito, Biome, testes (Vitest) e CI configurados.

## 🛠 Tecnologias Utilizadas

- **Next.js 16** (Pages Router + App Router para rotas especiais) + **React 19** + TypeScript estrito
- **Styled-Components** para estilos CSS-in-JS com temas
- **PWA**: [Serwist](https://serwist.pages.dev/) com **Turbopack** — service worker gerado em build e servido em `/serwist/sw.js`
- **Biome**: formatação, lint e organização de imports (substitui ESLint/Prettier)
- **Vitest + Testing Library**: testes unitários e de componentes
- **Husky + lint-staged**: hooks de pré-commit
- **GitHub Actions**: CI (check, typecheck, testes e build)
- **Auth.js v5 (next-auth)**: login com credenciais demo (`[email protected]` / `admin123`)

## 📂 Estrutura de Pastas

```bash
src/
│
├── components/                  # Componentes reutilizáveis
│   ├── Links/                   # Tags <head> (manifest, ícones)
│   └── SEO/                     # Meta tags e SEO por página
│
├── homepage/                    # Layout de exemplo (Header, Footer, Layout,
│                                # seções da home, i18n, hooks e estilos)
│
├── pages/                       # Páginas da aplicação (Pages Router)
│   ├── _app.tsx                 # Providers globais (auth, tema, PWA, fontes)
│   ├── _document.tsx            # Documento customizado (SSR styled-components)
│   ├── index.tsx                # Página inicial
│   ├── login/                   # Página de login (Auth.js)
│   ├── dashboard/               # Página protegida (withAuth)
│   └── 404/                     # Página de erro 404
│
├── app/                         # App Router (rotas especiais)
│   ├── api/auth/[...nextauth]/  # Route handler do Auth.js
│   ├── serwist/[path]/          # Route handler que serve o service worker
│   └── sw.ts                    # Service worker (Serwist + Turbopack)
│
├── auth.ts                      # Configuração do Auth.js v5
├── lib/                         # Utilitários de servidor (withAuth)
├── services/api/                # Camada de API (wrapper de fetch)
├── components/
│   ├── ui/                      # Componentes base (Button, Input, Modal, Toast, Spinner)
│   └── ...
│
├── ui/
│   ├── assets/                  # Ícones e imagens
│   └── styles/                  # Estilos globais e tema
│       ├── theme.ts             # Tema (cores, fontes, breakpoints)
│       ├── GlobalStyles.ts      # Reset e estilos globais
│       └── styles.d.ts          # Tipagem do tema para styled-components
│
└── utils/
    └── functions/               # Funções utilitárias
        ├── getDate.ts           # Ano, mês e dia atuais
        ├── hexToRgba.ts         # Conversão de HEX para RGBA
        ├── scrollToElement.ts   # Scroll suave até um elemento
        └── valueFormat.ts       # Formatação de valores (BRL)
```

## 🔧 Como Usar

1. Clone o repositório e instale as dependências:

```bash
npm install
```

2. Copie as variáveis de ambiente e gere um secret para o Auth.js:

```bash
cp .env.example .env.local
npx auth secret
```

3. Rode em desenvolvimento:

```bash
npm run dev
```

Acesse `http://localhost:3000`.

## 📜 Scripts

| Script             | Descrição                                     |
| ------------------ | --------------------------------------------- |
| `npm run dev`      | Ambiente de desenvolvimento (Turbopack)       |
| `npm run build`    | Build de produção (Turbopack)                 |
| `npm start`        | Servidor de produção                          |
| `npm run lint`     | Lint com Biome                                |
| `npm run format`   | Formatação com Biome                          |
| `npm run check`    | Formatação + lint + organização de imports    |
| `npm run typecheck`| Verificação de tipos (tsc --noEmit)           |
| `npm test`         | Executa os testes (Vitest)                    |
| `npm run test:watch` | Executa os testes em modo watch             |

## 🧪 Testes

Os testes ficam colados aos arquivos utilitários (`*.test.ts`) e são executados com Vitest em ambiente `jsdom`.

## 🚀 PWA

O service worker é gerado durante o build pelo Serwist com **Turbopack** (`src/app/sw.ts`, empacotado via esbuild) e servido em `/serwist/sw.js` pelo route handler `src/app/serwist/[path]/route.ts`. O registro é feito pelo `SerwistProvider` no `_app.tsx`; em desenvolvimento o SW fica desabilitado.

## 🔐 Autenticação

Auth.js v5 configurado em `src/auth.ts` com provider de credenciais **demo** (`[email protected]` / `admin123`). O route handler fica em `src/app/api/auth/[...nextauth]/route.ts` e páginas protegidas usam `withAuth` (`src/lib/withAuth.ts`) no `getServerSideProps`.

## 🚀 Iniciar um novo projeto a partir deste template

1. **Crie o repositório** usando este template e clone-o.
2. **Renomeie o projeto** no `package.json` (campo `name`) e ajuste a `src/config/site.ts` (nome do site, autor, descrição, tema e URL de produção).
3. **Copie e preencha as variáveis de ambiente**:

```bash
cp .env.example .env.local
npx auth secret
```

4. **Instale e verifique**:

```bash
npm install
npm run check
npm run typecheck
npm test
npm run build
```

5. **Comece a desenvolver**: adicione páginas em `src/pages/` e componentes em `src/components/`. Para autenticar uma página, use `withAuth` no `getServerSideProps`. Para chamadas de API, use `src/services/api`.

> O Node.js v24+ é necessário (`.nvmrc` incluído). A página de login e o dashboard demo podem ser removidos ao trocar o provider de credenciais pelo de produção.

## 🧹 Removendo o layout de exemplo (homepage)

O template inclui um layout de exemplo opcional, consolidado em `src/homepage/`:
Header fixo com scrollspy, Footer com ano dinâmico, 5 seções na homepage (Intro,
Features, Como usar, Comandos, Métricas), i18n pt/en e hooks auxiliares.

> Guia completo e detalhado: [`src/homepage/README.md`](src/homepage/README.md)

### Opção automática (dev mode)

Rodando `npm run dev`, um botão fixo **Remover layout de exemplo** aparece no
canto inferior direito. Ele exige confirmação (modal com **Remover e limpar**)
e dispara `POST /api/remove-homepage`, que reverte os arquivos de wiring,
apaga `src/homepage` e se auto-destrói. A rota só executa em desenvolvimento
(fora dele responde `403`) e o badge fica oculto.

Para excluir manualmente, siga a ordem:

1. **Apague a pasta `src/homepage/`:**

```bash
rm -rf src/homepage
# Windows (PowerShell):
# Remove-Item -Recurse -Force src/homepage
```

2. **Reverta `src/pages/_app.tsx`** — remova o `Layout` e o `LanguageProvider`,
   mantendo `SerwistProvider`, `SessionProvider`, as fontes e o `<ToastProvider>`
   em volta de `<Component {...pageProps} />`.
3. **Reverta `src/pages/index.tsx`** — troque os imports/seções de
   `@/homepage/components/Home/…` pelo placeholder original (`<h1>home page</h1>`).
4. **Reverta `src/ui/styles/GlobalStyles.ts`** — remova o bloco de
   `scroll-behavior: smooth` e o `@media (prefers-reduced-motion: reduce)`.
5. **Verifique:**

```bash
npm run check
npm run typecheck
npm test
npm run build
```

Depois disso, `/login` e `/dashboard` renderizam sem Header/Footer/Layout, em um
estado minimalista pronto para o seu próprio layout.

## 📄 Licença

MIT. Sinta-se à vontade para usar, modificar e compartilhar.