{"id":13705218,"url":"https://github.com/yumauri/gotenberg-js-client","last_synced_at":"2025-04-06T10:13:11.673Z","repository":{"id":40389025,"uuid":"215290669","full_name":"yumauri/gotenberg-js-client","owner":"yumauri","description":"A simple JS/TS client for interacting with a Gotenberg API","archived":false,"fork":false,"pushed_at":"2023-12-19T16:33:43.000Z","size":2719,"stargazers_count":113,"open_issues_count":12,"forks_count":9,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T09:07:30.485Z","etag":null,"topics":["gotenberg","pdf","pdf-converter"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/yumauri.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-15T12:15:06.000Z","updated_at":"2024-12-25T16:04:53.000Z","dependencies_parsed_at":"2023-12-19T21:25:40.306Z","dependency_job_id":"70c6e43c-ca0e-4d6b-a1d5-88126ff928b5","html_url":"https://github.com/yumauri/gotenberg-js-client","commit_stats":{"total_commits":94,"total_committers":5,"mean_commits":18.8,"dds":0.06382978723404253,"last_synced_commit":"c299b63f63d30ec03ec2d94f760cb53e25bfc6f9"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumauri%2Fgotenberg-js-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumauri%2Fgotenberg-js-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumauri%2Fgotenberg-js-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yumauri%2Fgotenberg-js-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yumauri","download_url":"https://codeload.github.com/yumauri/gotenberg-js-client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464222,"owners_count":20942970,"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":["gotenberg","pdf","pdf-converter"],"created_at":"2024-08-02T22:00:35.605Z","updated_at":"2025-04-06T10:13:11.640Z","avatar_url":"https://github.com/yumauri.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Clients"],"sub_categories":[],"readme":"# Gotenberg JS/TS client\n\n[![Build Status](https://github.com/yumauri/gotenberg-js-client/workflows/build/badge.svg)](https://github.com/yumauri/gotenberg-js-client/actions?workflow=build)\n[![Coverage Status](https://coveralls.io/repos/github/yumauri/gotenberg-js-client/badge.svg?branch=master)](https://coveralls.io/github/yumauri/gotenberg-js-client?branch=master)\n[![License](https://img.shields.io/github/license/yumauri/gotenberg-js-client.svg?color=yellow)](./LICENSE)\n[![NPM](https://img.shields.io/npm/v/gotenberg-js-client)](https://www.npmjs.com/package/gotenberg-js-client)\n![Made with Love](https://img.shields.io/badge/made%20with-❤-red.svg)\n\nA simple JS/TS client for interacting with a [Gotenberg](https://gotenberg.dev/) API.\u003cbr\u003e\n[Gotenberg](https://gotenberg.dev/) is a Docker-powered stateless API for converting HTML, Markdown and Office documents to PDF.\n\n- HTML and Markdown conversions using Google Chrome headless\n- Office conversions (.txt, .rtf, .docx, .doc, .odt, .pptx, .ppt, .odp and so on) using [unoconv](https://github.com/dagwieers/unoconv)\n- Assets: send your header, footer, images, fonts, stylesheets and so on for converting your HTML and Markdown to beautiful PDFs!\n- Easily interact with the API using [Go](https://github.com/thecodingmachine/gotenberg-go-client) and [PHP](https://github.com/thecodingmachine/gotenberg-php-client) libraries (and now - JavaScript too ;)\n\n## Install\n\n```bash\n$ yarn add gotenberg-js-client\n```\n\nOr using `npm`\n\n```bash\n$ npm install --save gotenberg-js-client\n```\n\n## NB ⚠️\n\nThis library is not yet fully compatible with Gotenberg 7.\u003cbr/\u003e\nYou can find more info in [this comment](https://github.com/yumauri/gotenberg-js-client/issues/32#issuecomment-981140727).\n\nThere are three main issues:\n\n- Gotenberg 7 has introduced new concept of conversion modules, thus, changing conversion URLs, so now they are different, than ones, this library creates. This can be sidestepped using custom connection string or adjusting URL manually (see [this comment](https://github.com/yumauri/gotenberg-js-client/issues/32#issuecomment-981140727)).\n- New modules has some new possibilities/parameters, which are impossible to pass, using this library. This can be sidestepped using `adjust`, and casting to `any`, if you use TypeScript (see [this issue](https://github.com/yumauri/gotenberg-js-client/issues/33) for reference).\n- Gotenberg 7 can potentially has many many different custom conversion modules, you can even write your own one. You can combine p.1 and p.2 to use any module with any path with any parameters, but I guess it will look not good. But it should work nonetheless.\n\nSo, nothing you can live without, but there are some inconveniences. For a while ;)\n\n## Usage\n\n```typescript\nimport { pipe, gotenberg, convert, html, please } from 'gotenberg-js-client'\n\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  html,\n  please\n)\n\n// --- 8\u003c ---\n\n// convert file from disk\nconst pdf = await toPDF('file://index.html')\n\n// or convert stream\nconst pdf = await toPDF(fs.createReadStream('index.html'))\n\n// or convert string!\nconst pdf = await toPDF('\u003chtml\u003e...\u003c/html\u003e')\n\n// library returns NodeJS.ReadableStream,\n// so you can save it to file, if you want, for example\npdf.pipe(fs.createWriteStream('index.pdf'))\n\n// or you can send it as response in Express application\napp.get('/pdf', function (req, res) {\n  //...\n  pdf.pipe(res)\n})\n```\n\nYou can define any source like `string`, `Buffer`, [file link](https://en.wikipedia.org/wiki/File_URI_scheme), `stream.Readable`, or `URL` (for url conversions).\u003cbr\u003e\nDetailed sources format you can find [here](https://github.com/yumauri/gotenberg-js-client/wiki/Source).\n\n## Header, footer and assets\n\nYou can define sources as array or object, for example:\n\n```typescript\n// `toPDF` function is defined above ↑↑↑\n\n// as object\nconst pdf = await toPDF({\n  'index.html': 'file://index.html',\n  'header.html': 'file://header.html',\n  'footer.html': 'file://footer.html',\n  'style.css': 'file://style.css',\n  'img.png': 'file://img.png',\n  'font.wof': 'file://font.wof',\n})\n\n// as array of tuples\nconst pdf = await toPDF([\n  ['index.html', 'file://index.html'],\n  ['header.html', 'file://header.html'],\n  ['footer.html', 'file://footer.html'],\n])\n\n// as even 1-dimensional array of files\n// in that case filenames will be retrieved from file path\nconst pdf = await toPDF([\n  'file://index.html',\n  'file://header.html',\n  'file://footer.html',\n])\n```\n\nInstead of array you can use any [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols), like `Map`, `Set`, `arguments`, iterator from generator function, or any object with `[Symbol.iterator]` defined.\u003cbr\u003e\nDetailed sources format you can find [here](https://github.com/yumauri/gotenberg-js-client/wiki/Source).\n\n## Paper size, margins, orientation\n\nWhen converting HTML or Markdown, you can use `to` helper, to set paper size, margins and orientation:\n\n```typescript\nimport {\n  pipe,\n  gotenberg,\n  convert,\n  html,\n  please,\n  to,\n  a4,\n  landscape,\n} from 'gotenberg-js-client'\n\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  html,\n  to(a4, landscape),\n  please\n)\n```\n\nYou can use simple object(s) for `to` argument(s) as well:\n\n```typescript\n//...\nto({\n  paperWidth: 8.27,\n  paperHeight: 11.69,\n  marginTop: 0,\n  marginBottom: 0,\n  marginLeft: 0,\n  marginRight: 0,\n  landscape: true,\n})\n//...\n\n// or\nto([8.27, 11.69], [0, 0, 0, 0], { landscape: true })\n//...\n\n// or\nto({ paper: [8.27, 11.69], margins: [0, 0, 0, 0], landscape: true })\n//...\n\n// or\nto({ width: 8.27, height: 11.69 }, { landscape: true })\n//...\n\n// or\nto({ top: 0, bottom: 0 })\n//...\n\n// or any other combination\n```\n\nWhen using array for paper size, order should be `[width, height]`\u003cbr\u003e\nWhen using array for margins, order should be `[top, right, bottom, left]` (just like in CSS)\n\n## Common options\n\nYou can set common options, like [resultFilename](https://thecodingmachine.github.io/gotenberg/#result_filename), or [waitTimeout](https://thecodingmachine.github.io/gotenberg/#timeout), or, actually, you can override _any_ option, using `set` helper:\n\n```typescript\n//...\nset({\n  resultFilename: 'foo.pdf',\n  waitTimeout: 2.5,\n})\n//...\n```\n\nThere are some _modifiers_ functions as well, like `filename`, `timeout`, `delay`, `webhook` and `googleChromeRpccBufferSize`:\n\n```typescript\n//...\nset(filename('foo.pdf'), timeout(2.5))\n//...\n```\n\nAlso you can specify page ranges using `set(range)` (will not work with `merge`):\n\n```typescript\n//...\nset(range('1-1'))\n//...\n```\n\nor scale, using `set(scale)` (works with HTML, Markdown and URL conversions):\n\n```typescript\n//...\nset(scale(0.75))\n//...\n```\n\n## Markdown // [Gotenberg documentation](https://thecodingmachine.github.io/gotenberg/#markdown)\n\n```typescript\nimport { pipe, gotenberg, convert, markdown, please } from 'gotenberg-js-client'\n\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  markdown,\n  please\n)\n\n// --- 8\u003c ---\n\nconst pdf = await toPDF({\n  'index.html': `\n    \u003c!doctype html\u003e\n    \u003chtml lang=\"en\"\u003e\n      \u003chead\u003e\n        \u003cmeta charset=\"utf-8\"\u003e\n        \u003ctitle\u003eMy PDF\u003c/title\u003e\n      \u003c/head\u003e\n      \u003cbody\u003e\n        {{ toHTML .DirPath \"content.md\" }}\n      \u003c/body\u003e\n    \u003c/html\u003e`,\n\n  'content.md': `\n    # My awesome markdown\n    ...\n  `,\n})\n```\n\nNote: I use strings here as an example, remind that you can use other supported [source](https://github.com/yumauri/gotenberg-js-client/wiki/Source) type.\n\n## Office // [Gotenberg documentation](https://thecodingmachine.github.io/gotenberg/#office)\n\n```typescript\nimport {\n  pipe,\n  gotenberg,\n  convert,\n  office,\n  to,\n  landscape,\n  set,\n  filename,\n  please,\n} from 'gotenberg-js-client'\n\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  office,\n  to(landscape),\n  set(filename('result.pdf')),\n  please\n)\n\n// --- 8\u003c ---\n\nconst pdf = await toPDF('file://document.docx')\n```\n\nNote: I use [file link](https://en.wikipedia.org/wiki/File_URI_scheme) here as an example, remind that you can use other supported [source](https://github.com/yumauri/gotenberg-js-client/wiki/Source) type, say, `Buffer`, or `stream.Readable`:\n\n```typescript\nhttps.get(\n  'https://file-examples.com/wp-content/uploads/2017/02/file-sample_100kB.docx',\n  async (document) =\u003e {\n    const pdf = await toPDF({ 'document.docx': document })\n    // ...\n  }\n)\n```\n\n## Url // [Gotenberg documentation](https://thecodingmachine.github.io/gotenberg/#url)\n\n```typescript\nimport { pipe, gotenberg, convert, url, please } from 'gotenberg-js-client'\n\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  url,\n  please\n)\n\n// --- 8\u003c ---\n\n// you can use link as string\nconst pdf = await toPDF('https://google.com')\n\n// or URL object\nconst pdf = await toPDF(new URL('https://google.com'))\n```\n\nNote: The only supported source for Url conversion is text url or instance of `URL` class.\n\nYou can set remote url header (for example, for [authentication](https://github.com/thecodingmachine/gotenberg/issues/81) or [host specifying](https://github.com/thecodingmachine/gotenberg/issues/116)) with helper `add(header)` (or `add(headers)`, or both):\n\n```typescript\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  url,\n  add(\n    header('Foo-Header', 'Foo'),\n    header('Bar-Header', 'Bar'),\n    headers({ 'Baz1-Header': 'Baz1', 'Baz2-Header': 'Baz2' })\n  ),\n  please\n)\n```\n\n(This also applies for Webhook headers, just use `webhookHeader` instead of `header` and `webhookHeaders` instead of `headers`).\n\n## Merge // [Gotenberg documentation](https://thecodingmachine.github.io/gotenberg/#merge)\n\nLike you would think:\n\n```typescript\nimport { pipe, gotenberg, merge, please } from 'gotenberg-js-client'\n\nconst toMergedPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  merge,\n  please\n)\n```\n\n## Advanced fine adjustment\n\nThere is special function `adjust`, which you can use to modify _any_ field in prepared internal `Request` object. You can check internal `Request` object structure in types. Any object, passed to `adjust`, will be merged with prepared `Request`.\n\nFor example, you can modify `url`, if your Gotenberg instance is working behind reverse proxy with some weird url replacement rules:\n\n```typescript\nimport { pipe, gotenberg, convert, html, adjust, please } from 'gotenberg-js-client'\n\n// Original Gotenberg HTML conversion endpoint is\n//   -\u003e /convert/html\n// But your reverse proxy uses location\n//   -\u003e /hidden/html/conversion\nconst toPDF = pipe(\n  gotenberg('http://localhost:3000'),\n  convert,\n  html,\n  adjust({ url: '/hidden/html/conversion' }),\n  please\n)\n```\n\nBut, using that function, remember about Peter Parker principle:\n\u003e \"With great power comes great responsibility\"\n\n## Bonus\n\nIf you happen to use this package from JavaScript, you will, obviously, lost type safety, but in return, you can use [proposed pipe operator](https://github.com/tc39/proposal-pipeline-operator) (with [Babel plugin](https://babeljs.io/docs/en/babel-plugin-proposal-pipeline-operator)), to get beauty like this:\n\n```javascript\nconst toPDF = source =\u003e\n  source\n    |\u003e gotenberg('http://localhost:3000')\n    |\u003e convert\n    |\u003e html\n    |\u003e to(a4, noMargins)\n    |\u003e set(filename('out.pdf'))\n    |\u003e please\n```\n\n## Names clashes\n\nIf you don't like to have simple imported names in your namespace, you can use `import *` syntax:\n\n```typescript\nimport * as got from 'gotenberg-js-client'\n\nconst toPDF = got.pipe(\n  got.gotenberg('http://localhost:3000'),\n  got.convert,\n  got.html,\n  got.please\n)\n```\n\n## Sponsored\n\n[\u003cimg src=\"https://setplex.com/img/logo.png\" alt=\"Setplex OTT Platform\" width=\"236\"\u003e](https://setplex.com/en/)\n\n[Setplex OTT Platform](https://setplex.com/en/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumauri%2Fgotenberg-js-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyumauri%2Fgotenberg-js-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyumauri%2Fgotenberg-js-client/lists"}