Svelte Starter

This starter template aims for fast and easy web development speficially for data-driven and visual stories. It is an opinionated template built on top of SvelteKit.

Please Note: 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
• LayerCake enabled by default for chart making
• Style Dictionary for CSS/JS style parity
• Includes csv, json, and svg imports by default
• Static-hosted builds by default

Quickstart

New school: just click the Use this template button above.

Old school:

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

Then in your local repo:

npm install

Development

To start the dev server:

npm run dev

Modify content in src and static/assets.

Deploy

npm run build

This generates a directory called build with the server-side rendered static-hostable app.

If deploying to github pages:

make github

Style

There are a few stylesheets included by default in src/styles. Put anything global in app.css. For variable parity in both CSS and JS, modify files in the properties folder using the Style Dictionary API.

You can use SCSS or another CSS preprocessor by installing the module (eg. node-sass) and including the property in the svelte-preprocess in svelte.config.cjs.

Google Docs and Sheets

• Create a Google Doc or Sheet
• Click Share button -> advanced -> Change... -> to "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.

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

Helper Components

Located in src/lib/components/helpers.

• Window.svelte: A wrapper around svelte:window that automatically debounces resize and throttles scroll, storing innerHeight, innerWidth, and scrollY as global stores.
• Icon.svelte: Simple integration with Feather Icons.
• 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.

Actions

Located in src/lib/actions.

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

Utils

Located in src/lib/utils/.

• mapToArray.js: Convenience function to convert maps (generated from d3 group and rollup) to iterable array of objects.
• move.js: transform translate function shorthand.

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. To include them do this (replacing name):

import name from "$stores/name.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

transformSvg.js: this custom transition lets you apply an svg transform property with the in/out svelte transition. Parameters (with defaults):

{
    target: "", // string: transform properties [required]
    delay: 0, // number: ms
    duration: 250, // number: in ms
    easing: linear, // function: svelte easing function
    relative: false, // boolean: adds target onto pre-existing transform
    opacity: false // boolean: to fade in/out as well
}

Usage

<g out:transformSvg={{ target: "translate(50, 50)" }}>

Notes

Any @html tags, e.g., {@html user} must be the child of a dom element so they can be properly hydrated.