Aegir

Aegir is an opinionated JavaScript/TypeScript project management tool that streamlines build, test, lint, and release workflows. It provides pre-configured tooling for modern JS/TS development with minimal setup, targeting developers who want to ship working code without configuring individual build tools.

Package Information

• Package Name: aegir
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: npm install aegir

Core Imports

Aegir is primarily used as a CLI tool, but also provides testing utilities:

// Testing utilities (programmatic use)
import { expect, assert } from 'aegir/chai';
import EchoServer from 'aegir/echo-server';
import loadFixtures from 'aegir/fixtures';
import getPort from 'aegir/get-port';
import resolve from 'aegir/resolve';
import { isNode, isBrowser } from 'aegir/env';

CommonJS:

const { expect, assert } = require('aegir/chai');
const EchoServer = require('aegir/echo-server');
const loadFixtures = require('aegir/fixtures');
const getPort = require('aegir/get-port');
const resolve = require('aegir/resolve');
const { isNode, isBrowser } = require('aegir/env');

Basic Usage

CLI Usage

# Build project
aegir build

# Run tests in multiple environments
aegir test
aegir test --target node
aegir test --target browser

# Lint code
aegir lint

# Generate documentation
aegir docs

# Release package
aegir release

Testing Utilities

import { expect } from 'aegir/chai';
import EchoServer from 'aegir/echo-server';
import { isNode } from 'aegir/env';

// Testing with enhanced Chai
expect('hello').to.be.a('string');

// HTTP testing server
const server = new EchoServer();
await server.start();
// Server available at http://127.0.0.1:3000
await server.stop();

// Environment detection
if (isNode) {
  // Node.js specific code
}

Architecture

Aegir is built around several key components:

• CLI Interface: Yargs-based command system with 17 commands for different development tasks
• Build System: esbuild-based bundling with TypeScript support and browser compatibility
• Testing Framework: Multi-environment test runner supporting Node.js, browsers, WebWorkers, and Electron
• Configuration System: Unified configuration via .aegir.js files or package.json properties
• Utility Library: Testing helpers and environment detection for cross-platform development
• Release Automation: Semantic release integration with automated versioning and publishing

Capabilities

Project Building

Build system with esbuild integration, TypeScript compilation, and browser bundle generation. Includes bundle size analysis and optimization features.

// CLI command: aegir build [options]
// Options: --bundle, --bundlesize, --types

Build System

Testing Framework

Multi-environment test runner supporting Node.js, browsers, WebWorkers, Electron, and React Native. Includes coverage reporting and watch mode.

// CLI command: aegir test [options]
// Options: --target, --watch, --cov, --grep, --timeout

Testing

Code Quality Tools

Integrated linting with ESLint, spell checking, dependency validation, package.json validation, and project maintenance.

// CLI commands:
// aegir lint [options]
// aegir spell-check
// aegir dependency-check
// aegir lint-package-json
// aegir clean [files..]

Code Quality

Documentation Generation

TypeDoc-based documentation generation with GitHub Pages publishing support.

// CLI command: aegir docs [options]
// Options: --publish, --entryPoint, --directory

Documentation

Release Management

Automated semantic releases with version bumping, changelog generation, and npm publishing.

// CLI commands:
// aegir release [options]
// aegir release-rc [options]

Release Management

Testing Utilities

Pre-configured testing utilities including enhanced Chai assertions, HTTP echo server, fixture loading, and environment detection.

// Import paths:
// aegir/chai - Enhanced Chai with plugins
// aegir/echo-server - HTTP testing server
// aegir/fixtures - Test fixture loader
// aegir/get-port - Port finder utility
// aegir/resolve - Path resolution utility
// aegir/env - Environment detection

Testing Utilities

Monorepo Support

Commands for managing monorepo projects including cross-package command execution and dependency alignment.

// CLI commands:
// aegir exec <command>
// aegir run <script>
// aegir align-versions
// aegir test-dependant

Monorepo Tools

Configuration

Aegir supports configuration via .aegir.js files or aegir property in package.json:

interface Options {
  debug: boolean;
  build: BuildOptions;
  test: TestOptions;
  lint: LintOptions;
  docs: DocsOptions;
  release: ReleaseOptions;
  // ... other command options
}

Configuration File Exports

Aegir provides pre-configured configuration files for common tools:

// TypeScript base configuration
import 'aegir/src/config/tsconfig.aegir.json';

// ESLint configuration (also documented in Code Quality section)
import aegirEslintConfig from 'aegir/eslint.config.js';

Project Structure Requirements

Aegir enforces a specific project structure:

• Source: src/ directory with src/index.js or src/index.ts entry point
• Tests: test/ directory with .spec.js/.spec.ts files
• Build Output: dist/ directory for compiled code
• Configuration: .aegir.js file or aegir property in package.json