SwyxKit
A lightly opinionated starter for SvelteKit blogs:
Feel free to rip out these opinions as you see fit of course.
"Does anyone know what theme that blog is using? It looks really nice." - anon
Live Demo
See https://swyxkit.netlify.app/ (see Deploy Logs)
![screenshot of swyxkit in action](https://user-images.githubusercontent.com/6764957/147861359-3ad9438f-41d1-47c8-aa05-95c7d18497f0.png)
![screenshot of swyxkit in action](https://user-images.githubusercontent.com/6764957/147861337-d40a1798-e7ff-40e1-8dd8-ba1350fd3784.png)
Users in the wild
Key Features and Design Considerations:
- Features
- Dark mode
- GitHub-Issues-driven blog with index
- RSS (at
/rss.xml
), and Sitemap (at sitemap.xml
) with caching
- Performance/Security touches
- Minor design/UX touches
- Developer Experience
This is a partial implementation of https://www.swyx.io/the-surprisingly-high-table-stakes-of-modern-blogs/
Setup
Step 0: Clone project (and deploy)
npx degit https://github.com/sw-yx/swyxkit
export GH_TOKEN=your_gh_token_here # Can be skipped if just trying out this repo casually
npm install
npm run start # Launches site locally at http://localhost:5173/ and histoire at http://localhost:6006/
You should be able to deploy this project straight to Netlify as is, just like this project is. This project recently switched to use sveltejs/adapter-auto
(Oct 2022: currently pinned to v72 because of a Netlify issue), so you should also be able to deploy to Vercel and Cloudflare, but this is not regularly tested (please report/help fix issues if you find them)!
However, to have new posts show up, you will need to personalize the siteConfig
(see next step) - take note of APPROVED_POSTERS_GH_USERNAME
in particular (this is an allowlist of people who can post to the blog by opening a GitHub issue, otherwise any rando can blog and that's not good).
![Deploy to Netlify](https://camo.githubusercontent.com/5b6a0d20f6dd7e28daf146c3aa6493836efc7334c8f9675bbbb1c3750368c3f6/68747470733a2f2f7777772e6e65746c6966792e636f6d2f696d672f6465706c6f792f627574746f6e2e737667)
# These are just untested, suggested commands, use your discretion to hook it up or deploy wherever
git init
git add .
git commit -m "initial commit"
gh repo create # Make a new public GitHub repo and name it whatever
git push origin master
ntl init # Use the Netlify cli to deploy, assuming you already installed it and logged in. You can also use `ntl deploy`
Step 1: 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 APPROVED_POSTERS_GH_USERNAME = ['sw-yx']; // IMPORTANT: change this to at least your GitHub username, or add others if you want
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';
export const POST_CATEGORIES = ['Blog']; // Other categories you can consider adding: Talks, Tutorials, Snippets, Podcasts, Notes...
export const GH_PUBLISHED_TAGS = ['Published']; // List of allowed issue labels, only the issues having at least one of these labels will show on the blog.
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.
When deploying, don't forget to set it in Netlify: https://app.netlify.com/sites/YOUR_SITE/settings/deploys#environment
Step 2: Make your first post
Open a new GitHub issue on your new repo, write some title and markdown in the body, add a Published
tag (or any one of the label set in GH_PUBLISHED_TAGS
), and then save.
You should see it refetched in local dev or in the deployed site pretty quickly. You can configure SvelteKit to build each blog page up front, or on demand. Up to you to trade off speed and flexibility.
If your Published
post (any post with one of the labels set in GH_PUBLISHED_TAGS
) doesn't show up, you may have forgotten to set APPROVED_POSTERS_GH_USERNAME
to your GitHub username in siteConfig
.
If all of this is annoying feel free to rip out the GitHub Issues CMS wiring and do your own content pipeline, I'm not your boss. MDSveX is already set up in this repo if you prefer not having a disconnected content toolchain from your codebase (which is fine, I just like having it in a different place for a better editing experience). See also my blogpost on the benefits of using GitHub Issues as CMS.
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.
- Have a process to submit your sitemap to Google? (or configure
robots.txt
and hope it works)
- Testing: make sure you have run
npx playwright install
and then you can run npm run test
Further Reading
Acknowledgements
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