Nagare (流れ) - Deno Release Management Library documentation

Nagare (流れ) is a comprehensive release management library for JavaScript/TypeScript projects that automates version bumping, changelog generation, and GitHub releases using conventional commits and semantic versioning.

Nagare	Specifications
Version	2.20.1
Repository	https://github.com/RickCogley/nagare
JSR Package	https://jsr.io/@rick/nagare
Documentation	https://nagare.esolia.deno.net
License	MIT
Author	Rick Cogley, eSolia Inc.

Core Features

🚀 Automated Releases - Version calculation based on conventional commits
📝 Changelog Generation - Automatic CHANGELOG.md following Keep a Changelog format
🏷️ Git Integration - Smart tagging and commit management
🐙 GitHub Releases - Automatic GitHub release creation via CLI
🤖 Intelligent File Handlers - Automatic version updates for common file types (v1.1.0+)
📄 Template System - Flexible version file templates (TypeScript, JSON, YAML, custom)
✨ Extensible Version Files - Add custom exports without full templates (v1.8.0+)
🔄 Rollback Support - Safe rollback of failed releases
🛡️ Type-Safe - Full TypeScript support with comprehensive types
🌐 Multi-Language - English and Japanese interfaces (v2.4.0+)

Quick Start

Examples

Initialize Nagare in your project

deno run -A jsr:@rick/nagare/cli init

Basic programmatic usage

import { ReleaseManager } from "jsr:@rick/nagare";

const config = {
  project: {
    name: "My App",
    repository: "https://github.com/user/my-app"
  },
  versionFile: {
    path: "./version.ts",
    template: "typescript"
  }
};

const releaseManager = new ReleaseManager(config);
const result = await releaseManager.release();

if (result.success) {
  console.log(`Released version ${result.version}`);
}

Architecture Overview

Nagare follows a layered architecture with clear separation of concerns:

┌─────────────────────────────────────────┐
│            CLI Interface                │  ← User entry point
├─────────────────────────────────────────┤
│          Manager Layer                  │  ← Orchestration
│  ReleaseManager  │  RollbackManager     │
├─────────────────────────────────────────┤
│        Integration Layer                │  ← External systems
│ GitOperations │ GitHubIntegration │ ... │
├─────────────────────────────────────────┤
│        Processing Layer                 │  ← Data transformation
│ TemplateProcessor │ ChangelogGen │ ...  │
├─────────────────────────────────────────┤
│       Infrastructure Layer              │  ← Foundation
│    Logger    │   Config   │   Types    │
└─────────────────────────────────────────┘

Intelligent File Handlers (v1.1.0+)

Nagare includes built-in handlers that automatically detect and update common file types:

Simple file updates with built-in handlers

updateFiles: [
  { path: "./deno.json" },     // Automatically handled
  { path: "./package.json" },  // Automatically handled
  { path: "./README.md" },     // Updates badges and version references
  { path: "./jsr.json" }       // Automatically handled
]

Conventional Commits

Nagare analyzes commit messages to determine version bumps:

feat: → Minor version bump (1.0.0 → 1.1.0)
fix: → Patch version bump (1.0.0 → 1.0.1)
feat!: or BREAKING CHANGE: → Major version bump (1.0.0 → 2.0.0)
Other types → Patch version bump

Extensible Version Files (v1.8.0+)

Add custom exports to generated version files without writing full templates:

Additional exports configuration

versionFile: {
  path: "./version.ts",
  template: "typescript",

  // Add custom exports
  additionalExports: [
    {
      name: "API_CONFIG",
      type: "const",
      value: { baseUrl: "https://api.example.com", timeout: 5000 },
      description: "API configuration",
      asConst: true
    },
    {
      name: "Utils",
      type: "class",
      content: `
  static formatVersion(): string {
    return \`v\${VERSION}\`;
  }`
    }
  ],

  // Or add raw content
  extend: {
    prepend: "// Auto-generated file\\n\\n",
    append: "\\n// End of generated content"
  }
}

Advanced Usage

Custom file handler

import { FileHandlerManager } from "jsr:@rick/nagare";

const fileHandler = new FileHandlerManager();
fileHandler.registerHandler({
  id: "custom-config",
  name: "Custom Config Handler",
  detector: (filepath) => filepath.endsWith(".custom"),
  patterns: {
    version: /version:\s*"([^"]+)"/
  }
});

Custom version template

versionFile: {
  path: "./version.ts",
  template: "custom",
  customTemplate: `
export const VERSION = "{{version}}";
export const BUILD_DATE = "{{buildDate}}";
export const FEATURES = {{metadata.features | jsonStringify}};
`
}

Custom updateFn for complex replacements

// For files with special formatting like markdown tables
updateFiles: [{
  path: "./mod.ts",
  patterns: {
    version: /(\| Version \| )([^\s]+)( \|)/,
  },
  updateFn: (content: string, data: TemplateData) => {
    // Preserve table structure while updating only the version
    return content.replace(
      /(\| Version \| )([^\s]+)( \|)/,
      `$1${data.version}$3`
    );
  },
}]