Svelte Starter

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

Notes

Do not use or reproduce The Pudding logos or fonts without written permission.
Prettier Formatting: Disable any text editor Prettier extensions to take advantage of the built-in rules.

Features

Feather Icons for simple/easy svg icons
ArchieML for micro-CMS powered by Google Docs and Sheets
Style Dictionary for CSS/JS style parity
CSV, JSON, and SVG imports
SSR static-hosted builds by default

Quickstart

Click the green Use this template button above.
In your local repo run pnpm install or npm install

Alternatively:

npx degit the-pudding/svelte-starter my-project

Development

npm run dev

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

Subdirectories

If you are hosting the project on a subdirectory, set it in package.json.

For example, if you are deploying to https://domain.com/2021/01/test:

"svelteStarter": {
  "subdirectory": "/2021/01/test"
}

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.

Google Docs and Sheets

Create a Google Doc or Sheet
Click Share -> Advanced -> Change... -> Anyone with this link
In the address bar, grab the ID - eg. "...com/document/d/1IiA5a5iCjbjOYvZVgPcjGzMy5PyfCzpPF-LnQdCdFI0/edit"
paste in the ID above into google.config.cjs, and set the filepath to where you want the file saved
If you want to do a Google Sheet, be sure to include the gid value in the url as well

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

Pre-loaded helpers

Components

Located in src/lib/components.

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

Footer.svelte: Pudding recirculation and social links.
Header.svelte: Pudding logo.

Helper Components

Located in src/lib/components/helpers.

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

ButtonSet.svelte: Accessible button group inputs
Icon.svelte: Simple integration with Feather Icons.
Range.svelte: Customizable range slider
Scrolly.svelte: Scrollytelling
Slider.svelte (and Slider.Slide.svelte): A slider widget, especially useful for swipe/slide stories.
Tap.svelte: Edge-of-screen tapping library, designed to integrate with slider.
Toggle.svelte: Accessible toggle inputs

Actions

Located in src/lib/actions.

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

css.js: dynmically change the value of a CSS variable.
inView.js: detect when an element enters or exits the viewport.

Stores

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

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

mq: returns an object of media queries booleans if they are enabled or not. You can modify them in the js file.
viewport: returns an object { width, height } of the viewport dimensions. It is debounced for performance.
scrollY: returns an number window vertical scroll position. It is throttled using rAF for performance.
timer: returns an object { timer, elapsed }. timer has 5 methods (start, stop, toggle, set, reset) and elapsed is a store that is the number of ms.

Utils

Located in src/lib/utils/.

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

checkOverlap.js: Label overlapping detection. Loops through selection of nodes and adds a class to the ones that are overlapping. Once one is hidden it ignores it.
csvDownload.js: Converts a flat array of data to CSV content ready to be used as an href value for download.
loadImage.js: Loads an image.
loadPixels.js: Loads the pixel data of an image via an offscreen canvas.
mapToArray.js: Convenience function to convert a map to an array.
move.js: transform translate function shorthand.
transformSvg.js: Custom transition lets you apply an svg transform property with the in/out svelte transition. Parameters (with defaults):
translate.js: Convenience function for transform translate css.
urlParams.js: Get and set url parameters.

Gotchas

Any @html tags, e.g., {@html user} must be the child of a dom element so they can be properly hydrated.
Putting asset paths in CSS doesn't work without some hacks for subdirectory hosted projects

russellsamora / d3-the-mighty-join