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.