log4js-node: category-based logging for Node.js, configured in code
A port of log4js to node.js
At a glance
- What is it?
- log4js-node is a Node.js logging library ported from the original log4js. It uses named appenders and categories configured through log4js.configure, and it stays silent until you set a level.
- Who is it for?
- Adopt log4js-node if you want category-scoped levels and file rolling driven by a config object rather than by environment variables, and if your runtime is Node 8.0 or newer. Do not adopt it if you need a single structured JSON stream with no configuration layer, or if you expect log4j semantics: the README says thinking it behaves the same way will only bring sorrow and confusion.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 69 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- log4js-node/log4js-node5,824 ★ · +1
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| log4js-node/log4js-node | 5.8k | 5.8k |
1 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The problem log4js-node solves: one process, several log policies
A Node service rarely wants one log stream. The HTTP layer wants request lines. A payment module wants errors only. A background worker wants debug output that must never reach production stdout. Wiring that with console.log means scattering level checks through the codebase, and every new destination means another branch.
log4js-node answers this with the log4j vocabulary: appenders are destinations, categories are named loggers, and a configuration object maps one to the other. The README lists the built-in behaviour plainly: coloured console logging to stdout or stderr, a file appender with rolling based on file size or date, a logger for connect/express servers, configurable layouts, and different levels per category.
The intended users are application authors rather than library authors. The README makes that split explicit in its note for library makers, which points at a separate package, log4js-api, so that a library can accept a log4js logger without forcing the dependency on everyone downstream. If you are publishing a package that only wants to accept a logger, that note is the part of the README aimed at you.
How configuration, categories and appenders fit together
The mechanism is a two-level lookup. log4js.configure takes an object with an appenders map and a categories map. Each appender has a type and its own options. Each category names the appenders it writes to and the level that gates them. A call to log4js.getLogger(name) returns a logger bound to that category.
Appenders can be shared. Several categories may list the same appender name, so one file appender can collect output from three modules while a console appender shows only one of them. The README's optional appender list shows how far this extends: SMTP, GELF, Loggly, Logstash over UDP and HTTP, logFaces over UDP and HTTP, RabbitMQ, Redis, Hipchat, Slack, mailgun, and an InfluxDB appender hosted outside the main repository. Each is a separate package, so the core stays small and you install only the transport you use.
The default state is the design decision worth noticing. The README states that log4js will not output any logs by default, so that it can safely be used in libraries, and that the level for the default category is OFF. Nothing appears until you assign a level, either through configuration or by setting logger.level directly. That is the opposite of most console-based setups, and it is the single fact most likely to make a first experiment look broken.
Installing log4js and writing your first log line
Installation is a single npm command. The README gives it without qualification, and package.json declares engines.node as >=8.0, so the floor is Node 8.
npm install log4jsThe minimal usage in the README is four lines. Requiring the module gives you a logger, and you must set a level before anything is emitted. The README's own example sets debug and then writes one debug message.
var log4js = require("log4js");
var logger = log4js.getLogger();
logger.level = "debug";
logger.debug("Some debug messages");With that level set, the README says output goes to stdout with the coloured layout, and it shows the shape of a line as a timestamp, the level in brackets, the category, a dash, then the message. Without the level assignment you should expect silence, not an error.
The README's fuller example is the one to copy when you want a file. It configures a single file appender named cheese writing to cheese.log, and a default category that uses that appender at level error. It then gets a logger named cheese and calls trace, debug, info, warn, error and fatal in order. Only the last two calls appear in the file, because the category level is error.
const log4js = require("log4js");
log4js.configure({
appenders: { cheese: { type: "file", filename: "cheese.log" } },
categories: { default: { appenders: ["cheese"], level: "error" } },
});
const logger = log4js.getLogger("cheese");
logger.trace("Entering cheese testing");
logger.debug("Got cheese.");
logger.info("Cheese is Comté.");
logger.warn("Cheese is quite smelly.");
logger.error("Cheese is too ripe!");
logger.fatal("Cheese was breeding ground for listeria.");The README shows the resulting cheese.log containing only the ERROR and FATAL lines. The repository also carries examples/fromreadme.js and examples/example.js, plus targeted files such as examples/log-to-files.js, examples/date-file-rolling.js and examples/log-rolling.js, which is where to look when the README stops short of the appender options you need. The TypeScript section of the README shows the same configure call with an import statement, and package.json points types at ./types/log4js.d.ts.
Where log4js-node is the wrong tool
The README opens with a warning that deserves to be taken literally: although the name resembles the Java library log4j, thinking it will behave the same way will only bring sorrow and confusion. In the README, configuration is a JavaScript object passed to log4js.configure.
The silent default is the second trap. A logger with no level set writes nothing, and nothing about that failure looks like a failure. In a fresh module the symptom is an empty log, not an exception, and the fix is a level assignment that is easy to forget when the logger is created somewhere other than the configuration call.
Version drift is the third. The README links a migration guide because there were changes between 0.x, 1.x and 2.x, and links a separate page for changes in version 3.x. package.json puts the current version at 6.9.1. That is a lot of major versions, and it means old tutorials and Stack Overflow answers you find may describe an API that no longer exists. The repository keeps v2-changes.md at the top level alongside the docs directory, which suggests the maintainers expect people to arrive with outdated assumptions. If you need a logging library that has never changed its configuration surface, this is not it.
log4js-node against a single-stream structured logger
The obvious alternative in the Node ecosystem is a logger built around one JSON line per event, with levels and transports handled by a small number of options rather than by a named appender and category graph. The difference is not quality, it is where the configuration lives.
With log4js-node you express routing in the config object: which category writes to which appender at which level, with the appender list naming each destination. That gives you per-module levels and shared destinations without touching the call sites, and it is why the README can advertise different log levels for different log categories as a headline feature. A single-stream logger typically gives you one level for the whole process, and if you want a module to be quieter you filter downstream.
log4js-node also ships rolling in the core file appender, with the README describing rolling based on file size or date, and the repository carries examples/log-rolling.js, examples/date-file-rolling.js and examples/log-rolling-bug.js. A minimal structured logger usually leaves rotation to an external tool. The trade is that you now own a configuration graph, and the appender you need may live in a separate package from the optional list rather than in the core install.
Choose log4js-node when the routing itself is the requirement. Choose the simpler logger when you want one format, one destination, and no configuration layer between your code and the output.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-09-07. That is recent enough that the project is being touched, but the published version in package.json is 6.9.1 and the repository has no published releases, so do not read the push date as a promise of a new release cadence. The CHANGELOG.md at the top level is where release history is recorded.
On licence, package.json declares Apache-2.0, while the repository metadata carries a NOASSERTION licence identifier. The README states that the original log4js was distributed under Apache 2.0 and so is this, with the original copyright and author credits kept in place except in sections rewritten extensively. If you need a clean provenance statement for a legal review, read LICENSE in the repository rather than relying on the metadata field, and note that the package publishes SECURITY.md as one of its files. This is a description of what the files say, not legal advice.
Upgrade cost is the part to budget for. Several major versions separate the current 6.x line from 0.x, the README maintains a migration guide and a v3 changes page, and the codebase carries commitlint and husky configuration, which points at conventional commit messages and a disciplined change process rather than a frozen API. A team that pins a major version and reads the migration guide before moving will have a different experience from one that upgrades on a caret range. The dependency list is short and mostly small utilities, which limits the surface you inherit.
Editorial conclusion
Adopt log4js-node if you want category-scoped levels and file rolling driven by a config object rather than by environment variables, and if your runtime is Node 8.0 or newer. Do not adopt it if you need a single structured JSON stream with no configuration layer, or if you expect log4j semantics: the README says thinking it behaves the same way will only bring sorrow and confusion. Before committing, check the appender list in the documentation against the transports you actually need, and read SECURITY.md, because the package ships it in the published files.
Frequently asked questions
Why does log4js-node not output anything after I create a logger?
By default log4js does not output any logs, so that it can safely be used in libraries, and the level for the default category is OFF. Set a level, either in the categories block of log4js.configure or by assigning logger.level as in the README's minimal example.
How do I make log4js-node write to a file instead of the console?
Configure a file appender and point a category at it. The README's example uses appenders: { cheese: { type: "file", filename: "cheese.log" } } together with a default category listing cheese and a level, and the output lands in cheese.log.
Is log4js-node the same as the Java log4j library?
No. The README states that although it has a similar name to log4j, thinking it will behave the same way will only bring sorrow and confusion. It is a conversion of the original log4js framework to work with Node.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/log4js-node-log4js-node)Star history chart for your README
[](https://hysenlabs.com/projects/log4js-node-log4js-node)Was this useful?