{"id":14978502,"url":"https://github.com/bjrmatos/electron-html-to","last_synced_at":"2026-03-17T02:39:07.287Z","repository":{"id":57129751,"uuid":"44930283","full_name":"bjrmatos/electron-html-to","owner":"bjrmatos","description":"Highly scalable html conversion using electron workers :rocket:","archived":false,"fork":false,"pushed_at":"2022-06-08T20:22:26.000Z","size":625,"stargazers_count":55,"open_issues_count":6,"forks_count":5,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-02-01T14:13:48.683Z","etag":null,"topics":["conversion","electron","electron-html","electron-pdf","pdf"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bjrmatos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-25T21:19:48.000Z","updated_at":"2023-09-08T17:02:59.000Z","dependencies_parsed_at":"2022-08-31T19:00:51.115Z","dependency_job_id":null,"html_url":"https://github.com/bjrmatos/electron-html-to","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjrmatos%2Felectron-html-to","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjrmatos%2Felectron-html-to/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjrmatos%2Felectron-html-to/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bjrmatos%2Felectron-html-to/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bjrmatos","download_url":"https://codeload.github.com/bjrmatos/electron-html-to/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238481238,"owners_count":19479636,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["conversion","electron","electron-html","electron-pdf","pdf"],"created_at":"2024-09-24T13:57:48.344Z","updated_at":"2025-10-28T11:30:20.219Z","avatar_url":"https://github.com/bjrmatos.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"electron-html-to\n================\n\n[![NPM Version](http://img.shields.io/npm/v/electron-html-to.svg?style=flat-square)](https://npmjs.com/package/electron-html-to)[![License](http://img.shields.io/npm/l/electron-html-to.svg?style=flat-square)](http://opensource.org/licenses/MIT)[![Build Status](https://travis-ci.org/bjrmatos/electron-html-to.png?branch=master)](https://travis-ci.org/bjrmatos/electron-html-to)\n\n\u003e **Highly scalable html conversion in scale**\n\nThis module let you convert a web page (html, css, js) in any format you want (via a converter function) using [electron](http://electron.atom.io/).\n\n*Works in electron@\u003e=0.36.1 including electron@1*\n\n```js\nvar fs = require('fs'),\n    convertFactory = require('electron-html-to');\n\nvar conversion = convertFactory({\n  converterPath: convertFactory.converters.PDF\n});\n\nconversion({ html: '\u003ch1\u003eHello World\u003c/h1\u003e' }, function(err, result) {\n  if (err) {\n    return console.error(err);\n  }\n\n  console.log(result.numberOfPages);\n  console.log(result.logs);\n  result.stream.pipe(fs.createWriteStream('/path/to/anywhere.pdf'));\n  conversion.kill(); // necessary if you use the electron-server strategy, see bellow for details\n});\n```\n\nBuilt-in converters\n-------------------\n\n-\t`convertFactory.converters.PDF` (html to pdf) -\u003e when the conversion ends the `result` param will have `numberOfPages` (Number) and `stream` (Stream) properties.\n\nCustom converters\n-----------------\n\nConverters are functions that run in the electron process, see the [pdf conversion implementation](https://github.com/bjrmatos/electron-html-to/blob/master/src/converters/pdf.js) for an example.\n\nGlobal options\n--------------\n\n```js\nvar conversion = require('electron-html-to')({\n  /* optional absolute path to a custom electron executable, if not passed we will try to detect the path of the electron executable installed */\n  pathToElectron: '/path/to/custom/electron-executable',\n  /* optional array of custom arguments to pass to the electron executable */\n  electronArgs: ['--some-value=2', '--enable-some-behaviour'],\n  /* required absolute path to the converter function to use, every conversion will use the converter specified  */\n  converterPath: '/path/to/a/converter.js'\n  /* number of allocated electron processes (when using electron-server strategy). defaults to 2 */\n  numberOfWorkers: 2,\n  /* time in ms to wait for worker ping response in order to be considered alive when using `electron-server` or `electron-ipc` strategy, see https://github.com/bjrmatos/electron-workers#options for details */\n  pingTimeout: 100,\n  /* timeout in ms for html conversion, when the timeout is reached, the conversion is cancelled. defaults to 180000ms */\n  timeout: 5000,\n  /* directory where are stored temporary html and pdf files, use something like npm package reap to clean this up */\n  tmpDir: 'os/tmpdir',\n  /* optional port range where to start electron server (when using electron-server strategy) */\n  portLeftBoundary: 1000,\n  portRightBoundary: 2000,\n  /* optional hostname where to start electron server when using electron-server strategy) */\n  host: '127.0.0.1',\n  /* set to true to allow request using the file protocol (file:///). defaults to false */\n  allowLocalFilesAccess: false,\n  /* the collected console.log, console.error, console.warn messages are trimmed by default */\n  maxLogEntrySize: 1000,\n  /* optional chrome command line switches, see http://electron.atom.io/docs/v0.36.1/api/chrome-command-line-switches/ for details. defaults to { 'ignore-certificate-errors': null } */\n  chromeCommandLineSwitches: {\n    'disable-http-cache': null,\n    'log-net-log': '/path/to/save'\n  },\n  /* use rather dedicated process for every conversion,\n    dedicated-process strategy is quite slower but can solve some bugs\n    with corporate proxy. for a description of `electron-server` and `electron-ipc` strategy see [electron-workers docs](https://github.com/bjrmatos/electron-workers/#modes). defaults to electron-ipc strategy */\n  strategy: 'electron-ipc | electron-server | dedicated-process'\n});\n```\n\nLocal options\n-------------\n\n```js\nconversion({\n  html: '\u003ch1\u003eHello world\u003c/h1\u003e',\n  url: 'http://jsreport.net', // set direct url instead of html\n  delay: 0, // time in ms to wait before the conversion\n  // boolean that specifies if we should collect logs calls (console.log, console.error, console.warn) in webpage\n  // logs will be available as result.logs after the conversion\n  // defaults to true\n  collectLogs: true,\n  waitForJS: true, // set to true to enable programmatically specify (via Javascript of the page) when the conversion starts (see Programmatic conversion section for an example)\n  waitForJSVarName: 'MY_CUSTOM_VAR_NAME', // name of the variable that will be used as the conversion trigger, defaults to \"ELECTRON_HTML_TO_READY\" (see Programmatic pdf printing section for an example)\n  userAgent: 'CUSTOM_USER_AGENT', // set a custom user agent to use in electron's browser window\n  /* custom extra headers to load the html or url */\n  extraHeaders: {\n    'X-Foo': 'foo',\n    'X-Bar': 'bar'\n  },\n  converterPath: '/path/to/a/converter.js', // absolute path to the converter function to use in the local conversion, if no specified the global converterPath option will be used\n\n  // options for electron's browser window, see http://electron.atom.io/docs/v0.36.1/api/browser-window/ for details for each option.\n  // allowed browser-window options\n  browserWindow: {\n    width: 600, // defaults to 600\n    height: 600, // defaults to 600\n    x: 0,\n    y: 0,\n    useContentSize: false,\n    webPreferences: {\n      nodeIntegration: false, // defaults to false\n      partition: '',\n      zoomFactor: 3.0,\n      javascript: true, // defaults to true\n      webSecurity: false, // defaults to false\n      allowDisplayingInsecureContent: true,\n      allowRunningInsecureContent: true,\n      images: true,\n      java: true,\n      webgl: true,\n      webaudio: true,\n      plugins: ,\n      experimentalFeatures: ,\n      experimentalCanvasFeatures: ,\n      overlayScrollbars: ,\n      overlayFullscreenVideo: ,\n      sharedWorker: ,\n      directWrite:\n    }\n  },\n\n  // options to the pdf converter function, see electron's printoToPDF function http://electron.atom.io/docs/v0.36.1/api/web-contents/#webcontents-printtopdf-options-callback for details for each option.\n  // allowed printToPDF options\n  pdf: {\n    marginsType: 0,\n    pageSize: 'A4',\n    printBackground: false,\n    landscape: false\n  }\n}, cb);\n```\n\nLocal resources\n---------------\n\nYou can add local files like `.css`, `.jpg` or `.js` files by setting the\n`allowLocalFilesAccess` option to _true_. This option allow requests with the file protocol `file:///`.\n\n### Example:\n\n```html\n\u003c!-- index.html --\u003e\n\u003chead\u003e\n\t\u003clink rel=\"stylesheet\" href=\"/css/pdf.css\"\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\t\u003ch1 class=\"title\"\u003eIt Works!!\u003c/h1\u003e\n\t\u003cimg src=\"/images/company_logo.jpg\" title=\"MyLogo\"\u003e\n\u003c/body\u003e\n```\n\nIf your html doesn't have url in the form of `file://path/to/you/base/public/directory` you would need to transform paths from `/images/company_logo.jpg` to `file://path/to/you/base/public/directory/images/company_logo.jpg`.\n\n\n```js\nconst fs = require('fs');\nconst convertFactory = require('electron-html-to');\nfs.readFile('index.html', 'utf8', (err, htmlString) =\u003e {\n  // add local path in case your HTML has relative paths\n  htmlString = htmlString.replace(/href=\"|src=\"/g, match =\u003e {\n    return match + 'file://path/to/you/base/public/directory';\n  });\n  const conversion = convertFactory({\n    converterPath: convertFactory.converters.PDF,\n    allowLocalFilesAccess: true\n  });\n  conversion({ html: htmlString }, (err, result) =\u003e {\n    if (err) return console.error(err);\n    result.stream.pipe(fs.createWriteStream('/path/to/anywhere.pdf'));\n    conversion.kill(); // necessary if you use the electron-server strategy, see bellow for details\n  });\n});\n```\n\nKill workers\n------------\n\n```js\n// kill all electron workers when using electron-server strategy\nconversion.kill();\n```\n\nProgrammatic conversion\n-----------------------\n\nIf you need to programmatic trigger the conversion process (because you need to calculate some values or do something async in your page before convert it) you can enable the `waitForJS` local option, when `waitForJS` is set to true the conversion will wait until you set a variable to true in your page, by default the name of the variable is `ELECTRON_HTML_TO_READY` but you can customize it via `waitForJSVarName` option.\n\nExample\n-------\n\nlocal options:\n\n```js\nconversion({\n  html: '\u003ccustom html here\u003e',\n  waitForJS: true\n}, cb);\n```\n\ncustom html:\n\n```html\n\u003ch1\u003e\u003c/h1\u003e\n\u003cscript\u003e\n  // do some calculations or something async\n  setTimeout(function() {\n    window.ELECTRON_HTML_TO_READY = true; // this will start the conversion\n  }, 500);\n\u003c/script\u003e\n```\n\nDebugging\n---------\n\n- To get more information (internal debugging logs of the module) about what's happening inside the conversion run your app with the `DEBUG` env var: `DEBUG=electron-html-to,electron-html-to:* node app.js` (on Windows use `set DEBUG=electron-html-to,electron-html-to:* \u0026\u0026 node app.js`). This will print out some additional information about what's going on.\n\n- To see the electron process UI created (the visible electron window) and point stdout/stderr of the electron processes to console run your app with the `ELECTRON_HTML_TO_DEBUGGING` env var: `ELECTRON_HTML_TO_DEBUGGING=true node app.js` (on Windows use `set ELECTRON_HTML_TO_DEBUGGING=true \u0026\u0026 node app.js`).\n\n- To only point stdout/stderr of the electron processes to console run your app with the `ELECTRON_HTML_TO_STDSTREAMS` env var: `ELECTRON_HTML_TO_STDSTREAMS=true node app.js` (on Windows use `set ELECTRON_HTML_TO_STDSTREAMS=true \u0026\u0026 node app.js`).\n\n- To enable low level messages (chromium logs) of the electron processes run your app with the [`ELECTRON_ENABLE_LOGGING`](https://electron.atom.io/docs/api/chrome-command-line-switches/#enable-logging) env var: `ELECTRON_ENABLE_LOGGING=true node app.js` (on Windows use `set ELECTRON_ENABLE_LOGGING=true \u0026\u0026 node app.js`).\n\nRequirements\n------------\n\n-\tInstall [electron](http://electron.atom.io/) \u003e= 0.36.1 including electron@1, the easy way to install\nelectron in your app is `npm install electron --save` or `npm install electron-prebuilt --save`\n\nTroubleshooting\n---------------\n\n#### Using electron in single core machines\n\nIf you are using a machine with a single-core processor you will probably experience a high CPU usage when doing any conversion (97% in most cases and the usage is worse when using Windows), this is because a limitation in electron when it is being used on single core machines, unfortunately the only way to overcome this is to upgrade your machine to a processor with more cores (a processor with two cores is fine).\nmore info: [issue1](https://github.com/Microsoft/vscode/issues/17097), [issue2](https://github.com/Microsoft/vscode/issues/22724)\n\n#### env: node: No such file or directory when using electron-prebuilt and nvm\n\nIf you are using node with [nvm](https://github.com/creationix/nvm) and you have installed electron with `npm install -g electron-prebuilt` you probably will see an error or log with `env: node: No such file or directory`, this is because the electron executable installed by `electron-prebuilt` is a node CLI spawning the real electron executable internally, since nvm don't install/symlink node to `/usr/bin/env/node` when the electron executable installed by `electron-prebuilt` tries to run, it will fail because `node` won't be found in that context..\n\nSolution:\n\n1.- Install `electron-prebuilt` as a dependency in your app, this is the option **recommended** because you probably want to ensure your app always run with the exact version you tested it, and probably you don't want to install electron globally in your system.\n\n2.- You can make a symlink to `/usr/bin/env/node` but this is **not recommended** by nvm authors, because you will loose all the power that nvm brings.\n\n3.- Put the path to the **real electron executable** in your `$PATH`.\n\nLicense\n-------\n\nSee [license](https://github.com/bjrmatos/electron-html-to/blob/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjrmatos%2Felectron-html-to","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjrmatos%2Felectron-html-to","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjrmatos%2Felectron-html-to/lists"}