1.3 — Estrutura de Arquivos do Projeto

Tour completo por cada pasta e arquivo do seu projeto SvelteKit. Entenda onde cada coisa mora e por que.

Objetivos da Aula

Entender a estrutura de pastas de um projeto SvelteKit
Conhecer o papel de cada arquivo de configuracao
Dominar o sistema de rotas baseado em arquivos
Saber a diferenca entre src/routes, src/lib e static

Visao Geral da Estrutura

Apos criar um projeto com pnpm dlx sv create (template minimal, TypeScript, prettier, eslint), voce tera algo assim:

Estrutura do projeto

meu-projeto/

├── src/ ← seu codigo vive aqui

├── routes/ ← paginas e rotas

├── lib/ ← componentes e utilitarios

├── app.html ← template HTML base

└── app.css ← estilos globais

├── static/ ← arquivos estaticos

├── package.json

├── svelte.config.js ← config do SvelteKit

├── vite.config.ts ← config do Vite

└── tsconfig.json ← config do TypeScript

Parece muita coisa, mas na pratica voce vai trabalhar quase exclusivamente dentro da pasta src/. Vamos entender cada parte.

A pasta `src/` — Onde seu codigo vive

`src/routes/` — Paginas e Rotas

Esta e a pasta mais importante. No SvelteKit, a estrutura de pastas define as URLs da sua aplicacao.

Cada pasta dentro de routes/ vira um caminho na URL. Cada arquivo +page.svelte dentro dessas pastas vira uma pagina.

src/routes/
├── +page.svelte          → http://localhost:5173/
├── +layout.svelte        → layout que envolve todas as paginas
├── about/
│   └── +page.svelte      → http://localhost:5173/about
├── blog/
│   ├── +page.svelte      → http://localhost:5173/blog
│   └── [slug]/
│       └── +page.svelte  → http://localhost:5173/blog/meu-post
└── contato/
    └── +page.svelte      → http://localhost:5173/contato

PASTA → URL

src/routes/+page.svelte → /

src/routes/about/+page.svelte → /about

src/routes/blog/[slug]/+page.svelte → /blog/qualquer-coisa

Dica

Voce nao precisa configurar rotas em nenhum arquivo de configuracao. Criou a pasta e o arquivo? A rota ja funciona. Deletou? A rota deixa de existir. Simples assim.

Arquivos especiais nas rotas

Cada pasta de rota pode conter arquivos com o prefixo +. Cada um tem um papel especifico:

+page.svelte

A pagina em si. O componente Svelte que sera renderizado quando o usuario acessar essa rota. Todo o HTML, CSS e logica da pagina ficam aqui.

+layout.svelte

Layout compartilhado. Envolve a pagina com elementos persistentes como navegacao, sidebar, footer. Tudo que aparece em todas as paginas vai aqui.

+page.server.ts

Carregamento de dados no servidor. Funcao load que roda no servidor para buscar dados de banco, APIs, etc. Os dados ficam disponiveis na pagina.

+server.ts

API endpoint. Cria rotas de API (GET, POST, PUT, DELETE) que retornam JSON ou qualquer tipo de resposta. Nao renderiza HTML.

+error.svelte

Pagina de erro. Componente exibido quando ocorre um erro nessa rota ou em rotas filhas. Permite personalizar a experiencia de erro.

Por que os arquivos comecam com o sinal de +?

O prefixo + e uma convencao do SvelteKit para diferenciar arquivos especiais de rota de arquivos normais. Um arquivo +page.svelte e processado pelo roteador do SvelteKit. Um arquivo Header.svelte (sem +) e apenas um componente normal que voce importa manualmente.

O projeto inicial: `+page.svelte` da raiz

Quando voce cria o projeto, ja existe um arquivo src/routes/+page.svelte com conteudo basico:

<h1>Welcome to SvelteKit</h1>
<p>
  Visit
  <a href="https://svelte.dev/docs/kit">
    svelte.dev/docs/kit
  </a>
  to read the documentation
</p>

Esta e a pagina que aparece quando voce acessa http://localhost:5173/. Voce pode editar livremente.

`src/lib/` — Componentes e Utilitarios

A pasta lib e onde voce organiza tudo que nao e uma pagina: componentes reutilizaveis, funcoes utilitarias, stores, tipos, etc.

src/lib/
├── components/
│   ├── Header.svelte
│   ├── Footer.svelte
│   └── Button.svelte
├── utils/
│   ├── formatDate.ts
│   └── api.ts
├── stores/
│   └── auth.ts
└── server/
    └── db.ts

O grande beneficio: voce pode importar qualquer coisa de src/lib/ usando o alias $lib:

<script lang="ts">
  // Em vez de: import Header from '../../../lib/components/Header.svelte'
  // Voce escreve:
  import Header from '$lib/components/Header.svelte'
</script>

Dica

O alias $lib funciona em qualquer arquivo do projeto. Nao importa quao profundo voce esteja na arvore de pastas — o caminho e sempre o mesmo. Isso evita aqueles imports com ../../../ que sao dificeis de manter.

A subpasta lib/server/ e especial: arquivos aqui so podem ser importados em codigo que roda no servidor (+page.server.ts, +server.ts, hooks). O SvelteKit impede que voce importe acidentalmente codigo do servidor no cliente.

// src/lib/server/db.ts
// Esse arquivo so roda no servidor
// Pode conter credenciais de banco, secrets, etc.

import { DATABASE_URL } from '$env/static/private'

A pasta lib vem vazia?

Sim. No template minimal, a pasta lib pode nao existir. Voce a cria quando precisar. Normalmente a primeira coisa que fazemos e criar src/lib/components/ para nossos componentes reutilizaveis.

`src/app.html` — O Template HTML

Este e o esqueleto HTML de toda a sua aplicacao. O SvelteKit injeta o conteudo das paginas dentro dele:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%sveltekit.assets%/favicon.png" />
    <meta name="viewport"
      content="width=device-width, initial-scale=1"
    />
    %sveltekit.head%
  </head>
  <body data-sveltekit-preload-data="hover">
    <div style="display: contents">
      %sveltekit.body%
    </div>
  </body>
</html>

Os placeholders que o SvelteKit substitui:

%sveltekit.head% Tags <link>, <script>, e conteudo de <svelte:head> dos seus componentes

%sveltekit.body% O HTML renderizado da pagina atual

%sveltekit.assets% Caminho para a pasta static/

Voce raramente edita esse arquivo

Na maioria dos projetos, voce edita o app.html apenas uma vez — para mudar o lang, adicionar fontes ou tags de analytics. Todo o conteudo dinamico e gerenciado pelos componentes Svelte.

`src/app.css` — Estilos Globais

Arquivo de estilos CSS que se aplica a toda a aplicacao. E importado no layout raiz:

/* src/app.css */
:root {
  --color-primary: #ff3e00;
  --color-bg: #0a0a0a;
  --color-text: #ededed;
}

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  background: var(--color-bg);
  color: var(--color-text);
}

A pasta `static/` — Arquivos Estaticos

Arquivos na pasta static/ sao servidos diretamente, sem processamento. Imagens, fontes, robots.txt, favicon.png — tudo que precisa estar acessivel por URL fixa.

static/
├── favicon.png        → http://localhost:5173/favicon.png
├── robots.txt         → http://localhost:5173/robots.txt
└── images/
    └── logo.svg       → http://localhost:5173/images/logo.svg

Qual a diferenca entre static/ e src/lib/assets/?

Arquivos em static/ sao copiados para a raiz do build sem alteracao — a URL e fixa e previsivel. Arquivos importados de src/lib/ sao processados pelo Vite: recebem um hash no nome (para cache busting) e podem ser otimizados (compressao de imagens, por exemplo).

Arquivos de Configuracao na Raiz

`svelte.config.js`

Configuracao central do SvelteKit:

// svelte.config.js
import adapter from '@sveltejs/adapter-auto';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Pre-processadores (TypeScript, SCSS, etc.)
  preprocess: vitePreprocess(),

  kit: {
    // Adapter define onde o projeto sera hospedado
    // 'auto' detecta automaticamente (Vercel, Netlify, etc.)
    adapter: adapter()
  }
};

export default config;

Os principais campos que voce vai usar ao longo do curso:

preprocess — habilita TypeScript e outros pre-processadores
kit.adapter — define o target de deploy (Vercel, Node, static, etc.)
kit.alias — aliases de importacao customizados

`vite.config.ts`

O Vite e o bundler usado pelo SvelteKit. Na maioria dos casos, voce nao precisa mexer neste arquivo — o plugin sveltekit() ja configura tudo que e necessario.

Dica

Vamos explorar o Vite em detalhes no Modulo 2 — Configuracoes e Vite.

`tsconfig.json`

Configuracao do TypeScript:

{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "sourceMap": true,
    "strict": true,
    "moduleResolution": "bundler"
  }
}

O SvelteKit gera automaticamente um tsconfig.json base na pasta .svelte-kit/. Seu arquivo apenas estende ele com customizacoes.

`package.json`

Seu projeto vem com estas dependencias essenciais:

{
  "name": "meu-projeto",
  "version": "0.0.1",
  "type": "module",
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview",
    "check": "svelte-kit sync && svelte-check"
  },
  "devDependencies": {
    "@sveltejs/adapter-auto": "^4.0.0",
    "@sveltejs/kit": "^2.0.0",
    "@sveltejs/vite-plugin-svelte": "^5.0.0",
    "svelte": "^5.0.0",
    "svelte-check": "^4.0.0",
    "typescript": "^5.0.0",
    "vite": "^6.0.0"
  }
}

Dica

Note o "type": "module". Isso habilita ESModules nativos no Node.js, permitindo usar import/export em vez de require/module.exports.

A pasta `.svelte-kit/` — Gerada automaticamente

Quando voce roda pnpm dev ou pnpm build, o SvelteKit gera uma pasta .svelte-kit/ com arquivos internos. Voce nunca deve editar esses arquivos — eles sao regenerados automaticamente.

Esta pasta esta no .gitignore e nao vai para o repositorio.

Fluxo Completo: Da Pasta ao Navegador

COMO O SVELTEKIT MONTA UMA PAGINA

Usuario acessa uma URL

Ex: http://localhost:5173/about

▼

SvelteKit encontra a rota

Procura: src/routes/about/+page.svelte

▼

Executa funcoes load (se existirem)

+page.server.ts e +page.ts carregam dados

▼

Renderiza o componente

Aplica layouts (+layout.svelte) e gera HTML

▼

Injeta no app.html

Substitui %sveltekit.head% e %sveltekit.body%

▼

Pagina renderizada no navegador!

Resumo: Mapa Mental do Projeto

Local	O que mora aqui	Quando usar
`src/routes/`	Paginas, layouts, APIs	Sempre que criar uma nova pagina ou endpoint
`src/lib/`	Componentes, utils, stores	Codigo reutilizavel que nao e uma pagina
`src/lib/server/`	Codigo server-only	Acesso a banco, secrets, logica de servidor
`src/app.html`	Template HTML base	Raramente (fontes, meta tags globais)
`src/app.css`	Estilos globais	CSS que afeta toda a aplicacao
`static/`	Assets estaticos	Imagens, favicon, robots.txt
`svelte.config.js`	Config do SvelteKit	Adapter, aliases, pre-processadores
`vite.config.ts`	Config do Vite	Plugins extras, proxy, porta

Desafio da Aula

Objetivo

Criar sua primeira pagina customizada no projeto SvelteKit.

Instrucoes

Abra o projeto criado na aula anterior
Crie a pasta src/routes/about/
Dentro dela, crie o arquivo +page.svelte
Escreva uma pagina simples de “Sobre” com seu nome e uma breve descricao
Acesse http://localhost:5173/about no navegador

Dica

<!-- src/routes/about/+page.svelte -->
<h1>Sobre mim</h1>
<p>
  Estou aprendendo Svelte e SvelteKit!
</p>

<style>
  h1 {
    color: #ff3e00;
  }
</style>

Spec de Verificacao

A pasta src/routes/about/ existe
O arquivo +page.svelte existe dentro dela
Acessar /about no navegador exibe sua pagina
O CSS com escopo esta funcionando (so afeta essa pagina)

Extra

Crie tambem um +layout.svelte na raiz (src/routes/+layout.svelte) com uma navegacao simples:

Clique para ver a solucao do extra

<!-- src/routes/+layout.svelte -->
<script>
  let { children } = $props()
</script>

<nav>
  <a href="/">Inicio</a>
  <a href="/about">Sobre</a>
</nav>

<main>
  {@render children()}
</main>

<style>
  nav {
    padding: 1rem;
    display: flex;
    gap: 1rem;
    border-bottom: 1px solid #333;
  }

  nav a {
    color: #ff3e00;
    text-decoration: none;
  }

  nav a:hover {
    text-decoration: underline;
  }

  main {
    padding: 2rem;
  }
</style>

Proxima aula: 1.4 — Por que usamos pnpm neste curso

1.3 — Estrutura de Arquivos do Projeto

Objetivos da Aula

Visao Geral da Estrutura

A pasta src/ — Onde seu codigo vive

src/routes/ — Paginas e Rotas

Arquivos especiais nas rotas

O projeto inicial: +page.svelte da raiz

src/lib/ — Componentes e Utilitarios

src/app.html — O Template HTML

src/app.css — Estilos Globais

A pasta static/ — Arquivos Estaticos

Arquivos de Configuracao na Raiz

svelte.config.js

vite.config.ts

tsconfig.json

package.json

A pasta .svelte-kit/ — Gerada automaticamente

Fluxo Completo: Da Pasta ao Navegador

Resumo: Mapa Mental do Projeto

Desafio da Aula

Objetivo

Instrucoes

Dica

Spec de Verificacao

Extra

A pasta `src/` — Onde seu codigo vive

`src/routes/` — Paginas e Rotas

O projeto inicial: `+page.svelte` da raiz

`src/lib/` — Componentes e Utilitarios

`src/app.html` — O Template HTML

`src/app.css` — Estilos Globais

A pasta `static/` — Arquivos Estaticos

`svelte.config.js`

`vite.config.ts`

`tsconfig.json`

`package.json`

A pasta `.svelte-kit/` — Gerada automaticamente