Example: Bundling with Rollup
CodeMirror is distributed as a collection of modules. These aren't
directly loadable by the browser—though modern browsers can load
EcmaScript modules, at the time of writing their mechanism for
resolving further dependencies is still too primitive to load
collections of NPM-distributed modules.
(That being said, there are solutions that work around that by
rewriting dependencies on the server side, like
Snowpack or
esmoduleserve. I
definitely recommend a solution like this during development, since it
tends to introduce less indirection and delay when changing files, but
for actual deployment, you'll want to do classical bundling for the
time being.)
Bundlers are tools that take a given main script (or in some cases
multiple scripts), and produce a new, generally bigger, script that has
all (or some) of the script's dependencies (and their dependencies,
and so on) included. This makes it easier to run modern JavaScript
systems, which tend to consist of a whole graph of dependencies, in
the browser. (But also, for example, to combine a library package
written as a group of files into a single file before uploading it to
NPM.)
As far as bundler software goes, I'm a big fan of
Rollup. But there are also other systems, like
Webpack and
Parcel, that work well and have their own
advantages.
To use Rollup to create a bundle that loads CodeMirror, you must first
write a main script (say, editor.js) that imports the library and
creates the editor view.
import {EditorView, basicSetup} from "codemirror"
import {javascript} from "@codemirror/lang-javascript"
let editor = new EditorView({
extensions: [basicSetup, javascript()],
parent: document.body
})
Next, we must install the necessary packages. The
@rollup/plugin-node-resolve
package is necessary to teach rollup to resolve node-style
dependencies, so that it knows to find "@codemirror/lang-javascript"
under node_modules/@codemirror/lang-javascript/dist/index.js.
# The CodeMirror packages used in our script
npm i codemirror @codemirror/lang-javascript
# Rollup and its plugin
npm i rollup @rollup/plugin-node-resolve
With these, we can run rollup to create the bundle file.
node_modules/.bin/rollup editor.js -f iife -o editor.bundle.js \
-p @rollup/plugin-node-resolve
The -f iife file tells Rollup that the output file should be
formatted as an "immediately-invoked function expression" (as opposed
to other module styles, such as CommonJS or UMD). This means the code
will be wrapped in an anonymous function that is then immediately
called, using that function's scope as a local namespace so that its
variables don't end up in the global scope.
The -o option indicates which output file to write to, and the -p
option loads the resolution plugin. You can also create a
configuration file (called rollup.config.js) and just run rollup -c to take the configuration from that file.
import {nodeResolve} from "@rollup/plugin-node-resolve"
export default {
input: "./editor.js",
output: {
file: "./editor.bundle.js",
format: "iife"
},
plugins: [nodeResolve()]
}
Now if you load your bundle with a script tag you'll see the editor in
your HTML page.
<!doctype html>
<meta charset=utf8>
<h1>CodeMirror!</h1>
<script src="editor.bundle.js"></script>
Bundle Size
Because the library is a hundred-thousand-line marvel of JavaScript
engineering, shipped with its full source code (including comments and
whitespace), bundles built in the most straightforward way can get
somewhat big (around 1 megabyte for the basic
setup and a language mode).
You can more than halve this by using something like
Terser or Babel to strip
the comments and whitespace, and rename variables to use shorter
names, getting the full bundle down to around 400 kilobytes (135
kilobytes when gzipped for transfer over the network).
The library is built in such a way that unused code can be eliminated
by a smart bundler like Rollup (a feature called “tree shaking”). The
most minimal editor (see below) avoids loading a bunch of extensions,
taking the full bundle size down to 700 kilobytes and reducing the
stripped code to 250 kilobytes (75 kilobytes gzipped).
import {EditorView, minimalSetup} from "codemirror"
let editor = new EditorView({
extensions: minimalSetup,
parent: document.body
})
When you need to support multiple languages, it can often be useful to
dynamically load the language support packages as needed to avoid the
amount of code the browser has to load. The Rollup
documentation can tell
you more about how to do this.