nagare

Nagare (流れ) - Deno Release Management

Nagare means “flow” in Japanese - reflecting the smooth, automated flow from commits to releases.

JSR JSR Score License: MIT API Documentation Test Coverage Tests

A comprehensive, Deno-native release management library that automates version bumping, changelog generation, and GitHub releases using conventional commits and semantic versioning.

🚀 Quick Start (for the impatient)

Don’t want to read the docs? Just run this:

# Initialize Nagare in your project
deno run -A jsr:@rick/nagare/cli init

# Add to your deno.json (copy from init output)
{
  "tasks": {
    "nagare": "deno run -A nagare-launcher.ts",
    "nagare:minor": "deno task nagare minor",
    "nagare:patch": "deno task nagare patch"
  }
}

# Create your first release
deno task nagare

That’s it! Nagare will analyze your conventional commits and create a release automatically. Read on for details, or jump to full documentation.

What is Nagare?

Nagare (流れ - “flow”) provides intelligent release management for Deno projects. Install once, use everywhere. Rather than forcing you to manage versions manually, Nagare analyzes your git history and automatically determines the right version bump based on conventional commits - all while maintaining professional changelogs and GitHub releases.

📚 Documentation & Resources

🎯 Interactive Release Workflows (with Visual Diagrams)

📖 Complete Documentation

🔗 Quick Links

📦 JSR Package 🐙 GitHub Repository

✨ Key Features:

Installation Details

# Initialize Nagare in your project
deno run -A jsr:@rick/nagare/cli init

This single command will:

Configuration Example

import type { NagareConfig } from "jsr:@rick/nagare/types";

export default {
  project: {
    name: "My App",
    repository: "https://github.com/user/my-app",
    description: "A fantastic Deno application",
  },

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

  github: {
    owner: "user",
    repo: "my-app",
    createRelease: true,
  },

  // Automatic file updates - just specify the files!
  updateFiles: [
    { path: "./deno.json" },
    { path: "./package.json" },
    { path: "./README.md" },
    { path: "./jsr.json" },
  ],
} as NagareConfig;

How It Works

Nagare uses a 3-phase release system that ensures reliable, professional releases:

🔍 Analysis Phase

When you run deno task nagare, Nagare analyzes your git history since the last release, parsing conventional commits to determine the appropriate version bump.

🔧 Build Phase

Nagare updates all configured files using intelligent handlers, generates professional changelogs, and creates git tags with proper metadata.

📤 Publish Phase

Finally, Nagare pushes changes to GitHub and creates releases with detailed release notes, ensuring your users always know what’s new.

Usage Examples

Basic Release Management

# Automatic version bump based on conventional commits
deno task nagare

# Force specific version bumps
deno task nagare patch   # 1.0.0 → 1.0.1
deno task nagare minor   # 1.0.0 → 1.1.0
deno task nagare major   # 1.0.0 → 2.0.0

# Preview changes without making them
deno task nagare --dry-run

# Skip confirmation prompts (for CI)
deno task nagare --skip-confirmation

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}!`);
  console.log(`📦 ${result.commitCount} commits included`);
  console.log(`🔗 ${result.githubReleaseUrl}`);
}

🤖 Intelligent File Handlers

Nagare includes built-in handlers for common file types, eliminating the need for custom patterns:

Supported Files:

Simple Configuration:

// ✅ Just specify the file - Nagare handles the rest!
updateFiles: [
  { path: "./deno.json" },
  { path: "./package.json" },
  { path: "./README.md" },
];

🔀 PR-Aware Changelogs (New in v2.19.0!)

Nagare now automatically detects Pull Requests and organizes your changelog accordingly:

With PRs:

### Add authentication system (#123)

#### Added

- Implement JWT tokens (auth) (abc1234)
- Add login endpoint (api) (def5678)

Without PRs: Falls back to traditional format automatically.

Zero configuration required! Just works with your existing workflow. See PR-Aware Changelogs Documentation for details.

🛡️ Security & Reliability

Security-First Design

Reliability Features

🌐 Language Support

Nagare supports both English and Japanese interfaces:

# Use Japanese interface
deno task nagare --lang ja

# Set environment variable
export NAGARE_LANG=ja
deno task nagare

📋 Requirements

Architecture

Nagare uses a modular architecture with specialized components:

For detailed architecture diagrams and visual workflows, see the Architecture Overview and Release Workflow Guide.

Template System

Nagare uses a powerful template system for version files:

// TypeScript template (default)
export const VERSION = "";
export const BUILD_INFO = {
  buildDate: "",
  gitCommit: "",
};

// Custom template example
template: 'custom',
customTemplate: `
export const APP_VERSION = "";
export const FEATURES = ;
export const CHANGELOG = ;
`

🤝 Community & Support

Getting Help

Contributing

Additional Resources

Project Documentation

External Resources

License

Nagare is released under the MIT License.

🙏 Acknowledgments

Nagare was extracted and generalized from the Salty project’s sophisticated release automation system. Special thanks to the Deno team for creating an excellent TypeScript runtime.

Made with ❤️ by eSolia for the Deno community

This site is open source. Improve this page.