Publishing Workflow for Magiclogger

Project Build & Release Ecosystem

Magiclogger uses a comprehensive set of npm scripts and custom Node.js scripts to manage the entire development, build, test, and release process. This document explains the ecosystem, why each script exists, and how they work together.

Releases from CI

Releases to npm are made by semantic-release in CI (.github/workflows/releases.yml), through the package's trusted publisher, with no npm token. The Deployment & Release Guide covers when it runs, how to run it by hand and how to check a release with a dry run. The scripts below are for local checks and for a release made by hand with your own npm login. A v* tag pushed by hand runs .github/workflows/release.yml, which builds the package and creates the GitHub Release; it does not publish to npm. semantic-release takes the highest v* tag on master as the last release, so push a tag by hand only after npm publish has published that version.

🛠 Scripts Ecosystem

Development Scripts

Script	Purpose	What it Does
npm run dev	Development Watch Mode	Watches source files and rebuilds on changes
npm run check	Code Quality Check	Runs formatting and linting checks
npm run lint	Code Linting	Checks code against ESLint rules
npm run lint:fix	Auto-fix Linting	Automatically fixes linting issues
npm run format	Code Formatting	Formats code using Prettier
npm run test	Run Tests	Executes Jest test suite
npm run test:coverage	Test Coverage	Runs tests and generates coverage report

Build & Preparation Scripts

Script	Purpose	What it Does
npm run clean	Clean Build Artifacts	Removes previous build outputs and temporary files
npm run build	Production Build	Compiles TypeScript to JavaScript for distribution
npm run build:examples	Example Builds	Compiles example scripts
npm run analyze:build	Build Size Analysis	Generates a table of build output sizes in README
npm run preflight	Pre-publish Checks	Comprehensive script running all checks, tests, and builds

Release Management Scripts

Script	Purpose	What it Does
npm run version:bump	Version & Changelog	Bumps version, updates changelog, creates git tag
npm run release:manual	Manual Release	Runs preflight, then the version bump, which stops when preflight changed README.md (its build-size table) or formatted src/: commit those changes, then run npm run version:bump
npm run commit	Conventional Commit	Opens Commitizen for structured commit messages

🔍 Deep Dive: Key Scripts

preflight Script

"preflight": "npm run clean && npm run check && npm run lint && npm run test:coverage && npm run build && npm run analyze:build && npm run test:treeshake"

This script is the guardian of code quality:

1. Cleans previous builds
2. Checks code formatting
3. Runs linting
4. Executes full test suite with coverage
5. Builds the project
6. Analyzes and logs build sizes
7. Runs the tree-shaking test

version:bump Script

Located at scripts/version-bump.cjs, this comprehensive script:

• Validates version bump type (patch/minor/major)
• Stops when anything is staged, or when src/, package.json, CHANGELOG.md or README.md has uncommitted changes, and lists them: its release commit takes the whole index and the files it stages, and npm version runs the package's version script, which formats src/ and stages all of it
• Runs pre-bump checks (tests, linting)
• Fetches the tags from origin and stops when the branch lacks commits on origin/master
• Bumps the package version, from the highest v* tag on the branch when package.json is behind it (semantic-release commits nothing, so package.json on master stays behind the tag)
• Updates README version badge
• Updates CHANGELOG.md with git logs
• Stages and commits changes
• Creates git tag

analyze-build.js Script

Located at scripts/analyze-build.js, this script:

• Measures build output file sizes
• Generates a markdown table
• Injects the table into README.md
• Provides visibility into bundle sizes

Coverage

CI uploads the coverage of every push to master and every pull request to Codecov, and the coverage badge in the README and in Test Coverage reads it there. No script writes a coverage figure into the README or the docs.

🚀 Typical Workflow

1. Development

   npm run dev           # Start development mode
   npm run test          # Run tests
   npm run lint:fix      # Fix any linting issues

2. Before Release

   npm run preflight     # Run comprehensive checks
   npm run version:bump patch  # Bump version (patch/minor/major)

3. Publishing

   npm publish                  # Publish to npm with your own login
   git push -u origin HEAD      # From a branch: master refuses a direct push, so open and merge a pull request
   git push --tags              # Then push the version tag

   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.

🎯 Philosophy

Our scripts aim to:

• Automate repetitive tasks
• Ensure consistent code quality
• Provide transparency in build and release processes
• Reduce manual steps in development workflow

🔒 Best Practices

• Always run preflight before releasing
• Use conventional commit messages
• Ensure all tests pass before bumping version
• Review changelog and README updates before publishing

🆘 Troubleshooting

• If version:bump fails, check:
  • Git is initialized
  • Nothing is staged, and src/, package.json, CHANGELOG.md and README.md have no uncommitted changes (the script lists the ones it finds). After preflight, which writes the build-size table into README.md and formats src/, commit the changes it made there, then run npm run version:bump
  • You have proper npm and git configurations

📦 Extensibility

These scripts are designed to be easily modified. Feel free to:

• Add more pre-release checks
• Extend changelog formatting

---

🚀