JSNLog.js

Common errors

• TypeError: jsnlog_1.JL is not a function

  cause Attempting to use `JL()` after importing JSNLog as a default ES module import (e.g., `import JL from 'jsnlog';`).
  fix Change the import statement to a named import: `import { JL } from 'jsnlog';`.

• JL is not defined

  cause 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`.
  fix Ensure 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)

  cause 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.
  fix Verify 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.

Warnings

• gotcha JSNLog 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.
  Fix: Be 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.
• breaking When 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`.
  Fix: Always use a named import for `JL`: `import { JL } from 'jsnlog';`.
• gotcha Effective 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.
  Fix: Refer to the JSNLog documentation (jsnlog.com / nodejs.jsnlog.com) for instructions on setting up the appropriate server-side handler for your backend technology.

Install

• npm install jsnlog npm
• yarn add jsnlog yarn
• pnpm add jsnlog pnpm

Imports

• JL
  wrong:

  import JL from 'jsnlog';

  correct:

  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)
  wrong:

  const JSNLog = require('jsnlog'); JSNLog.JL().debug('message');

  correct:

  const JL = require('jsnlog').JL;

  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.

Quickstart

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.