Project structure in Svelte - Deep Dive

Overview - Project structure

What is it?

Project structure in Svelte means organizing your files and folders in a way that makes your app easy to build, understand, and maintain. It includes where you put your components, styles, scripts, and assets. A good structure helps you find things quickly and keeps your code clean.

Why it matters

Without a clear project structure, your app can become messy and confusing, making it hard to add new features or fix bugs. It slows down teamwork and can cause mistakes. A well-organized project saves time and makes your app more reliable and enjoyable to work on.

Where it fits

Before learning project structure, you should know basic Svelte syntax and how components work. After understanding structure, you can learn about advanced topics like routing, state management, and deployment.

Mental Model

Core Idea

Project structure is like a well-arranged toolbox where every tool has its place, making building and fixing your app faster and easier.

Think of it like...

Imagine your project as a kitchen. If all ingredients, utensils, and appliances are scattered randomly, cooking is slow and frustrating. But if everything has a labeled drawer or shelf, you find what you need quickly and cook smoothly.

Project Root
├── src
│   ├── routes
│   │   ├── +page.svelte
│   │   └── about
│   │       └── +page.svelte
│   ├── lib
│   │   ├── components
│   │   │   └── Button.svelte
│   │   └── utils.js
│   ├── app.html
│   └── main.js
├── static
│   └── images
└── svelte.config.js

Build-Up - 6 Steps

1

Foundation

Understanding the src folder role

Concept: Learn that the src folder holds all your app's source code like components and pages.

In Svelte projects, the src folder is where you write your app's code. It usually contains subfolders like routes for pages and lib for reusable parts. This keeps your code separate from configuration and static files.

Result

You know where to put your Svelte components and pages so they are easy to find and manage.

Knowing that src is the main workspace helps you avoid mixing code with unrelated files, which keeps your project clean.

2

Foundation

Role of static assets folder

Concept: Static assets like images and fonts go into a dedicated folder to keep them separate from code.

The static folder holds files that don’t change during app running, like images, icons, or robots.txt. These files are served as-is to the browser. Keeping them here avoids cluttering your code folders.

Result

You can organize images and other files so they load correctly and don’t get mixed with your code.

Separating static files prevents confusion and makes it easier to manage resources your app needs.

3

Intermediate

Organizing components in lib folder

🤔Before reading on: do you think components should be mixed with pages or kept separate? Commit to your answer.

Concept: Reusable UI parts like buttons or headers belong in a components folder inside lib for easy sharing.

Inside src/lib, create a components folder to store small, reusable pieces of UI. This way, you avoid repeating code and keep your pages clean. For example, a Button.svelte component can be used in many places.

Result

Your components are easy to find and reuse, making your app more consistent and maintainable.

Understanding component reuse saves time and reduces bugs by avoiding duplicate code.

4

Intermediate

Using routes folder for pages

🤔Before reading on: do you think routes folder controls navigation or just stores files? Commit to your answer.

Concept: The routes folder defines the pages users see and how they navigate your app.

In SvelteKit, the routes folder inside src holds files that become pages. For example, +page.svelte is the homepage, and about/+page.svelte is the About page. The folder structure matches the URL paths.

Result

Your app’s URLs and pages are connected naturally, making navigation simple to manage.

Knowing routes map to URLs helps you design your app’s structure around user experience.

5

Advanced

Config files and environment setup

🤔Before reading on: do you think config files belong inside src or at project root? Commit to your answer.

Concept: Configuration files like svelte.config.js live at the project root to control build and environment settings.

Files like svelte.config.js and package.json are at the top level. They tell tools how to build and run your app. Environment variables can be set here or in .env files to keep secrets safe and settings flexible.

Result

Your project builds correctly and adapts to different environments like development or production.

Separating config from code prevents accidental changes and keeps builds predictable.

6

Expert

Scaling project structure for large apps

🤔Before reading on: do you think a flat structure or nested folders work better for big apps? Commit to your answer.

Concept: Large apps need deeper folder organization and clear naming to stay manageable.

As your app grows, group related components, pages, and utilities into nested folders by feature or domain. For example, src/lib/components/ui for UI elements and src/routes/dashboard for dashboard pages. Use index files to simplify imports.

Result

Your app stays organized and easy to navigate even with hundreds of files.

Knowing how to organize by feature prevents chaos and helps teams work together smoothly.

Under the Hood

SvelteKit uses the project structure to map files to URLs and build the app. The routes folder defines pages automatically, and components in lib are compiled into JavaScript and CSS. Static files are copied as-is to the final build folder. Config files guide the build tools on how to process and bundle everything.

Why designed this way?

This structure was chosen to balance simplicity and scalability. Automatic routing from file names reduces manual setup. Separating code, static assets, and config keeps concerns clear. Alternatives like manual routing or mixing assets with code were rejected because they cause confusion and errors.

Project Root
├── svelte.config.js  <-- Build config
├── package.json      <-- Dependencies
├── src               <-- Source code
│   ├── routes        <-- Pages mapped to URLs
│   ├── lib           <-- Reusable components and utils
│   └── app.html      <-- HTML template
├── static            <-- Static assets served directly
└── node_modules      <-- Installed packages

Myth Busters - 4 Common Misconceptions

Quick: Do you think you can put any file anywhere in src and it will work as a page? Commit yes or no.

Common Belief: You can put page files anywhere inside src and they will become pages automatically.

Reality: Only files inside the src/routes folder become pages and map to URLs. Files outside routes are not pages.

Why it matters: Putting pages outside routes means they won’t show up in navigation, causing broken links and confusion.

Quick: Do you think static assets can be imported like components? Commit yes or no.

Common Belief: Static assets like images should be imported in code like components for easier use.

Reality: Static assets are placed in the static folder and referenced by URL paths, not imported as code.

Why it matters: Trying to import static files as code causes build errors and broken images.

Quick: Do you think config files can be placed inside src for better organization? Commit yes or no.

Common Belief: Config files belong inside src to keep all code-related files together.

Reality: Config files must be at the project root because build tools expect them there.

Why it matters: Moving config files inside src breaks the build process and causes errors.

Quick: Do you think a flat project structure is always better than nested folders? Commit yes or no.

Common Belief: Keeping all files in one folder is simpler and better for any project size.

Reality: Flat structures become confusing and hard to maintain as projects grow; nesting by feature improves clarity.

Why it matters: Ignoring nesting leads to messy projects that slow development and increase bugs.

Expert Zone

1

Some components are better placed close to their related pages rather than in a global components folder to reduce unnecessary imports.

2

Using index.js or index.svelte files in folders can simplify imports and improve code readability.

3

Static assets can be organized in subfolders inside static to mirror routes, improving clarity for large projects.

When NOT to use

For very small or experimental projects, strict project structure may slow you down; a simple flat layout can be enough. For complex apps, consider using monorepos or micro-frontends instead of a single large structure.

Production Patterns

In production, teams often use feature-based folder grouping, separate test folders, and environment-specific config files. They also automate checks to enforce structure rules and use aliases for cleaner imports.

Connections

Modular programming

Project structure builds on modular programming by organizing code into reusable, independent parts.

Understanding modularity helps you see why separating components and utilities improves maintainability.

Urban city planning

Both involve organizing spaces (files or buildings) logically to improve navigation and function.

Good project structure is like a well-planned city where roads and zones help people find places quickly and work efficiently.

Library classification systems

Project structure and library systems both categorize items to make searching and retrieval easy.

Knowing how libraries organize books helps understand why grouping files by purpose speeds up development.

Common Pitfalls

#1 Mixing static assets inside src folders

Wrong approach:

src/images/logo.png

Correct approach:

static/images/logo.png

Root cause:

Confusing static files with source code leads to wrong file placement and build errors.

#2 Placing page components outside routes folder

Wrong approach:

src/components/Home.svelte used as a page without routing setup

Correct approach:

src/routes/+page.svelte for homepage

Root cause:

Not understanding that only files in routes become pages causes navigation failures.

#3 Putting config files inside src

Wrong approach:

src/svelte.config.js

Correct approach:

svelte.config.js at project root

Root cause:

Misunderstanding build tool expectations breaks project setup.

Key Takeaways

A clear project structure separates source code, static assets, and configuration for easy management.

The src folder holds your app code, with routes defining pages and lib holding reusable components.

Static files go in the static folder to be served directly without processing.

Organizing by feature or purpose helps scale your app and keeps teamwork smooth.

Misplacing files or configs breaks builds and navigation, so follow the structure rules carefully.

Practice

1. In a Svelte project, where should you place reusable components that can be used across multiple pages?

easy

A. static/components

B. src/routes

C. src/lib

D. public/assets

Solution

1. Step 1: Understand folder purpose

   src/lib is designed for reusable components and utilities.

2. Step 2: Compare with other folders

   src/routes holds pages, public/assets is for static files, and static/components is not a standard folder.

3. Final Answer:

   src/lib -> Option C

4. Quick Check:

   Reusable components = src/lib [OK]

Hint: Reusable parts go in src/lib folder [OK]

Common Mistakes:

• Putting reusable components in src/routes
• Using public folder for components
• Creating non-standard folders like static/components

2. Which of the following is the correct folder to place page files in a SvelteKit project?

easy

A. src/pages

B. src/lib

C. public/pages

D. src/routes

Solution

1. Step 1: Identify the folder for pages

   In SvelteKit, src/routes is the folder where page components live.

2. Step 2: Check other options

   src/lib is for reusable components, public/pages and src/pages are not standard folders for pages.

3. Final Answer:

   src/routes -> Option D

4. Quick Check:

   Pages go in src/routes [OK]

Hint: Pages always go in src/routes in SvelteKit [OK]

Common Mistakes:

• Confusing src/lib with src/routes
• Placing pages in public folder
• Using non-standard src/pages folder

3. Given the following SvelteKit project structure:

project/
├─ public/
│  └─ logo.png
├─ src/
│  ├─ lib/
│  │  └─ Button.svelte
│  └─ routes/
│     └─ index.svelte

Where should you import the Button.svelte component to use it on the homepage?

medium

A. From ./Button.svelte inside src/routes/index.svelte

B. From ../lib/Button.svelte inside src/routes/index.svelte

C. From ../../public/logo.png inside src/routes/index.svelte

D. From public/Button.svelte inside src/routes/index.svelte

Solution

1. Step 1: Understand folder hierarchy

   src/routes/index.svelte is one level deeper than src/lib/Button.svelte, so import path is ../lib/Button.svelte.

2. Step 2: Eliminate wrong paths

   ../../public/logo.png is for static assets, not components; ./Button.svelte assumes Button is in routes folder; public/Button.svelte is incorrect location.

3. Final Answer:

   From ../lib/Button.svelte inside src/routes/index.svelte -> Option B

4. Quick Check:

   Import reusable components with relative path ../lib [OK]

Hint: Use relative path ../lib to import components from routes [OK]

Common Mistakes:

• Trying to import components from public folder
• Using wrong relative path like ./Button.svelte
• Confusing static assets with components

4. You placed an image file inside src/lib/images and tried to use it in your SvelteKit page, but it doesn't load in the browser. What is the most likely reason?

medium

A. Static assets must be inside the public folder to be served correctly.

B. Images must be imported from src/routes folder only.

C. You need to rename the image file to have a .svelte extension.

D. The image file size is too large to load.

Solution

1. Step 1: Understand static asset serving

   SvelteKit serves static files only from the public folder, so files in src/lib/images are not accessible directly.

2. Step 2: Check other options

   Images don't belong in src/routes, renaming to .svelte is incorrect, and file size doesn't prevent loading if path is correct.

3. Final Answer:

   Static assets must be inside the public folder to be served correctly. -> Option A

4. Quick Check:

   Static files go in public folder [OK]

Hint: Put images in public folder to load in browser [OK]

Common Mistakes:

• Placing images inside src/lib or src/routes
• Renaming images as .svelte files
• Assuming large file size causes loading failure

5. You want to organize your SvelteKit project so that:
1. All page routes are inside src/routes.
2. Reusable UI components are inside src/lib/components.
3. Static assets like images and fonts are inside public/assets.

Which folder structure below correctly reflects this setup?

hard

A. project/
├─ public/
│ └─ assets/
│ ├─ images/
│ └─ fonts/
├─ src/
│ ├─ lib/
│ │ └─ components/
│ │ └─ Button.svelte
│ └─ routes/
│ └─ index.svelte

B. project/
├─ src/
│ ├─ assets/
│ │ ├─ images/
│ │ └─ fonts/
│ ├─ components/
│ │ └─ Button.svelte
│ └─ pages/
│ └─ index.svelte

C. project/
├─ public/
│ └─ components/
│ └─ Button.svelte
├─ src/
│ ├─ lib/
│ └─ routes/
│ └─ index.svelte

D. project/
├─ public/
│ └─ assets/
│ └─ Button.svelte
├─ src/
│ ├─ lib/
│ └─ routes/
│ └─ index.svelte

Solution

1. Step 1: Verify static assets location

   Static assets like images and fonts must be inside public/assets to be served correctly.

2. Step 2: Check reusable components and routes

   Reusable components go inside src/lib/components, and pages go inside src/routes.

3. Step 3: Match folder structure

   project/
   ├─ public/
   │  └─ assets/
   │     ├─ images/
   │     └─ fonts/
   ├─ src/
   │  ├─ lib/
   │  │  └─ components/
   │  │     └─ Button.svelte
   │  └─ routes/
   │     └─ index.svelte

   matches all requirements exactly; other options place assets or components incorrectly.

4. Final Answer:

   Option A folder structure -> Option A

5. Quick Check:

   Correct folder setup =

   project/
   ├─ public/
   │  └─ assets/
   │     ├─ images/
   │     └─ fonts/
   ├─ src/
   │  ├─ lib/
   │  │  └─ components/
   │  │     └─ Button.svelte
   │  └─ routes/
   │     └─ index.svelte

   [OK]

Hint: Static assets in public, components in src/lib, pages in src/routes [OK]

Common Mistakes:

• Putting static assets inside src folder
• Placing components in public folder
• Using non-standard folders like pages instead of routes