Skip to content

Node.js tutorial

You’ll build: an asynchronous page workflow using @brimp/brimp. Save each example in an .mjs file and run it with Node.js 22.19 or newer.

Start the local tutorial server first.

import { createSession } from '@brimp/brimp';
const session = await createSession();
try {
const page = await session.get('http://127.0.0.1:8765/');
console.log(page.statusCode);
console.log(await page.evaluate('document.title'));
} finally {
await session.close();
}

Expect 200 and Brimp tutorial. Closing the session closes all its pages. Use session.newPage() when you need to attach routes or event listeners before navigating with page.get().

import { createSession } from '@brimp/brimp';
const session = await createSession();
try {
const page = await session.get('http://127.0.0.1:8765/');
const heading = await page.querySelector('h1');
if (heading) {
try {
await heading.setTextContent('Edited by Node');
console.log(await heading.textContent());
} finally {
await heading.dispose();
}
}
} finally {
await session.close();
}

Expect Edited by Node. A detached node keeps its identity, but a handle from a previous navigation raises StaleHandle.

import { writeFile } from 'node:fs/promises';
import { createSession } from '@brimp/brimp';
const session = await createSession();
try {
const page = await session.get('http://127.0.0.1:8765/');
const result = await page.evaluate(`({
title: document.title,
links: document.querySelectorAll('a').length
})`);
console.log(result);
await writeFile('example.html', await page.html(), 'utf8');
} finally {
await session.close();
}

The result contains title: 'Brimp tutorial' and links: 1. Evaluation returns copied values, including BigInt and binary buffers, and awaits Promises. See Values and handles for the full conversion contract. File access runs in Node; page JavaScript has no Node process, require or filesystem API.

The fixture’s /slow endpoint waits three seconds. Abort it after 100 ms:

import { createSession } from '@brimp/brimp';
const session = await createSession();
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 100);
try {
await session.get('http://127.0.0.1:8765/slow', {
timeout: 10_000,
signal: controller.signal,
});
} catch (error) {
if (error.code !== 'cancelled') throw error;
console.log('Request cancelled');
} finally {
clearTimeout(timer);
await session.close();
}

Timeouts use milliseconds. Requests and streams accept an AbortSignal.

import { createSession } from '@brimp/brimp';
const session = await createSession({identity: {languages: ['en-US', 'en']}});
try {
session.setCookie('http://127.0.0.1:8765/', 'experiment', 'rendered');
const page = await session.get('http://127.0.0.1:8765/echo');
console.log(page.json().cookie);
console.log(await page.evaluate('navigator.languages'));
} finally {
await session.close();
}

Expect a cookie header containing experiment=rendered and ['en-US', 'en']. identity accepts userAgent, languages and platform. Pass a captured or partial profile as profile, for example createSession({profile}) with the parsed profile object. A supplied profile drives navigator identity, screen/viewport values, locale and timezone; identity still overrides individual identity fields.

Next: extract and stream content, or browse the generated Node API.