Introduction
At This Dot Labs, we love Svelte. We've even created a starter.dev kit for SvelteKit that you can use to scaffold your next frontend project using SCSS, TypeScript, Vitest and Storybook.
What is starter.dev?
Starter.dev helps developers get started building web apps with a variety of frameworks, showcasing how various libraries can fit together to solve similar problems. To do that, This Dot Labs has built a series of showcase apps that recreate the experience of using GitHub.
What is SvelteKit? How is it unique?
SvelteKit is a full-stack framework that gives you the best of both worlds: the page is server-side rendered on your first visit, but when you navigate to other pages, they are client-side rendered. SvelteKit gives you levers for your pages to use SSR (server-side rendering), CSR (client-side rendering), SSG (static site generation), SPA (single page application) & MPA (multi page application). The core of SvelteKit provides a highly configurable rendering engine.
Why SvelteKit and not Svelte?
SvelteKit isn’t built on top of Svelte, but it’s a backend web framework where Svelte is used as the view layer. In theory, you could rip it out and replace it with another component framework that supports server-side rendering, and the same is true for other web frameworks.
This allows us to deploy everything as a Node server, or even use Vercel and serverless functions.
Other reasons to use SvelteKit include:
- Pages (file based routing)
- Endpoints (API routes)
- Nested layouts (way more powerful than just nesting files because the segment of the URL maps to your component hierarchy)
- Hot module replacement (instant updates in the browser when you make a change preserving application state)
- Preprocessing (TypeScript, SCSS, and Pug among others)
- Building component libraries (creating and publishing npm packages)
- Deployment options (adapters for any platform)
Building a SvelteKit showcase presented several challenges given its uniqueness and different approach to building web apps. This blog post details what we chose to include in our SvelteKit GitHub clone, and how we integrated them.
Project Structures and Naming Conventions
SvelteKit has unique conventions in its project structure and naming conventions.
Project Files
src
This is the meat of the project:
lib
contains your library code, which can be imported via the$lib
alias, or packaged up for distribution usingsvelte-package
. It can be imported by using the$lib/*
alias.server
contains your server-only library code. SvelteKit will prevent you from importing these in client code.components
contain single responsibility components that are imported in our routes. They typically contain three files:.spec.ts
for unit tests,.svelte
and.stories.ts
for storybook stories. Barrel files were not necessary here.images
contains images that can be imported, and used in the project.stores
contains state that needs to be accessed by multiple unrelated components, or by a regular JS module.styles
contains styles that can be imported in our Svelte applications.
params
contains any param matchers your app needsroutes
contains theroutes
of your applicationapp.html
is your page template — an HTML document containing the following placeholders:%sveltekit.head%
— link and script elements needed by the app, plus any head content%sveltekit.body%
— the markup for a rendered page. This should live inside a<div>
or other element, rather than directly inside the body element, to prevent bugs caused by browser extensions injecting elements that are then destroyed by the hydration process. SvelteKit will warn you in development if this is not the case%sveltekit.assets%
— either paths.assets, if specified, or a relative path to paths.base%sveltekit.nonce%
— a CSP nonce for manually included links and scripts, if used
hooks.server.ts
contains your application's hooks
static
Any static assets that should be served as-is, like robots.txt
or favicon.png
, go in here.
svelte.config.js
This file contains your Svelte and SvelteKit configuration.
tsconfig.json
Since SvelteKit relies on certain configuration being set a specific way, it generates its own .svelte-kit/tsconfig.json
file, which your own config extends.
vite.config.js
A SvelteKit project is really just a Vite project that uses the @sveltejs/kit/vite plugin, along with any other Vite configuration.
Routing
To get a deep dive of how routing works with SvelteKit, please check out this article.
SCSS
SvelteKit supports a number of CSS preprocessors.
For people who are new to Svelte or SvelteKit, the syntax for using SCSS or SASS is simple, just need to add the lang="sass" attribute to the style tag.
<style lang="scss">
ul {
list-style-type: circle;
li {
position: relative;
}
}
</style>
npm i -D sass
Then add SCSS support with the svelte-preprocess
package.
// svelte.config.js
import adapter from "@sveltejs/adapter-auto";
import preprocess from "svelte-preprocess";
/** @type {import('@sveltejs/kit').Config} */
const config = {
// Consult https://github.com/sveltejs/svelte-preprocess
// for more information about preprocessors
preprocess: preprocess({ typescript: true, scss: true }),
kit: {
adapter: adapter(),
},
};
export default config;
Why SCSS and not Tailwind?
Tailwind CSS has been used by several other starter kits. We otherwise decided to go with SCSS as the syntax is simple and easily understood by even beginners.
Vitest
Test Driven Development (TDD) is one of the best ways to ensure your code works like it's supposed to work. It can also help you create reliable builds during continuous deployments.
Vitest is an up-and-coming testing framework which has similar functionality to Jest.
Since we are using Vite as our build tool for Svelte in this kit, Vitest has very good integration with Vite, and offers a similar testing environment without needing extra configuration.
To test Svelte components that seemed to be hard to test. Such as two-way bindings, name slots, Context API, etc., we need to add more configuration.
We added @testing-library/svelte
, jsdom
and @testing-library/jest-dom
that allow for similar functionality as Jest.
npm i -D @testing-library/svelte @testing-library/jest-dom jsdom
We ensured the $lib
alias is supported in our tests by resolving the alias in our vite.config.ts
. We also added a setupTest.ts
to add @testing-library/jest-dom
matchers & mocks of SvelteKit modules.
// vite.config.ts
import { sveltekit } from "@sveltejs/kit/vite";
import type { UserConfig } from "vite";
import { configDefaults, type UserConfig as VitestConfig } from "vitest/config";
import path from "path";
const config: UserConfig & { test: VitestConfig["test"] } = {
plugins: [sveltekit()],
define: {
// Eliminate in-source test code
"import.meta.vitest": "undefined",
},
test: {
// jest like globals
globals: true,
environment: "jsdom",
// in-source testing
includeSource: ["src/**/*.{js,ts,svelte}"],
// Add @testing-library/jest-dom matchers & mocks of SvelteKit modules
setupFiles: ["./setupTests.ts"],
// Exclude files in c8
coverage: {
exclude: ["setupTest.ts"],
},
deps: {
// Put Svelte component here, e.g., inline: [/svelte-multiselect/, /msw/]
inline: [],
},
// Exclude playwright tests folder
exclude: [...configDefaults.exclude, "tests"],
},
// Ensure the $lib alias is supported in our tests
resolve: {
alias: {
$lib: path.resolve(__dirname, "./src/lib"),
},
},
};
export default config;
// setupTest.ts
/* eslint-disable @typescript-eslint/no-empty-function */
import matchers from "@testing-library/jest-dom/matchers";
import { expect, vi } from "vitest";
import type { Navigation, Page } from "@sveltejs/kit";
import { readable } from "svelte/store";
import * as environment from "$app/environment";
import * as navigation from "$app/navigation";
import * as stores from "$app/stores";
// Add custom jest matchers
expect.extend(matchers);
// Mock SvelteKit runtime module $app/environment
vi.mock("$app/environment", (): typeof environment => ({
browser: false,
dev: true,
building: false,
version: "any",
}));
// Mock SvelteKit runtime module $app/navigation
vi.mock("$app/navigation", (): typeof navigation => ({
afterNavigate: () => {},
beforeNavigate: () => {},
disableScrollHandling: () => {},
goto: () => Promise.resolve(),
invalidate: () => Promise.resolve(),
invalidateAll: () => Promise.resolve(),
preloadData: () => Promise.resolve(),
preloadCode: () => Promise.resolve(),
}));
// Mock SvelteKit runtime module $app/stores
vi.mock("$app/stores", (): typeof stores => {
const getStores: typeof stores.getStores = () => {
const navigating = readable<Navigation | null>(null);
const page = readable<Page>({
url: new URL("http://localhost"),
params: {},
route: {
id: null,
},
status: 200,
error: null,
data: {},
form: undefined,
});
const updated = {
subscribe: readable(false).subscribe,
check: () => false,
};
return { navigating, page, updated };
};
const page: typeof stores.page = {
subscribe(fn) {
return getStores().page.subscribe(fn);
},
};
const navigating: typeof stores.navigating = {
subscribe(fn) {
return getStores().navigating.subscribe(fn);
},
};
const updated: typeof stores.updated = {
subscribe(fn) {
return getStores().updated.subscribe(fn);
},
check: () => false,
};
return {
getStores,
navigating,
page,
updated,
};
});
If you want to see some test recipes you can use on your SvelteKit projects, check out our SvelteKit-SCSS Github showcase.
Storybook
Like many of the other starter.dev kits, the SvelteKit starter uses Storybook to interactively view and build components in isolation.
For more information on Storybook and SvelteKit visit the article.
Linting
ESLint
and Prettier
are useful tools for keeping the project neat and consistent among multiple contributors.
To quickly format your project, run:
npm run format
Running ESLint and Prettier as part of your git workflow is important because it helps you fail fast. This helps us, as contributors, to have a more consistent production codebase.
We achieved this in our SvelteKit-SCSS Github showcase with the help of Husky
, lint-staged
and Prettier
.
How does lint-staged
work? It's specifically designed to work on "staged" files, which are files you've changed or created, but haven't yet committed to your project. Working on staged files limits the number of files you need to lint at any given time, and makes the workflow faster.
We configured lint-staged
in our package.json
. This runs Prettier
pre-commit, and ensures the code is up to our ESLint standards.
// package.json
"lint-staged": {
"src/**/*{.js,.ts,.html,.css,.svelte}": [
"prettier --plugin-search-dir . --write ."
],
"src/**/*{.js,.ts,.svelte}": "eslint ."
},
The commands you configure will run "pre-commit". As you're attempting to commit files to your project you'll see ESLint run in your terminal. Once it's done you may have successfully committed, or find yourself with linting errors you need to fix before you're able to commit the code.
This works hand-in-hand with husky
. Husky uses distinct bash files with filenames that match the workflow step they correspond to, e.g. "pre-commit".
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
cd svelte-kit-scss
npx lint-staged
Running ESLint, or Prettier as part of your git workflow is important because it helps you fail fast, which helps contributors have a more consistent production codebase.
Conclusion
SvelteKit is a relatively new and novel framework. The structure represents our best judgment of how a basic SvelteKit application should be. We welcome everyone to take a look, and contribute back to the SvelteKit-SCSS and our SvelteKit-SCSS Github showcase if you have any improvements that you would like to propose!