# sindresorhus/electron-timber architecture

> Architecture diagram of the GitHub repository sindresorhus/electron-timber, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sindresorhus/electron-timber
- Repository: https://github.com/sindresorhus/electron-timber

## Overview

##### Project type and purpose
- This is an open-source utility library for Electron apps, “electron-timber,” that captures and pretty-prints logs from both the main and renderer processes. It acts as a drop-in replacement for console.* calls and routes renderer logs through the main process so they appear in the terminal.

##### File structure
- Top-level module files:
- index.js – Entry point, detects process type (main or renderer) and exports the logger API.
- preload.mjs – Optional preload script for the renderer to inject or initialize the logger before your web code runs.
- Config & metadata: .editorconfig, .gitignore, .npmrc, package.json, license, README.
- Tests: A “test/fixture” folder with sample main/renderer code, HTML, and test runners demonstrating how the logger behaves.

##### README insights
- Describes API surface: log, warn, error, time, timeEnd, streamLog/Warn/Error, create, getDefaults, setDefaults.
- Highlights that renderer logs must be “required” in the main process to be forwarded.
- Mentions IPC under the hood (implied by cross-process functionality) and environment-variable filtering (TIMBER_LOGGERS).

##### Main components
A. Application Main Process
– User’s Electron main script that calls logger.log/error/time/etc.
– Imports and initializes electron-timber (index.js).
B. Electron-Timber Main Module
– Core Logger class and default instance, console output logic, prefix padding, logLevel filtering, environment‐variable filtering.
– IPC listener (via ipcMain) that receives serialized log events from renderer processes.
C. Console/Terminal (stdout/stderr)
– Final sink for formatted log messages.
D. Application Renderer Process
– User’s renderer script or UI code that calls logger.log/error/time/etc.
– May load logger via preload.mjs or bundler.
E. Electron-Timber Renderer Module
– Proxy logger that serializes log calls and sends events over IPC (via ipcRenderer).
F. Node Streams (optional)
– streamLog/Warn/Error helpers wrap a stream.Readable and forward each chunk/line to the logger methods.

##### Relationships and data flows
1. In Main:
- Calls to logger.log → Electron-Timber Main Module → direct console.log with prefix “main” and optional custom names.
2. In Renderer:
- Calls to logger.log → Electron-Timber Renderer Module → ipcRenderer.send('TIMBER_LOG', payload).
- Electron-Timber Main Module’s ipcMain.on('TIMBER_LOG') → dispatches to core logger.log with prefix “renderer”.
3. streamLog:
- Attaches to a stream → on data event splits into lines → for each line calls appropriate logger method.
4. Environment filtering:
- Main Module checks TIMBER_LOGGERS env var → filters out loggers not in the list.

##### Architectural patterns and design principles
- Facade over console and Electron IPC to unify logging API.
- Singleton/default instance pattern + factory (create) for custom named loggers.
- Separation of concerns: main logic vs. renderer proxy vs. stream adapters.
- Extensibility via create(options) and defaults override.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Code
    AMain["App Main Process"]:::app
    ARenderer["App Renderer Process"]:::app

    %% Library Internals
    TIMain["Electron-Timber Main Module"]:::library
    TIRenderer["Electron-Timber Renderer Module"]:::library
    StreamAdapter["Stream Adapters"]:::library

    %% External Systems
    Console["Console (stdout/stderr)"]:::external
    IPC["IPC Channel (ipcMain/ipcRenderer)"]:::external

    %% Test Fixtures & Runners
    subgraph "Test Fixtures & Runners"
        F1["index-hook-console.js"]:::external
        F2["index-log-level.js"]:::external
        F3["test.js"]:::external
    end

    %% Config & Metadata
    subgraph "Config & Metadata"
        C1["package.json"]:::external
        C2[".editorconfig"]:::external
        C3[".gitignore"]:::external
        C4[".npmrc"]:::external
        C5["readme.md"]:::external
        C6["license"]:::external
    end

    %% Data Flows
    AMain -->|"logger.log()/error()/time()"| TIMain
    TIMain -->|"formatted output"| Console
    ARenderer -->|"logger.log()/error()/time()"| TIRenderer
    TIRenderer -->|"ipcRenderer.send('TIMBER_LOG', payload)"| IPC
    IPC -->|"ipcMain.on('TIMBER_LOG')"| TIMain
    StreamAdapter -.->|"optional stream data flow"| TIMain
    ARenderer -.->|"optional preload injection"| TIRenderer

    %% Click Events
    click AMain "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/index.js"
    click ARenderer "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/renderer.js"
    click ARenderer "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/index.html"
    click TIMain "https://github.com/sindresorhus/electron-timber/blob/main/index.js"
    click TIRenderer "https://github.com/sindresorhus/electron-timber/blob/main/preload.mjs"
    click StreamAdapter "https://github.com/sindresorhus/electron-timber/blob/main/index.js"
    click F1 "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/index-hook-console.js"
    click F2 "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/index-log-level.js"
    click F3 "https://github.com/sindresorhus/electron-timber/blob/main/test/fixture/test.js"
    click C1 "https://github.com/sindresorhus/electron-timber/blob/main/package.json"
    click C2 "https://github.com/sindresorhus/electron-timber/blob/main/.editorconfig"
    click C3 "https://github.com/sindresorhus/electron-timber/blob/main/.gitignore"
    click C4 "https://github.com/sindresorhus/electron-timber/blob/main/.npmrc"
    click C5 "https://github.com/sindresorhus/electron-timber/blob/main/readme.md"
    click C6 "https://github.com/sindresorhus/electron-timber/tree/main/license"

    %% Styles
    classDef app fill:#E3F6F5,stroke:#006D77,stroke-width:2px
    classDef library fill:#FFDDD2,stroke:#E29578,stroke-width:2px
    classDef external fill:#E8F1F2,stroke:#E0FBFC,stroke-width:2px
```
