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.
1. Create a session and read a page
Section titled “1. Create a session and read a page”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().
2. Work with DOM handles
Section titled “2. Work with DOM handles”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.
3. Evaluate structured data and save HTML
Section titled “3. Evaluate structured data and save HTML”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.
4. Cancel a slow request
Section titled “4. Cancel a slow request”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.
5. Set identity and keep cookies
Section titled “5. Set identity and keep cookies”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.