aemeath-js

aemeath-js

A pure frontend logging & monitoring SDK. The frontend does the heavy lifting — your backend just stores and cleans up.

English | 中文

v2.0 Beta Available — Multi-platform support (browsers + WeChat / Alipay / Douyin / Baidu mini-programs + Taro / uni-app). Install with npm install aemeath-js@beta. See what's new →

What it does

Error tracking, log management, and performance monitoring — all handled in the browser. Your backend only needs to receive and store the data.

• 🌲 Tree-shakable — Import what you need. Unused code is never bundled.
• 🔓 Frontend-driven — Queuing, retry, caching, and deduplication run client-side.
• 🌐 Framework support — React, Vue, vanilla JS, jQuery.
• 🔧 Build tool support — Vite, Webpack 4+, Rsbuild.

Installation

npm install aemeath-js

yarn add aemeath-js
# or
pnpm add aemeath-js

Quick Start

// Initialize once (e.g. in main.ts)
import { initAemeath } from 'aemeath-js';

initAemeath({
  upload: async (log) => {
    const res = await fetch('/api/logs', {
      method: 'POST',
      body: JSON.stringify(log),
    });
    const data = await res.json();
    return data.code === 200
      ? { success: true }
      : { success: false, shouldRetry: true, error: data.message };
  },
  context: {
    userId: '12345',
    appVersion: '1.0.0',
  },
});

// Use anywhere
import { getAemeath } from 'aemeath-js';

const logger = getAemeath();
logger.info('User logged in');
logger.error('Something went wrong', { error });
logger.updateContext('userId', '67890');

What's included by default? initAemeath() automatically enables the following plugins. No extra .use() needed:

💡 Need more capabilities? You can still .use() additional plugins on the singleton at any time. Duplicate .use() calls are safely ignored — if a plugin is already installed, it won't be added again.

Browser (No Build Tools)

For jQuery, vanilla JS, or static HTML pages — no npm required:

<script src="https://unpkg.com/aemeath-js/dist/aemeath-js.global.js"></script>
<script>
  AemeathJs.init({
    upload: function(log) {
      fetch('/api/logs', { method: 'POST', body: JSON.stringify(log) });
    }
  });

  var logger = AemeathJs.getAemeath();
  logger.info('Page loaded');
</script>

Plugins

All plugins are optional. Only import what you need — unused plugins are tree-shaken away.

Need to control plugin execution order? See Plugin Ordering (priority field).

Reliable delivery (1.10.1)

With upload configured, offlinePolicy: 'pause' and offline persistence are enabled by default; opt out with offlinePersistence: false or restore 1.10.0 retry behavior with queue: { offlinePolicy: 'legacy' }. 1.10.1 also parses HTTP Retry-After, exposes a unified getDeliveryStatus(), and supports true runtime pause through setUpload(null).

Multi-tab delivery can still repeat a stable logId. Your backend must deduplicate on (project/tenant scope, logId); requestId changes on every attempt. See Upload Plugin and Offline Persistence.

beforeSend — privacy & redaction

import { initAemeath } from 'aemeath-js';

initAemeath({
  upload: async (log) => { /* ... */ },
  // Modify, drop, or pass through every log entry (incl. auto-captured network logs).
  // NetworkPlugin tags network logs as `errorCategory: 'http'` and writes
  // url / requestData / responseData on `entry.context` (see docs/en/9-before-send.md).
  beforeSend: (entry) => {
    if (entry.tags?.errorCategory === 'http' && entry.context) {
      return {
        ...entry,
        context: {
          ...entry.context,
          requestData: '[REDACTED]',
          responseData: '[REDACTED]',
        },
      };
    }
    return entry;
  },
});

Return null to drop the entry entirely. See docs/en/9-before-send.md for full reference.

Framework Integrations

⚠️ Important: Always call initAemeath() first in your app entry (e.g. main.ts). The framework integrations below do not replace initialization — they simply provide convenient ways to access the same singleton instance within your components.

// main.tsx — Step 1: Initialize (same as Quick Start)
import { initAemeath } from 'aemeath-js';

initAemeath({
  upload: async (log) => { /* ... */ return { success: true }; },
});

// App.tsx — Step 2: Use framework integration
import { AemeathErrorBoundary, useAemeath } from 'aemeath-js/react';

function App() {
  return (
    <AemeathErrorBoundary
      fallback={(error, reset) => (
        <div>
          <p>Error: {error.message}</p>
          <button onClick={reset}>Retry</button>
        </div>
      )}
    >
      <MyApp />
    </AemeathErrorBoundary>
  );
}

// useAemeath() returns the same instance created by initAemeath()
function MyComponent() {
  const logger = useAemeath();
  logger.info('Component mounted');
  return <div>...</div>;
}

// main.ts — Step 1: Initialize (same as Quick Start)
import { createApp } from 'vue';
import { initAemeath } from 'aemeath-js';
import { createAemeathPlugin } from 'aemeath-js/vue';

initAemeath({
  upload: async (log) => { /* ... */ return { success: true }; },
});

const app = createApp(App);
app.use(createAemeathPlugin({ captureWarnings: true }));
app.mount('#app');

<!-- MyComponent.vue — Step 2: useAemeath() returns the same singleton -->
<script setup>
import { inject } from 'vue';
import { useAemeath } from 'aemeath-js/vue';

const logger = useAemeath(inject);
logger.info('Component setup');
</script>

Build Tool Plugins

// vite.config.ts
import { ameathEarlyErrorPlugin } from 'aemeath-js/build-plugins/vite';
import { ameathViteSourceMapPlugin } from 'aemeath-js/build-plugins/vite-sourcemap';

export default defineConfig({
  build: { sourcemap: true },
  plugins: [
    ameathEarlyErrorPlugin({ enabled: true }),
    ameathViteSourceMapPlugin({
      onUpload: async (file) => {
        await fetch('/api/sourcemaps', { method: 'POST', body: file.content });
      },
      deleteAfterUpload: true,
    }),
  ],
});

// webpack.config.js
const { AemeathEarlyErrorWebpackPlugin } = require('aemeath-js/build-plugins/webpack');
const { AemeathSourceMapWebpackPlugin } = require('aemeath-js/build-plugins/webpack-sourcemap');

module.exports = {
  devtool: 'source-map',
  plugins: [
    new AemeathEarlyErrorWebpackPlugin({ enabled: true }),
    new AemeathSourceMapWebpackPlugin({
      onUpload: async (file) => {
        await fetch('/api/sourcemaps', { method: 'POST', body: file.content });
      },
    }),
  ],
};

// rsbuild.config.ts
import { ameathEarlyErrorPlugin } from 'aemeath-js/build-plugins/rsbuild';
import { ameathSourceMapPlugin } from 'aemeath-js/build-plugins/rsbuild-sourcemap';

export default defineConfig({
  output: { sourceMap: { js: 'source-map' } },
  plugins: [
    ameathEarlyErrorPlugin({ enabled: true }),
    ameathSourceMapPlugin({
      onUpload: async (file) => {
        await fetch('/api/sourcemaps', { method: 'POST', body: file.content });
      },
    }),
  ],
});

Bundle Size

Custom Plugin

import type { AemeathPlugin, AemeathInterface } from 'aemeath-js';

class MyPlugin implements AemeathPlugin {
  readonly name = 'my-plugin';
  readonly version = '1.0.0';

  install(logger: AemeathInterface) {
    logger.on('log', (entry) => {
      // your custom logic
    });
  }

  uninstall(logger: AemeathInterface) {
    // cleanup
  }
}

logger.use(new MyPlugin());

Documentation

📖 中文文档：查看中文 README | 快速开始 | 模块文档

Compatibility

Browser

All packages (ESM, CJS, IIFE) are built with ES2017 target and can run directly in the following browsers:

Supporting Older Browsers (Chrome < 64)

If your browserslist includes browsers older than the versions listed above, you need to add aemeath-js to your build tool's transpilation scope:

Rsbuild / Rspack

// rsbuild.config.ts
export default defineConfig({
  source: {
    include: [/[\\/]node_modules[\\/]aemeath-js[\\/]/],
  },
});

Webpack

// webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\.m?js$/,
        include: [
          path.resolve(__dirname, 'src'),
          /node_modules[\\/]aemeath-js/,
        ],
        use: {
          loader: 'babel-loader',
          options: {
            presets: [['@babel/preset-env', { targets: '> 0.5%, not dead' }]],
          },
        },
      },
    ],
  },
};

Vite

Vite uses esbuild which skips node_modules by default. For production builds targeting legacy browsers, use @vitejs/plugin-legacy:

// vite.config.ts
import legacy from '@vitejs/plugin-legacy';

export default defineConfig({
  plugins: [
    legacy({
      targets: ['Chrome >= 49'],
    }),
  ],
});

Next.js

// next.config.js
module.exports = {
  transpilePackages: ['aemeath-js'],
};

Node.js

Build Tools

Frameworks

Module Formats

Also Check Out

If you need session recording & user behavior replay, check out sigillum-js — a lightweight session recording library.

Together, aemeath-js (logging & monitoring) + sigillum-js (session replay) provide a complete frontend observability solution — all data stays on your own servers.

Contributing

Issues and feature requests are welcome! Feel free to open an issue.

License

MIT © TieriaSail

Built with AI assistance.