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.

Do not write your own. A citation style is not a format string. APA alone is 86 KB of XML describing disambiguation, name particles, et al. collapsing, ordering and substitution, and a style is revised. Take a processor.

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:

apps/web/lib/citations.ts
// 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 = null
export 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:

StyleSizegojanode
harvard-cite-them-right10.5 KB0.44 s
ieee17.6 KB0.30 s
modern-language-association44 KB1.1 s
apa86 KB44 to 80 s0.61 s
chicago-author-date168 KB209 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.