Skip to main content

Build and Run Instructions

Why Two Module Formats?​

MagicLogger provides both ESM (.mjs) and CommonJS (.js) entry points to support:

  • ✅ Modern environments using import statements
  • ✅ Legacy environments using require()
  • ✅ Hybrid codebases migrating from CommonJS to ESM
  • ✅ TypeScript projects with different module resolutions

Use whichever format fits your stack — the library supports both seamlessly.

Browser Support​

MagicLogger works in browser-based projects (like React or Vue) with automatic adaptation:

  • Terminal-specific features (e.g., cursor movement) are disabled
  • ANSI styling is adjusted for browser console support
  • File logging is disabled in browser contexts
  • The environment is auto-detected and fallback-safe

Getting Started​

  1. Install dependencies:
npm install
  1. Build the library:
npm run build

This compiles the src files into dist/ with both ESM and CJS outputs.

Development Mode​

Watch mode for rapid iteration:

npm run dev

This runs tsup in watch mode to rebuild on file changes.

Running the Demo​

You can run examples in multiple ways:

node dist/examples/demo.mjs

CommonJS​

node dist/examples/demo.js

Without Building (TS Direct)​

npx ts-node examples/demo.ts

Testing​

Run all tests:

npm test

Run with coverage:

npm run test:coverage

CI uploads the coverage of every push to master and every pull request to Codecov, and the coverage badge in the README reads it there (Test Coverage).

Linting and Formatting​

Format code:

npm run format

Lint code:

npm run lint

Auto-fix lint issues:

npm run lint:fix

Preflight Check (Before Releasing)​

Run a full validation of the build before tagging or publishing:

npm run preflight

This will:

  • Clean build artifacts
  • Run format checks and lint
  • Run all tests
  • Build the output
  • Inject build size stats into README.md

Manual Release Workflow​

  1. Run a preflight check:
npm run preflight
  1. Bump version and generate changelog:
npm run version:bump patch # or minor / major

version:bump stops, and lists them, when anything is staged or when src/, package.json, CHANGELOG.md or README.md has uncommitted changes, preflight's among them (the formatter's in src/, the build-size table in README.md): its release commit would include them. Commit them, then run it again. It fetches the tags from origin, stops when the branch lacks commits on origin/master, and bumps from the highest v* tag on the branch when package.json is behind it, as it is after a release from CI.

  1. Publish, then bring the commit to master through a pull request and push its tag (semantic-release takes the highest v* tag as the last release, so the version reaches npm first, and master refuses a direct push):
npm publish                  # with your own npm login
git push -u origin HEAD      # from a branch, then open and merge the pull request
git push --tags

Merge that pull request with a merge commit, so the tagged commit is on master, and start no release before it lands: until then semantic-release does not see the tag, picks the same version, and npm refuses it.

Or run it all in one step:

npm run release:manual patch

This runs preflight, then version:bump. When preflight changed README.md (its build-size table) or formatted src/, the bump stops: commit those changes, then run npm run version:bump patch.

Troubleshooting​

Common ESM/CJS Issues​

  1. Make sure you're using the correct file extensions:

    • .mjs for ES Modules
    • .js for CommonJS

  2. For older Node.js versions, fall back to CommonJS:

node dist/index.js
  1. If you see errors related to file extensions in import paths, make sure you're using Node 16.11 or later (the engines range in package.json) with "type": "module" in package.json.

Package Structure​

  • src/ — Source TypeScript files
  • dist/index.js — CommonJS build
  • dist/index.mjs — ESM build
  • dist/index.d.ts — TypeScript types
  • examples/ — Example/demo scripts
  • scripts/ — Automation scripts (coverage, versioning, build analysis)
  • tests/ — Unit test files
  • docs/ — Developer documentation