Skip to main content

​
Ephemeral vs. Session mode

By default, each fetch() call runs in ephemeral mode. Cookies and connection state are isolated per call. This is a good fit for one-off requests. For multi-step flows (like login sequences), use sessions to persist state.
ScenarioRecommendedWhy
One-off request, no cookie carryoverEphemeral (default)Fresh TLS/cookie jar per call
Multi-step login or reuse cookiesSessionShared cookie jar and TLS cache
Parallel jobs that must stay isolatedEphemeral or per-job sessionAvoid cross-talk between tasks

​
Creating a session

import { createSession } from 'wreq-js';

const session = await createSession({ browser: 'chrome_142' });

// All requests share the same cookie jar
await session.fetch('https://example.com/login', {
  method: 'POST',
  body: new URLSearchParams({ user: 'name', pass: 'secret' }),
});

// Cookies from login are automatically included
const dashboard = await session.fetch('https://example.com/dashboard');
console.log(await dashboard.text());

// Always close when done
await session.close();

​
Auto-disposing sessions

Use withSession() to automatically close the session when done: 
import { withSession } from 'wreq-js';

await withSession(async (session) => {
  await session.fetch('https://example.com/login', {
    method: 'POST',
    body: 'credentials',
  });
  
  const data = await session.fetch('https://example.com/data');
  console.log(await data.json());
}); // Session is automatically closed here

​
Session options

Sessions accept the same options as fetch() for default behavior: 
const session = await createSession({
  browser: 'chrome_142',
  os: 'windows',
  proxy: 'http://proxy.example.com:8080',
  insecure: false,
});

​
Per-request overrides

Within a session, browser, os, and proxy are fixed at creation time. You can still override per-request values like timeout, headers, redirect, and body: 
const session = await createSession({
  browser: 'chrome_142',
  timeout: 30_000,
});

// Override timeout for a single request
await session.fetch('https://example.com', {
  timeout: 5_000,
  headers: {
    'accept': 'text/html,application/xhtml+xml',
  },
});

​
Session isolation

Each session maintains its own:
  • Cookie jar: cookies are not shared between sessions
  • TLS cache: connection state is isolated
  • Connection pool: HTTP/2 multiplexing within the session
// These sessions are completely isolated
const session1 = await createSession({ browser: 'chrome_142' });
const session2 = await createSession({ browser: 'firefox_139' });

// Cookies set in session1 do not affect session2
await session1.fetch('https://example.com/set-cookie');
await session2.fetch('https://example.com/check-cookie'); // No cookie present

​
Best practices

Always close sessions

Call session.close() or use withSession() to prevent resource leaks.

One session per flow

Use a dedicated session for each logical user flow or task.

Parallel isolation

For parallel scraping, create separate sessions to avoid cookie cross-contamination.

Reuse for performance

Sessions reuse connections, making subsequent requests faster.