1 | # PDFKit
|
2 |
|
3 | A JavaScript PDF generation library for Node and the browser.
|
4 |
|
5 | ## Description
|
6 |
|
7 | PDFKit is a PDF document generation library for Node and the browser that makes creating complex, multi-page, printable
|
8 | documents easy. The API embraces chainability, and includes both low level functions as well as abstractions for higher
|
9 | level functionality. The PDFKit API is designed to be simple, so generating complex documents is often as simple as
|
10 | a few function calls.
|
11 |
|
12 | Check out some of the [documentation and examples](http://pdfkit.org/docs/getting_started.html) to see for yourself!
|
13 | You can also read the guide as a [self-generated PDF](http://pdfkit.org/docs/guide.pdf) with example output displayed inline.
|
14 | If you'd like to see how it was generated, check out the README in the [docs](https://github.com/foliojs/pdfkit/tree/master/docs)
|
15 | folder.
|
16 |
|
17 | You can also try out an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html).
|
18 |
|
19 | ## Installation
|
20 |
|
21 | Installation uses the [npm](http://npmjs.org/) package manager. Just type the following command after installing npm.
|
22 |
|
23 | npm install pdfkit
|
24 |
|
25 | ## Features
|
26 |
|
27 | - Vector graphics
|
28 | - HTML5 canvas-like API
|
29 | - Path operations
|
30 | - SVG path parser for easy path creation
|
31 | - Transformations
|
32 | - Linear and radial gradients
|
33 | - Text
|
34 | - Line wrapping (with soft hyphen recognition)
|
35 | - Text alignments
|
36 | - Bulleted lists
|
37 | - Font embedding
|
38 | - Supports TrueType (.ttf), OpenType (.otf), WOFF, WOFF2, TrueType Collections (.ttc), and Datafork TrueType (.dfont) fonts
|
39 | - Font subsetting
|
40 | - See [fontkit](http://github.com/foliojs/fontkit) for more details on advanced glyph layout support.
|
41 | - Image embedding
|
42 | - Supports JPEG and PNG files (including indexed PNGs, and PNGs with transparency)
|
43 | - Annotations
|
44 | - Links
|
45 | - Notes
|
46 | - Highlights
|
47 | - Underlines
|
48 | - etc.
|
49 | - AcroForms
|
50 | - Outlines
|
51 | - PDF security
|
52 | - Encryption
|
53 | - Access privileges (printing, copying, modifying, annotating, form filling, content accessibility, document assembly)
|
54 | - Accessibility support (marked content, logical structure, Tagged PDF, PDF/UA)
|
55 |
|
56 | ## Coming soon!
|
57 |
|
58 | - Patterns fills
|
59 | - Higher level APIs for creating tables and laying out content
|
60 | - More performance optimizations
|
61 | - Even more awesomeness, perhaps written by you! Please fork this repository and send me pull requests.
|
62 |
|
63 | ## Example
|
64 |
|
65 | ```javascript
|
66 | const PDFDocument = require('pdfkit');
|
67 | const fs = require('fs');
|
68 |
|
69 | // Create a document
|
70 | const doc = new PDFDocument();
|
71 |
|
72 | // Pipe its output somewhere, like to a file or HTTP response
|
73 | // See below for browser usage
|
74 | doc.pipe(fs.createWriteStream('output.pdf'));
|
75 |
|
76 | // Embed a font, set the font size, and render some text
|
77 | doc
|
78 | .font('fonts/PalatinoBold.ttf')
|
79 | .fontSize(25)
|
80 | .text('Some text with an embedded font!', 100, 100);
|
81 |
|
82 | // Add an image, constrain it to a given size, and center it vertically and horizontally
|
83 | doc.image('path/to/image.png', {
|
84 | fit: [250, 300],
|
85 | align: 'center',
|
86 | valign: 'center'
|
87 | });
|
88 |
|
89 | // Add another page
|
90 | doc
|
91 | .addPage()
|
92 | .fontSize(25)
|
93 | .text('Here is some vector graphics...', 100, 100);
|
94 |
|
95 | // Draw a triangle
|
96 | doc
|
97 | .save()
|
98 | .moveTo(100, 150)
|
99 | .lineTo(100, 250)
|
100 | .lineTo(200, 250)
|
101 | .fill('#FF3300');
|
102 |
|
103 | // Apply some transforms and render an SVG path with the 'even-odd' fill rule
|
104 | doc
|
105 | .scale(0.6)
|
106 | .translate(470, -380)
|
107 | .path('M 250,75 L 323,301 131,161 369,161 177,301 z')
|
108 | .fill('red', 'even-odd')
|
109 | .restore();
|
110 |
|
111 | // Add some text with annotations
|
112 | doc
|
113 | .addPage()
|
114 | .fillColor('blue')
|
115 | .text('Here is a link!', 100, 100)
|
116 | .underline(100, 100, 160, 27, { color: '#0000FF' })
|
117 | .link(100, 100, 160, 27, 'http://google.com/');
|
118 |
|
119 | // Finalize PDF file
|
120 | doc.end();
|
121 | ```
|
122 |
|
123 | [The PDF output from this example](http://pdfkit.org/demo/out.pdf) (with a few additions) shows the power of PDFKit — producing
|
124 | complex documents with a very small amount of code. For more, see the `demo` folder and the
|
125 | [PDFKit programming guide](http://pdfkit.org/docs/getting_started.html).
|
126 |
|
127 | ## Browser Usage
|
128 |
|
129 | There are three ways to use PDFKit in the browser:
|
130 |
|
131 | - Use [Browserify](http://browserify.org/). See demo [source code](demo/browser.js) and [build script](https://github.com/foliojs/pdfkit/blob/master/package.json#L56)
|
132 | - Use [webpack](https://webpack.js.org/). See [complete example](https://github.com/blikblum/pdfkit-webpack-example).
|
133 | - Use prebuilt version. Distributed as `pdfkit.standalone.js` file in the [releases](https://github.com/foliojs/pdfkit/releases) or in the package `js` folder.
|
134 |
|
135 | In addition to PDFKit, you'll need somewhere to stream the output to. HTML5 has a
|
136 | [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object which can be used to store binary data, and
|
137 | get URLs to this data in order to display PDF output inside an iframe, or upload to a server, etc. In order to
|
138 | get a Blob from the output of PDFKit, you can use the [blob-stream](https://github.com/devongovett/blob-stream)
|
139 | module.
|
140 |
|
141 | The following example uses Browserify or webpack to load `PDFKit` and `blob-stream`. See [here](https://codepen.io/blikblum/pen/gJNWMg?editors=1010) and [here](https://codepen.io/blikblum/pen/YboVNq?editors=1010) for examples
|
142 | of prebuilt version usage.
|
143 |
|
144 | ```javascript
|
145 | // require dependencies
|
146 | const PDFDocument = require('pdfkit');
|
147 | const blobStream = require('blob-stream');
|
148 |
|
149 | // create a document the same way as above
|
150 | const doc = new PDFDocument();
|
151 |
|
152 | // pipe the document to a blob
|
153 | const stream = doc.pipe(blobStream());
|
154 |
|
155 | // add your content to the document here, as usual
|
156 |
|
157 | // get a blob when you are done
|
158 | doc.end();
|
159 | stream.on('finish', function() {
|
160 | // get a blob you can do whatever you like with
|
161 | const blob = stream.toBlob('application/pdf');
|
162 |
|
163 | // or get a blob URL for display in the browser
|
164 | const url = stream.toBlobURL('application/pdf');
|
165 | iframe.src = url;
|
166 | });
|
167 | ```
|
168 |
|
169 | You can see an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html).
|
170 |
|
171 | Note that in order to Browserify a project using PDFKit, you need to install the `brfs` module with npm,
|
172 | which is used to load built-in font data into the package. It is listed as a `devDependency` in
|
173 | PDFKit's `package.json`, so it isn't installed by default for Node users.
|
174 | If you forget to install it, Browserify will print an error message.
|
175 |
|
176 | ## Documentation
|
177 |
|
178 | For complete API documentation and more examples, see the [PDFKit website](http://pdfkit.org/).
|
179 |
|
180 | ## License
|
181 |
|
182 | PDFKit is available under the MIT license.
|