basic_logger_file

A lightweight, high-performance file output logger extension for basic_logger.

Works seamlessly across both pure Dart (CLI tools, server-side backends) and Flutter applications on any non-web platform with dart:io support (Android, iOS, Linux, macOS, and Windows).

---

Features

• 🎯 Pure Dart & Flutter Ready: Zero Flutter SDK dependency. Runs anywhere dart:io is supported—standalone CLI tools, backend servers (Serverpod, Dart Frog, Shelf), and Flutter desktop/mobile apps.
• 📅 Daily Log Rotation: Automatically rotates log files daily using date stamps (e.g., YYYY-MM-DD.log).
• ⚡ Buffered Asynchronous I/O: Batches log records in memory before writing to disk to minimize I/O overhead.
• 🗂 Categorization & Filtering: Supports custom file extensions (e.g., _sql.log), target directories, and logger name filtering.
• 🪶 Minimal Dependencies: Depends only on basic_logger. Drops direct dependencies on package:path (via built-in joinPath) and package:logging (via basic_logger/logging.dart), eliminating version conflicts and bloat.
• 🛠 Built-in joinPath: Lightweight, cross-platform path joining helper—no need to pull in package:path for simple path operations.

---

Getting Started

Add the dependency to your project:

dart pub add basic_logger_file
# or for Flutter
flutter pub add basic_logger_file

---

Usage

Quick Start

import 'package:basic_logger/basic_logger.dart';
import 'package:basic_logger/logging.dart';
import 'package:basic_logger_file/basic_logger_file.dart';

void main() {
  Logger.root.level = Level.ALL;
  final basicLogger = BasicLogger('main');

  // Attach FileOutputLogger (default bufferSize: 100)
  basicLogger.attachLogger(FileOutputLogger(basicLogger.name));

  // Output to all attached loggers
  basicLogger.info('hello world');

  // Manually flush memory buffer to disk when needed
  basicLogger.output();

  // Written to ./YYYY-MM-DD.log:
  // 2026-11-05 10:15:30.123 [INFO] main: hello world
}

---

Configuration & Options

FileOutputLogger Parameters

Parameter	Type	Default	Description
parentName	String	(required)	Name of the parent logger to listen to.
selfname	String	'file'	Name identifier for this file logger instance.
selfonly	bool	false	If true, captures only records emitted directly by this logger.
dir	String	'.'	Output directory for log files.
ext	String	'.log'	Custom file extension (e.g., _error.log).
bufferSize	int	100	Number of records to buffer before auto-flushing to disk.

Examples

1. Custom Directory & Flutter Integration

Use with path_provider in Flutter and the built-in joinPath utility:

import 'dart:io';
import 'package:path_provider/path_provider.dart';
import 'package:basic_logger_file/basic_logger_file.dart';

final appDocDir = await getApplicationDocumentsDirectory();
final logDir = joinPath(appDocDir.path, 'logs');

// Ensure directory exists (createSync is idempotent)
Directory(logDir).createSync(recursive: true);

basicLogger.attachLogger(FileOutputLogger(
  basicLogger.name,
  dir: logDir,
));

2. Custom Buffer Size

basicLogger.attachLogger(FileOutputLogger(
  basicLogger.name,
  bufferSize: 200, // Flushes to disk every 200 records
));

3. Log Categorization by Extension

// Generates: YYYY-MM-DD_sql.log
basicLogger.attachLogger(FileOutputLogger(
  basicLogger.name,
  ext: '_sql.log',
));

---

Utility: joinPath

This package exports a standalone joinPath helper so you don't need to add package:path for simple path joining:

import 'package:basic_logger_file/basic_logger_file.dart';

// Automatically handles separators across POSIX and Windows:
final path1 = joinPath('logs', 'app.log');  // 'logs/app.log' or r'logs\app.log'
final path2 = joinPath('logs/', 'app.log'); // 'logs/app.log' (no duplicate slashes)
final path3 = joinPath('.', 'app.log');     // 'app.log'