docs: puppeteer

sst · Sep 4, 2024 · bb32026 · bb32026
1 parent 905f587
commit bb32026
Show file tree

Hide file tree

Showing 7 changed files with 292 additions and 6 deletions.
diff --git a/examples/aws-puppeteer/.gitignore b/examples/aws-puppeteer/.gitignore
@@ -0,0 +1,3 @@
+
+# sst
+.sst
diff --git a/examples/aws-puppeteer/index.ts b/examples/aws-puppeteer/index.ts
@@ -0,0 +1,42 @@
+import puppeteer from "puppeteer-core";
+import chromium from "@sparticuz/chromium";
+
+// This is the path to the local Chromium binary
+const YOUR_LOCAL_CHROMIUM_PATH = "/tmp/localChromium/chromium/mac_arm-1350406/chrome-mac/Chromium.app/Contents/MacOS/Chromium";
+
+export async function handler() {
+  const url = "https://sst.dev";
+  const width = 1024;
+  const height = 768;
+
+  const browser = await puppeteer.launch({
+    args: chromium.args,
+    defaultViewport: chromium.defaultViewport,
+    executablePath: process.env.SST_LIVE
+      ? YOUR_LOCAL_CHROMIUM_PATH
+      : await chromium.executablePath(),
+    headless: chromium.headless,
+  });
+
+  const page = await browser.newPage();
+
+  await page.setViewport({
+    width: width,
+    height: height,
+  });
+
+  await page.goto(url!);
+
+  const screenshot = (await page.screenshot({ encoding: "base64" })) as string;
+
+  return {
+    statusCode: 200,
+    body: screenshot,
+    isBase64Encoded: true,
+    headers: {
+      "Content-Type": "image/png",
+      "Content-Disposition": "inline"
+    },
+  };
+}
+
diff --git a/examples/aws-puppeteer/package.json b/examples/aws-puppeteer/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "aws-puppeteer",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@sparticuz/chromium": "^127.0.0",
+    "puppeteer-core": "^23.1.1",
+    "sst": "latest"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "8.10.145"
+  }
+}
diff --git a/examples/aws-puppeteer/sst.config.ts b/examples/aws-puppeteer/sst.config.ts
@@ -0,0 +1,108 @@
+/// <reference path="./.sst/platform/config.d.ts" />
+
+/**
+ * ## Puppeteer in Lambda
+ *
+ * To use Puppeteer in a Lambda function you need:
+ *
+ * 1. [`puppeteer-core`](https://www.npmjs.com/package/puppeteer-core)
+ * 2. Chromium
+ *    - In `sst dev`, we'll use a locally installed Chromium version.
+ *    - In `sst deploy`, we'll use the [`@sparticuz/chromium`](https://github.com/sparticuz/chromium) package. It comes with a pre-built binary for Lambda.
+ *
+ * #### Chromium version
+ *
+ * Since Puppeteer has a preferred version of Chromium, we'll need to check the version of
+ * Chrome that a given version of Puppeteer supports. Head over to the
+ * [Puppeteer's Chromium Support page](https://pptr.dev/chromium-support) and check which
+ * versions work together.
+ *
+ * For example, Puppeteer v23.1.1 supports Chrome for Testing 127.0.6533.119. So, we'll use the
+ * v127 of `@sparticuz/chromium`.
+ *
+ * ```bash
+ * npm install [email protected] @sparticuz/[email protected]
+ * ```
+ *
+ * #### Install Chromium locally
+ *
+ * To use this locally, you'll need to install Chromium.
+ *
+ * ```bash
+ * npx @puppeteer/browsers install chromium@latest --path /tmp/localChromium
+ * ```
+ *
+ * Once installed you'll see the location of the Chromium binary.
+ *
+ * ```bash
+ * chromium@1350406 /tmp/localChromium/chromium/mac_arm-1350406/chrome-mac/Chromium.app/Contents/MacOS/Chromium
+ * ```
+ *
+ * Next, update this in your Lambda function.
+ *
+ * ```ts title="index.ts"
+ * // This is the path to the local Chromium binary
+ * const YOUR_LOCAL_CHROMIUM_PATH = "/tmp/localChromium/chromium/mac_arm-1350406/chrome-mac/Chromium.app/Contents/MacOS/Chromium";
+ * ```
+ *
+ * You'll notice we are using the right binary with the `SST_LIVE` environment variable.
+ *
+ * ```ts title="index.ts" {4-6}
+ * const browser = await puppeteer.launch({
+ *   args: chromium.args,
+ *   defaultViewport: chromium.defaultViewport,
+ *   executablePath: process.env.SST_LIVE
+ *     ? YOUR_LOCAL_CHROMIUM_PATH
+ *     : await chromium.executablePath(),
+ *   headless: chromium.headless,
+ * });
+ * ```
+ *
+ * #### Deploy
+ *
+ * We don't need a layer to deploy this because `@sparticuz/chromium` comes with a pre-built
+ * binary for Lambda.
+ *
+ * :::note
+ * As of writing this, `arm64` is not supported by `@sparticuz/chromium`.
+ * :::
+ *
+ * We just need to set it in the [`nodejs.install`](/docs/component/aws/function#nodejs-install).
+ *
+ * ```ts title="sst.config.ts"
+ * {
+ *   nodejs: {
+ *     install: ["@sparticuz/chromium"]
+ *   }
+ * }
+ * ```
+ *
+ * And on deploy, SST will use the right binary.
+ *
+ * We are giving our function more memory and a longer timeout since running Puppeteer can
+ * take a while.
+ */
+export default $config({
+  app(input) {
+    return {
+      name: "aws-puppeteer",
+      removal: input?.stage === "production" ? "retain" : "remove",
+      home: "aws",
+    };
+  },
+  async run() {
+    const api = new sst.aws.Function("MyFunction", {
+      url: true,
+      memory: "2 GB",
+      timeout: "15 minutes",
+      handler: "index.handler",
+      nodejs: {
+        install: ["@sparticuz/chromium"],
+      },
+    });
+
+    return {
+      url: api.url,
+    };
+  },
+});
diff --git a/examples/aws-puppeteer/tsconfig.json b/examples/aws-puppeteer/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true
+  }
+}
diff --git a/examples/aws-sharp/sst.config.ts b/examples/aws-sharp/sst.config.ts
@@ -1,7 +1,7 @@
 /// <reference path="./.sst/platform/config.d.ts" />
 
 /**
- * ## Sharp image resizer
+ * ## Sharp in Lambda
  *
  * Uses the [Sharp](https://sharp.pixelplumbing.com/) library to resize images. In this example,
  * it resizes a `logo.png` local file to 100x100 pixels.
@@ -12,7 +12,10 @@
  * }
  * ```
  *
- * The sharp package is handled by [`nodejs.install`](/docs/component/aws/function#nodejs-install). In dev, this uses the sharp npm package locally.
+ * We don't need a layer to deploy this because `sharp` comes with a pre-built binary for Lambda.
+ * This is handled by [`nodejs.install`](/docs/component/aws/function#nodejs-install).
+ *
+ * In dev, this uses the sharp npm package locally.
  *
  * ```json title="package.json"
  * {
@@ -22,7 +25,8 @@
  * }
  * ```
  *
- * On deploy, the sharp package for the right target Lambda architecture is used.
+ * On deploy, SST will use the right binary from the sharp package for the target Lambda
+ * architecture.
  */
 export default $config({
   app(input) {

diff --git a/www/src/content/docs/docs/examples.mdx b/www/src/content/docs/docs/examples.mdx
@@ -327,6 +327,106 @@ return {
 View the [full example](https://github.com/sst/ion/tree/dev/examples/aws-kinesis-stream).
 
 
+---
+## Puppeteer in Lambda
+
+To use Puppeteer in a Lambda function you need:
+
+1. [`puppeteer-core`](https://www.npmjs.com/package/puppeteer-core)
+2. Chromium
+   - In `sst dev`, we'll use a locally installed Chromium version.
+   - In `sst deploy`, we'll use the [`@sparticuz/chromium`](https://github.com/sparticuz/chromium) package. It comes with a pre-built binary for Lambda.
+
+#### Chromium version
+
+Since Puppeteer has a preferred version of Chromium, we'll need to check the version of
+Chrome that a given version of Puppeteer supports. Head over to the
+[Puppeteer's Chromium Support page](https://pptr.dev/chromium-support) and check which
+versions work together.
+
+For example, Puppeteer v23.1.1 supports Chrome for Testing 127.0.6533.119. So, we'll use the
+v127 of `@sparticuz/chromium`.
+
+```bash
+npm install [email protected] @sparticuz/[email protected]
+```
+
+#### Install Chromium locally
+
+To use this locally, you'll need to install Chromium.
+
+```bash
+npx @puppeteer/browsers install chromium@latest --path /tmp/localChromium
+```
+
+Once installed you'll see the location of the Chromium binary.
+
+```bash
+chromium@1350406 /tmp/localChromium/chromium/mac_arm-1350406/chrome-mac/Chromium.app/Contents/MacOS/Chromium
+```
+
+Next, update this in your Lambda function.
+
+```ts title="index.ts"
+// This is the path to the local Chromium binary
+const YOUR_LOCAL_CHROMIUM_PATH = "/tmp/localChromium/chromium/mac_arm-1350406/chrome-mac/Chromium.app/Contents/MacOS/Chromium";
+```
+
+You'll notice we are using the right binary with the `SST_LIVE` environment variable.
+
+```ts title="index.ts" {4-6}
+const browser = await puppeteer.launch({
+  args: chromium.args,
+  defaultViewport: chromium.defaultViewport,
+  executablePath: process.env.SST_LIVE
+    ? YOUR_LOCAL_CHROMIUM_PATH
+    : await chromium.executablePath(),
+  headless: chromium.headless,
+});
+```
+
+#### Deploy
+
+We don't need a layer to deploy this because `@sparticuz/chromium` comes with a pre-built
+binary for Lambda.
+
+:::note
+As of writing this, `arm64` is not supported by `@sparticuz/chromium`.
+:::
+
+We just need to set it in the [`nodejs.install`](/docs/component/aws/function#nodejs-install).
+
+```ts title="sst.config.ts"
+{
+  nodejs: {
+    install: ["@sparticuz/chromium"]
+  }
+}
+```
+
+And on deploy, SST will use the right binary.
+
+We are giving our function more memory and a longer timeout since running Puppeteer can
+take a while.
+```ts title="sst.config.ts"
+const api = new sst.aws.Function("MyFunction", {
+  url: true,
+  memory: "2 GB",
+  timeout: "15 minutes",
+  handler: "index.handler",
+  nodejs: {
+    install: ["@sparticuz/chromium"],
+  },
+});
+
+return {
+  url: api.url,
+};
+```
+
+View the [full example](https://github.com/sst/ion/tree/dev/examples/aws-puppeteer).
+
+
 ---
 ## Subscribe to queues
 
@@ -380,7 +480,7 @@ View the [full example](https://github.com/sst/ion/tree/dev/examples/aws-router)
 
 
 ---
-## Sharp image resizer
+## Sharp in Lambda
 
 Uses the [Sharp](https://sharp.pixelplumbing.com/) library to resize images. In this example,
 it resizes a `logo.png` local file to 100x100 pixels.
@@ -391,7 +491,10 @@ it resizes a `logo.png` local file to 100x100 pixels.
 }
 ```
 
-The sharp package is handled by [`nodejs.install`](/docs/component/aws/function#nodejs-install). In dev, this uses the sharp npm package locally.
+We don't need a layer to deploy this because `sharp` comes with a pre-built binary for Lambda.
+This is handled by [`nodejs.install`](/docs/component/aws/function#nodejs-install).
+
+In dev, this uses the sharp npm package locally.
 
 ```json title="package.json"
 {
@@ -401,7 +504,8 @@ The sharp package is handled by [`nodejs.install`](/docs/component/aws/function#
 }
 ```
 
-On deploy, the sharp package for the right target Lambda architecture is used.
+On deploy, SST will use the right binary from the sharp package for the target Lambda
+architecture.
 ```ts title="sst.config.ts"
 const func = new sst.aws.Function("MyFunction", {
   url: true,