How to use our new and improved SDK for Browserless v2

As we mentioned when we launched v2 of Browserless, there is now an official SDK.

The SDK is something I have wanted for years, so I'm so excited that it now exists. It's a fully-fledged npm module that you can install here. You'll see that it's a CLI to create, run, build and package your project for distribution via a docker image. The SDK allows you to extend, modify, or even re-implement core parts of Browserless.

To go along with the kit, I wanted to give a quick run through of the design approach and how to use it.

Possibilities with the SDK

We believe that the new SDK opens a whole load of possibilities. It's the same SDK that we are using ourselves to develop new upcoming features such as SSO and session management.

To get ideas flowing, here's a few examples of what's now possible

• Dynamically make tokens or fetch them from a database by extending the Token module.
• Add new parameters in the Config module, which you can reference in new routes to add or improve functionality.
• Implement simple and complex cases like PDF generation that automatically uploads to your AWS S3 bucket by writing a BrowserHTTPRoute that handles it all.
• Add support for other browsers like Edge by extending the core Browser interface and installing your own.
• Generate your own docker image with your own specific business logic, modules, or routes and run them wherever you want.

If that intrigues you, let's move on to actually using it!

How to get started

Start a project by running npx @browserless.io/browserless create.

You'll be prompted with a few questions such as the project name, after which the CLI will create a repo with all the packages.

You might notice that we don't have many dependencies. That's because the Browserless CLI and SDK come bundled with all the things you’ll likely need, including TypeScript compilation.

Once you've created a project, you'll notice some npm commands are already built out for you. These are:

• npm run dev: This command will build your Typescript files, generate the OpenAPI schema, and create the documentation site and start your server.
• npm run start: This will simply start the already built server and run it – no compilation or new generation of assets.
• npm run build: Builds the Typescript files, the OpenAPI docs and documentation site, then exits. Useful for CI environments where you want to ensure builds work but don’t want to start the HTTP server.
• npm run clean: Cleans out all prior built assets.
• npm run docker: This starts an interactive CLI where you can specify the architecture you’re targeting (linux/amd64 for example), the base image you’d like to extend (ghcr.io/browserless/multi by default) and more. Builds a docker image and loads that image into docker or pushes it to a registry.

Fundamentally, the SDK runs the same browserless V2 code but with your overrides and provided routes. The exact same application stack is used in both our open-source image and your project.

Overriding modules

The SDK is built around six modules. These are:

• browser-manager.ts
• config.ts
• file-system.ts
• limiter.ts
• metrics.ts
• monitoring.ts
• router.ts
• token.ts
• webhooks.ts

Overriding modules is done by a naming semantic. . For example, if you wanted to override how tokens worked on the service, you’d name that file token.ts in your project’s src folder. This informs browserless that an override is present and it’ll use that module instead.

To see the details about how these modules all work you can take a look at our source code, including our readme section about extending modules.

v2 source code

HTTP and WebSocket APIs

The SDK allows you to build your own APIS. When writing new HTTP APIs or new WebSocket APIs you need to use a naming semantic of your-http-name-here.http.ts for your-websocket-name-here.ws.

Browserless will load these appropriately, compile them, and generate documentation for them. For examples of how to use these, visit one of our own APIs here.

You can place these files anywhere you’d like in the src directory. For each of use, Browserless scans for files matching these patterns and load them. Don’t worry about having to import or require them elsewhere.

Typing info and README generation

Browserless also exports all the typing information you’ll need to get the best experience when authoring with the SDK.

Make sure to look at things like Token or Config when extending them, and see our route definitions for modules like BrowserHTTPRoute or BrowserWebSocketRoute when writing new routes.

Finally, when creating a new project, we automatically generate a README for you, which you can view here.

What's coming next

As we develop new features and functionality, we’ll expose those modules as part of the SDK, allowing you to disable, extend or modify them as you wish. Keep an eye on the changelog in GitHub to see what's new.

Since our prebuilt APIs are pretty encompassing, we’ll add a way to disable certain features as well without having to override them or delete them.

Want to use our SDK?

The SDK is available under our open-source license, free for non-commercial use.

If you want to use Browserless to build commercial sites, applications, or in a continuous-integration system that's closed-source then you'll need to purchase a commercial license. This allows you to keep your software proprietary whilst still using Browserless.

You can request a commercial license here.