Development Guide for Magiclogger

Project Overview

Magiclogger is a fully typed, high-performance logging library built with TypeScript. This guide provides comprehensive instructions for setting up, developing, and contributing to the project.

Prerequisites

Node.js 22 or later recommended (CI and the docs deploy use Node 22; the docs site needs Node 20 or later)
The published library runs on Node.js 16.11 or later, the engines range in package.json: its build keeps class static blocks, which Node parses from 16.11.0. CI's runtime-floor job installs the packed package on that version and loads both entry points, so raise engines with any change that needs a newer Node.
pnpm (preferred). Corepack can enable pnpm automatically.
TypeScript 5.x

Clone the repository and install dependencies (pnpm preferred for lockfile fidelity and speed):

Installation

git clone https://github.com/manicinc/magiclogger.git
cd magiclogger
# Enable corepack if not already
corepack enable
pnpm install

Development Workflow

Available Scripts

Command	Description
`pnpm dev`	Start development (tsup watch)
`pnpm test`	Run test suite
`pnpm test:coverage`	Run tests with coverage report
`pnpm build`	Build ESM + CJS bundles via tsup
`pnpm lint`	Run ESLint on src/tests/examples
`pnpm lint:fix`	Autofix lint issues
`pnpm format`	Format with Prettier
`pnpm format:check`	Verify formatting
`pnpm preflight`	Full validation (format, lint, test, coverage, build, analysis)
`npm run dev`	Start development mode with file watching
`npm test`	Run test suite
`npm run format`	Format code with Prettier
`npm run preflight`	Run comprehensive pre-release checks
View detailed coverage report with:
`pnpm test:coverage`

Testing

CI reports coverage to Codecov on every push to master and every pull request. Test Coverage has the coverage badge and the coverage checks on pull requests.

Branch & Merge Workflow

master is the only long-lived development branch; gh-pages holds the built documentation site.

Flow:

Create feature/fix branches from master (e.g. feat/browser-export).
Open a pull request into master. CI (lint/tests/build) must pass.
Merging updates the draft release notes (Release Drafter). Releases to npm are made by semantic-release; see Version & Release below.
If a pull request should stay out of the release notes (e.g. docs only), add the label skip-release (optionally also skip-changelog).

A dedicated GitHub Action (skip-release-guard.yml) enforces that no version bump or release-style commits occur while this label is present.

Version & Release

semantic-release makes the releases from .github/workflows/releases.yml: it reads the conventional commits since the last v* tag, tags the new version, publishes it to npm through the package's trusted publisher (no npm token) and creates the GitHub Release. A push to master (or main) whose commit message starts with feat, fix, perf or revert, scoped or not, or with Revert " from git revert, or that carries a BREAKING CHANGE: footer under any type the job does not exclude (chore, docs, style, test, ci and build never start it), starts it; after a merge commit, run it by hand:

gh workflow run releases.yml --ref master

To see what the next release would be without making it, run a dry run on any branch:

gh workflow run releases.yml --ref <branch> -f dry_run=true

The Deployment & Release Guide has the details. A v* tag pushed by hand (for example after scripts/version-bump.cjs) builds the package and creates a GitHub Release; it does not publish to npm. semantic-release takes the highest v* tag as the last release, so push one by hand only for a version already on npm.

Preflight checks before opening a pull request:

pnpm preflight

Recommended TypeScript configuration:

Commit Guidelines

We use Conventional Commits for semantic versioning:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Commit Types

Type	Purpose	Version Impact
`feat`	New feature	Minor version bump
`fix`	Bug fix	Patch version bump
`perf`	Performance improvement	Patch version bump
`revert`	Revert of an earlier commit (also `git revert`'s `Revert "..."`)	Patch version bump
`docs`	Documentation changes	No version change
`style`	Code formatting	No version change
`refactor`	Code restructuring	No version change
`test`	Test modifications	No version change
`build`	Build system and dependencies	No version change
`ci`	CI configuration	No version change
`chore`	Maintenance tasks	No version change

Breaking Changes

Indicate a breaking change with a BREAKING CHANGE: footer. The angular preset in .releaserc does not read a ! after the type, so feat!: ... with no footer releases nothing.

Release Process

Checking a Release

See what the next release would be, without publishing, tagging or pushing anything, with a dry run of the Release workflow on your branch:

gh workflow run releases.yml --ref <branch> -f dry_run=true

Preflight Checks

Before any release, run comprehensive checks:

npm run preflight

This script ensures:

Code is formatted
Linting passes
All tests pass
Build succeeds
Coverage requirements met

Contributing

Fork the repository
Create a feature branch
Make your changes
Run npm run preflight
Submit a pull request

TypeScript Support

Magiclogger is built 100% in TypeScript, providing:

Full type safety
Comprehensive type definitions
Intelligent type inference
Zero runtime type overhead

Recommended TypeScript configuration:

{
  "compilerOptions": {
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "declaration": true,
    "declarationMap": true
  }
}

Documentation Site

The documentation site uses Docusaurus and is located in the website directory.

Local Development

cd website
pnpm install
pnpm start  # Starts dev server at http://localhost:3000

Building Documentation

cd website
pnpm build  # Creates static build in website/build

Analytics Configuration

The documentation site includes Google Analytics and Microsoft Clarity for usage tracking.

Analytics are configured via GitHub Secrets only (for security):

Go to Settings → Secrets and variables → Actions
Add GA_TRACKING_ID (Google Analytics Measurement ID)
Add MS_CLARITY_ID (Microsoft Clarity Project ID)

Analytics only work in production deployment via GitHub Actions.

The site includes a minimal cookie consent banner that:

Appears on first visit
Blocks analytics until user consent
Remembers user preference
Styled to match site theme (light/dark mode)

Deploying Documentation

Documentation automatically deploys to GitHub Pages when pushing to main/master branch. The GitHub Actions workflow uses the repository secrets for analytics.

Local Security/Secret Scanning (Optional)

We run Trivy secret scanning in CI. You can mirror this locally to catch issues before pushing:

macOS: brew install trivy
Windows: choco install trivy

Docker (no install):

docker run --rm -v "$PWD":/project -w /project aquasec/trivy:latest fs --scanners secret .

Exit code 1 means potential secrets detected; rotate credentials and purge from history if confirmed.

Project Overview​

Prerequisites​

Installation​

Development Workflow​

Available Scripts​

Testing​

Branch & Merge Workflow​

Version & Release​

Commit Guidelines​

Commit Types​

Breaking Changes​

Release Process​

Checking a Release​

Preflight Checks​

Contributing​

TypeScript Support​

Documentation Site​

Local Development​

Building Documentation​

Analytics Configuration​

GDPR Compliance​

Deploying Documentation​

Local Security/Secret Scanning (Optional)​