const createServer = ;const app = ;// createServer returns a node http.Serverapp;
const createClient = ;const runOnServer = ;// You can pass a function...;// ...or a string:;// runOnServer returns a Promise:;// You can pass arguments in as a second argument:;// When using a string, you can access passed arguments via the "args" variable:; // Server logs [1, 2, 3]// Async functions are also supported:;// You can use `runOnServer.sync` for Synchronous XHR:const result = runOnServer;console; // 4
- JSON is used as the transport mechanism. As such, the return value from the server and any arguments passed from the client must be JSON-serializable.
- When passing a function to
runOnServer, the function source code is executed as-is server-side. This means that if you attempt to reference any local variables from the client in the function, the server will not be able to see them. To work around this, pass local variables in as function arguments via
runOnServer's second argument.
Warnings / Security
Out of the box, this effectively gives the client serverside
eval. However, there's a babel plugin that will restrict the server so that it will only run the code that appeared in your source at compile-time. For more info, read the README for babel-plugin-run-on-server
npm install run-on-server
or with yarn:
yarn add run-on-server
JS API Documentation
createServer(options: ?Object) => http.Server
createServer function is obtained from the module
run-on-server/server. When called, it returns a node http.Server configured to respond to JSON HTTP
/. You can call its
listen method to run it on an HTTP port or Unix Socket.
const createServer = ;const app = ;
options object that can be passed to
createServer has this shape:
requireFrom?: stringidMappings?: key: string: Function | Stringcors?: booleanrequestSizeLimit?: string
requireFrom is present, it will specify the starting folder for top-level
require calls in the code passed to
runOnServer. For instance, If you set
requireFrom to "/Users/suchipi/Code/run-on-server", then you would be able to load "/Users/suchipi/Code/run-on-server/foo.js" with
require("./foo"). If you don't specify a
requireFrom, it will default to the server's current working directory.
idMappings is used in conjunction with a babel plugin to restrict the server so that it can only run code that appeared in your source. For more info, see the README for babel-plugin-run-on-server.
The server will allow CORS requests from all origins by default. To override this behavior, pass
When the server parses the incoming JSON from a request, it keeps all the bytes in memory. For safety reasons (to prevent high memory usage), a limit can be configured, and if a request that is too large comes through, the server wil reject the request. The limit is configured as
"1GB" by default, but you can pass
requestSizeLimit to change it. You can pass any string that can be parsed by the npm bytes package, eg.
"2MB", etc (unit is case-insensitive).
createClient(url: string) => Function
createClient function is obtained from the module
run-on-server/client. When called, it returns a
runOnServer function configured with the specified url.
const createClient = ;const runOnServer = ;
runOnServer(code: Function | string, args: ?Array<any>) => Promise<any>
runOnServer function is obtained by calling
createClient. It can be called with either a function or string, and an optional array of arguments to pass to the function (when using a function). It returns a Promise.
;;;;// You can access the passed args in the string form via the `args` variable.;
- If the function or code string passed to
runOnServerreturns a value, it must be JSON-serializable.
- If an arguments array is passed in as the second argument to
runOnServer, it must be JSON-serializable.
- If the serverside code throws an Error, the Promise returned from
runOnServerwill reject with an Error with the same name, message, and stack as the serverside error.
runOnServer.sync(code: Function | string, args: ?Array<any>) => any
runOnServer.sync works just like
runOnServer but it uses a Synchronous XHR instead of an async one, so it blocks the main thread until the server responds, and then returns the result.
const result = runOnServer;console; // 4
createSocketUrl(handler: Function) => string
You can require
run-on-server/socket within a
runOnServer.sync call to get the
createSocketUrl function. It lets you set up a websocket server, and returns a URL that you can connect to clientside to connect to that server:
createSocketUrl should be called with a handler function. The handler function receives a websocket as its first argument, and the request object for the connection as its second argument.
Note: After the client disconnects, the generated URL will no longer be valid. Re-run the
runOnServer call to generate a new one before reconnecting.
run-on-server was inspired by karma-server-side.