Build a screenshot API with Functions and Browserless

Deploy a Hono project on Functions that captures a page screenshot through the Browserless API and returns the PNG image.

Last updated

View as Markdown Agent setup

In this tutorial, you will build a screenshot API that returns a web page as a PNG image. You will create the project from the Hono template, write the route, store the API token, deploy the project, and request the endpoint.

The function runs no browser of its own. It posts the target URL to Browserless, a hosted service that renders the page and answers with the image. The function returns those bytes to the client.

Prerequisites

  • An Azion account. To create one, refer to How to create an account on Azion.
  • Azion CLI installed on your machine. Refer to Azion CLI.
  • Node.js version 18 or higher.
  • A Browserless account and its API token. To create one, refer to Browserless.
  • Working knowledge of JavaScript.

1. Authenticate Azion CLI

Sign in to your Azion account from the terminal:

azion login

Azion CLI opens a browser-based flow when you omit the credential flags. It stores the resulting credentials locally, and they authorize every later command.

2. Create the project from the Hono template

Azion CLI initializes the project from a starter template. To create it:

Initialize the project

Run the command and answer the prompts that follow:

azion init --name screenshot-api
Select Hono in the preset list

The prompt lists one preset per framework:

Shell
01? Choose a preset: [Use arrows to move, type to filter]
02 Angular
03 Astro
04 Docusaurus
05 Eleventy
06 Emscripten
07 Gatsby
08 Hexo
09> Hono
10 Hugo
11 Javascript
12 ...
Select the Hono Boilerplate template
Enter n at the prompt for a local development server

The prompt appears after Azion CLI fetches and configures the template:

Do you want to start a local development server? (y/N)
Enter n at the deploy prompt

The route and the API token are not in place yet:

Do you want to deploy your project? (y/N)

Azion CLI creates the screenshot-api directory and writes the Hono project into it. Go to that directory:

cd screenshot-api

The remaining commands run from there.

3. Write the screenshot route

The entry field of azion.config.js names the entry file of the project. Open that file and replace its contents with the route that captures the page:

JavaScript
01import { Hono } from 'hono';
02
03const app = new Hono();
04
05app.get('/screenshot', async (c) => {
06 const url = c.req.query('url') || 'https://www.example.com';
07 const token = Azion.env.get('PUPPETEER_BROWSERLESS_IO_KEY');
08
09 const response = await fetch(
10 `https://production-sfo.browserless.io/screenshot?token=${token}`,
11 {
12 method: 'POST',
13 headers: {
14 'Cache-Control': 'no-cache',
15 'Content-Type': 'application/json',
16 },
17 body: JSON.stringify({
18 url,
19 options: { type: 'png' },
20 }),
21 },
22 );
23
24 if (!response.ok) {
25 return c.html(await response.text(), response.status);
26 }
27
28 const image = new Uint8Array(await response.arrayBuffer());
29
30 return c.body(image, {
31 status: 200,
32 headers: { 'Content-Type': 'image/png' },
33 });
34});
35
36export default app;

The route reads the target page from the url query parameter, and it falls back to https://www.example.com. export default app is the ES Modules handler pattern, which Azion recommends over the Service Worker pattern. To compare both patterns, refer to Migrate handler patterns in Functions.

The complete project is in the browserless package of the functions examples repository.

4. Store the Browserless token as an environment variable

An environment variable holds the token outside the function code and outside version control. To create it:

azion create variables --key "PUPPETEER_BROWSERLESS_IO_KEY" --value "[TOKEN VALUE]" --secret true

Azion stores the variable on the account, and Azion.env.get() returns its value at run time. A variable whose key contains password, pwd, secret, key, hash, encrypted, passcode, auth, or token is sent as a secret by default. The --secret true flag repeats that default here.

A change to a variable does not reach a function that is already running. Redeploy the function for a new value to take effect. Azion Runtime also reads a variable through process.env. For both interfaces, the fields of a variable, and the other management interfaces, refer to Environment variables.

5. Deploy the project

Build the project and send it to Azion:

azion deploy

The command uploads the function code and configures the application and its routing rules. It returns a workload domain in the format https://xxxxxxx.map.azionedge.net.

Azion opens a page in Azion Console that shows the deployment logs. Open the printed link when the browser does not open on its own.

The application answers on that domain a few minutes later, once the DNS propagation completes.

6. Verify the screenshot response

Request the route with the address of the page to capture:

curl -s -o screenshot.png -w '%{content_type}\n' "https://<your-azion-domain>/screenshot?url=https://www.example.com"

The command prints the content type of the response:

image/png

The file screenshot.png holds the capture of https://www.example.com. A request without the url parameter captures the same page, because the route falls back to it. When Browserless rejects a request, the route answers with the body and the status code that Browserless returned.

Next steps

Environment variablesThe fields of a variable, the size ceilings, and every interface that creates one.Migrate handler patterns in FunctionsThe ES Modules and Service Worker handlers side by side, with the parameters each one receives.LimitsThe CPU time, execution time, sub-request, and memory ceilings a single invocation runs inside.Troubleshoot function execution and logsRead the function logs, and find the cause when a function never runs or stops before it responds.Object StorageBuckets on the Azion Web Platform, reachable through the S3 standard, to keep the images the route captures.How to build with HonoThe rest of the Hono workflow on Azion, including the local development server.