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/devongovett/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
|
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/devongovett/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 | * Outlines
|
50 | * PDF security
|
51 | * Encryption
|
52 | * Access privileges (printing, copying, modifying, annotating, form filling, content accessibility, document assembly)
|
53 |
|
54 | ## Coming soon!
|
55 |
|
56 | * Patterns fills
|
57 | * Higher level APIs for creating tables and laying out content
|
58 | * More performance optimizations
|
59 | * Even more awesomeness, perhaps written by you! Please fork this repository and send me pull requests.
|
60 |
|
61 | ## Example
|
62 |
|
63 | ```javascript
|
64 | const PDFDocument = require('pdfkit');
|
65 |
|
66 | // Create a document
|
67 | const doc = new PDFDocument;
|
68 |
|
69 | // Pipe its output somewhere, like to a file or HTTP response
|
70 | // See below for browser usage
|
71 | doc.pipe(fs.createWriteStream('output.pdf'));
|
72 |
|
73 | // Embed a font, set the font size, and render some text
|
74 | doc.font('fonts/PalatinoBold.ttf')
|
75 | .fontSize(25)
|
76 | .text('Some text with an embedded font!', 100, 100);
|
77 |
|
78 | // Add an image, constrain it to a given size, and center it vertically and horizontally
|
79 | doc.image('path/to/image.png', {
|
80 | fit: [250, 300],
|
81 | align: 'center',
|
82 | valign: 'center'
|
83 | });
|
84 |
|
85 | // Add another page
|
86 | doc.addPage()
|
87 | .fontSize(25)
|
88 | .text('Here is some vector graphics...', 100, 100);
|
89 |
|
90 | // Draw a triangle
|
91 | doc.save()
|
92 | .moveTo(100, 150)
|
93 | .lineTo(100, 250)
|
94 | .lineTo(200, 250)
|
95 | .fill("#FF3300");
|
96 |
|
97 | // Apply some transforms and render an SVG path with the 'even-odd' fill rule
|
98 | doc.scale(0.6)
|
99 | .translate(470, -380)
|
100 | .path('M 250,75 L 323,301 131,161 369,161 177,301 z')
|
101 | .fill('red', 'even-odd')
|
102 | .restore();
|
103 |
|
104 | // Add some text with annotations
|
105 | doc.addPage()
|
106 | .fillColor("blue")
|
107 | .text('Here is a link!', 100, 100)
|
108 | .underline(100, 100, 160, 27, {color: "#0000FF"})
|
109 | .link(100, 100, 160, 27, 'http://google.com/');
|
110 |
|
111 | // Finalize PDF file
|
112 | doc.end();
|
113 | ```
|
114 |
|
115 | [The PDF output from this example](http://pdfkit.org/demo/out.pdf) (with a few additions) shows the power of PDFKit — producing
|
116 | complex documents with a very small amount of code. For more, see the `demo` folder and the
|
117 | [PDFKit programming guide](http://pdfkit.org/docs/getting_started.html).
|
118 |
|
119 | ## Browser Usage
|
120 |
|
121 | There are two ways to use PDFKit in the browser. The first is to use [Browserify](http://browserify.org/),
|
122 | which is a Node module packager for the browser with the familiar `require` syntax. The second is to use
|
123 | a prebuilt version of PDFKit, which you can [download from Github](https://github.com/devongovett/pdfkit/releases).
|
124 |
|
125 | In addition to PDFKit, you'll need somewhere to stream the output to. HTML5 has a
|
126 | [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob) object which can be used to store binary data, and
|
127 | get URLs to this data in order to display PDF output inside an iframe, or upload to a server, etc. In order to
|
128 | get a Blob from the output of PDFKit, you can use the [blob-stream](https://github.com/devongovett/blob-stream)
|
129 | module.
|
130 |
|
131 | The following example uses Browserify to load `PDFKit` and `blob-stream`, but if you're not using Browserify,
|
132 | you can load them in whatever way you'd like (e.g. script tags).
|
133 |
|
134 | ```javascript
|
135 | // require dependencies
|
136 | const PDFDocument = require('pdfkit');
|
137 | const blobStream = require('blob-stream');
|
138 |
|
139 | // create a document the same way as above
|
140 | const doc = new PDFDocument;
|
141 |
|
142 | // pipe the document to a blob
|
143 | const stream = doc.pipe(blobStream());
|
144 |
|
145 | // add your content to the document here, as usual
|
146 |
|
147 | // get a blob when you're done
|
148 | doc.end();
|
149 | stream.on('finish', function() {
|
150 | // get a blob you can do whatever you like with
|
151 | const blob = stream.toBlob('application/pdf');
|
152 |
|
153 | // or get a blob URL for display in the browser
|
154 | const url = stream.toBlobURL('application/pdf');
|
155 | iframe.src = url;
|
156 | });
|
157 | ```
|
158 |
|
159 | You can see an interactive in-browser demo of PDFKit [here](http://pdfkit.org/demo/browser.html).
|
160 |
|
161 | Note that in order to Browserify a project using PDFKit, you need to install the `brfs` module with npm,
|
162 | which is used to load built-in font data into the package. It is listed as a `devDependency` in
|
163 | PDFKit's `package.json`, so it isn't installed by default for Node users.
|
164 | If you forget to install it, Browserify will print an error message.
|
165 |
|
166 | ## Documentation
|
167 |
|
168 | For complete API documentation and more examples, see the [PDFKit website](http://pdfkit.org/).
|
169 |
|
170 | ## License
|
171 |
|
172 | PDFKit is available under the MIT license.
|