This is the companion babel plugin for run-on-server.
It does two things:
- Compiles "id mappings" to prevent run-on-server from running arbitrary code.
See the documentation below for an explanation of each functionality and the rationale behind it.
If you try to compile this using webpack:
Then webpack will include the "prettier" module in your clientside code.
Since you're only using it serverside, this is unnecesary.
eval("require") is used instead of
require, then webpack won't include the module in your clientside code:
This plugin can replace
eval("require") for you.
Compiles "ID Mappings"
This babel plugin solves that issue by making
run-on-server/server refuse to run any code except for the code that appeared in your source.
Here's how it works:
- The plugin reads through your client source code to find all the places you call
- It replaces the code you pass into
runOnServerwith an autogenerated ID
- It then outputs an "id mappings file" mapping each ID to the code you passed into
This id mappings file can then be fed into
run-on-server/server, which configures the server so that it only runs code appearing in the id mappings file.
It might be easier to visualize with an example:
run-on-server/client code looks like this:
// src/client.js;const runOnServer = ;;
The babel plugin compiles it to this:
// dist/client.js;const runOnServer = ;;
And the babel plugin also creates an id mappings file with this content:
// run-on-server-id-mappings.js/*This file was generated by the run-on-server babel plugin. It should notbe edited by hand.*/ moduleexports =processversion;
Note that the autogenerated id (
073f3eb62747a1dbb64a5527c79224ad) is the same in the code and the id mappings file.
Now, if you feed the id mappings into
const createServer = ;const server =;server;
Then the server will be locked down so that it can only ever run
() => process.version.
By leveraging this babel plugin,
run-on-server becomes feasible for use in production-facing libraries and applications.
Install the package
$ npm install --save-dev babel-plugin-run-on-server# OR$ yarn add --dev babel-plugin-run-on-server
Add it to your
By default, the plugin doesn't do anything. You need to enable each feature by passing options to the plugin in your
Whether to compile
runOnServer calls. Defaults to
Whether to compile id mappings and replace the code in
runOnServer calls with id mappings. Defaults to
By default, the id mappings file will be written to
run-on-server-id-mappings.js in whatever directory you run babel in. You can configure it by setting the
ID mappings file contains old entries until recreated
The plugin never removes entries from the id mappings file, it only adds them. This means that your id mappings file will grow over time and contain entries for code you no longer have. To clean the entries up, remove the id mappings file and re-run babel. It's best practice to clear out all entries before releasing a new production-facing build.
If you are building content from a
src directory into a
dist directory, my recommendation is to output the id mappings file into
dist, and then clear the contents of
dist before running each build (as part of your build script).
outputPath resolution may not work as expected
The outputPath in
.babelrc is resolved relative to where you run
process.cwd()). This usually works, but if your id mappings file is getting put in the wrong place, you might want to use this workaround to give an absolute path to the plugin:
- Change your
.babelrcto have this content:
- Create a new file named
.babelrc.jsin the same directory as
.babelrc, and make it export a config object containing everything your
.babelrchad in it before:
moduleexports =plugins:"run-on-server"idMappings:enabled: trueoutputPath: "./server/idMappings.js";
- Import the
pathmodule and wrap your
const path = ;moduleexports =plugins:"run-on-server"idMappings:enabled: trueoutputPath: path;
Note: If you are using Babel 7, you don't need to do the
.babelrc.jswill be loaded by babel without any additional config.