• Font size
  • Line height
  • Font

    • Migrate to astro-pdf v2

    Breaking changes

    Removed ensurePath page option

    In v1, when trying to generate a PDF with a filename which already exists, astro-pdf would add a counter suffix to the end of the filename (e.g. xxx-1.pdf) to handle the conflicting filename. However, this can lead to unexpected behaviour as pages are processed in parallel, meaning the suffix could be different between builds. This dynamic filename behaviour makes it difficult to link to the generated files, which is why it was recommended to set ensurePath to true, which disables the suffix behaviour.

    In v2, ensurePath has been removed, and the default (and only) behaviour now is the same as ensurePath: true. If trying to output a file with a filename which already exists, the page will fail with a ‘file already exists’ error.

    Removed install option

    In v1, astro-pdf would check the executable path specified in the Puppeteer configuration, and if the executable was not found, it would try to install the latest stable version of Chrome for Testing (which may not be the same as the pinned version which the installed version of Puppeteer installs by default). This would make it difficult to do a custom browser installation without astro-pdf also installing a browser.

    As such, in v2, astro-pdf will no longer handle the installation of browsers, and instead leaves the task to the user.

    What should I do?

    To use any custom browser, install the browser yourself and pass the browser and executablePath to the launch option.

    // https://astro.build/configexport default defineConfig({    integrations: [        pdf({            install: true,             launch: {                // the browser (eg 'chrome') and executable path of the installed browser.                browser: '...',                 executablePath: '...'            }        })    ]})

    In order to prevent Puppeteer from installing a browser automatically, you may also want to set skipDownload in the Puppeteer configuration, or set the PUPPETEER_SKIP_DOWNLOAD environment variable.

    // .puppeteerrc.jsexport default {    skipDownload: true}

    For most cases, the version of Chrome which Puppeteer automatically installs in its postinstall script (or by running npx puppeteer browsers install) can be used without having to do any other configuration. If you wish to recreate the behaviour of the removed install option, you can install the @puppeteer/browsers package.

    import { install, resolveBuildId, Browser, detectBrowserPlatform } from '@puppeteer/browsers'const platform = detectBrowserPlatform()if (platform) {    const buildId = await resolveBuildId(Browser.CHROME, platform, 'stable')    const installed = await install(buildId)    console.log(installed.browser, installed.executablePath)}

    Increased minimum node version

    The minimum version of node supported by astro-pdf has been increased to 22.12.0. This is the same as the minimum version requirements for Astro 6+ and Puppeteer 25+.

    What should I do?

    Check your node version by running node -v. If it is less than 22.12.0, download a newer version of node using a version manager or from the official installers. See the Node.js migration guides.