Cmsvelte
CMSvelte
A Svelte starter template built with newsroom CMS's in mind. Dynamically create inline graphics based on the placement of figure elements with defined data-cmsvelte attributes.
Inspired by graphics rigs at Bloomberg, The Pudding, and The Wall Street Journal. Created with the help of Kazi Awal.
Previously known as tiny-svelte.
Local env requirements
Useful docs to features
- Svelte as a component framework
- Vite (with Rollup under the hood) for front-end tooling
- TailwindCSS + PostCSS for predefined styles, classes and syntax
- ArchieML as a micro-CMS powered by Google Docs
- ai2html for responsive static images and charts
- D3 + LayerCake for charting
- vite-imagetools for transforming images on the fly in Vite using Sharp
Quickstart
Use degit to create a new repo using this one as a template.
npx degit sawyerclick/cmsvelte my-cmsvelte
Scripts
npm run fetch:sheet
This template has out-of-the-box features to help with consuming data from google sheets. Tag the Google Sheet for your graphic in ./config.json and make sure you have the ID and sheet ID (gid) filled out correctly. Make sure the share permissions on the sheet are set up so that it is viewable by anyone with the share link. Note: Don't make it available to edit by anybody!
Directly import csv's into your .svelte file via @rollup/plugin-dsv
import data from '$lib/data/data.csv'
npm run fetch:copy
Like a lot of newsrooms, this uses a Google Doc and ArchieMl approach to make copy content management easier. The setup is similar to using Sheets data. Make sure the share permissions on the doc are set up so that it is viewable by anyone with the share link. Grab the document ID from the address bar — ...com/document/d/1IiA5a5iCjbjOYvZVgPcjGzMy5PyfCzpPF-LnQdCdFI0/edit — and paste it into the respective property in ./config.json.
htmlparser2 and html-entities act as a middle man to catch various tags like <a>, <h*>, <ul> and more.
Import copy into your package like any JSON file
import copy from '$lib/data/copy.json'
Development
nvm use
npm install
npm run dev
Modify content in src.
Adding and removing graphics
CMSvelte's power is dynamic placement unrestrained by content. After build, you can place the <figure data-cmsvelte="CHART-ID"> elements anywhere in the CMS and they will load.
To place graphics, edit index.html by adding or removing figures such as this: <figure data-cmsvelte="CHART-ID"></figure>.
Then, in src/main.ts, import your wrapper component up top and add the applicable data to the component array. Every object in this array should have 1) a matching <figure> element in index.html and 2) an imported component:
const components = [
{
chartID: 'CHART-ID',
Component: ImportedComponent,
props: {}
},
{
chartID: 'CHART-ID2',
Component: ImportedComponent2,
props: {}
},
{
chartID: 'CHART-ID3',
Component: ImportedComponent3,
props: {}
},
];
Notes:
- High-level props can be passed down here as well using the
props: {}object passed in MountComponent.
Writing styles
It's recommended to include the CMS's styles in a development environment and defer to them for fonts and classes to reduce the shipped CSS. This can be done by adding objects to a cmsFiles array in main.ts. This appends any tag and it's listed attributes to the <head> while in dev mode. These are not included in production.
Otherwise, this template uses Tailwind for out-of-the-box classes that we don't have to think about. By default, these classes are prefixed with cmsvelte- to prevent clashing with CMS classes. This can be changed in tailwind.config.cjs.
Write global styles in app.postcss. Otherwise, use Svelte's built-in scroped styling syntax.
Asset management
For image optimization see vite-imagetools or sharp.
Vite's Static Asset Handling lets us import image and SVG files with several options.
As files
Imports the hashed file name for the asset. For example, imgUrl will be /img.png during development, and become /assets/img.2d8efhg.png in the production build.
import imgUrl from '$lib/assets/img.png'
As strings
Import raw strings by appending ?raw at the end. This is useful for SVG files.
import imgUrl from '$lib/assets/img.svg?raw'
Useful libs
- body-scroll-lock - Enables body scroll locking (for iOS Mobile and Tablet, Android, desktop Safari/Chrome/Firefox) without breaking scrolling of a target element (eg. modal/lightbox/flyouts/nav-menus).
- focus-trap - Trap focus within a DOM node.
- fullpage.js - Create fullscreen scrolling websites.
- gsap - Professional-grade animation for the modern web.
- journalize - A collection of functions useful for making prose reader friendly.
- lodash - Various helper functions.
- slugify - Easily slug a string.
- @sveltejs/svelte-scroller - Svelte-y scrollytelling
- svelte-select - A select/autocomplete component for Svelte apps. With support for grouping, filtering, async and more.
- swiper - Modern mobile touch slider with hardware accelerated transitions and amazing native behavior.
Deployment
npm run build
In the project root the command generates a directory called build. The built files have names without hashing thanks to Rollup's config options. You only need to embed once as the graphics are generated client-side.
The generated files will likely live in an S3 bucket or other storage site. Update the base url in vite.config.js to match the final URL of the files. A script to facilitate file uploading to S3 or another service can be easily written in the scripts folder.
base: mode === 'production' ? link : '/',
The resulting build/index.html file is what can be embedded. It should look something like this, with a <figure> element for each graphic, as well as <script>s and <link>s to external files:
<script type="module" crossorigin src="https://www.site.com/path/to/index.js"></script>
<link rel="modulepreload" href="https://www.site.com/path/to/vendor.js">
<link rel="stylesheet" href="https://www.site.com/path/to/vendor.css">
<link rel="stylesheet" href="https://www.site.com/path/to/index.css">
<figure data-cmsvelte="castle-img"></figure>
<figure data-cmsvelte="bar-chart"></figure>
<figure data-cmsvelte="ai2html"></figure>
Scripts and styles should be embedded once anywhere in the CMS. The <figure data-cmsvelte=""> elements can be moved around as needed and do not need to live side-by-side. The index.js script will generate the graphics accordingly based on the data-cmsvelte attribute.
