Registry / web-framework / carlo

carlo

JSON →
library0.1.9jsnpmunverified

Carlo is a Node.js framework designed to create hybrid desktop applications by rendering Node.js data structures and UIs using a locally installed Google Chrome browser instance. It establishes communication between Node.js and the browser via the Puppeteer project, offering a remote call infrastructure for seamless interoperability. Unlike Electron or NW.js, Carlo does not bundle Chromium, relying instead on the user's existing Chrome installation. This approach can lead to smaller application sizes and leverage an up-to-date browser. The project, currently at version 0.9.46, was last updated in June 2019, and its GitHub repository under `GoogleChromeLabs` shows no recent activity, indicating it is no longer actively maintained. Key differentiators included the ability to bundle the application into a single executable using `pkg`, exposing Node.js capabilities to a web frontend, and leveraging the web stack for dynamic visualization of Node.js app states.

web-frameworkhttp-networkingdevopsserialization
npm install carlo
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · CARLO
C
carlo
web-frameworkjavascriptv0.1.9
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

carlo
✓ import carlo from 'carlo'; // (Not officially supported, but may work with bundlers)
✗ const carlo = require('carlo');
Carlo was primarily designed for CommonJS (`require`). While modern bundlers might transpile `import` statements, direct ESM support is not officially provided due to the project's abandoned status and age. The `require` syntax is the idiomatic way to use Carlo.
carlo.launch
✓ const app = await carlo.launch();
✗ const app = carlo.launch(); // Missing 'await'
The `launch()` function returns a Promise and must be awaited to ensure the browser instance is ready before proceeding.
app.exposeFunction
✓ await app.exposeFunction('funcName', (arg) => { /* ... */ });
✗ app.exposeFunction('funcName', (arg) => { /* ... */ }); // Missing 'await' is a common mistake that can lead to race conditions.
This method also returns a Promise. Awaiting it ensures the function is properly exposed in the browser context before any browser-side calls attempt to use it, preventing race conditions or 'function not found' errors.

This quickstart demonstrates launching a Carlo application, serving static HTML content, and exposing a Node.js function (`getSystemInfo`) to the browser environment. The browser-side JavaScript then calls this exposed function to retrieve and display system information from the Node.js process.

const carlo = require('carlo'); const path = require('path'); (async () => { // Launch the browser. Carlo requires a locally installed Chrome/Chromium. const app = await carlo.launch({ args: ['--disable-extensions', '--start-maximized'], width: 800, height: 600 }); // Terminate Node.js process on app window closing. app.on('exit', () => process.exit()); app.on('unhandledRejection', (reason, promise) => { console.error('Unhandled Rejection at:', promise, 'reason:', reason); }); // Serve static web files from the 'app' directory. // Make sure to create a simple `index.html` in a folder named `app` // or serve from `__dirname` if your html is alongside your JS file. app.serveFolder(path.join(__dirname, 'app')); // Expose a Node.js function 'getSystemInfo' to the web environment. // This function will be callable from the browser-side JavaScript. await app.exposeFunction('getSystemInfo', async () => { return { nodeVersion: process.version, platform: process.platform, arch: process.arch, envVars: Object.keys(process.env).sort() }; }); // Navigate to the main page of your app. await app.load('index.html'); console.log('Carlo app launched. Check the new Chrome window.'); })(); // A minimal app/index.html to be served by Carlo // (Save this in a subfolder named 'app' next to your main JS file) /* <!DOCTYPE html> <html> <head> <title>Carlo System Info</title> <style> body { font-family: sans-serif; padding: 20px; } pre { background-color: #f4f4f4; padding: 10px; border-radius: 4px; } </style> </head> <body> <h1>System Information</h1> <pre id="info-display"></pre> <script> async function displaySystemInfo() { const info = await getSystemInfo(); // Call Node.js function document.getElementById('info-display').textContent = JSON.stringify(info, null, 2); } window.onload = displaySystemInfo; </script> </body> </html> */
Debug
Known issues
breakingCarlo is an abandoned project and has not been updated since June 2019. It may not be compatible with newer versions of Node.js, Puppeteer, or Google Chrome. Using it in production environments is highly discouraged due to potential security vulnerabilities, lack of maintenance, and compatibility issues.
fix
Consider migrating to actively maintained alternatives like Electron, NW.js, or Tauri, which provide similar desktop application capabilities with active development and community support.
affects: >=0.9.46
gotchaCarlo relies on a *locally installed* Google Chrome or Chromium browser. If Chrome is not found on the system where the application is run, Carlo will fail to launch with an error message. It does not bundle its own browser like Electron.
fix
Ensure Google Chrome (or a compatible Chromium-based browser) is installed on the target system. For specific browser paths, you might need to configure Puppeteer options within Carlo's launch arguments, although this is not directly exposed as a top-level Carlo option.
affects: >=0.1.0
gotchaThe `puppeteer-core` dependency in Carlo `0.9.46` is pinned to `~1.12.0`. This old version of Puppeteer may not be compatible with very recent versions of Google Chrome, potentially leading to connection issues or unexpected behavior when Carlo tries to control a modern browser. The 'Chrome Stable channel, versions 70.*' are explicitly mentioned as supported.
fix
If encountering issues, try installing an older version of Chrome (e.g., Chrome 70-75) if possible for development/testing, or inspect Puppeteer's troubleshooting guides for compatibility with older client versions. There is no direct fix within Carlo itself due to its abandoned status.
affects: >=0.9.0
gotchaCarlo's API methods like `launch()`, `exposeFunction()`, `load()`, and `serveFolder()` return Promises. Failing to `await` these promises can lead to race conditions where subsequent operations try to interact with uninitialized browser contexts or functions that haven't been exposed yet, resulting in runtime errors.
fix
Always use `await` when calling Carlo's asynchronous API methods within an `async` function. Ensure proper error handling (e.g., `try...catch` blocks) for these awaited operations.
affects: >=0.1.0
Errors
Common errors & fixes
Error: Failed to launch the browser process! No browser found at /path/to/chrome. Please download a browser at https://chromium.woolyss.com/ or set 'executablePath' to a browser in 'carlo.launch'.
Carlo could not locate an installed Google Chrome or Chromium browser on the system.
fix
Install Google Chrome or Chromium on your system. If Chrome is installed in a non-standard location, you might need to specify its executable path in the `carlo.launch()` options, for example: `carlo.launch({ executablePath: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome' })` (macOS).
TypeError: Cannot read property 'launch' of undefined
The `carlo` module was not correctly imported or required, or the Node.js environment did not properly load it.
fix
Ensure `const carlo = require('carlo');` is at the top of your script and that `carlo` is properly installed via `npm install carlo`. Verify your Node.js version meets the `engines` requirement (>=7.6.0).
ReferenceError: <exposedFunctionName> is not defined at <anonymous>
A function exposed from Node.js via `app.exposeFunction` was called from the browser before it was fully registered, or a typo exists in the function name.
fix
Ensure `await app.exposeFunction('functionName', ...)` completes before any browser-side code attempts to call `functionName()`. Double-check that the function name in `exposeFunction` matches the name used in the browser JavaScript exactly.
Upgrade
Version history
0.1.9latest on npm
Audit
Dependencies
puppeteer-corerequiredCarlo uses `puppeteer-core` internally to establish and manage the connection with the locally installed Chrome browser, and to expose a high-level API for browser control. It is a direct runtime dependency.
debugrequiredUsed for logging and debugging purposes within the Carlo framework.
Agent activity
16 hits · last 30 days
node
14
Amazon
1
OpenAI (training)
1
Resources
githubhttps://github.com/GoogleChromeLabs/carlo ↗
packagehttps://www.npmjs.com/package/carlo ↗
homepagehttps://carlo.dev ↗