alexjsteffen/swyxkit

A lightly opinionated starter for Svelte projects:

SvelteKit + Netlify adapter!
Tailwind 3 + Tailwind Typography (with swyx fixes)
JSDoc Typechecking
GitHub Issues as CMS

Feel free to rip out these opinions as you see fit of course.

Live Demo

See https://swyxkit.netlify.app/ (see Deploy Logs)

Users in the wild

https://swyx.io
https://twitter.com/iambenwis/status/1500998985388937216?s=21
add yourself here!

Key Features and Design Considerations:

Features
- Dark mode
- Github-issues-driven Blog with blog index
  - Blog content pulled from the GitHub Issues API
  - Comment and Reaction system from Github Issues
  - 🆕 Shortcodes for embedding Tweets and YouTube videos
  - Consumes markdown/MDSveX
    - with syntax highlighting
    - fixes for known MDSvex render issue
- RSS (at /api/rss.xml) with caching
Performance/Security touches
- set s-maxage (not max-age) to 1 minute to cache (consider making it 1-7 days on older posts)
  - for API endpoints as well as pages
- Security headers in netlify.toml
  - X-Content-Type
  - X-Frame-Options
  - X-XSS-Protection
  - SvelteKit does not yet support CSP - PR pending here
- Builds and Deploys in ~40 seconds on Netlify
Minor design/UX touches
- Top level blog URLs (/myblog instead of /blog/myblog - why)
- Blog index truncates at 20 posts to make sure to render quickly
- Comments are rendered and sanitized
- Error page (try going to URL that doesnt exist)
  - including nice error when github api rate limit exceeded - fix with GH_TOKEN
- Navlink hover effect
- Mobile/Responsive styling
  - Mobile menu with animation
- Og:image and meta tags for social unfurls (not automatically generated though)
- Accessibility
  - SVG Icons https://github.com/sw-yx/spark-joy/blob/master/README.md#general--misc
  - Tap targets
- Custom scrollbar https://css-tricks.com/strut-your-stuff-with-a-custom-scrollbar/
- Defensive CSS touches https://ishadeed.com/article/defensive-css
Code Quality
- JSDoc Typechecking
- ESLint + Prettier
- Nightly lockfile upgrades

Setup

npx degit https://github.com/sw-yx/swyxkit
export GH_TOKEN=your_gh_token_here # can skip if just trying out this repo casually
npm install
npm run start

You should be able to deploy this project straight to Netlify as is, just like this project is.

Personalization Configuration

As you become ready to seriously adopt this, remember to configure /lib/siteConfig.js - just some hardcoded vars i want you to remember to configure.

export const SITE_URL = 'https://swyxkit.netlify.app';
export const GH_USER_REPO = 'sw-yx/swyxkit'; // used for pulling github issues and offering comments
export const REPO_URL = 'https://github.com/' + GH_USER_REPO;
export const SITE_TITLE = 'SwyxKit';
export const SITE_DESCRIPTION = "swyx's default SvelteKit + Tailwind starter";
export const DEFAULT_OG_IMAGE =
	'https://user-images.githubusercontent.com/6764957/147861359-3ad9438f-41d1-47c8-aa05-95c7d18497f0.png';
export const MY_TWITTER_HANDLE = 'swyx';
export const MY_YOUTUBE = 'https://youtube.com/swyxTV';

Of course, you should then go page by page (there aren't that many) and customize some of the other hardcoded items, for example

the Newsletter component needs to be wired up to a newsletter service (I like buttondown, tinyletter, and revue)
page Cache-Control policy and SvelteKit maxage
site favicons (use https://realfavicongenerator.net/ to make all the variants and stick it in /static)
(if migrating content from previous blog) setup Netlify redirects at /static/_redirects

This blog uses GitHub as a CMS - if you are doing any serious development at all, you should give the GH_TOKEN env variable to raise rate limit from 60 to 5000.

Just make a really basic personal access token here, should be enough. https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
and set the env variables in Netlify

When deploying, don't forget to set it in Netlify: https://app.netlify.com/sites/YOUR_SITE/settings/deploys#environment

Optimizations to try after you are done deploying

Customize your JSON+LD for FAQ pages, organization, or products. There is a schema for blogposts, but it is so dead simple that swyxkit does not include it.

Acknowledgements

Design from Lee Robinson: https://github.com/leerob/leerob.io/
MDSvex from Pngwn is amazing https://mdsvex.pngwn.io/docs#layout
Other people's code I borrowed from
- https://github.com/mvasigh/sveltekit-mdsvex-blog
- https://github.com/sveltejs/kit/blob/master/examples/hn.svelte.dev/src/routes/%5Blist%5D/rss.js
- RSS
  - https://scottspence.com/posts/make-an-rss-feed-with-sveltekit
  - https://www.davidwparker.com/posts/how-to-make-an-rss-feed-in-sveltekit
  - Reasons it is hard to do dynamic RSS in Sveltekit:
    - Sveltekit Endpoints dont take over from Sveltekit dynamic param routes ([slug].svelte has precedence over rss.xml.js)
    - RSS Endpoint runs locally but doesnt run in Netlify bc no access to the content in prod (SvelteKit issue)
Find more sveltekit projects at https://github.com/janosh/awesome-svelte-kit

Todos

implement etag header for github api
store results in netlify build cache
separate hydration path for mobile nav (so that we could hydrate=false some pages)
custom components in MDX, and rehype plugins

alexjsteffen / swyxkit