gotenberg-js-client
Advanced tools
A simple JS/TS client for interacting with a Gotenberg API.
Gotenberg is a Docker-powered stateless API for converting HTML, Markdown and Office documents to PDF.
$ yarn add gotenberg-js-client
Or using npm
$ npm install --save gotenberg-js-client
import { pipe, gotenberg, convert, html, please } from 'gotenberg-js-client'
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
html,
please
)
// --- 8< ---
// convert file from disk
const pdf = await toPDF('file://index.html')
// or convert stream
const pdf = await toPDF(fs.createReadStream('index.html'))
// or convert string!
const pdf = await toPDF('<html>...</html>')
// library returns NodeJS.ReadableStream,
// so you can save it to file, if you want, for example
pdf.pipe(fs.createWriteStream('index.pdf'))
// or you can send it as response in Express application
app.get('/pdf', function (req, res) {
//...
pdf.pipe(res)
})
You can define any source like string, Buffer, file link, stream.Readable, or URL (for url conversions).
Detailed sources format you can find here.
You can define sources as array or object, for example:
// `toPDF` function is defined above ↑↑↑
// as object
const pdf = await toPDF({
'index.html': 'file://index.html',
'header.html': 'file://header.html',
'footer.html': 'file://footer.html',
'style.css': 'file://style.css',
'img.png': 'file://img.png',
'font.wof': 'file://font.wof',
})
// as array of tuples
const pdf = await toPDF([
['index.html', 'file://index.html'],
['header.html', 'file://header.html'],
['footer.html', 'file://footer.html'],
])
// as even 1-dimensional array of files
// in that case filenames will be retrieved from file path
const pdf = await toPDF([
'file://index.html',
'file://header.html',
'file://footer.html',
])
Instead of array you can use any iterable, like Map, Set, arguments, iterator from generator function, or any object with [Symbol.iterator] defined.
Detailed sources format you can find here.
When converting HTML or Markdown, you can use to helper, to set paper size, margins and orientation:
import {
pipe,
gotenberg,
convert,
html,
please,
to,
a4,
landscape,
} from 'gotenberg-js-client'
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
html,
to(a4, landscape),
please
)
You can use simple object(s) for to argument(s) as well:
//...
to({
paperWidth: 8.27,
paperHeight: 11.69,
marginTop: 0,
marginBottom: 0,
marginLeft: 0,
marginRight: 0,
landscape: true,
})
//...
// or
to([8.27, 11.69], [0, 0, 0, 0], { landscape: true })
//...
// or
to({ paper: [8.27, 11.69], margins: [0, 0, 0, 0], landscape: true })
//...
// or
to({ width: 8.27, height: 11.69 }, { landscape: true })
//...
// or
to({ top: 0, bottom: 0 })
//...
// or any other combination
When using array for paper size, order should be [width, height]
When using array for margins, order should be [top, right, bottom, left] (just like in CSS)
You can set common options, like resultFilename, or waitTimeout, or, actually, you can override any option, using set helper:
//...
set({
resultFilename: 'foo.pdf',
waitTimeout: 2.5,
})
//...
There are some modifiers functions as well, like filename, timeout, delay, webhook and googleChromeRpccBufferSize:
//...
set(filename('foo.pdf'), timeout(2.5))
//...
Also you can specify page ranges using set(range) (will not work with merge):
//...
set(range('1-1'))
//...
or scale, using set(scale) (works with HTML, Markdown and URL conversions):
//...
set(scale(0.75))
//...
import { pipe, gotenberg, convert, markdown, please } from 'gotenberg-js-client'
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
markdown,
please
)
// --- 8< ---
const pdf = await toPDF({
'index.html': `
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My PDF</title>
</head>
<body>
{{ toHTML .DirPath "content.md" }}
</body>
</html>`,
'content.md': `
# My awesome markdown
...
`,
})
Note: I use strings here as an example, remind that you can use other supported source type.
import {
pipe,
gotenberg,
convert,
office,
to,
landscape,
set,
filename,
please,
} from 'gotenberg-js-client'
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
office,
to(landscape),
set(filename('result.pdf')),
please
)
// --- 8< ---
const pdf = await toPDF('file://document.docx')
Note: I use file link here as an example, remind that you can use other supported source type, say, Buffer, or stream.Readable:
https.get(
'https://file-examples.com/wp-content/uploads/2017/02/file-sample_100kB.docx',
async (document) => {
const pdf = await toPDF({ 'document.docx': document })
// ...
}
)
import { pipe, gotenberg, convert, url, please } from 'gotenberg-js-client'
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
url,
please
)
// --- 8< ---
// you can use link as string
const pdf = await toPDF('https://google.com')
// or URL object
const pdf = await toPDF(new URL('https://google.com'))
Note: The only supported source for Url conversion is text url or instance of URL class.
You can set remote url header (for example, for authentication or host specifying) with helper add(header) (or add(headers), or both):
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
url,
add(
header('Foo-Header', 'Foo'),
header('Bar-Header', 'Bar'),
headers({ 'Baz1-Header': 'Baz1', 'Baz2-Header': 'Baz2' })
),
please
)
(This also applies for Webhook headers, just use webhookHeader instead of header and webhookHeaders instead of headers).
Like you would think:
import { pipe, gotenberg, merge, please } from 'gotenberg-js-client'
const toMergedPDF = pipe(
gotenberg('http://localhost:3000'),
merge,
please
)
There 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.
For example, you can modify url, if your Gotenberg instance is working behind reverse proxy with some weird url replacement rules:
import { pipe, gotenberg, convert, html, adjust, please } from 'gotenberg-js-client'
// Original Gotenberg HTML conversion endpoint is
// -> /convert/html
// But your reverse proxy uses location
// -> /hidden/html/conversion
const toPDF = pipe(
gotenberg('http://localhost:3000'),
convert,
html,
adjust({ url: '/hidden/html/conversion' }),
please
)
But, using that function, remember about Peter Parker principle:
"With great power comes great responsibility"
If you happen to use this package from JavaScript, you will, obviously, lost type safety, but in return, you can use proposed pipe operator (with Babel plugin), to get beauty like this:
const toPDF = source =>
source
|> gotenberg('http://localhost:3000')
|> convert
|> html
|> to(a4, noMargins)
|> set(filename('out.pdf'))
|> please
If you don't like to have simple imported names in your namespace, you can use import * syntax:
import * as got from 'gotenberg-js-client'
const toPDF = got.pipe(
got.gotenberg('http://localhost:3000'),
got.convert,
got.html,
got.please
)
FAQs
A simple JS/TS for interacting with a Gotenberg API
The npm package gotenberg-js-client receives a total of 7,184 weekly downloads. As such, gotenberg-js-client popularity was classified as popular.
We found that gotenberg-js-client demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."