tail

library0.1.12jsnpmunverified

tail is a zero-dependency Node.js module designed for monitoring and reading file changes in real-time, similar to the `tail -f` command-line utility. It provides an event-driven API to react to new lines appended to a file. The current stable version is 2.2.6. Recent releases indicate a consistent maintenance cadence with bug fixes and minor feature additions (e.g., `nLines` flag in v2.2.0). A key differentiator is its minimal dependency footprint and its robust handling of file rotation and renaming scenarios through the `follow` option, mimicking `tail -F`. It transitioned from CoffeeScript to pure ES6 in December 2020, ensuring modern JavaScript compatibility and performance. It supports various configurations for line separators, file watching options, and starting positions.

observability

npm install tail

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TAIL

tail

observabilityjavascriptv0.1.12

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Tail

✓ import { Tail } from 'tail'

✗ import Tail from 'tail'

Tail is a named export. While the CommonJS `require('tail').Tail` pattern works, prefer named ESM imports for clarity and tree-shaking benefits.

Tail (CommonJS)

✓ const { Tail } = require('tail')

✗ const Tail = require('tail')

When using CommonJS, access the `Tail` constructor as a named export from the module. Direct `require('tail')` returns the module object, not the constructor itself.

Tail (Legacy CommonJS)

✓ const Tail = require('tail').Tail

This pattern is explicitly shown in the README and remains a valid way to import the `Tail` constructor in CommonJS environments.

This quickstart demonstrates how to install `tail`, initialize it for a temporary log file, listen for new lines, handle potential errors, and simulate log activity by appending data. It also shows how to stop watching and clean up resources.

const { Tail } = require('tail'); const path = require('path'); const fs = require('fs'); const tempFilePath = path.join(__dirname, 'log.txt'); // Create a dummy log file for demonstration fs.writeFileSync(tempFilePath, 'Initial log entry\n'); try { const tail = new Tail(tempFilePath, { fromBeginning: true }); tail.on('line', function(data) { console.log('New line:', data); }); tail.on('error', function(error) { console.error('Tail Error:', error); }); // Append some lines after a delay to simulate log activity let counter = 0; const interval = setInterval(() => { counter++; fs.appendFileSync(tempFilePath, `Appended line ${counter}\n`); if (counter >= 3) { clearInterval(interval); setTimeout(() => { console.log('Stopping tail...'); tail.unwatch(); fs.unlinkSync(tempFilePath); // Clean up temp file }, 1000); } }, 500); } catch (ex) { console.error('Failed to initialize Tail:', ex); if (fs.existsSync(tempFilePath)) { fs.unlinkSync(tempFilePath); // Clean up temp file on error too } }

Debug

Known issues

gotchaThe `fromBeginning` option takes precedence over `nLines`. If both are set, `fromBeginning` will be honored, and `nLines` will be ignored.

fix

Carefully choose between `fromBeginning` (tail entire file) and `nLines` (tail from the last N lines). Do not set both if you expect `nLines` to take effect.

affects: >=2.2.0

gotchaThe `Tail` constructor throws a synchronous exception if the specified file path is missing or invalid, preventing initialization.

fix

Always wrap `Tail` constructor calls in a `try...catch` block to handle file existence or path validity errors gracefully. Ensure the file exists before instantiation.

affects: >=1.0.0

gotchaSetting `follow: false` (default is `true`) will cause an `error` event to be emitted if the file is moved, renamed, or logrotated, instead of automatically re-watching the new file.

fix

If automatic re-watching is desired for scenarios like log rotation (simulating `tail -F`), ensure `follow` is set to its default value of `true` or explicitly configure it.

affects: >=1.0.0

gotchaForcing `useWatchFile: true` will bypass the library's internal logic for choosing between `fs.watch` and `fs.watchFile`, potentially leading to different performance characteristics or platform-specific issues.

fix

Only set `useWatchFile: true` if you have specific reasons or are troubleshooting issues with `fs.watch` behavior on your platform. Generally, allow the library to make the default choice.

affects: >=1.0.0

Errors

Common errors & fixes

Tail constructor will throw an Exception and won't initialize.

The file path provided to the `Tail` constructor is invalid, or the file does not exist at the specified location.

fix

Verify that the file path is correct and accessible. Wrap the `Tail` constructor call in a `try...catch` block to handle this synchronous error: `try { new Tail('missingFile.txt') } catch (ex) { console.error(ex); }`

TypeError: Tail is not a constructor

Attempting to import or require the `Tail` constructor incorrectly, often by trying to use a default import with ESM or directly requiring the module without accessing the `.Tail` property in CommonJS.

fix

For CommonJS, use `const { Tail } = require('tail');` or `const Tail = require('tail').Tail;`. For ESM, use `import { Tail } from 'tail';`.

Unhandled 'error' event

The `tail` instance encountered an issue (e.g., file system error, underlying read error, or `follow: false` on file rename) and emitted an 'error' event, but no listener was registered to handle it.

fix

Always register an error listener on the `tail` instance to prevent unhandled promise rejections or process crashes: `tail.on('error', (err) => { console.error('Tail encountered an error:', err); });`

Upgrade

Version history

0.1.12latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/lucagrulla/node-tail ↗

packagehttps://www.npmjs.com/package/tail ↗

homepagehttps://www.lucagrulla.com/node-tail ↗