@docs-islands/logger

@docs-islands/logger is the framework-agnostic logger package for docs-islands projects. Its root entry is intentionally small:

import { createLogger, setLoggerConfig } from '@docs-islands/logger';

Use it when code is not inside a controlled VitePress createDocsIslands() graph, such as standalone scripts, shared packages, examples, or documentation-site utilities.

Runtime Demo

The demo below imports the real package from this docs site. Pick a runtime config and run the scenario; the component captures the console calls produced by createLogger().

Runtime logger demo

Default visibility keeps info, success, warn, and error; debug stays hidden.

Active config

null

Captured output

Run a scenario to capture logger output here.

Runtime API

Create a main logger, then derive a group logger:

import { createLogger, setLoggerConfig } from '@docs-islands/logger';

setLoggerConfig({
  debug: true,
  levels: ['info', 'warn', 'error'],
});

const logger = createLogger({ main: 'my-package' }).getLoggerByGroup('build');

logger.info('build started', { elapsedTimeMs: 12 });
logger.warn('cache is cold', { elapsedTimeMs: 18 });
logger.debug('debug is visible only when debug is enabled');

setLoggerConfig() updates the default runtime scope. Pass null when a page, test, or script should restore the default behavior.

Tree-Shaking Plugin

The plugin entry lives under @docs-islands/logger/plugin:

import { loggerPlugin } from '@docs-islands/logger/plugin';

export default {
  vite: {
    plugins: [loggerPlugin.vite()],
  },
};

The docs site uses this plugin during docs:build. A small static debug fixture is imported by the demo component, so production builds exercise compile-time pruning without changing the interactive runtime demo.

loggerPlugin enables treeshake by default. In build mode, treeshake: true lets the plugin remove statically provable logger calls that are hidden by the resolved logger config. Set treeshake: false when a build should keep every logger call and only rely on runtime filtering:

import { loggerPlugin } from '@docs-islands/logger/plugin';

export default {
  vite: {
    plugins: [
      loggerPlugin.vite({
        treeshake: false,
      }),
    ],
  },
};

The plugin only removes statically provable calls. Dynamic messages, variable groups, aliases, destructured methods, and indirect wrappers are kept.

Boundary With VitePress

Use @docs-islands/logger for generic runtime logging. Use @docs-islands/vitepress/logger only inside the controlled VitePress integration, where createDocsIslands({ logging }) owns the logger scope.