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

cleanup readme

This commit is contained in:
Kyle McNally 2024-04-15 11:30:32 -04:00
parent 636fa64bfa
commit e96aadfaf8
1 changed files with 32 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.md
View File

@ -11,7 +11,7 @@
[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). [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. 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, and a set of predefined arguments tailored to serverless usage. 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 an additional set of predefined arguments tailored to serverless usage.
## Install ## Install
@ -50,11 +50,6 @@ const test = require("node:test");
const puppeteer = require("puppeteer-core"); const puppeteer = require("puppeteer-core");
const chromium = require("@sparticuz/chromium"); const chromium = require("@sparticuz/chromium");
// Optional: If you'd like to use the new headless mode. "shell" is the default.
// NOTE: Because we build the shell binary, this option does not work.
// However, this option will stay so when we migrate to full chromium it will work.
chromium.setHeadlessMode = true;
// Optional: If you'd like to disable webgl, true is the default. // Optional: If you'd like to disable webgl, true is the default.
chromium.setGraphicsMode = false; chromium.setGraphicsMode = false;
@ -65,10 +60,13 @@ await chromium.font(
test("Check the page title of example.com", async (t) => { test("Check the page title of example.com", async (t) => {
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: chromium.args, args: puppeteer.defaultArgs({
args: chromium.args,
headless: "shell",
}),
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath(), executablePath: await chromium.executablePath(),
headless: chromium.headless, headless: "shell",
}); });
const page = await browser.newPage(); const page = await browser.newPage();
@ -127,10 +125,13 @@ In this example, /opt/chromium contains all the brotli files
```javascript ```javascript
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: chromium.args, args: puppeteer.defaultArgs({
args: chromium.args,
headless: "shell",
}),
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath("/opt/chromium"), executablePath: await chromium.executablePath("/opt/chromium"),
headless: chromium.headless, headless: "shell",
}); });
``` ```
@ -142,12 +143,15 @@ The latest chromium-pack.tar file will be on the latest [release](https://github
```javascript ```javascript
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: chromium.args, args: puppeteer.defaultArgs({
args: chromium.args,
headless: "shell",
}),
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: await chromium.executablePath( executablePath: await chromium.executablePath(
"https://www.example.com/chromiumPack.tar" "https://www.example.com/chromiumPack.tar"
), ),
headless: chromium.headless, headless: "shell",
}); });
``` ```
@ -177,12 +181,12 @@ For example, you can set your code to use an ENV variable such as `IS_LOCAL`, th
```javascript ```javascript
const browser = await puppeteer.launch({ const browser = await puppeteer.launch({
args: process.env.IS_LOCAL ? puppeteer.defaultArgs() : chromium.args, args: process.env.IS_LOCAL ? puppeteer.defaultArgs() : puppeteer.defaultArgs({args:chromium.args, process.env.IS_LOCAL ? false : "shell"}),
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
executablePath: process.env.IS_LOCAL executablePath: process.env.IS_LOCAL
? "/tmp/localChromium/chromium/linux-1122391/chrome-linux/chrome" ? "/tmp/localChromium/chromium/linux-1122391/chrome-linux/chrome"
: await chromium.executablePath(), : await chromium.executablePath(),
headless: process.env.IS_LOCAL ? false : chromium.headless, headless: process.env.IS_LOCAL ? false : "shell",
}); });
``` ```
@ -294,20 +298,20 @@ zip -9 --filesync --move --recurse-paths fonts.zip fonts/
## Graphics ## Graphics
NOTE: Disabling the Graphics stack is currently broken, causing Chromium to crash repeadly. For now, even if you `setGraphicsMode=false`, this package will set it to `true`.
By default, this package uses `swiftshader`/`angle` to do CPU acceleration for WebGL. This is the only known way to enable WebGL on a serverless platform. You can disable WebGL by setting `chromium.setGraphiceMode = false;` _before_ launching Chromium. Disabling this will also skip the extract of the `bin/swiftshader.tar.br` file, which saves about a second of initial execution time. Disabling graphics is recommended if you know you are not using any WebGL. By default, this package uses `swiftshader`/`angle` to do CPU acceleration for WebGL. This is the only known way to enable WebGL on a serverless platform. You can disable WebGL by setting `chromium.setGraphiceMode = false;` _before_ launching Chromium. Disabling this will also skip the extract of the `bin/swiftshader.tar.br` file, which saves about a second of initial execution time. Disabling graphics is recommended if you know you are not using any WebGL.
## API ## API
| Method / Property | Returns | Description | | Method / Property | Returns | Description |
| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | ----------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `font(url)` | `Promise<string>` | Provisions a custom font and returns its basename. | | `font(url)` | `Promise<string>` | Provisions a custom font and returns its basename. |
| `args` | `Array<string>` | Provides a list of recommended additional [Chromium flags](https://github.com/GoogleChrome/chrome-launcher/blob/master/docs/chrome-flags-for-tools.md). | | `args` | `Array<string>` | Provides a list of recommended additional [Chromium flags](https://github.com/GoogleChrome/chrome-launcher/blob/master/docs/chrome-flags-for-tools.md) that are specific to running in Lambda. |
| `defaultViewport` | `Object` | Returns a sensible default viewport for serverless. | | `defaultViewport` | `Object` | Returns a sensible default viewport for serverless. |
| `executablePath(location?: string)` | `Promise<string>` | Returns the path the Chromium binary was extracted to. | | `executablePath(location?: string)` | `Promise<string>` | Returns the path the Chromium binary was extracted to. |
| `setHeadlessMode` | `void` | Sets the headless mode to either `true` or `"shell"` | | `setGraphicsMode` | `void` | Sets the graphics mode to either `true` or `false` |
| `headless` | `true \| "shell"` | Returns `true` or `"shell"` depending on what version of chrome's headless you are running | | `graphics` | `boolean` | Returns a boolean depending on whether webgl is enabled or disabled |
| `setGraphicsMode` | `void` | Sets the graphics mode to either `true` or `false` |
| `graphics` | `boolean` | Returns a boolean depending on whether webgl is enabled or disabled |
## Compiling ## Compiling
@ -357,11 +361,13 @@ exports.handler = async (event, context, callback) => {
try { try {
- browser = await chromium.puppeteer.launch({ - browser = await chromium.puppeteer.launch({
+ browser = await puppeteer.launch({ + browser = await puppeteer.launch({
args: chromium.args, - args: chromium.args,
+ args: puppeteer.defaultArgs({ args: chromium.args, headless: "shell" }),
defaultViewport: chromium.defaultViewport, defaultViewport: chromium.defaultViewport,
- executablePath: await chromium.executablePath, - executablePath: await chromium.executablePath,
+ executablePath: await chromium.executablePath(), + executablePath: await chromium.executablePath(),
headless: chromium.headless, - headless: chromium.headless,
+ headless: "shell",
ignoreHTTPSErrors: true, ignoreHTTPSErrors: true,
}); });