SousChef

A finishable feed for the accounts you follow. Pick your YouTube channels, X accounts and Substack publications, get one chronological feed, mark items Done or Archive, and reach "You're all caught up." No infinite scroll, no algorithm.

Live at https://trysouschef.vercel.app

Features

• Three sources, one feed. Add YouTube channels (URL, @handle, ID or name, or import your subscriptions), X accounts (@handle) and Substack publications (URL or name).
• Keyword filters. Give a channel keyword chips to see only matching items. Any chip can match; a chip with several words needs all of them. Matching ignores case and Turkish diacritics.
• Read and watch in place. YouTube plays in the app, with an option to hide Shorts. X posts show full text, images, video and quoted posts. Substack posts expand into the full article.
• Done and Archive. Done clears an item; Archive saves it for later in its own tab. New items since your last visit are badged.
• Topic grouping (optional). A switch groups your unread X posts into labelled topic cards, each with a short AI summary. It is off by default.
• Accounts. Sign in with Google or an emailed magic link. Your channels, archive and settings sync across devices, and you can export your data or delete your account from Settings.
• Light and dark themes.

Stack

• Front end: vanilla JavaScript, with no framework and no build step.
• Back end: Vercel serverless functions in api/.
• Database: Neon Postgres, through the project's only npm dependency.
• External services: YouTube Data API v3, X API v2, Substack RSS, the Anthropic Messages API (topic grouping), Resend (sign-in emails) and Google OAuth.

Run locally

Requires Node 18 or later.

npm install
node dev-server.mjs

The landing page is at http://localhost:3000 and the app is at http://localhost:3000/app. The server answers only this computer; use node dev-server.mjs --lan to open the app on a phone on the same network.

Configuration goes in a .env file at the repo root:

Variable	What it enables	Without it
DATABASE_URL	Sign-in and sync (Neon Postgres)	Nobody can sign in
DEV_DATABASE_URL	A separate development database, used instead of DATABASE_URL outside production	DATABASE_URL is used
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET	Sign in with Google, and YouTube import	The Google button is unavailable
RESEND_API_KEY	Magic-link emails	No email is sent
YOUTUBE_API_KEY	The YouTube Data API	Falls back to RSS and page scraping
X_BEARER_TOKEN	X accounts	X is unavailable
ANTHROPIC_API_KEY	Topic grouping	The feed stays ungrouped
X_DAILY_POST_QUOTA	A daily per-person limit on X posts	Usage is counted and nobody is limited
ADMIN_EMAIL	The usage dashboard at /admin.html for that account	The dashboard is closed

Create the tables once with node scripts/init-db.mjs. It is safe to re-run.

Check which database you are on. If DATABASE_URL is your production database, set DEV_DATABASE_URL to a development one before running anything locally. The dev server prints the database host when it starts, and scripts that write refuse production unless you pass --prod.

If you fork this: magic-link emails are sent from the address in api/_resend.js. Change it to a domain you have verified with Resend. The Google OAuth client needs <origin>/api/auth/google/callback as an authorised redirect URI.

Project layout

index.html, landing.js    landing page, served at /
app/index.html            app shell, served at /app
app.js, style.css         client logic and styles
lib/pure.js               pure functions shared by the app and the tests
privacy/index.html        privacy policy, served at /privacy
admin.html, admin.js      usage dashboard
api/                      serverless functions; files starting with _ are helpers, not routes
scripts/                  database setup and maintenance scripts
dev-server.mjs            local server
test/                     tests and fixtures
test-helpers/             test harnesses

Tests

npm test

The suite uses node:test, which is built into Node, so there is no test framework to install. It covers the server code in api/, the pure functions in lib/pure.js, and the client logic in app.js and landing.js, which the harnesses in test-helpers/ run against a stubbed browser. npm install sets up a pre-commit hook that runs the suite.

npm run mutate <spec> runs a mutation battery: it applies each deliberate breakage listed in a spec file, runs the suite, and reports which test caught it.

Contributing

SousChef is developed in a private repository, and this one is a snapshot of its code and tests. Contributions are welcome: see CONTRIBUTING.md, the Code of Conduct, and SECURITY.md for reporting a vulnerability.

Licence

MIT. See LICENSE.