chore(docs): regenerate v4 docs snapshot

Sync versioned_docs/version-4.0 with current /docs/ and regenerate
api-typedoc.json from the latest TypeScript sources. The snapshot still
showed the removed Configuration.get/set methods and stale guide copy;
regenerating pulls in the new property-based getters and the updated
configuration guide. Also adds the custom-logger guide that landed in
v4 after the snapshot was taken.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: B4nan

website/versioned_docs/version-4.0/api-typedoc.json

@@ -15,9 +15,9 @@ There are three ways of changing the configuration parameters:
 - using the `Configuration` class
 
 You could also combine all the above, but you should keep in mind, that the precedence for these 3 options is the following:
-***`crawlee.json`*** < ***constructor options*** < ***environment variables***.
+***constructor options*** > ***environment variables*** > ***`crawlee.json`***.
 
-`crawlee.json` is a baseline. The options provided in the `Configuration` constructor will override the options provided in the JSON. Environment variables will override both.
+Constructor options have the highest priority. Environment variables override `crawlee.json`. The JSON file serves as a baseline.
 
 ## `crawlee.json`
 
@@ -133,7 +133,7 @@ the autoscaling feature will only use up to 2048 MB of memory.
 
 ## Configuration class
 
-The last option to adjust Crawlee configuration is to use the <ApiLink to="core/class/Configuration">`Configuration`</ApiLink> class in the code.
+The last option to adjust Crawlee configuration is to use the <ApiLink to="core/class/Configuration">`Configuration`</ApiLink> class in the code. Configuration is immutable — values are set via the constructor and cannot be changed afterwards.
 
 ### Global Configuration
 
@@ -144,13 +144,17 @@ import { CheerioCrawler, Configuration, sleep } from 'crawlee';
 
 // Get the global configuration
 const config = Configuration.getGlobalConfig();
-// Set the 'persistStateIntervalMillis' option
-// of global configuration to 10 seconds
-config.set('persistStateIntervalMillis', 10_000);
+// Access configuration values directly as properties
+console.log(config.persistStateIntervalMillis);
 
-// Note, that we are not passing the configuration to the crawler
-// as it's using the global configuration
-const crawler = new CheerioCrawler();
+// To use custom configuration values, create a new Configuration instance
+const customConfig = new Configuration({
+    // Set the 'persistStateIntervalMillis' option to 10 seconds
+    persistStateIntervalMillis: 10_000,
+});
+
+// Pass the configuration to the crawler
+const crawler = new CheerioCrawler({ configuration: customConfig });
 
 crawler.router.addDefaultHandler(async ({ request }) => {
     // For the first request we wait for 5 seconds,
@@ -170,15 +174,13 @@ crawler.router.addDefaultHandler(async ({ request }) => {
 await crawler.run(['https://www.example.com/1']);
 ```
 
-This is pretty much the same example we used for showing `crawlee.json` usage,
-but now we're using the global configuration, which is the only difference.
-If you run this example - you will find the `SDK_CRAWLER_STATISTICS` file in default Key-Value store as before,
-which would show the same number of finishes requests (one) and the same crawler runtime (~10 seconds).
-This confirms that provided parameters worked: the state was persisted after 10 seconds, as it was set in the global configuration.
+If you run this example - you will find the `SDK_CRAWLER_STATISTICS` file in default Key-Value store,
+which would show the same number of finished requests (one) and the same crawler runtime (~10 seconds).
+This confirms that provided parameters worked: the state was persisted after 10 seconds, as it was set in the configuration.
 
 :::note
 
-After running the same example with commented two lines of code related to `Configuration` there will be
+After running the same example without the custom configuration, there will be
 no `SDK_CRAWLER_STATISTICS` file stored in the default Key-Value store:
 as we did not change the `persistStateIntervalMillis`, Crawlee used the default value of 60 seconds,
 and the crawler was forcefully aborted after ~15 seconds of run time before it persisted the state for the first time.
@@ -187,7 +189,7 @@ and the crawler was forcefully aborted after ~15 seconds of run time before it p
 
 ### Custom configuration
 
-Alternatively, you can create a custom configuration. In this case you need to pass it to the class that is going to use it, e.g. to the crawler. Let's adjust the previous example:
+You can create a custom configuration and pass it to the crawler via the `configuration` option:
 
 ```js
 import { CheerioCrawler, Configuration, sleep } from 'crawlee';
@@ -198,8 +200,8 @@ const config = new Configuration({
     persistStateIntervalMillis: 10_000,
 });
 
-// Now we need to pass the configuration to the crawler
-const crawler = new CheerioCrawler({}, config);
+// Pass the configuration to the crawler
+const crawler = new CheerioCrawler({ configuration: config });
 
 crawler.router.addDefaultHandler(async ({ request }) => {
     // for the first request we wait for 5 seconds,

website/versioned_docs/version-4.0/guides/configuration.mdx

@@ -0,0 +1,88 @@
+---
+id: custom-logger
+title: Custom logger
+description: Use your own logging library (Winston, Pino, etc.) with Crawlee
+---
+
+import ApiLink from '@site/src/components/ApiLink';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import WinstonSource from '!!raw-loader!./winston.ts';
+import PinoSource from '!!raw-loader!./pino.ts';
+
+Crawlee uses `@apify/log` as its default logging library, but you can replace it with any logger you prefer, such as Winston or Pino. This is done by implementing a small adapter and passing it to the crawler.
+
+## Creating an adapter
+
+All Crawlee logging goes through the <ApiLink to="core/interface/CrawleeLogger">`CrawleeLogger`</ApiLink> interface. To plug in your own logger, extend the <ApiLink to="core/class/BaseCrawleeLogger">`BaseCrawleeLogger`</ApiLink> abstract class and implement two methods:
+
+- **`logWithLevel(level, message, data)`** — dispatches a log message to your logging library. The `level` parameter uses <ApiLink to="core/enum/LogLevel">`LogLevel`</ApiLink> constants (`ERROR = 1`, `SOFT_FAIL = 2`, `WARNING = 3`, `INFO = 4`, `DEBUG = 5`, `PERF = 6`). Map these to your logger's native levels. The `message` is a human-readable `string`, and `data` is an optional `Record<string, unknown>` with structured context (e.g. `{ url, statusCode }`) — pass it to your logger as metadata or structured fields.
+- **`createChild(options)`** — returns a new child logger instance scoped to a specific component. Crawlee calls this internally to give each subsystem (e.g. `CheerioCrawler`, `AutoscaledPool`, `SessionPool`) its own identifiable logger. The `options` parameter is a <ApiLink to="core/interface/CrawleeLoggerOptions">`CrawleeLoggerOptions`</ApiLink> object with a single field: `prefix` — a string label prepended to each log line from that component.
+
+All other methods (`error`, `warning`, `info`, `debug`, `exception`, `perf`, etc.) are derived automatically from `logWithLevel` — you don't need to implement them.
+
+:::info Level filtering
+
+`logWithLevel()` is called for **every** log message, regardless of the configured level. Level filtering is the responsibility of the underlying logging library (e.g. Winston's `level` option or Pino's `level` setting). This means your adapter doesn't need to check log levels — just forward everything and let the library decide what to output.
+
+:::
+
+## Injecting the logger
+
+There are two ways to inject a custom logger: per-crawler and globally.
+
+### Per-crawler logger
+
+Pass your adapter via the `logger` option in the crawler constructor. When a `logger` is provided, the crawler creates its own isolated <ApiLink to="core/class/ServiceLocator">`ServiceLocator`</ApiLink> instance, so the custom logger is used by all internal components of that crawler (autoscaling, session pool, statistics, etc.):
+
+```ts
+import { CheerioCrawler } from 'crawlee';
+
+const crawler = new CheerioCrawler({
+    logger: new WinstonAdapter(winstonLogger),
+    async requestHandler({ log }) {
+        // `log` is a child of your custom logger, with prefix set to the crawler class name
+        log.info('Hello from my custom logger!');
+    },
+});
+```
+
+The same logger is available as `crawler.log` outside of the request handler, for example when setting up routes.
+
+### Global logger via service locator
+
+Instead of passing the logger to each crawler individually, you can set it globally via the `serviceLocator`. This is useful when you run multiple crawlers and want them all to use the same logging backend:
+
+```ts
+import { serviceLocator, CheerioCrawler, PlaywrightCrawler } from 'crawlee';
+
+// Set the logger globally — must be done before creating any crawlers
+serviceLocator.setLogger(new WinstonAdapter(winstonLogger));
+
+// Both crawlers will use the Winston logger
+const cheerioCrawler = new CheerioCrawler({ /* ... */ });
+const playwrightCrawler = new PlaywrightCrawler({ /* ... */ });
+```
+
+:::warning
+
+`serviceLocator.setLogger()` must be called **before** any crawler is created. Once a logger has been retrieved from the service locator (which happens during crawler construction), it cannot be replaced — an error will be thrown.
+
+:::
+
+## Full examples
+
+<Tabs>
+<TabItem value="winston" label="Winston" default>
+
+<CodeBlock language="ts">{WinstonSource}</CodeBlock>
+
+</TabItem>
+<TabItem value="pino" label="Pino">
+
+<CodeBlock language="ts">{PinoSource}</CodeBlock>
+
+</TabItem>
+</Tabs>

website/versioned_docs/version-4.0/guides/custom-logger/custom-logger.mdx

@@ -0,0 +1,48 @@
+import { CheerioCrawler, BaseCrawleeLogger, LogLevel } from 'crawlee';
+import type { CrawleeLogger, CrawleeLoggerOptions } from 'crawlee';
+import pino from 'pino';
+
+// Map Crawlee log levels to Pino levels
+const CRAWLEE_TO_PINO: Record<number, string> = {
+    [LogLevel.ERROR]: 'error',
+    [LogLevel.SOFT_FAIL]: 'warn',
+    [LogLevel.WARNING]: 'warn',
+    [LogLevel.INFO]: 'info',
+    [LogLevel.DEBUG]: 'debug',
+    [LogLevel.PERF]: 'trace',
+};
+
+class PinoAdapter extends BaseCrawleeLogger {
+    constructor(
+        private logger: pino.Logger,
+        options?: Partial<CrawleeLoggerOptions>,
+    ) {
+        super(options);
+    }
+
+    logWithLevel(level: number, message: string, data?: Record<string, unknown>): void {
+        const pinoLevel = CRAWLEE_TO_PINO[level] ?? 'info';
+        this.logger[pinoLevel as pino.Level](data ?? {}, message);
+    }
+
+    protected createChild(options: Partial<CrawleeLoggerOptions>): CrawleeLogger {
+        return new PinoAdapter(this.logger.child({ prefix: options.prefix }), { ...this.getOptions(), ...options });
+    }
+}
+
+// Create a Pino logger with your preferred configuration
+const pinoLogger = pino({
+    level: 'debug',
+});
+
+// Pass the adapter to the crawler via the `logger` option
+const crawler = new CheerioCrawler({
+    logger: new PinoAdapter(pinoLogger),
+    async requestHandler({ request, $, log }) {
+        log.info(`Processing ${request.url}`);
+        const title = $('title').text();
+        log.debug('Page title extracted', { title });
+    },
+});
+
+await crawler.run(['https://crawlee.dev']);

website/versioned_docs/version-4.0/guides/custom-logger/pino.ts

@@ -0,0 +1,57 @@
+import { CheerioCrawler, BaseCrawleeLogger, LogLevel } from 'crawlee';
+import type { CrawleeLogger, CrawleeLoggerOptions } from 'crawlee';
+import winston from 'winston';
+
+// Map Crawlee log levels to Winston levels
+const CRAWLEE_TO_WINSTON: Record<number, string> = {
+    [LogLevel.ERROR]: 'error',
+    [LogLevel.SOFT_FAIL]: 'warn',
+    [LogLevel.WARNING]: 'warn',
+    [LogLevel.INFO]: 'info',
+    [LogLevel.DEBUG]: 'debug',
+    [LogLevel.PERF]: 'debug',
+};
+
+class WinstonAdapter extends BaseCrawleeLogger {
+    constructor(
+        private logger: winston.Logger,
+        options?: Partial<CrawleeLoggerOptions>,
+    ) {
+        super(options);
+    }
+
+    logWithLevel(level: number, message: string, data?: Record<string, unknown>): void {
+        const winstonLevel = CRAWLEE_TO_WINSTON[level] ?? 'info';
+        this.logger.log(winstonLevel, message, data);
+    }
+
+    protected createChild(options: Partial<CrawleeLoggerOptions>): CrawleeLogger {
+        return new WinstonAdapter(this.logger.child({ prefix: options.prefix }), { ...this.getOptions(), ...options });
+    }
+}
+
+// Create a Winston logger with your preferred configuration
+const winstonLogger = winston.createLogger({
+    level: 'debug',
+    format: winston.format.combine(
+        winston.format.colorize(),
+        winston.format.timestamp(),
+        winston.format.printf(({ level, message, timestamp, prefix }) => {
+            const tag = prefix ? `[${prefix}] ` : '';
+            return `${timestamp} ${level}: ${tag}${message}`;
+        }),
+    ),
+    transports: [new winston.transports.Console()],
+});
+
+// Pass the adapter to the crawler via the `logger` option
+const crawler = new CheerioCrawler({
+    logger: new WinstonAdapter(winstonLogger),
+    async requestHandler({ request, $, log }) {
+        log.info(`Processing ${request.url}`);
+        const title = $('title').text();
+        log.debug('Page title extracted', { title });
+    },
+});
+
+await crawler.run(['https://crawlee.dev']);

website/versioned_docs/version-4.0/guides/custom-logger/winston.ts

@@ -1,4 +1,5 @@
-import { CheerioCrawler, GotScrapingHttpClient } from 'crawlee';
+import { CheerioCrawler } from 'crawlee';
+import { GotScrapingHttpClient } from '@crawlee/got-scraping-client';
 
 const crawler = new CheerioCrawler({
     httpClient: new GotScrapingHttpClient(),

website/versioned_docs/version-4.0/guides/http-clients/cheerio-got-scraping-example.ts

@@ -7,7 +7,7 @@ const crawler = new BasicCrawler({
     }),
     async requestHandler({ sendRequest, log }) {
         const response = await sendRequest();
-        log.info('Received response', { statusCode: response.statusCode });
+        log.info('Received response', { status: response.status });
     },
 });
 

website/versioned_docs/version-4.0/guides/impit-http-client/basic-usage.ts

@@ -5,7 +5,6 @@ const proxyConfiguration = new ProxyConfiguration({
 });
 
 const crawler = new CheerioCrawler({
-    useSessionPool: true,
     persistCookiesPerSession: true,
     proxyConfiguration,
     // ...

website/versioned_docs/version-4.0/guides/proxy_management_session_cheerio.ts

@@ -5,7 +5,6 @@ const proxyConfiguration = new ProxyConfiguration({
 });
 
 const crawler = new HttpCrawler({
-    useSessionPool: true,
     persistCookiesPerSession: true,
     proxyConfiguration,
     // ...

website/versioned_docs/version-4.0/guides/proxy_management_session_http.ts

@@ -5,7 +5,6 @@ const proxyConfiguration = new ProxyConfiguration({
 });
 
 const crawler = new JSDOMCrawler({
-    useSessionPool: true,
     persistCookiesPerSession: true,
     proxyConfiguration,
     // ...