{"id":23070553,"url":"https://github.com/uyamazak/hc-pdf-server","last_synced_at":"2025-07-17T23:33:58.232Z","repository":{"id":37049880,"uuid":"302505392","full_name":"uyamazak/hc-pdf-server","owner":"uyamazak","description":"Convert HTML to PDF Server by headless chrome with TypeScript. The new version of hcep-pdf-server. ","archived":false,"fork":false,"pushed_at":"2023-12-14T20:21:12.000Z","size":3038,"stargazers_count":45,"open_issues_count":20,"forks_count":16,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T15:43:21.138Z","etag":null,"topics":["docker","fastify","headless-chrome","puppeteer","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uyamazak.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["uyamazak"]}},"created_at":"2020-10-09T01:48:01.000Z","updated_at":"2025-01-30T07:11:17.000Z","dependencies_parsed_at":"2024-12-16T06:28:05.703Z","dependency_job_id":"37fee61e-7313-4f5d-a6a2-1997e9fd0979","html_url":"https://github.com/uyamazak/hc-pdf-server","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/uyamazak/hc-pdf-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uyamazak%2Fhc-pdf-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uyamazak%2Fhc-pdf-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uyamazak%2Fhc-pdf-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uyamazak%2Fhc-pdf-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uyamazak","download_url":"https://codeload.github.com/uyamazak/hc-pdf-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uyamazak%2Fhc-pdf-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265678643,"owners_count":23810115,"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":["docker","fastify","headless-chrome","puppeteer","typescript"],"created_at":"2024-12-16T06:27:09.886Z","updated_at":"2025-07-17T23:33:57.930Z","avatar_url":"https://github.com/uyamazak.png","language":"TypeScript","funding_links":["https://github.com/sponsors/uyamazak","https://github.com/sponsors/uyamazak/"],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/uyamazak/hc-pdf-server/workflows/ci/badge.svg)](https://github.com/uyamazak/hc-pdf-server/actions?query=workflow%3Aci)\n[![Docker](https://github.com/uyamazak/hc-pdf-server/workflows/docker-build/badge.svg)](https://github.com/uyamazak/hc-pdf-server/actions?query=workflow%3Adocker-build)\n[![CodeQL](https://github.com/uyamazak/hc-pdf-server/workflows/CodeQL/badge.svg)](https://github.com/uyamazak/hc-pdf-server/actions?query=workflow%3ACodeQL)\n[![Apache License](https://img.shields.io/badge/license-Apache-blue.svg?style=flat)](LICENSE)\n\n# hc-pdf-server\n\nconvert HTML to PDF server by Headless Chrome.\n\nGET URL or POST HTML returns PDF binary.\n\nThis is new version of [hcep-pdf-server](https://github.com/uyamazak/hcep-pdf-server/) with buit-in TypeScript supoort and sufficient testing, excellent new features.\n\nOf course, Docker is also supported!\n\n## New features compared to hcep-pdf-server\n\n- Writing in TypeScript\n- Use [Fasity](https://www.fastify.io/) instead of [Express](https://expressjs.com/) for native TypeScript support and fast response\n- You can Change User Agent and Accept Language etc with environment variables\n- Bearer token authorization Support\n\n# Getting Started\n\n## Clone\ngit clone this repository.\n\n## Run\nYou can try it in 2 ways: 1.`Docker` or 2.`Local`\n\n### 1. Docker\n\n#### Requirement\nYou need install docker.\n\nhttps://docs.docker.com/get-docker/\n\n#### Build without installing fonts\n\n```zsh\ndocker build -t hc-pdf-server:latest .\n```\n\n#### Install Fonts (optionary)\nIf you wanto to convert pages in Japanese, Chinese or languages other than English with Docker.\n\nYou will need to install each font files.\n\nAlso, you can use WEB fonts, but since it takes a long time for requesting and downloading them,\nwe recommend that install the font files in the server.\n\n\n##### 1. From font file\nAdd your font files (ex. *.otf) to `fonts/` dir.\n\n```zsh\ncp AnyFonts.ttf ./fonts/\n```\n\nAnd build image.\n\n```zsh\ndocker build -t hc-pdf-server:latest .\n```\n\n##### 2. From package\nYou can use build-arg `ADDITONAL_FONTS` as package names.\n\nSee below available font package names.\n\nhttps://packages.debian.org/stable/fonts/\n\n```zsh\ndocker build \\\n  --build-arg ADDITONAL_FONTS=fonts-ipafont \\\n  -t hc-pdf-server:latest .\n\n# multiple (split by space)\ndocker build \\\n  --build-arg ADDITONAL_FONTS=\"fonts-ipafont fonts-ipaexfont-gothic\" \\\n  -t hc-pdf-server:latest .\n```\n#### Run docker\n```zsh\ndocker run -it -p 8080:8080 hc-pdf-server:latest\n```\n\n### 2. Local (for development use)\n\n#### Requirement\nYou need to install Node.js and yarn.\n\n- [Node.js](https://nodejs.org/)\n- [yarn](https://classic.yarnpkg.com/)\n\ninstall packages\n```zsh\nyarn install\n```\n\nstart dev server\n```zsh\nyarn dev\n```\n\nlint and fix\n```zsh\nyarn lint\n```\n\ncompile ts files\n```zsh\nyarn build\n```\n\nlaunch server\n```zsh\nyarn start\n```\n\n# Usage\n## GET request '/' with URL parameter\n\n```zsh\ncurl \"http://localhost:8080?url=http://example.com\" -o hcpdf-get.pdf\n```\n[hcpdf-get.pdf](/docs/pdf-samples/hcpdf-get.pdf)\n\n## POST request '/' with HTML parameter\n`html` parameter should be urlencoded beforehand, as the inclusion of certain characters (e.g. \"\u0026\") can cause problems.\n\n```zsh\ncurl -sS http://localhost:8080 -v \\\n  --data-urlencode html=\"\u003chtml\u003e\u003cp\u003ehcpdf \u003cstrong\u003eok\u003c/strong\u003e\u003c/p\u003e\u003c/html\u003e\"\\\n  -o hcpdf-post.pdf\n```\n[hcpdf-post.pdf](/docs/pdf-samples/hcpdf-post.pdf)\n\n# Customize PDF options by preset name\n\nThe Puppeteer's PDF options are flexible and complex.\n\nI thought about taking them directly as GET or POST parameters, but it's not simple.\n\nSo I make with the preset method.\n\nJust pass the preset name as request parameter `pdf_option` that you have prepared in `PDFOptionsPreset`.\n\nThe default presets are below.\n\n[src/pdf-options/presets/default.ts](src/pdf-options/presets/defaults.ts)\n\nYou can extend it or create another file and switch it by environment variables.\n\n```zsh\n# make file\ncp src/pdf-options/presets/my-preset.sample.ts src/pdf-options/presets/my-preset.ts\n\n# edit\nvim src/pdf-options/presets/my-preset.ts\n\n# build image\ndocker build -t hc-pdf-server:latest .\n\n# and set env example with dorcker run\ndocker run -it -p 8080:8080 \\\n  -e HCPDF_PRESET_PDF_OPTIONS_FILE_PATH='./presets/my-preset' \\\n  -e HCPDF_DEFAULT_PRESET_PDF_OPTIONS_NAME='MYA4' \\\n  hc-pdf-server:latest\n\n# request with pdf_option\ncurl \"http://localhost:8080?url=http://example.com\u0026pdf_option=MYA4\" -o hcpdf-get-MYA4.pdf\n```\n\nThe default is the minimum (e.g. A4, A3).\n\nIf you have something you think should be included, I'd be happy to receive a pull request.\n\nYou can check what options are currently available by looking at the following path after the server starts\n\n```zsh\n$ curl http://localhost:8080/pdf_options\n{\"A4\":{\"format\":\"A4\",\"margin\":{\"top\":\"10mm\",\"bottom\":\"10mm\",\"left\":\"10mm\",\"right\":\"10mm\"},\"printBackground\":true},\"A3\":{\"format\":\"A3\",\"margin\":{\"top\":\"10mm\",\"bottom\":\"10mm\",\"left\":\"10mm\",\"right\":\"10mm\"},\"printBackground\":true},\"A4L\":{\"format\":\"A4\",\"landscape\":true,\"margin\":{\"top\":\"10mm\",\"bottom\":\"10mm\",\"left\":\"10mm\",\"right\":\"10mm\"},\"printBackground\":true},\"A3L\":{\"format\":\"A3\",\"landscape\":true,\"margin\":{\"top\":\"10mm\",\"bottom\":\"10mm\",\"left\":\"10mm\",\"right\":\"10mm\"},\"printBackground\":true}}\n```\n\n\n# Bearer Authorization\nYou can enable bearer auth by setting your secret key to `HCPDF_BEARER_AUTH_SECRET_KEY` (default empty, disabled) .\n\nThis application can be exploited if it is published on a global network, as it allows you to manipulate Chrome.\n\nSo it is recommended that you enable this option to control access to it when you place it on a global network.\n\n```zsh\ndocker run -it -p 8080:8080 \\\n  -e HCPDF_BEARER_AUTH_SECRET_KEY='yourSecretKey' \\\n  hc-pdf-server:latest\n\ncurl \"http://localhost:8080/?url=http://example.com\" \\\n  -H 'Authorization: Bearer yourSecretKey' \\\n  -o hcpdf-auth-get.pdf\n```\n\nThis feature uses the following the plugin.\n\nDetails are below.\n\nhttps://github.com/fastify/fastify-bearer-auth\n\n# Support for concurrent access\n\nIn Puppeteer, if you make another request to `Page` during the PDF conversion process, it will result in an error.\n\nAt present, it seems not to be able to judge whether `Page` is being processed or not.\n\nTherefore, in hc-pdf-server, the error is avoided by preparing two or more `Page` at the time of server starting, and using them in order.\n\nThe number of starting pages can be changed by env `HCPDF_PAGES_NUM` (default: 3).\n\nIf you increase the number of pages, the memory required will also increase, so adjust it according to your machine resource.\n\n# Configuring with environment variables\nAll have a prefix of `'HCPDF_'`\n## PDF Options presets\nMultiple PDF Options can be prepared in advance and used upon request.\nsee detail about [PDF options](https://pptr.dev/#?product=Puppeteer\u0026version=v8.0.0\u0026show=api-pagepdfoptions)\n\n### HCPDF_PRESET_PDF_OPTIONS_FILE_PATH\nIf the default is not sufficient, please specify your own.\nSpecify relative path from `plugins/pdf-options.ts`\n\ndefault: '../pdf-options/presets/default'\n\n### HCPDF_DEFAULT_PRESET_PDF_OPTIONS_NAME\ndefalt key name.\n\ndefault: 'DEFAULT'\n\nYou can change the default items for simple changes such as size and margins\n\n### HCPDF_DEFAULT_PDF_OPTION_FORMAT\n\nCorresponds to `format`\n```\nLetter: 8.5in x 11in\nLegal: 8.5in x 14in\nTabloid: 11in x 17in\nLedger: 17in x 11in\nA0: 33.1in x 46.8in\nA1: 23.4in x 33.1in\nA2: 16.54in x 23.4in\nA3: 11.7in x 16.54in\nA4: 8.27in x 11.7in\nA5: 5.83in x 8.27in\nA6: 4.13in x 5.83in\n```\n\n### HCPDF_DEFAULT_PDF_OPTION_MARGIN\n\nCorresponds to all `margin`s\n\n### HCPDF_DEFAULT_PDF_OPTION_PRINT_BACKGROUND\nCorresponds `printBackground`\n\n### HCPDF_DEFAULT_PDF_OPTION_LANDSCAPE\nCorresponds to `landscape`\n\n## Page settings\n### HCPDF_PAGES_NUM\nAllows you to specify the number of pages to be launched when the server starts.\n\nChange the number according to the number of requests and the response speed and server resources.\n\ndefault: 3\n\n### HCPDF_USER_AGENT\nYou can change the User agent string.\n\ndefault: puppeteer's user agent\n\n### HCPDF_PAGE_TIMEOUT_MILLISECONDS\nTimeout values used in various Page operations.\nsee detail [Page.setDefaultTimeout()](https://pptr.dev/#?product=Puppeteer\u0026version=v8.0.0\u0026show=api-pagesetdefaulttimeouttimeout)\n\ndefault: 10000\n### HCPDF_EMULATE_MEDIA_TYPE_SCREEN_ENABLED\nif 'true', CSS media type set to `screen`\n\ndefault: false (`print`)\n\n### HCPDF_ACCEPT_LANGUAGE\nAccept-Language can be given at the time of request.\n\ndefault: ''\n## Server settings\n\n### HCPDF_SERVER_ADDRESS\n\ndefault: '127.0.0.1'\n\n### HCPDF_SERVER_PORT\n\ndefault: 8080\n\n### HCPDF_FASTIFY_BODY_LIMIT\nThe maximum request size that the server will accept.\n\ndefault: 10485760 (10MiB)\n\n### HCPDF_BEARER_AUTH_SECRET_KEY\nsee [Bearer Authorization](#bearer-authorization)\n\ndefault: '' (disabled)\n\n\n## Viewport\nsee [page.setViewport](https://pptr.dev/#?product=Puppeteer\u0026version=v8.0.0\u0026show=api-pagesetviewportviewport)\n### HCPDF_VIEWPORT_WIDTH\ndefault: 800\n### HCPDF_VIEWPORT_HEIGHT\ndefault: 600\n\n### HCPDF_DEVICE_SCALE_FACTOR\ndefault: 1\n\n### HCPDF_VIEWPORT_IS_MOBILE\ndefault: false\n\n### HCPDF_VIEWPORT_HAS_TOUCH\ndefault: false\n### HCPDF_VIEWPORT_IS_LANDSCAPE\ndefault: false\n\n## Browser Launch Options\n### HCEP_DEFAULT_BROWSER_LAUNCH_ARGS\n`args` of browser launch options. Comma separated string needed.\n\ndefault: '--no-sandbox,--disable-setuid-sandbox,--disable-gpu,--disable-dev-shm-usage'\n\nsee [puppeteer.launch](https://pptr.dev/#?product=Puppeteer\u0026version=v13.5.2\u0026show=api-puppeteerlaunchoptions)\n\n## Others\nOther settings can be changed by environment variables.\n\nSee the following file for details.\n\n[src/config.ts](src/config.ts)\n\n# Test\n\n## Local\n\n```zsh\nyarn test\n```\n\n### Result example\n![test result example](docs/img/test-result.png)\n\n\n## Docker\n\n```zsh\n# before you need build image\ndocker build -t hc-pdf-server:latest .\n\ndocker run hc-pdf-server:latest yarn test\n```\n# License\nLicensed under [Apache License](LICENSE)\n\n# Contributing\nPull requests, Issues, [GitHub Sponsors](https://github.com/sponsors/uyamazak/) are welcome.\n\n# Contributors ✨\nThanks!\n\n- [salos1982](https://github.com/salos1982)\n\n# Author\n[uyamazak](https://github.com/uyamazak)\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuyamazak%2Fhc-pdf-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuyamazak%2Fhc-pdf-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuyamazak%2Fhc-pdf-server/lists"}