From 2de5a42d1f20b5c9719c8c5506fd772d73d7ec70 Mon Sep 17 00:00:00 2001 From: Andrey Lushnikov Date: Tue, 4 Sep 2018 17:32:57 +0100 Subject: [PATCH] docs(api.md): expand on puppeteer-core vs puppeteer (#3189) --- README.md | 2 ++ docs/api.md | 24 ++++++++++++++++++++++++ 2 files changed, 26 insertions(+) diff --git a/README.md b/README.md index 2942d4d33fc..cd8c42a7bdb 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,8 @@ npm i puppeteer-core `puppeteer-core` is intended to be a lightweight version of puppeteer for launching an existing browser installation or for connecting to a remote one. +See [puppeteer vs puppeteer-core](https://github.com/GoogleChrome/puppeteer/blob/v1.7.0/docs/api.md#puppeteer-vs-puppeteer-core). + ### Usage Note: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater. diff --git a/docs/api.md b/docs/api.md index 985915f2c40..e0762c2b3a0 100644 --- a/docs/api.md +++ b/docs/api.md @@ -17,6 +17,7 @@ - [Overview](#overview) +- [puppeteer vs puppeteer-core](#puppeteer-vs-puppeteer-core) - [Environment Variables](#environment-variables) - [Error handling](#error-handling) - [Working with Chrome Extensions](#working-with-chrome-extensions) @@ -313,6 +314,29 @@ The Puppeteer API is hierarchical and mirrors the browser structure. (Diagram source: [link](https://docs.google.com/drawings/d/1Q_AM6KYs9kbyLZF-Lpp5mtpAWth73Cq8IKCsWYgi8MM/edit?usp=sharing)) +### puppeteer vs puppeteer-core + +Every release since v1.7.0 we publish two packages: +- [puppeteer](https://www.npmjs.com/package/puppeteer) +- [puppeteer-core](https://www.npmjs.com/package/puppeteer-core) + +`puppeteer` is a *product* for browser automation. When installed, it downloads a version of +Chromium, which it then drives using `puppeteer-core`. Being an end-user product, `puppeteer` supports a bunch of convenient `PUPPETEER_*` env variables to tweak its behavior. + +`puppetee-core` is a *library* to help drive anything that supports DevTools protocol. `puppeteer-core` doesn't download Chromium when installed. Being a library, `puppeteer-core` is fully driven +through its programmatic interface and disregards all the `PUPPETEER_*` env variables. + +To sum up, the only differences between `puppeteer-core` and `puppeteer` are: +- `puppeteer-core` doesn't automatically download Chromium when installed. +- `puppeteer-core` ignores all `PUPPETEER_*` env variables. + +In most cases, you'll be fine using the `puppeteer` package. + +However, you should use `puppeteer-core` if: +- you're building another end-user product or library atop of DevTools protocol. For example, one might build PDF generator using `puppeteer-core` and write a custom `install.js` script that downloads [`headless_shell`](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) instead of Chromium to save disk space. +- you're bundling Puppeteer to use in Chrome Extension / browser with the DevTools protocol where downloading an additional Chromium binary is unnecessary. + + ### Environment Variables Puppeteer looks for certain [environment variables](https://en.wikipedia.org/wiki/Environment_variable) to aid its operations.