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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JL
✓ import { JL } from 'jsnlog';
✗ import JL from 'jsnlog';
JSNLog exports 'JL' as a named export. Attempting a default import will result in a runtime error. This applies to consuming JSNLog in an ESM context.
JL (CommonJS)
✓ const JL = require('jsnlog').JL;
✗ const JSNLog = require('jsnlog'); JSNLog.JL().debug('message');
For CommonJS environments, the main JL logger instance is available as a property of the module export.
JL (Global)
✓ // With <script> tag inclusion: <script src="path/to/jsnlog.min.js"></script>
JL().debug('message from global JL');
When JSNLog is included directly via a script tag in HTML, it exposes the 'JL' object globally. This is common for client-side usage without a module bundler.
This quickstart demonstrates setting up JSNLog for client-side logging, configuring it to send logs to a Node.js server, and integrating with a Winston logger on the server to process and store these client-side messages.
import { JL } from 'jsnlog';
import express from 'express';
import winston from 'winston';
import { JSNLogMiddleware } from 'jsnlog-nodejs'; // Assuming jsnlog-nodejs is installed for server-side
// --- Client-side (in your frontend application) ---
// Configure JSNLog to send logs to the /jsnlog endpoint on your server
JL.setOptions({
"appenders": [
{
"name": "ajaxAppender",
"type": "ajax",
"url": "/jsnlog",
"level": "DEBUG", // Send all debug+ messages
"bufferSize": 1,
"batchSize": 5,
"batchTimeout": 1000
}
],
"defaultLogger": {
"appenders": ["ajaxAppender"]
}
});
console.log('Client-side JSNLog configured. Sending logs to /jsnlog.');
// Example client-side logging
JL().debug('This is a debug message from the client');
JL().info('An informational message from the client');
try {
throw new Error('Something went wrong on the client!');
} catch (e: any) {
JL().fatalException('Caught a client-side error!', e);
}
// --- Server-side (in your Node.js application) ---
const app = express();
const PORT = process.env.PORT || 3000;
// Configure Winston logger for server-side logging
const serverLogger = winston.createLogger({
level: 'info',
format: winston.format.json(),
transports: [
new winston.transports.Console(),
new winston.transports.File({ filename: 'combined.log' }),
],
});
// Integrate JSNLog with Express and Winston
app.use(JSNLogMiddleware(serverLogger));
app.get('/', (req, res) => {
res.send('JSNLog example running. Check your client console and server logs!');
});
app.listen(PORT, () => {
console.log(`Server listening on port ${PORT}`);
console.log('Open your browser to http://localhost:3000 and check the network tab/console for client logs being sent.');
serverLogger.info('Server started and JSNLog middleware active.');
});
// To run this example:
// 1. npm install jsnlog express winston jsnlog-nodejs
// 2. Add "type": "module" to your package.json for ESM support if not already present.
// 3. run `npx ts-node your-file.ts` (if using ts-node) or compile and run.
Debug
Known issues
gotchaJSNLog has been in an inactive maintenance state for approximately five years, with no new releases or significant commits. While stable, active development and new features are not expected.fixBe aware that community support may be limited and consider the long-term implications for new projects. Review the codebase for any potential unaddressed security concerns if integrating into critical systems.
affects: >=2.30.0
breakingWhen using ES Modules (ESM), importing JSNLog with a default import (e.g., `import JL from 'jsnlog';`) will result in a runtime `TypeError: jsnlog_1.JL is not a function`.fixAlways use a named import for `JL`: `import { JL } from 'jsnlog';`. affects: All versions supporting ESM (likely >=v2)
gotchaEffective client-side logging to a server requires a corresponding server-side handler (e.g., for Node.js, .Net, or PHP). The `jsnlog` npm package only provides the client-side library; server-side integration components (like `jsnlog-nodejs` for Winston) must be separately installed and configured.fixRefer to the JSNLog documentation (jsnlog.com / nodejs.jsnlog.com) for instructions on setting up the appropriate server-side handler for your backend technology.
affects: All versions
Errors
Common errors & fixes
TypeError: jsnlog_1.JL is not a function
Attempting to use `JL()` after importing JSNLog as a default ES module import (e.g., `import JL from 'jsnlog';`).
fixChange the import statement to a named import: `import { JL } from 'jsnlog';`. JL is not defined
The JSNLog library was not loaded or imported correctly in the current scope, or the script tag for client-side usage was placed after code attempting to use `JL`.
fixEnsure JSNLog is either imported using `import { JL } from 'jsnlog';` in a module environment or that `jsnlog.min.js` is included via a `<script>` tag before any code that calls `JL()` in a global script environment. Client-side logs are not appearing in server logs (e.g., Winston files)
The server-side JSNLog handler (e.g., `jsnlog-nodejs`) is not correctly installed, configured, or integrated with your server's logging framework (e.g., Winston), or the client-side `url` option for the AjaxAppender is incorrect.
fixVerify that `jsnlog-nodejs` (or equivalent server-side package) is installed, its middleware is applied to your Express/Koa app, and it's correctly configured to use your Winston logger. Also, confirm the `url` in `JL.setOptions` matches your server's JSNLog endpoint.
Audit
Dependencies
winstonoptionalRequired for Node.js server-side integration to handle and store client-side logs using Winston transports.