This is a pre-release API, so it is a subject to change. Please use it at your own risk. Once API is validated, it will be bumped to v1.0 and preserved for backwards compatibility.
options<Object> Set of configurable options to set on the app. Can have the following fields:width<number> app window width in pixels.height<number> app window height in pixels.bgcolor<string> background color using hex notation, defaults to#ffffff.userDataDir<string> Path to a User Data Directory. This folder is created upon the first app launch and contains user settings and Web storage data. Defaults to.profile.executablePath<string> Path to a Chromium or Chrome executable to run instead of the automatically located Chrome. IfexecutablePathis a relative path, then it is resolved relative to current working directory. Carlo is only guaranteed to work with the latest Chrome stable version.args<Array<string>> Additional arguments to pass to the browser instance. The list of Chromium flags can be found here.
return: <Promise<App>> Promise which resolves to the app instance.
Launches the browser.
Emitted when the App window closes.
pageFunction<function|string> Function to be evaluated in the page context...args<...Serializable> Arguments to pass topageFunctionreturn: <Promise<Serializable>> Promise which resolves to the return value ofpageFunction
If the function passed to the page.evaluate returns a Promise, then page.evaluate would wait for the promise to resolve and return its value.
If the function passed to the App.evaluate returns a non-Serializable value, then page.evaluate resolves to undefined.
Passing arguments to pageFunction:
const result = await app.evaluate(() => navigator.userAgent);
console.log(result); // prints "<UA>" in Node consolePassing arguments to pageFunction:
const result = await app.evaluate(x => {
return Promise.resolve(8 * x);
}, 7);
console.log(result); // prints "56" in Node consoleA string can also be passed in instead of a function:
console.log(await app.evaluate('1 + 2')); // prints "3"
const x = 10;
console.log(await app.evaluate(`1 + ${x}`)); // prints "11"return: <Promise>
Closes the browser window.
name<string> Name of the function on the window objectcarloFunction<function> Callback function which will be called in Carlo's context.return: <Promise>
The method adds a function called name on the page's window object.
When called, the function executes carloFunction in node.js and returns a Promise which resolves to the return value of carloFunction.
If the carloFunction returns a Promise, it will be awaited.
NOTE Functions installed via
App.exposeFunctionsurvive navigations.
An example of adding an md5 function into the page:
main.js
const carlo = require('carlo');
const crypto = require('crypto');
carlo.launch().then(async app => {
app.on('exit', () => process.exit());
app.serveFolder(__dirname);
await app.exposeFunction('md5', text => // <-- expose function
crypto.createHash('md5').update(text).digest('hex')
);
await app.load('index.html');
});index.html
<script>
md5('digest').then(result => document.body.textContent = result);
</script>uri<string> Path to the resource relative to the folder passed intoserveFolder.params<*> Optional parameters to pass the the web application. Parameters can be primitive types, <Array>, <Object> or rpchandles.return: <Promise> <*> result of theload()invocation, can be rpc handle.
Navigates the Chrome web app to the given uri, loads the target page and calls the load
function in the context of the loaded page.
main.js
const carlo = require('carlo');
const { rpc } = require('carlo/rpc');
carlo.launch().then(async app => {
app.serveFolder(__dirname);
app.on('exit', () => process.exit());
const frontend = await app.load('index.html', rpc.handle(new Backend));
console.log(await frontend.hello('from backend'));
});
class Backend {
hello(name) {
console.log('Hello ' + name);
return 'Backend is happy';
}
}index.html
<script>
class Frontend {
hello(name) {
console.log('Hello ' + name);
return 'Frontend is happy';
}
}
async function load(backend) {
console.log(await backend.hello('from frontend'));
return rpc.handle(new Frontend);
}
</script>
<body>Open console</body>folder<string> Folder with web content to make available to Chrome.prefix<string> Prefix of the URL path to serve from the given folder.
Makes the content of the given folder available to the Chrome web app.
An example of adding a local www folder along with the node_modules:
main.js
const carlo = require('carlo');
carlo.launch().then(async app => {
app.on('exit', () => process.exit());
app.serveFolder(__dirname + '/www');
app.serveFolder(__dirname + '/node_modules', 'node_modules');
await app.load('index.html');
});www/index.html
<style>body { white-space: pre; }</style>
<script>
fetch('node_modules/carlo/package.json')
.then(response => response.text())
.then(text => document.body.textContent = text);
</script>origin<origin> Origin to serve web content from.
Fetches Carlo content from the specified origin instead of reading it from the
file system, eg http://localhost:8080.
This mode can be used for the fast development mode available in web frameworks.
An example of adding the local http://localhost:8080 origin:
main.js
const carlo = require('carlo');
carlo.launch().then(async app => {
app.on('exit', () => process.exit());
app.serveFolder(__dirname); // <-- won't be used
app.serveOrigin('http://localhost:8080'); // <-- fetch from the local server
await app.load('index.html');
});www/index.html
<style>body { white-space: pre; }</style>
<script>
fetch('node_modules/carlo/package.json')
.then(response => response.text())
.then(text => document.body.textContent = text);
</script>