@shad0wz7/nestjs-pdf 2.5.2 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +54 -27
- package/dist/index.cjs +1206 -2335
- package/dist/index.d.cts +43 -7
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +43 -7
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +1207 -2324
- package/dist/index.mjs.map +1 -1
- package/package.json +27 -67
package/README.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# nestjs-pdf
|
|
2
2
|
|
|
3
|
+
> **v3 — ESM-first, NestJS 12.** This is the active `main` line: authored in
|
|
4
|
+
> ESM, published as a dual CJS/ESM package, and targets **NestJS 12+**.
|
|
5
|
+
>
|
|
6
|
+
> Still on **NestJS 11** or need a pure CommonJS package? Use the maintenance
|
|
7
|
+
> `v2` branch instead:
|
|
8
|
+
>
|
|
9
|
+
> ```bash
|
|
10
|
+
> npm install @shad0wz7/nestjs-pdf@^2
|
|
11
|
+
> ```
|
|
12
|
+
>
|
|
13
|
+
> See the [`v2` branch README](https://github.com/ShadowZ11/nestjs-pdf/blob/v2/README.md)
|
|
14
|
+
> for details. It receives maintenance/security fixes only — new features land on v3.
|
|
15
|
+
|
|
3
16
|
[](https://www.npmjs.com/package/%40shad0wz7%2Fnestjs-pdf)
|
|
4
17
|
[](https://github.com/ShadowZ11/nestjs-pdf?tab=MIT-1-ov-file)
|
|
5
18
|
[](https://www.npmjs.com/package/%40shad0wz7%2Fnestjs-pdf)
|
|
@@ -7,7 +20,6 @@
|
|
|
7
20
|
[](https://codecov.io/github/ShadowZ11/nestjs-pdf)
|
|
8
21
|
[](https://www.typescriptlang.org/)
|
|
9
22
|
|
|
10
|
-
|
|
11
23
|
A NestJS library to generate and manipulate PDFs using Puppeteer and multiple template engines, including Handlebars, EJS, Pug, MJML, Nunjucks, Eta and Mustache.
|
|
12
24
|
|
|
13
25
|
Main features:
|
|
@@ -17,6 +29,11 @@ Main features:
|
|
|
17
29
|
- Add signature fields based on a text anchor in an existing PDF
|
|
18
30
|
- Simple API (module and service) to integrate easily into a Nest application
|
|
19
31
|
|
|
32
|
+
## Requirements
|
|
33
|
+
|
|
34
|
+
- **Node.js** `^20.19.0`, `^22.12.0` or `>=24.0.0` (aligned with NestJS 12)
|
|
35
|
+
- **NestJS** `^12.0.0` (`@nestjs/common`, `@nestjs/core`) and `rxjs ^7.8.0` as peer dependencies
|
|
36
|
+
|
|
20
37
|
## Installation
|
|
21
38
|
|
|
22
39
|
To add the library inside your project :
|
|
@@ -38,7 +55,7 @@ Import the module and configure it in your Nest application:
|
|
|
38
55
|
|
|
39
56
|
To use a template engine, you need to install the corresponding package as a dependency in your project:
|
|
40
57
|
|
|
41
|
-
- For Handlebars: `npm install
|
|
58
|
+
- For Handlebars: `npm install handlebars`
|
|
42
59
|
- For EJS: `npm install ejs`
|
|
43
60
|
- For Pug: `npm install pug`
|
|
44
61
|
- For MJML: `npm install mjml`
|
|
@@ -48,7 +65,7 @@ To use a template engine, you need to install the corresponding package as a dep
|
|
|
48
65
|
|
|
49
66
|
```ts
|
|
50
67
|
import { Module } from '@nestjs/common';
|
|
51
|
-
import { NestjsPdfModule } from 'nestjs-pdf';
|
|
68
|
+
import { NestjsPdfModule } from '@shad0wz7/nestjs-pdf';
|
|
52
69
|
|
|
53
70
|
@Module({
|
|
54
71
|
imports: [
|
|
@@ -62,11 +79,20 @@ import { NestjsPdfModule } from 'nestjs-pdf';
|
|
|
62
79
|
export class AppModule {}
|
|
63
80
|
```
|
|
64
81
|
|
|
82
|
+
> **Enable shutdown hooks.** On shutdown, `nestjs-pdf` waits for in-flight PDF jobs
|
|
83
|
+
> to finish, closes the Puppeteer browser and (optionally) wipes its browser cache.
|
|
84
|
+
> This only runs if your app enables Nest's shutdown hooks:
|
|
85
|
+
>
|
|
86
|
+
> ```ts
|
|
87
|
+
> const app = await NestFactory.create(AppModule);
|
|
88
|
+
> app.enableShutdownHooks();
|
|
89
|
+
> ```
|
|
90
|
+
|
|
65
91
|
Inject the service and generate a PDF:
|
|
66
92
|
|
|
67
93
|
```ts
|
|
68
94
|
import { Controller, Get } from '@nestjs/common';
|
|
69
|
-
import { NestjsPdfService } from 'nestjs-pdf';
|
|
95
|
+
import { NestjsPdfService } from '@shad0wz7/nestjs-pdf';
|
|
70
96
|
|
|
71
97
|
@Controller()
|
|
72
98
|
export class AppController {
|
|
@@ -117,28 +143,28 @@ If the anchor is not found, the signature field will be added at a default posit
|
|
|
117
143
|
|
|
118
144
|
The library exposes Puppeteer options via the `PuppeteerParameters` interface (see `src/puppeteer/puppeteer-parameters.interface.ts`). You can configure:
|
|
119
145
|
|
|
120
|
-
|
|
121
|
-
|
|
|
122
|
-
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `
|
|
132
|
-
| `
|
|
133
|
-
| `
|
|
134
|
-
| `
|
|
135
|
-
| `
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `executablePath` | The path to the browser executable to use. If not specified, Puppeteer will install Chromium in cache dir. (useLockedBrowser is useless with this param specified) |
|
|
146
|
+
| | Description |
|
|
147
|
+
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
148
|
+
| `pdfOptions` | The pdf options can be found on: https://pptr.dev/api/puppeteer.pdfoptions. Native Puppeteer options for `page.pdf` |
|
|
149
|
+
| `hbsOptions` | Handlebars configuration: `templateDirectory` (base dir for `renderFile`), `partialDirectory` (files registered as partials), `compileOptions`, `templateOptions`, and `helpers` (`{ name, fn }[]`). Like the other engines it can be set globally here or overridden per call (`generatePdfFromTemplateHbs*(..., { hbsOptions })`). Helpers/partials run on an isolated Handlebars environment (no global leakage). |
|
|
150
|
+
| `ejsOptions` | The ejs options can be found on [EJS documentation](https://ejs.co/#options) |
|
|
151
|
+
| `pugOptions` | The pug options can be found on [Pug documentation](https://pugjs.org/api/reference.html#options) |
|
|
152
|
+
| `mjmlOptions` | The mjml options can be found on [MJML documentation](https://mjml.io/documentation/#options) |
|
|
153
|
+
| `nunjucksOptions` | The nunjucks options can be found on [Nunjucks documentation](https://mozilla.github.io/nunjucks/api.html#configure) |
|
|
154
|
+
| `etaOptions` | The eta options can be found on [Eta documentation](https://eta.js.org/docs/4.x.x/api/configuration) |
|
|
155
|
+
| `mustacheOptions` | The mustache options can be found on [Mustache documentation](https://mustache.github.io/mustache.5.html) |
|
|
156
|
+
| `browser` | The browser to use for the PDF generation. By default: `Browser.CHROMIUM`. Allowed values `Browser.CHROMIUM`, `Browser.CHROMEHEADLESSSHELL`, `Browser.CHROME`, `Browser.FIREFOX`, `Browser.CHROMEDRIVER` ([Official documentation of Browser](https://pptr.dev/browsers-api/browsers.browser)) |
|
|
157
|
+
| `browserTag` | The version of the browser to use for the PDF generation. By default: `BrowserTag.LATEST` if Browser is **CHROMIUM** else `BrowserTag.STABLE`. Allowed values `BrowserTag.STABLE`, `BrowserTag.LATEST`, `BrowserTag.BETA`, `BrowserTag.DEV`, `BrowserTag.CANARY` |
|
|
158
|
+
| `browserInstallBaseUrl` | The baseUrl used for the installation of the browser. This baseUrl is passed to the [`install`](https://pptr.dev/browsers-api/browsers.install) method of `@puppeteer/browsers` |
|
|
159
|
+
| `headless` | Define if you want to use chromium headless or not, or the old headless version (`shell`). By default it's `true`. Allowed values: `true`,`false`,`"shell"` |
|
|
160
|
+
| `useLockedBrowser` | Define if you want to use the locked version of the browser. By default it's `false`. Allowed values: `true`,`false` |
|
|
161
|
+
| `buildId` | You can force the build id. Should be `string` |
|
|
162
|
+
| `cleanupBrowserCacheOnExit` | Wipe the downloaded browser cache folder when the app shuts down (requires `app.enableShutdownHooks()`). Set to `false` to keep the cache between runs. By default it's `true`. Allowed values: `true`,`false` |
|
|
163
|
+
| `extraPuppeteerArgs` | It passes some extra arguments to Puppeteer's launch method. You can check the default args at bellow. Should be `string[]` |
|
|
164
|
+
| `executablePath` | The path to the browser executable to use. If not specified, Puppeteer will install Chromium in cache dir. (useLockedBrowser is useless with this param specified) |
|
|
140
165
|
|
|
141
166
|
these are the default extra arguments passed to Puppeteer:
|
|
167
|
+
|
|
142
168
|
```ts
|
|
143
169
|
[
|
|
144
170
|
'--autoplay-policy=user-gesture-required',
|
|
@@ -198,11 +224,12 @@ If you want to test locally the examples with the entire project, you can follow
|
|
|
198
224
|
|
|
199
225
|
## Tests
|
|
200
226
|
|
|
201
|
-
This repository includes unit
|
|
227
|
+
This repository includes unit tests (Vitest). To run them:
|
|
202
228
|
|
|
203
229
|
```bash
|
|
204
|
-
pnpm run
|
|
205
|
-
pnpm
|
|
230
|
+
pnpm test # single run
|
|
231
|
+
pnpm test:watch # watch mode
|
|
232
|
+
pnpm test:cov # with coverage
|
|
206
233
|
```
|
|
207
234
|
|
|
208
235
|
## Contributing
|