Home

Awesome

Svelte Starter

NOTE: This uses Svelte 5 and is under active migration (not all features will work). For the less adventurous, use the previous version (with Svelte 4).

This starter template aims to quickly scaffold a SvelteKit project, designed around data-driven, visual stories at The Pudding.

Notes

Features

Quickstart

From Scratch

Pre-existing Project

Installation

Development

npm run dev

Change the script in package.json to "dev": "svelte-kit dev --host" to test on your local network on a different device.

Deploy

npm run build

This generates a directory called build with the statically rendered app.

A shortcut for github pages:

make github

Deploying to Pudding AWS:

make pudding

Style

There are a few stylesheets included by default in src/styles. Refer to them in app.css, the place for applying global styles.

For variable parity in both CSS and JS, modify files in the properties folder using the Style Dictionary API.

Run npm run style to regenerate the style dictionary.

Some css utility classes in reset.css

Custom Fonts

For locally hosted fonts, simply add the font to the static/assets folder and include a reference in src/styles/font.css, making sure the url starts with "assets/...".

Google Docs and Sheets

Running npm run gdoc at any point (even in new tab while server is running) will fetch the latest from all Docs and Sheets.

Structural Overview

Pages

The src/routes directory contains pages for your app. For a single-page app (most cases) you don't have to modify anything in here. +page.svelte represents the root page, think of it as the index.html file. It is prepopulated with a few things like metadata and font preloading. It also includes a reference to a blank slate component src/components/Index.svelte. This is the file you want to really start in for your app.

Embedding Data

For smaller datasets, it is often great to embed the data into the HTML file. If you want to use data as-is, you can use normal import syntax (e.g., import data from "$data/file.csv"). If you are working with data but you want to preserve the original or clean/parse just what you need to use in the browser to optimize the front-end payload, you can load it via +page.server.js, do some work on it, and return just what you need. This is passed automatically to +page.svelte and accessible in any component with getContext("data").

Pre-loaded helpers

Components

Located in src/components.

// Usage
import Example from "$components/Example.svelte";

Helper Components

Located in src/components/helpers.

// Usage
import Example from "$components/helpers/Example.svelte";

Available

Need to migrate

Headless Components

bits UI comes pre-installed. It is recommended to use these for any UI components.

Layercake Chart Components

Starter templates for various chart types to be used with LayerCake. Located in src/components/layercake.

Note: You must install the module layercake first.

// Usage
import Example from "$components/layercake/Example.svelte";

Actions

Located in src/actions.

// Usage
import example from "$actions/action.js";

Runes

These are located in src/runes. You can put custom ones in src/runes/misc.js or create unique files for more complex ones.

// Usage
import example from "$runes/example.js";
import { example } from "$runes/misc.js";

Available

Need to migrate

Utils

Located in src/utils/.

// Usage
import example from "$utils/example.js";

Tips

Image asset paths

For img tags, use relative paths:

<img src="assets/demo/test.jpg" alt="cat" />

For CSS background images, use absolute paths:

background: url("/assets/demo/test.jpg");

View example code in the preloaded demo.