Saat pertama kali membuka project SvelteKit, banyak developer pemula bingung karena struktur foldernya terlihat ringkas, tetapi setiap file punya peran yang cukup spesifik. Kabar baiknya, struktur ini justru dirancang agar mudah dipahami setelah kita melihat contoh nyata.

Di artikel ini, kita akan membedah struktur folder dasar SvelteKit lewat project sederhana: sebuah halaman home yang menampilkan judul, deskripsi, dan satu komponen kartu. Fokus kita bukan teori panjang, melainkan cara membaca struktur project, fungsi tiap file, dan kapan file tersebut dipakai.

Kita akan membahas folder src, routes, lib, static, file app.html, serta beberapa file konfigurasi yang penting dipahami sejak awal.

Membuat project SvelteKit sederhana

Jika Anda belum punya project, buat dulu project baru. Perintah bisa sedikit berbeda tergantung tool yang dipakai, tetapi pola umumnya seperti ini:

npm create svelte@latest my-sveltekit-app
cd my-sveltekit-app
npm install
npm run dev

Setelah project dibuat, struktur folder dasarnya biasanya mirip seperti berikut:

my-sveltekit-app/
├── src/
│   ├── app.html
│   ├── lib/
│   └── routes/
├── static/
├── package.json
├── svelte.config.js
├── vite.config.js
└── tsconfig.json

Pada project nyata, mungkin ada file tambahan seperti .gitignore, README.md, atau konfigurasi linting. Namun untuk pemula, struktur di atas adalah titik awal yang paling penting.

Gambaran project contoh yang akan dibuat

Kita akan membuat halaman home dengan struktur seperti ini:

src/
├── app.html
├── lib/
│   └── components/
│       └── InfoCard.svelte
└── routes/
    ├── +layout.svelte
    └── +page.svelte
static/
└── logo.png

Hasil akhirnya sederhana:

  • Halaman utama tampil di route /
  • Ada komponen InfoCard yang disimpan di src/lib/components
  • Ada gambar statis di folder static
  • Kita juga melihat peran app.html dan file konfigurasi dasar

Folder src: pusat kode aplikasi

Folder src adalah tempat utama untuk source code aplikasi. Di sinilah Anda biasanya menaruh halaman, komponen, helper, style, dan file lain yang diproses oleh SvelteKit.

Dalam konteks artikel ini, tiga bagian penting di dalam src adalah:

  • src/routes untuk halaman dan route
  • src/lib untuk komponen atau utilitas yang bisa dipakai ulang
  • src/app.html sebagai template HTML utama

Aturan praktisnya sederhana: jika file berhubungan dengan route, letakkan di routes. Jika file ingin dipakai ulang lintas halaman, letakkan di lib.

Kenapa src penting?

SvelteKit memproses folder ini sebagai bagian inti aplikasi. Artinya, file di dalam src akan dikenali oleh sistem routing, bundler, dan proses build. Karena itu, penempatan file yang benar akan sangat membantu ketika project mulai membesar.

Folder routes: tempat halaman dibuat

Folder src/routes adalah jantung routing di SvelteKit. Nama file dan folder di dalamnya menentukan URL aplikasi.

Untuk halaman home, kita cukup membuat file:

src/routes/+page.svelte

Isi file tersebut bisa seperti ini:

<script>
  import InfoCard from '$lib/components/InfoCard.svelte';
</script>

<svelte:head>
  <title>Home | Belajar SvelteKit</title>
  <meta name="description" content="Contoh project sederhana untuk memahami struktur folder SvelteKit" />
</svelte:head>

<section>
  <h1>Selamat datang di project SvelteKit</h1>
  <p>
    Halaman ini dibuat untuk memahami struktur folder dasar seperti routes,
    lib, static, dan app.html.
  </p>

  <img src="/logo.png" alt="Logo aplikasi" width="120" />

  <InfoCard
    title="Komponen dari folder lib"
    content="Komponen ini diimpor dari src/lib/components dan dipakai di halaman home."
  />
</section>

<style>
  section {
    max-width: 720px;
    margin: 2rem auto;
    padding: 0 1rem;
  }

  h1 {
    margin-bottom: 0.75rem;
  }

  img {
    display: block;
    margin: 1rem 0;
  }
</style>

Di sini terlihat beberapa hal penting:

  • +page.svelte berarti file ini merepresentasikan satu halaman
  • Karena lokasinya di src/routes, maka route-nya adalah /
  • Komponen dari src/lib bisa diimpor dengan alias $lib
  • File di static bisa diakses langsung dari root URL, misalnya /logo.png

Bagaimana jika ingin membuat route lain?

Misalnya Anda ingin membuat halaman about. Struktur foldernya cukup seperti ini:

src/routes/
├── +page.svelte
└── about/
    └── +page.svelte

Maka file src/routes/about/+page.svelte akan tersedia di URL /about.

Ini salah satu hal yang membuat SvelteKit nyaman digunakan: struktur folder langsung mencerminkan struktur URL.

Peran +layout.svelte

Selain +page.svelte, file lain yang sering ditemui adalah +layout.svelte. File ini dipakai untuk layout bersama, misalnya navbar, footer, atau wrapper umum yang dipakai di banyak halaman.

Contoh sederhana:

src/routes/+layout.svelte
<slot />

Versi paling minimal memang sesederhana itu. Namun biasanya file ini akan berkembang menjadi tempat layout global. Contoh:

<header>
  <nav>
    <a href="/">Home</a>
    <a href="/about">About</a>
  </nav>
</header>

<main>
  <slot />
</main>

<footer>
  <p>Dibuat dengan SvelteKit</p>
</footer>

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

  main {
    min-height: 70vh;
  }

  footer {
    padding: 1rem;
    border-top: 1px solid #ddd;
  }
</style>

Dengan pendekatan ini, semua halaman di bawah routes akan dibungkus oleh layout yang sama.

Catatan: Pemula sering menaruh semua UI di +page.svelte. Itu tidak salah untuk project kecil, tetapi saat ada elemen yang dipakai berulang, pindahkan ke src/lib agar lebih rapi.

Folder lib: tempat komponen dan kode reusable

Folder src/lib umumnya dipakai untuk menyimpan hal-hal yang ingin digunakan ulang, misalnya:

  • Komponen UI
  • Helper function
  • Store
  • Konstanta
  • Utility formatting

Untuk contoh ini, kita buat komponen kartu sederhana:

src/lib/components/InfoCard.svelte
<script>
  export let title = '';
  export let content = '';
</script>

<article class="card">
  <h2>{title}</h2>
  <p>{content}</p>
</article>

<style>
  .card {
    margin-top: 1.5rem;
    padding: 1rem;
    border: 1px solid #dcdcdc;
    border-radius: 12px;
    background: #fafafa;
  }

  h2 {
    margin: 0 0 0.5rem 0;
    font-size: 1.1rem;
  }

  p {
    margin: 0;
    color: #444;
  }
</style>

Lalu komponen ini diimpor dari halaman:

import InfoCard from '$lib/components/InfoCard.svelte';

Alias $lib memudahkan import tanpa harus menulis path relatif panjang seperti ../../lib/components/InfoCard.svelte. Ini sangat membantu saat struktur project makin dalam.

Kapan file sebaiknya dipindah ke lib?

Gunakan src/lib jika:

  • Komponen dipakai lebih dari satu halaman
  • Fungsinya bersifat umum, bukan khusus satu route
  • Anda ingin menjaga file halaman tetap fokus pada logika halaman

Jangan terlalu cepat memindahkan semua file ke lib jika project masih sangat kecil. Namun begitu ada pengulangan, pindahkan agar struktur tetap sehat.

File app.html: template HTML utama aplikasi

File src/app.html adalah template HTML dasar yang dipakai SvelteKit untuk merender aplikasi. Ini bukan tempat menulis komponen Svelte, melainkan kerangka HTML global.

Contoh isi default yang umum:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <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>

Dua placeholder yang paling penting adalah:

  • %sveltekit.head% untuk konten <head> dari halaman atau layout, misalnya title dan meta tag
  • %sveltekit.body% untuk isi aplikasi SvelteKit

Anda bisa menyesuaikan file ini untuk kebutuhan global, misalnya menambah bahasa dokumen:

<html lang="id">

Atau menambah script eksternal yang memang harus dimuat secara global. Namun hati-hati: jangan sembarangan menaruh script berat di sini karena akan memengaruhi semua halaman.

Kesalahan umum di app.html

  • Menghapus placeholder %sveltekit.head% atau %sveltekit.body%
  • Menaruh markup komponen Svelte di file ini
  • Mengubah struktur dasar tanpa memahami dampaknya ke render aplikasi

Jika setelah mengedit app.html halaman jadi blank, periksa lagi apakah placeholder SvelteKit masih ada.

Folder static: aset publik yang diakses langsung

Folder static dipakai untuk menyimpan file statis seperti gambar, favicon, robots.txt, atau file lain yang tidak perlu diproses oleh bundler aplikasi.

Contoh struktur:

static/
├── logo.png
└── favicon.png

File di folder ini bisa diakses langsung dari root URL:

<img src="/logo.png" alt="Logo aplikasi" />

Gunakan static ketika:

  • File memang ingin tersedia apa adanya
  • Tidak perlu import dari JavaScript atau komponen
  • File perlu URL stabil, misalnya untuk icon atau dokumen publik

Untuk pemula, aturan mudahnya adalah: jika ingin file diakses langsung lewat URL, pertimbangkan taruh di static.

Trade-off penggunaan static

Kelebihannya adalah sederhana dan mudah dipahami. Kekurangannya, Anda tidak mendapatkan manfaat import asset secara modular seperti saat file diproses melalui bundler. Untuk gambar sederhana seperti logo, folder ini sudah sangat cukup.

File konfigurasi penting yang perlu dikenali

Anda tidak harus hafal semua konfigurasi sejak awal, tetapi ada beberapa file yang sebaiknya dikenali fungsinya.

package.json

File ini menyimpan metadata project, dependency, dan script yang bisa dijalankan.

Contoh bagian penting:

{
  "scripts": {
    "dev": "vite dev",
    "build": "vite build",
    "preview": "vite preview"
  }
}

Perintah yang sering dipakai:

npm run dev
npm run build
npm run preview
  • dev untuk development lokal
  • build untuk membuat hasil produksi
  • preview untuk melihat hasil build secara lokal

svelte.config.js

Ini adalah konfigurasi utama SvelteKit. Di sinilah adapter biasanya diatur untuk target deployment tertentu.

Contoh bentuk umum:

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

/** @type {import('@sveltejs/kit').Config} */
const config = {
  preprocess: vitePreprocess(),
  kit: {
    adapter: adapter()
  }
};

export default config;

Untuk pemula, poin pentingnya adalah:

  • File ini menghubungkan SvelteKit dengan adapter deployment
  • Biasanya tidak sering diubah di tahap awal
  • Jika deploy ke platform tertentu, file ini mungkin perlu penyesuaian

vite.config.js

SvelteKit menggunakan Vite sebagai bundler dan dev server. File ini mengatur integrasi tersebut dan konfigurasi Vite tambahan jika diperlukan.

Sering kali Anda tidak perlu menyentuhnya di awal, tetapi penting tahu bahwa file ini ada ketika nanti butuh plugin atau custom alias tertentu.

tsconfig.json

Jika project menggunakan TypeScript atau template bawaan menyertakannya, file ini mengatur perilaku TypeScript. Meski Anda menulis JavaScript biasa, file ini tetap mungkin ada sebagai bagian dari setup project.

Untuk pemula, cukup pahami bahwa file ini berkaitan dengan pengecekan tipe, editor hints, dan konsistensi konfigurasi tooling.

Contoh struktur akhir project

Setelah semua file contoh ditambahkan, struktur project kita menjadi seperti ini:

my-sveltekit-app/
├── src/
│   ├── app.html
│   ├── lib/
│   │   └── components/
│   │       └── InfoCard.svelte
│   └── routes/
│       ├── +layout.svelte
│       └── +page.svelte
├── static/
│   └── logo.png
├── package.json
├── svelte.config.js
├── vite.config.js
└── tsconfig.json

Dengan struktur sekecil ini saja, Anda sudah bisa melihat pola utama SvelteKit:

  • routes untuk halaman berdasarkan URL
  • lib untuk komponen atau kode reusable
  • static untuk aset publik
  • app.html untuk template HTML global
  • config files untuk perilaku build, tooling, dan deployment

Tips praktis untuk pemula

1. Jangan campur komponen reusable ke routes tanpa alasan

Kalau sebuah komponen hanya milik satu halaman, menyimpannya dekat halaman tersebut masih masuk akal. Namun jika mulai dipakai ulang, pindahkan ke src/lib.

2. Gunakan nama file dan folder yang jelas

Hindari nama seperti Card2.svelte atau test-final.svelte. Nama yang jelas membuat struktur project mudah dibaca beberapa minggu kemudian.

3. Pahami hubungan folder dan URL

Jika route tidak muncul seperti yang diharapkan, periksa dulu struktur folder di src/routes. Sering kali masalahnya hanya salah penempatan file.

4. Cek console saat halaman blank

Jika setelah edit halaman tidak muncul:

  • Periksa error di terminal npm run dev
  • Periksa console browser
  • Pastikan import path benar, terutama saat memakai $lib
  • Pastikan file app.html tidak rusak

5. Mulai dari struktur kecil dulu

Tidak perlu langsung membuat banyak folder tambahan seperti services, hooks, utils, dan seterusnya jika project masih sederhana. Ikuti kebutuhan nyata project agar struktur tetap mudah dipelihara.

Penutup

Struktur folder SvelteKit sebenarnya cukup ramah untuk pemula jika dipahami lewat praktik. Kuncinya adalah mengenali peran inti tiap bagian: src sebagai pusat source code, routes untuk halaman, lib untuk komponen reusable, static untuk aset publik, dan app.html sebagai template HTML dasar.

Dari contoh project sederhana ini, Anda sudah punya fondasi untuk membaca project SvelteKit lain dengan lebih percaya diri. Langkah berikutnya biasanya adalah menambah route baru, membuat layout bersama, lalu mulai memisahkan komponen reusable ke src/lib.

Kalau Anda baru mulai belajar SvelteKit, fokuslah dulu pada struktur folder dan alur kerja dasar ini. Setelah itu, fitur yang lebih lanjut seperti load function, form actions, atau endpoint akan jauh lebih mudah dipahami karena pondasi project-nya sudah jelas.