Developer guide on Emet CMS

Local development

Mon, 01 Jan 0001 00:00:00 +0000

Developing Emet means running the Vite dev server against a Hugo site. Most of the time that’s a site on your disk, with no GitHub involved at all; when you’re working on something GitHub-specific there’s a mode for that too. This page covers both, plus the full list of npm scripts.

What you’ll need#

Node.js 22.12 or later, with npm.
A Hugo site to point at. Any site will do, though one with a few sections, some shortcodes and a theme will exercise more of the code. If you don’t have one, Emet will fall back to some built-in demo content.

Getting it running#

git clone https://github.com/dmyates/emetcms.git
cd emetcms
npm install
HUGO_ROOT=/path/to/your/hugo/site npm run dev

Open http://localhost:5173 and you should see the site’s sections in the sidebar. There’s no sign-in; the dev server signs you in as a made-up “Development User” and goes straight to the editor. If the site has no admin/site.yaml, the dev server scans it and writes one (plus admin/cms.yaml) first, so the very first load can take a second longer.

Testing

Mon, 01 Jan 0001 00:00:00 +0000

Emet’s tests run on Vitest, with jsdom standing in for the browser and Testing Library for anything that renders. There are a little over a hundred test files, sitting next to the code they test, and they cover most of the subsystems: frontmatter parsing, slugs and filenames, config loading and defaults, the sync service, shortcode and table serialisation, the SEO rules, the Hugo config parser, the AI client and providers, the GitHub client and pull request helpers and a fair few hooks and components.

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Emet is a React and TypeScript single-page app, built with Vite, that treats a Git repository as its database. This page is a tour of how that works: the backends that read and write content, how a running copy decides which one it’s using, where configuration comes from, how state is kept and what the build produces. It’s meant to be read before you go poking around in src/.

Why there’s no backend#

The design decision everything else follows from is that Emet has no application server. The site repository already holds the content, Git already keeps the history, and GitHub already has an API for reading and writing files, opening pull requests and checking CI. Putting a server and a database in front of that would mean a second copy of the content, a sync problem between the two and another thing to host and keep patched. I didn’t want any of those, so the browser talks to GitHub directly and the repository stays the single source of truth.