Cleanup docs
This commit is contained in:
Sparticuz
parent
47dc5aef53
commit
665283328a
69
README.md
69
README.md
|
|
@ -1,24 +1,21 @@
|
|||
# @sparticuz/chromium
|
||||
|
||||
[](https://www.npmjs.com/package/@sparticuz/chromium)
|
||||
[](https://www.typescriptlang.org/dt/search?search=chromium)
|
||||
[](bin/)
|
||||
[](bin/)
|
||||
[](https://www.npmjs.com/package/@sparticuz/chromium)
|
||||
[](https://www.npmjs.com/package/@sparticuz/chromium-min)
|
||||
[](https://paypal.me/sparticuz)
|
||||
|
||||
## Chromium for Serverless platforms
|
||||
|
||||
This package 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,
|
||||
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.
|
||||
[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, 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`,
|
||||
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.
|
||||
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.
|
||||
|
||||
## Install
|
||||
|
||||
[`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).
|
||||
[`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).
|
||||
|
||||
> 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).
|
||||
|
||||
```shell
|
||||
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:
|
||||
`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
|
||||
|
||||
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,
|
||||
executablePath: await chromium.executablePath(),
|
||||
headless: chromium.headless,
|
||||
ignoreHTTPSErrors: true,
|
||||
});
|
||||
|
||||
const page = await browser.newPage();
|
||||
|
|
@ -73,8 +72,8 @@ test("Check the page title of example.com", async (t) => {
|
|||
```javascript
|
||||
const test = require("node:test");
|
||||
// Need to rename playwright's chromium object to something else
|
||||
const { chromium: playwright } = require('playwright-core');
|
||||
const chromium = require('@sparticuz/chromium');
|
||||
const { chromium: playwright } = require("playwright-core");
|
||||
const chromium = require("@sparticuz/chromium");
|
||||
|
||||
test("Check the page title of example.com", async (t) => {
|
||||
const browser = await playwright.launch({
|
||||
|
|
@ -92,18 +91,19 @@ test("Check the page title of example.com", async (t) => {
|
|||
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
|
||||
|
||||
The -min package DOES NOT include the chromium brotli files. There are a few instances where this
|
||||
is useful. Primarily, this is useful when you have file size limits.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
In this example, /opt/chromium contains all the brotli files
|
||||
|
||||
```
|
||||
/opt
|
||||
/chromium
|
||||
|
|
@ -111,22 +111,19 @@ In this example, /opt/chromium contains all the brotli files
|
|||
/chromium.br
|
||||
/swiftshader.tar.br
|
||||
```
|
||||
|
||||
```javascript
|
||||
const browser = await puppeteer.launch({
|
||||
args: chromium.args,
|
||||
defaultViewport: chromium.defaultViewport,
|
||||
executablePath: await chromium.executablePath("/opt/chromium"),
|
||||
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,
|
||||
then will un-brotli the files to /tmp/chromium. The next iteration will have /tmp/chromium exist
|
||||
and will use the already downloaded files.
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
|
|
@ -134,18 +131,21 @@ The latest chromium-pack.tar file will be on the latest [release](https://github
|
|||
const browser = await puppeteer.launch({
|
||||
args: chromium.args,
|
||||
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,
|
||||
ignoreHTTPSErrors: true,
|
||||
});
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
Here are some example projects and help with other services
|
||||
|
||||
- [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)
|
||||
- [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)
|
||||
- [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
|
||||
|
||||
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:
|
||||
|
||||
* Latin
|
||||
* Greek
|
||||
* Cyrillic
|
||||
- Latin
|
||||
- Greek
|
||||
- Cyrillic
|
||||
|
||||
To provision additional fonts, simply call the `font()` method with an absolute path or URL:
|
||||
|
||||
```typescript
|
||||
await chromium.font('/var/task/fonts/NotoColorEmoji.ttf');
|
||||
await chromium.font("/var/task/fonts/NotoColorEmoji.ttf");
|
||||
// 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/).
|
||||
|
|
@ -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)
|
||||
|
||||
```shell
|
||||
bucketName="chromiumUploadBucket" && \
|
||||
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`
|
||||
- Change the browser launch to use the native `puppeteer.launch()` function
|
||||
- Change the `executablePath` to be a function.
|
||||
|
||||
```diff
|
||||
-const chromium = require('@sparticuz/chrome-aws-lambda');
|
||||
+const chromium = require("@sparticuz/chromium");
|
||||
|
|
@ -276,6 +280,7 @@ exports.handler = async (event, context, callback) => {
|
|||
return callback(null, result);
|
||||
};
|
||||
```
|
||||
|
||||
## Compression
|
||||
|
||||
The Chromium binary is compressed using the Brotli algorithm.
|
||||
|
|
|
|||
Loading…
Reference in New Issue