z0rs
/
chromium
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Cleanup docs

This commit is contained in:
Sparticuz 2023-03-27 11:40:18 -04:00
parent 47dc5aef53
commit 665283328a
1 changed files with 37 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
README.md
View File

@ -1,24 +1,21 @@
# @sparticuz/chromium # @sparticuz/chromium
[![@sparticuz/chromium](https://img.shields.io/npm/v/@sparticuz/chromium.svg?style=for-the-badge)](https://www.npmjs.com/package/@sparticuz/chromium) [![@sparticuz/chromium](https://img.shields.io/npm/v/@sparticuz/chromium.svg?style=for-the-badge)](https://www.npmjs.com/package/@sparticuz/chromium)
[![TypeScript](https://img.shields.io/npm/types/chrome-aws-lambda?style=for-the-badge)](https://www.typescriptlang.org/dt/search?search=chromium) [![Chromium](https://img.shields.io/github/size/sparticuz/chromium/bin/chromium.br?label=Chromium&style=for-the-badge)](bin/)
[![Chromium](https://img.shields.io/badge/chromium-51_MB-brightgreen.svg?style=for-the-badge)](bin/) [![npm](https://img.shields.io/npm/dw/@sparticuz/chromium?label=%40sparticuz%2Fchromium&style=for-the-badge)](https://www.npmjs.com/package/@sparticuz/chromium)
[![npm](https://img.shields.io/npm/dw/@sparticuz/chromium-min?label=%40sparticuz%2Fchromium-min&style=for-the-badge)](https://www.npmjs.com/package/@sparticuz/chromium-min)
[![Donate](https://img.shields.io/badge/donate-paypal-orange.svg?style=for-the-badge)](https://paypal.me/sparticuz) [![Donate](https://img.shields.io/badge/donate-paypal-orange.svg?style=for-the-badge)](https://paypal.me/sparticuz)
## Chromium for Serverless platforms ## Chromium for Serverless platforms
This package was originally forked from [alixaxel/chrome-aws-lambda#264](https://github.com/alixaxel/chrome-aws-lambda/pull/264). [sparticuz/chrome-aws-lambda](https://github.com/sparticuz/chrome-aws-lambda) was originally forked from [alixaxel/chrome-aws-lambda#264](https://github.com/alixaxel/chrome-aws-lambda/pull/264).
The biggest difference, besides the chromium version, is the inclusion of some code from https://github.com/alixaxel/lambdafs, The biggest difference, besides the chromium version, is the inclusion of some code from https://github.com/alixaxel/lambdafs, as well as dropping that as a dependency. Due to some changes in WebGL, the files in bin/swiftshader.tar.br need to be extracted to `/tmp` instead of `/tmp/swiftshader`. This necessitated changes in lambdafs.
as well as dropping that as a dependency. Due to some changes in WebGL, the files in bin/swiftshader.tar.br need to
be extracted to `/tmp` instead of `/tmp/swiftshader`. This necessitated changes in lambdafs.
However, it quickly became difficult to maintain because of the pace of `puppeteer` updates. This package, `@sparticuz/chromium`, However, it quickly became difficult to maintain because of the pace of `puppeteer` updates. This package, `@sparticuz/chromium`, is not chained to `puppeteer` versions, but also does not include the overrides and hooks that the original package contained. It is only `chromium`, as well as the special code needed to decompress the brotli package, and a set of predefined arguments tailored to serverless usage.
is not chained to `puppeteer` versions, but also does not include the overrides and hooks that the original package contained. It is only `chromium`, as well as the special code needed to decompress the brotli package.
## Install ## Install
[`puppeteer` ships with a prefered version of `chromium`](https://pptr.dev/faq/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy). [`puppeteer` ships with a prefered version of `chromium`](https://pptr.dev/faq/#q-why-doesnt-puppeteer-vxxx-work-with-chromium-vyyy). In order to figure out what version of `@sparticuz/chromium` you will need, please visit [Puppeteer's Chromium Support page](https://pptr.dev/chromium-support).
In order to figure out what version of `@sparticuz/chromium` you will need, please visit [Puppeteer's Chromium Support page](https://pptr.dev/chromium-support).
> For example, as of today, the latest version of `puppeteer` is `18.0.5`. The latest version of `chromium` stated on `puppeteer`'s support page is `106.0.5249.0`. So you need to install `@sparticuz/chromium@106`. > For example, as of today, the latest version of `puppeteer` is `18.0.5`. The latest version of `chromium` stated on `puppeteer`'s support page is `106.0.5249.0`. So you need to install `@sparticuz/chromium@106`.
@ -30,6 +27,7 @@ npm install --save-dev @sparticuz/chromium@$CHROMIUM_VERSION
``` ```
If your vendor does not allow large deploys (`chromium.br` is 50+ MB), you'll need to host the `chromium-v#-pack.tar` separatly and use the [`@sparticuz/chromium-min` package](https://github.com/Sparticuz/chromium#-min-package). If your vendor does not allow large deploys (`chromium.br` is 50+ MB), you'll need to host the `chromium-v#-pack.tar` separatly and use the [`@sparticuz/chromium-min` package](https://github.com/Sparticuz/chromium#-min-package).
```shell ```shell
npm install --save @sparticuz/chromium-min@$CHROMIUM_VERSION npm install --save @sparticuz/chromium-min@$CHROMIUM_VERSION
``` ```
@ -41,6 +39,8 @@ If you wish to install an older version of Chromium, take a look at [@sparticuz/
The @sparticuz/chromium version schema is as follows: The @sparticuz/chromium version schema is as follows:
`MajorChromiumVersion.MinorChromiumIncrement.@Sparticuz/chromiumPatchLevel` `MajorChromiumVersion.MinorChromiumIncrement.@Sparticuz/chromiumPatchLevel`
Beacuse this package follows Chromium's releases, it does NOT follow semantic versioning. **Breaking changes can occur with the 'patch' level.** Please check the release notes for information on breaking changes.
## Usage ## Usage
This package works with all the currently supported AWS Lambda Node.js runtimes out of the box. This package works with all the currently supported AWS Lambda Node.js runtimes out of the box.
@ -56,7 +56,6 @@ test("Check the page title of example.com", async (t) => {
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath(), executablePath: await chromium.executablePath(),
headless: chromium.headless, headless: chromium.headless,
ignoreHTTPSErrors: true,
}); });
const page = await browser.newPage(); const page = await browser.newPage();
@ -73,8 +72,8 @@ test("Check the page title of example.com", async (t) => {
```javascript ```javascript
const test = require("node:test"); const test = require("node:test");
// Need to rename playwright's chromium object to something else // Need to rename playwright's chromium object to something else
const { chromium: playwright } = require('playwright-core'); const { chromium: playwright } = require("playwright-core");
const chromium = require('@sparticuz/chromium'); const chromium = require("@sparticuz/chromium");
test("Check the page title of example.com", async (t) => { test("Check the page title of example.com", async (t) => {
const browser = await playwright.launch({ const browser = await playwright.launch({
@ -92,18 +91,19 @@ test("Check the page title of example.com", async (t) => {
assert.strictEqual(pageTitle, "Example Domain"); assert.strictEqual(pageTitle, "Example Domain");
}); });
``` ```
You should allocate at least 512 MB of RAM to your Lambda, however 1600 MB (or more) is recommended.
You should allocate at least 512 MB of RAM to your instance, however 1600 MB (or more) is recommended.
### -min package ### -min package
The -min package DOES NOT include the chromium brotli files. There are a few instances where this The -min package DOES NOT include the chromium brotli files. There are a few instances where this is useful. Primarily, this is useful when your host has file size limits.
is useful. Primarily, this is useful when you have file size limits.
To use the -min package please install the `@sparticuz/chromium-min` package. To use the -min package please install the `@sparticuz/chromium-min` package.
When using the -min package, you need to specify the location of the brotli files. When using the -min package, you need to specify the location of the brotli files.
In this example, /opt/chromium contains all the brotli files In this example, /opt/chromium contains all the brotli files
``` ```
/opt /opt
/chromium /chromium
@ -111,22 +111,19 @@ In this example, /opt/chromium contains all the brotli files
/chromium.br /chromium.br
/swiftshader.tar.br /swiftshader.tar.br
``` ```
```javascript ```javascript
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: chromium.args, args: chromium.args,
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath("/opt/chromium"), executablePath: await chromium.executablePath("/opt/chromium"),
headless: chromium.headless, headless: chromium.headless,
ignoreHTTPSErrors: true,
}); });
``` ```
In the following example, https://www.example.com/chromiumPack.tar contains all the brotli files.
Generally, this would be a location on S3, or another very fast downloadable location,
that is close to your function's execution location.
@sparticuz/chromium will download the pack tar file, untar the files to /tmp/chromium-pack, In the following example, https://www.example.com/chromiumPack.tar contains all the brotli files. Generally, this would be a location on S3, or another very fast downloadable location, that is in close proximity to your function's execution location.
then will un-brotli the files to /tmp/chromium. The next iteration will have /tmp/chromium exist
and will use the already downloaded files. On the initial iteration, `@sparticuz/chromium` will download the pack tar file, untar the files to `/tmp/chromium-pack`, then will un-brotli the `chromium` binary to `/tmp/chromium`. The following iterations will see that `/tmp/chromium` exists and will use the already downloaded files.
The latest chromium-pack.tar file will be on the latest [release](https://github.com/Sparticuz/chromium/releases). The latest chromium-pack.tar file will be on the latest [release](https://github.com/Sparticuz/chromium/releases).
@ -134,18 +131,21 @@ The latest chromium-pack.tar file will be on the latest [release](https://github
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: chromium.args, args: chromium.args,
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath("https://www.example.com/chromiumPack.tar"), executablePath: await chromium.executablePath(
"https://www.example.com/chromiumPack.tar"
),
headless: chromium.headless, headless: chromium.headless,
ignoreHTTPSErrors: true,
}); });
``` ```
### Examples ### Examples
Here are some example projects and help with other services Here are some example projects and help with other services
- [Production Dependency](https://github.com/Sparticuz/chromium/tree/master/examples/production-dependency) - [Production Dependency](https://github.com/Sparticuz/chromium/tree/master/examples/production-dependency)
- [Serverless Framework with Lambda Layer](https://github.com/Sparticuz/chromium/tree/master/examples/serverless-with-lambda-layer) - [Serverless Framework with Lambda Layer](https://github.com/Sparticuz/chromium/tree/master/examples/serverless-with-lambda-layer)
- [Chromium-min](https://github.com/Sparticuz/chromium/tree/master/examples/remote-min-binary) - [Chromium-min](https://github.com/Sparticuz/chromium/tree/master/examples/remote-min-binary)
- AWS SAM *TODO* - AWS SAM _TODO_
- [Webpack](https://github.com/Sparticuz/chromium/issues/24#issuecomment-1343196897) - [Webpack](https://github.com/Sparticuz/chromium/issues/24#issuecomment-1343196897)
- [Netlify](https://github.com/Sparticuz/chromium/issues/24#issuecomment-1414107620) - [Netlify](https://github.com/Sparticuz/chromium/issues/24#issuecomment-1414107620)
@ -165,20 +165,22 @@ This package will run in headless mode when `NODE_ENV = "test"`. If you want to
## Fonts ## Fonts
The Amazon Linux 2 AWS Lambda runtime is no longer provisioned with any font faces. The Amazon Linux 2 AWS Lambda runtime is not provisioned with any font faces.
Because of this, this package ships with [Open Sans](https://fonts.google.com/specimen/Open+Sans), which supports the following scripts: Because of this, this package ships with [Open Sans](https://fonts.google.com/specimen/Open+Sans), which supports the following scripts:
* Latin - Latin
* Greek - Greek
* Cyrillic - Cyrillic
To provision additional fonts, simply call the `font()` method with an absolute path or URL: To provision additional fonts, simply call the `font()` method with an absolute path or URL:
```typescript ```typescript
await chromium.font('/var/task/fonts/NotoColorEmoji.ttf'); await chromium.font("/var/task/fonts/NotoColorEmoji.ttf");
// or // or
await chromium.font('https://raw.githack.com/googlei18n/noto-emoji/master/fonts/NotoColorEmoji.ttf'); await chromium.font(
"https://raw.githack.com/googlei18n/noto-emoji/master/fonts/NotoColorEmoji.ttf"
);
``` ```
> `Noto Color Emoji` (or similar) is needed if you want to [render emojis](https://getemoji.com/). > `Noto Color Emoji` (or similar) is needed if you want to [render emojis](https://getemoji.com/).
@ -223,6 +225,7 @@ make chromium.zip
``` ```
The above will create a `chromium.zip` file, which can be uploaded to your Layers console. You can and should upload using the `aws cli`. (Replace the variables with your own values) The above will create a `chromium.zip` file, which can be uploaded to your Layers console. You can and should upload using the `aws cli`. (Replace the variables with your own values)
```shell ```shell
bucketName="chromiumUploadBucket" && \ bucketName="chromiumUploadBucket" && \
versionNumber="107" && \ versionNumber="107" && \
@ -240,6 +243,7 @@ According to our benchmarks, it's 40% to 50% faster than using the off-the-shelf
- Add the import or require for `puppeteer-core` - Add the import or require for `puppeteer-core`
- Change the browser launch to use the native `puppeteer.launch()` function - Change the browser launch to use the native `puppeteer.launch()` function
- Change the `executablePath` to be a function. - Change the `executablePath` to be a function.
```diff ```diff
-const chromium = require('@sparticuz/chrome-aws-lambda'); -const chromium = require('@sparticuz/chrome-aws-lambda');
+const chromium = require("@sparticuz/chromium"); +const chromium = require("@sparticuz/chromium");
@ -276,6 +280,7 @@ exports.handler = async (event, context, callback) => {
return callback(null, result); return callback(null, result);
}; };
``` ```
## Compression ## Compression
The Chromium binary is compressed using the Brotli algorithm. The Chromium binary is compressed using the Brotli algorithm.