Frontend
Citations and bibliographies
Formatting a citation in APA, Harvard, IEEE or Chicago means running a CSL processor. Grit does not ship one, and this page is the reason why, plus the arrangement that works today and the one rule that will cost you a day if you get it wrong.
Render on the client
The only complete CSL implementation is citeproc-js, the engine behind Zotero and Mendeley. Run it in the browser, lazily, so the pages that do not cite anything never pay for it:
// citeproc is ~967 KB of ES5 and a style is another 10 to 170 KB, so this// is a dynamic import and never a top-level one. For comparison, the whole// rich text editor in a Grit project is 173 KB raw and 18.6 KB gzipped: a// static import here would dwarf everything else the app ships, on a phone,// on a slow connection.let enginePromise: Promise<CiteprocEngine> | null = nullexport async function engine(styleId: string) {if (!enginePromise) {enginePromise = (async () => {const { default: CSL } = await import('citeproc')const [style, locale] = await Promise.all([fetch(`/csl/${styleId}.csl`).then((r) => r.text()),fetch('/csl/locales-en-GB.xml').then((r) => r.text()),])return new CSL.Engine({retrieveLocale: () => locale,retrieveItem: (id: string) => itemsById[id],},style,)})()}return enginePromise}
Persist what it rendered
This is the rule. When the document is later exported as a Word file or a PDF, the server needs the same citation text the person saw on screen. Store what the client rendered and have the server read it. Do not give the server a second implementation that derives it again.
Two implementations of one rule in two languages drift, and they drift quietly. This exact shape has already cost a day in a Grit project: an FNV hash written once in TypeScript and once in Go stopped agreeing, nothing failed, and every passage simply reported as unrecorded until a golden-file fixture that ran both sides caught it.
grit generate resource Reference \--fields "csl_json:json,rendered:text,style:string,rendered_at:datetime,document_id:belongs_to:Document"
csl_json is the source data in CSL-JSON, which is the interchange format every reference manager exports. rendered is what the engine produced, with the style it was produced in, so a change of style is a re-render and not a silent mismatch. The export reads rendered.
Why not on the server
Because it was tried. Running citeproc-js under goja, the pure-Go JavaScript runtime, produces correct output, and the cost of building the engine, which is parsing the style XML, is this:
| Style | Size | goja | node |
|---|---|---|---|
| harvard-cite-them-right | 10.5 KB | 0.44 s | |
| ieee | 17.6 KB | 0.30 s | |
| modern-language-association | 44 KB | 1.1 s | |
| apa | 86 KB | 44 to 80 s | 0.61 s |
| chicago-author-date | 168 KB | 209 s |
It is a cliff, not a slope: everything under about 45 KB is sub-second, and APA and Chicago fall off it. goja is 70 to 130 times slower than V8 at parsing a style, and a goja VM is not safe for concurrent use, so a server would need one engine per style per worker and the warm-up multiplies by both. APA and Chicago are the two styles most people ask for. Rendering, once an engine exists, is fine in either: roughly 200 ms for a bibliography.
v8go would fix the speed and brings CGO_ENABLED=1, a C toolchain in the image, no more cross-compiling and about 30 MB of image growth. Grit has a precedent for exactly that trade in the vips image backend, which is pure Go by default and cgo behind a build tag. If server-side rendering becomes necessary, that is the shape it should take. It is not the default.
The licence
citeproc-js is dual licensed CPAL-1.0 or AGPL-1.0, which is why it is a dependency your project adds deliberately rather than one Grit puts in every scaffolded app. @citation-js/plugin-csl is MIT but depends on citeproc, so it does not escape it. The style files themselves are CC-BY-SA, which is fine as data. Read the terms against what you are building before you ship it.
What would change this
A native Go CSL processor. front-matter/citeproc is MIT, native Go and under active development, and its README says basic functionality is not yet working with a first working release expected in December 2026. When it renders, server-side citations become a few lines and this page gets shorter. Until then it is worth watching and not worth depending on.
