Welcome to my digital home. 👋

This is where I share what I've learned, showcase what I've built, give back to the open-source community with tools worth using, and write about performance, design systems, and the craft of engineering - everything worth sharing as I grow and learn.

Not a static résumé - a living one. Every commit is CI-gated, every touched file hits 100% coverage, and the whole thing ships to production on green. What you see is how I work.

It is organized as a pnpm workspace monorepo: the website and a desktop markdown editor are apps among their own shared tooling packages and backend workers.

https://soroush.tech

---

SEO is handled in-house:

• @soroush.tech/vite-plugin-sitemap emits sitemap.xml from the prerendered HTML (skipping noindex pages).
• a static robots.txt ships from apps/web/public/ at build time.
• meta-tags are injected for each page.

---

🚀 Getting started

Prerequisites

• Node 26 - pinned in .nvmrc (nvm use).
• pnpm 10.13.1 - pinned via the packageManager field.

Install & run

pnpm install   # installs every workspace (also runs the setup below)
pnpm prepare   # set up all you need - git hooks + per-workspace local env
pnpm dev       # starts the web app dev server

pnpm prepare runs husky and then each workspace's setup (pnpm -r run setup): it bootstraps .env.local from their default.env It runs automatically on pnpm install; re-run it any time with pnpm prepare (or pnpm run setup).

---

📚 Documentation

• .github/workflows/README.md - CI/CD pipeline explained with Mermaid diagrams.
• apps/web/README.md - the website: structure, scripts, testing.
• apps/editor/README.md - the desktop editor: architecture and release flow, with diagrams.
• .github/workflows/ci-editor.md - how the editor is tested.
• packages/README.md - workspace packages.
• workers/README.md - backend.

---

🚦 Status

Area	Coverage	NPM	Downloads	Unpacked size
web		-	-	-
web:unit		-	-	-
web:unit:browser		-	-	-
web:storybook		-	-	-
web:e2e		-	-	-
editor		-	-	-
editor:e2e		-	-	-
worker:api		-	-	-
worker:bench-api		-	-	-
package:bench
package:vite-plugin-msw-server
package:vite-plugin-sitemap		-	-	-
package:vite-plugin-watch		-	-	-
package:wrangler-tools		-	-	-
package:styled-system
package:playwright-coverage
package:design-system
package:markdown

---

✅ Quality & CI/CD

• Pre-commit - a husky hook formats the staged files, then runs the release and build checks and the tests before each commit.
• Lint - pnpm lint runs oxlint --deny-warnings; any warning fails.
• Format - pnpm format runs oxfmt; CI enforces it with pnpm format:check.
• Coverage - touched files reach 100%, and every packages/* package is held at 100% as a hard threshold.
• One workflow per area - CI is an entry workflow calling one file per area (packages, workers, apps), each declaring on its own first line what it validates. A change runs what it touches: editing how the editor is tested does not re-run twelve packages.
• Matrices - the web app builds on Linux only; its e2e is the one multi-OS matrix, one Playwright engine per native OS (Chromium · Firefox · WebKit).
• Visual regression - Storybook publishes to Chromatic on every PR (live demo).
• Performance gate - PRs touching styled-system run its bench suite in a CPU-pinned Docker sandbox via soroush-tech/bench-action; regressions below the speed threshold fail CI, and results land as one sticky PR comment.
• Deploy - CI success on main triggers the CD workflow, which builds with production env and deploys to GitHub Pages.

Full pipeline detail - with Mermaid diagrams of every workflow - lives in .github/workflows/README.md and the app README.

---

🗂️ Repository layout

soroush.tech/
├── apps/
│   ├── web/        # The website itself - React 19 + Vike (SSG/SSR)
│   └── editor/     # Desktop markdown editor - Electron, gists, Claude CLI
├── packages/       # Shared @soroush.tech/* packages (12 and counting)
│   ├── styled-system / design-system / markdown     # the UI stack
│   ├── bench / playwright-coverage                  # testing & benchmarking
│   ├── vite-plugin-{watch,sitemap,msw-server}       # Vite plugins
│   └── eslint-config / schema / hooks / wrangler-tools
└── workers/        # Backend deployables (Cloudflare Workers)
    ├── api/        # api.soroush.tech - contact-form intake + cron
    └── bench/      # api.bench.soroush.tech - bench-action comment relay

Workspace	What it is	Details
apps/web	The production website - pages, sections, hooks, tests.	apps/web/README.md
apps/editor	A desktop markdown editor - Electron, editing gist files in place, rewrites through the local Claude CLI.	apps/editor/README.md
packages/*	@soroush.tech/* packages - the published UI stack (styled-system, design-system, markdown), testing tools (bench, playwright-coverage), Vite plugins, and internal shared tooling.	packages/README.md
workers/*	Backend deployables - the contact-form API and the bench comment relay, both Hono on Cloudflare Workers.	workers/README.md

Globs live in pnpm-workspace.yaml (apps/*, packages/*, workers/*).

---

🧰 Tech stack - and why

Area	Choice	Why
Quality	SonarQube + CodeRabbit	Static analysis for bugs, smells, and security, plus AI-assisted code review on every PR.
Framework	React 19 (Isomorphic, SSG, SSR)	Pre-render every route to static HTML for speed and SEO, while keeping React's component model.
Build	Vite 8	Fast dev server and an extensible plugin pipeline - the same pipeline our own plugins plug into.
UI docs	Storybook + Chromatic	Component catalogue with visual-regression review on every PR.
Monorepo	pnpm workspaces	Cheap internal packages with workspace:* links and no publish step for internal use.
Packaging	tsdown	Builds publishable packages (ESM/CJS + types) without the deprecated config that breaks under TS 6.
Lint & format	oxlint + oxfmt + husky	--deny-warnings and a pre-commit gate keep the tree always-green.
Styling	@soroush.tech/design-system	Token-driven, prop-based styling with a typed design system and its own styling engine - no ad-hoc CSS.
Data	TanStack Query	Declarative server-state with caching.
Forms	TanStack Form + zod	Headless, type-safe form state and schema-validated (used by the contact form).
Backend	Hono on Cloudflare Workers	Type-safe edge API with OpenAPI docs (@hono/swagger-ui), backed by D1 and deployed via Wrangler.
Testing	Vitest + Playwright + MSW	Unit/component in Vitest, cross-browser e2e in Playwright, network mocked deterministically with MSW.

---

📬 Contact

Masoud Soroush
Email: masoud@soroush.tech
Website: soroush.tech

---

This project is a personal space to experiment, write, and share ideas. Contributions and feedback are welcome if you find something useful or inspiring.