Internal HTTP service that renders Markdown to HTML using the alienmark workspace package (see packages/alienmark/AGENTS.md). Called by the Django backend.
- Fastify 5 — HTTP server.
- TypeScript — strict, ESM.
- alienmark (
workspace:*) — the actual parser/renderer. This service is a thin HTTP wrapper aroundrenderMarkdown. - Built with
vp pack src/server.ts --format esm --dts false→ emitsdist/server.mjs.
Single source file: src/server.ts. Two routes:
| Method | Path | Body | Returns | Notes |
|---|---|---|---|---|
GET |
/health |
— | { ok: true, service: "alienmark" } |
Liveness probe. |
POST |
/render-html |
{ markdown: string } |
{ html: string } |
Renders Markdown via renderMarkdown. Body limit 1 MiB. Fastify JSON schema validates request and response. |
Config via env:
PORT(default8787) — must be an integer in(0, 65535]; invalid values throw.HOST(default0.0.0.0).
The server uses top-level await on app.listen — it's an ESM entrypoint, not a long-running importable module.
| Action | Command |
|---|---|
| Dev (watch) | pnpm --filter alienmark-service dev (tsx watch src/server.ts) |
| Build | pnpm turbo run build --filter=alienmark-service → dist/server.mjs |
| Start (built) | pnpm --filter alienmark-service start (node dist/server.mjs) |
| Full check | pnpm turbo run check --filter=alienmark-service |
| Typecheck | pnpm turbo run typecheck --filter=alienmark-service (tsc --noEmit) |
| Lint | pnpm turbo run lint:check --filter=alienmark-service |
| Format check | pnpm turbo run fmt:check --filter=alienmark-service |
- Keep the surface intentionally small. This service exists to move Markdown rendering out of the Python process; don't grow it into a general-purpose API.
- No business logic here. Parsing behavior lives in
packages/alienmark. If the renderer needs a new feature, add it there and ship a new lib version — don't patch around it in the service. - Validate at the Fastify schema layer (JSON schema on route definitions), as the existing routes already do.
- ESM + top-level await are expected — don't refactor to CommonJS or wrap
app.listenin a function unless there's a concrete reason. - TypeScript strict. No
any, no@ts-ignore.
- Match the existing style in
src/server.ts. - Don't commit
dist/. - Coordinate changes with the backend caller (see
apps/backend/AGENTS.md) and the parser library (seepackages/alienmark/AGENTS.md) when changing the request/response contract.
pnpm turbo run check --filter=alienmark-service # vp check (lint + format + type-aware)
pnpm turbo run typecheck --filter=alienmark-service # tsc --noEmitFor behavioral changes, also exercise the running service:
pnpm turbo run build --filter=alienmark-service && pnpm --filter alienmark-service start
# in another terminal:
curl -s localhost:8787/health
curl -s -X POST localhost:8787/render-html -H 'content-type: application/json' -d '{"markdown":"# hi"}'