Using Ogma with Google Closure Compiler (ADVANCED mode)

If your application is compiled with the Google Closure Compiler in ADVANCED optimization mode, the compiler aggressively renames properties to shorten the output. When you call into a pre-built third-party library such as Ogma, those calls would be renamed too — ogma.addNode(...) could become ogma.a(...) — and break at runtime, because the library bundle still exposes the original names.

To prevent this, Ogma ships an externs file that describes its public API. Passing it to your compiler tells Closure "these names belong to an external library, do not rename them".

TIP

You only need this if you compile your own app with Closure Compiler in ADVANCED mode. Bundlers like Vite, Webpack, Rollup, esbuild or Parcel do not rename properties, so no externs are required — see the other build-tool tutorials.

What ships in the package

Every published release of @linkurious/ogma contains:

File	Purpose
ogma.js	ESM bundle (also ogma.umd.cjs, ogma.dev.js)
ogma.d.ts	TypeScript declarations
ogma.externs.js	Closure ADVANCED externs for the public API

ogma.externs.js is generated directly from ogma.d.ts, so it always matches the API surface of the version you installed. It declares every exported class, interface, enum, option-bag key and event-payload field as a reserved name.

You can reference it through the package's exports map:

// resolves to node_modules/@linkurious/ogma/ogma.externs.js
require.resolve('@linkurious/ogma/externs');

Example

Given a small application that uses Ogma:

// app.js
import Ogma from '@linkurious/ogma';

const ogma = new Ogma({
  container: 'graph-container',
  graph: { nodes: [{ id: 0, attributes: { color: 'blue' } }] }
});

ogma.view.locateGraph();
console.log(ogma.getNode(0).getData('label'));

Compile it while passing Ogma's externs:

google-closure-compiler \
  --compilation_level ADVANCED \
  --js app.js \
  --externs node_modules/@linkurious/ogma/ogma.externs.js \
  --js_output_file app.min.js

The references to new Ogma(...), view, locateGraph, getNode, getData, and the option keys container, graph, nodes, id, attributes, color survive the renaming pass, because they all appear in ogma.externs.js.

Good to know

• Only the public API is covered. Anything not part of the published ogma.d.ts is considered internal and may be renamed inside the Ogma bundle — do not rely on undocumented members.
• Keep the externs in sync with the version you install. Because the file is regenerated from the declarations on every release, re-copy it whenever you upgrade Ogma.
• You do not recompile Ogma. The shipped bundle is already optimized; the externs simply protect your references to it during your compilation.