Milkee

English | 日本語

A simple CoffeeScript build tool with coffee.config.cjs

Official site: https://milkee.org

How to get started

Install

Install Milkee:

# global installation
npm i -g milkee

# or local installation
npm i -D milkee

CoffeeScript & @babel/core are required.

[!TIP] @babel/core is required if options.transpile is true .

# global installation
npm i -g coffeescript @babel/core

# or local installation
npm i -D coffeescript @babel/core

Setup

Run -s (--setup) command, generate coffee.config.cjs!

# global
milkee -s

# or local
npx milkee -s

coffee.config.cjs

/** @type {import('@milkee/d').Config} */

module.exports = {
  // The entry point for compilation.
  // This can be a single file or a directory (e.g., 'src/' or 'src/app.coffee').
  entry: 'src',
  // The output for the compiled JavaScript files.
  // If 'options.join' is true, this should be a single file path (e.g., 'dist/app.js').
  // If 'options.join' is false, this should be a directory (e.g., 'dist').
  output: 'dist',
  // (Optional) Additional options for the CoffeeScript compiler.
  // See `coffee --help` for all available options.
  // Web: https://coffeescript.org/annotated-source/command.html
  options: {
    // The following options are supported:
    // bare: false,
    // join: false,
    // map: false,
    // inlineMap: false,
    // noHeader: false,
    // transpile: false,
    // literate: false,
    // watch: false,
  },
  // (Optional) Additional options/plugins for the Milkee builder.
  milkee: {
    options: {
      // Before compiling, reset the directory.
      // refresh: false,
      // Before compiling, prompt "Do you want to Continue?".
      // confirm: false,
      // After compiling, copy non-coffee files from entry to output directory. (Only works when options.join is false)
      // copy: false,
    },
    plugins: []
  },
};

options (CoffeeScript Compiler Options)

These options are passed directly to the coffee compiler.

Option	Type	Default	Description
bare	boolean	false	compile without a top-level function wrapper
join	boolean	false	concatenate the source CoffeeScript before compiling
map	boolean	false	generate source map and save as .js.map files
inlineMap	boolean	false	generate source map and include it directly in output
noHeader	boolean	false	suppress the "Generated by" header
transpile	boolean	false	pipe generated JavaScript through Babel
literate	boolean	false	treat stdio as literate style coffeescript
watch	boolean	false	watch scripts for changes and rerun commands

CoffeeScript - command.coffee

milkee.options (Milkee Specific Options)

These options control Milkee's behavior.

Option	Type	Default	Description
refresh	boolean	false	Before compiling, reset the output directory.
confirm	boolean	false	Before compiling, prompt "Do you want to Continue?".
copy	boolean	false	After compiling, copy non-coffee files from entry to output directory. (Only works when options.join is false)

milkee.plugins (Milkee Specific Plugins)

You can extend Milkee's functionality by using plugins. Plugins are simple functions that run after each successful compilation, giving you access to the compiled files and configuration.

Example:

const myPlugin = require('./plugins/my-plugin.js');

module.exports = {
  // ...
  milkee: {
    plugins: [
      // This call returns the PluginExecutor
      myPlugin({ option: 'value' }),
      // ...
    ]
  }
}

Compile

Milkee will automatically read coffee.config.cjs, assemble the command from your options, and start compilation!

# global
milkee

# or local
npx milkee

Creating a Plugin

Want to create your own Milkee plugin? Check out the plugin documentation:

• English
• 日本語

Milkee

English | 日本語

coffee.config.cjs を使ったシンプルな CoffeeScript ビルドツール

公式サイト: https://milkee.org

はじめに

インストール

Milkee をインストールします:

# グローバルインストール
npm i -g milkee

# ローカルインストール
npm i -D milkee

CoffeeScript と @babel/core が必要です。

[!TIP] options.transpile が true の場合は @babel/core が必要です。

# グローバルインストール
npm i -g coffeescript @babel/core

# ローカルインストール
npm i -D coffeescript @babel/core

セットアップ

-s (--setup) コマンドを実行すると、coffee.config.cjs が生成されます！

# グローバル
milkee -s

# ローカル
npx milkee -s

coffee.config.cjs

/** @type {import('@milkee/d').Config} */

module.exports = {
  // コンパイルのエントリーポイント。
  // 単一ファイルまたはディレクトリ（例: 'src/' や 'src/app.coffee'）を指定できます。
  entry: 'src',
  // コンパイルされた JavaScript ファイルの出力先。
  // `options.join` が true の場合は単一ファイルパス（例: 'dist/app.js'）
  // `options.join` が false の場合はディレクトリ（例: 'dist'）を指定します。
  output: 'dist',
  // (任意) CoffeeScript コンパイラの追加オプション。
  // 利用可能な全オプションは `coffee --help` を参照してください。
  // Web: https://coffeescript.org/annotated-source/command.html
  options: {
    // 以下のオプションがサポートされています:
    // bare: false,
    // join: false,
    // map: false,
    // inlineMap: false,
    // noHeader: false,
    // transpile: false,
    // literate: false,
    // watch: false,
  },
  // (任意) Milkee ビルダーの追加オプション / プラグイン。
  milkee: {
    options: {
      // コンパイル前に出力ディレクトリをリセットします。
      // refresh: false,
      // コンパイル前に「実行しますか？」と確認します。
      // confirm: false,
      // コンパイル後に entry から output へ非 CoffeeScript ファイルをコピーします。（`options.join` が false の場合のみ有効）
      // copy: false,
    },
    plugins: []
  },
};

options (CoffeeScript コンパイラオプション)

これらのオプションは coffee コンパイラに直接渡されます。

オプション	型	デフォルト	説明
bare	boolean	false	トップレベルの関数ラッパーなしでコンパイルする
join	boolean	false	コンパイル前にソースを連結する
map	boolean	false	ソースマップを生成して .js.map として保存する
inlineMap	boolean	false	ソースマップを生成して出力内に直接含める
noHeader	boolean	false	"Generated by" ヘッダを抑制する
transpile	boolean	false	生成された JavaScript を Babel に通す
literate	boolean	false	標準入力をリテラート形式の CoffeeScript として扱う
watch	boolean	false	ファイル変更を監視してコマンドを再実行する

CoffeeScript - command.coffee

milkee.options (Milkee 固有オプション)

これらのオプションは Milkee の動作を制御します。

オプション	型	デフォルト	説明
refresh	boolean	false	コンパイル前に出力ディレクトリをリセットする
confirm	boolean	false	コンパイル前に「実行しますか？」と確認する
copy	boolean	false	コンパイル後に entry から output へ非 CoffeeScript ファイルをコピーする（options.join が false の場合のみ）

milkee.plugins (Milkee 固有プラグイン)

Milkee の機能はプラグインで拡張できます。プラグインは、各コンパイル成功後に実行され、コンパイル済みファイルと設定にアクセスできる単純な関数です。

例:

const myPlugin = require('./plugins/my-plugin.js');

module.exports = {
  // ...
  milkee: {
    plugins: [
      // この呼び出しは PluginExecutor を返します
      myPlugin({ option: 'value' }),
      // ...
    ]
  }
}

コンパイル

Milkee は自動で coffee.config.cjs を読み、options からコマンドを組み立ててコンパイルを開始します！

# グローバル
milkee

# ローカル
npx milkee

プラグインの作成

独自の Milkee プラグインを作成したいですか？プラグインのドキュメントを確認してください:

• English
• 日本語

Creating a Milkee Plugin

English | 日本語

Extend Milkee's functionality with custom plugins.

Quick Start

Run -p (--plugin) command to set up your plugin project:

# global
milkee -p

# or local
npx milkee -p

This will:

1. Initialize package.json (if needed)
2. Install dependencies (consola, coffeescript, milkee)
3. Create template files
4. Update package.json (main, scripts, keywords)

Project Structure

your-plugin/
  src/
    main.coffee    # Your plugin source
  dist/
    main.js        # Compiled output
  .github/
    workflows/
      publish.yml  # npm publish workflow
  coffee.config.cjs
  package.json

Writing Your Plugin

Basic Template

fs = require 'fs'
path = require 'path'
consola = require 'consola'

pkg = require '../package.json'
PREFIX = "[#{pkg.name}]"

# Custom logger with prefix
c = {}
for method in ['log', 'info', 'success', 'warn', 'error', 'debug', 'start', 'box']
  do (method) ->
    c[method] = (args...) ->
      if typeof args[0] is 'string'
        args[0] = "#{PREFIX} #{args[0]}"
      consola[method] args...

# Main plugin function
main = (compilationResult) ->
  { config, compiledFiles, stdout, stderr } = compilationResult

  c.info "Compiled #{compiledFiles.length} file(s)"
  for file in compiledFiles
    c.log "  - #{file}"

module.exports = main

Compilation Result

Milkee passes this object to your plugin after compilation:

Property	Type	Description
config	object	Full config from coffee.config.cjs
compiledFiles	string[]	Paths to compiled .js and .js.map files
stdout	string	Compiler standard output
stderr	string	Compiler standard error

Using in coffee.config.cjs

const myPlugin = require('your-plugin-name');

module.exports = {
  entry: 'src',
  output: 'dist',
  milkee: {
    plugins: [
      myPlugin({ customOption: 'value' }),
    ]
  }
};

Build & Test

# Build your plugin
npm run build

# Link for local testing
npm link

# In another project
npm link your-plugin-name

Publishing

Using GitHub Actions

The included workflow publishes to npm manually:

1. Add NPM_TOKEN secret to your repository
2. Go to Actions → Manual Publish to npm
3. Click Run workflow

Manual

npm run build
npm publish --access public

Best Practices

Naming & Keywords

• Name: milkee-plugin-xxx or @yourname/milkee-plugin-xxx
• Keywords (auto-added): milkee, coffeescript, coffee, ext, plugin, milkee-plugin

Error Handling

main = (compilationResult) ->
  try
    # Your logic
  catch error
    c.error "Failed:", error.message
    throw error

Milkee プラグインの作成

English | 日本語

カスタムプラグインで Milkee の機能を拡張できます。

クイックスタート

-p (--plugin) コマンドでプラグインプロジェクトをセットアップ：

# グローバル
milkee -p

# ローカル
npx milkee -p

以下が実行されます：

1. package.json の初期化（必要な場合）
2. 依存関係のインストール (consola, coffeescript, milkee)
3. テンプレートファイルの作成
4. package.json の更新 (main, scripts, keywords)

プロジェクト構造

your-plugin/
  src/
    main.coffee    # プラグインのソース
  dist/
    main.js        # コンパイル後の出力
  .github/
    workflows/
      publish.yml  # npm公開ワークフロー
  coffee.config.cjs
  package.json

プラグインの書き方

基本テンプレート

fs = require 'fs'
path = require 'path'
consola = require 'consola'

pkg = require '../package.json'
PREFIX = "[#{pkg.name}]"

# プレフィックス付きカスタムロガー
c = {}
for method in ['log', 'info', 'success', 'warn', 'error', 'debug', 'start', 'box']
  do (method) ->
    c[method] = (args...) ->
      if typeof args[0] is 'string'
        args[0] = "#{PREFIX} #{args[0]}"
      consola[method] args...

# メインプラグイン関数
main = (compilationResult) ->
  { config, compiledFiles, stdout, stderr } = compilationResult

  c.info "#{compiledFiles.length} ファイルをコンパイルしました"
  for file in compiledFiles
    c.log "  - #{file}"

module.exports = main

コンパイル結果

Milkee はコンパイル後にこのオブジェクトをプラグインに渡します：

プロパティ	型	説明
config	object	coffee.config.cjs の設定オブジェクト
compiledFiles	string[]	コンパイルされた .js と .js.map のパス
stdout	string	コンパイラの標準出力
stderr	string	コンパイラの標準エラー

coffee.config.cjs での使用

const myPlugin = require('your-plugin-name');

module.exports = {
  entry: 'src',
  output: 'dist',
  milkee: {
    plugins: [
      myPlugin({ customOption: 'value' }),
    ]
  }
};

ビルド & テスト

# プラグインをビルド
npm run build

# ローカルテスト用にリンク
npm link

# 別のプロジェクトで
npm link your-plugin-name

公開

GitHub Actions を使用

同梱のワークフローで npm に手動公開：

1. リポジトリに NPM_TOKEN シークレットを追加
2. Actions → Manual Publish to npm に移動
3. Run workflow をクリック

手動

npm run build
npm publish --access public

ベストプラクティス

命名規則 & キーワード

• 名前: milkee-plugin-xxx または @yourname/milkee-plugin-xxx
• キーワード（自動追加）: milkee, coffeescript, coffee, ext, plugin, milkee-plugin

エラーハンドリング

main = (compilationResult) ->
  try
    # ロジック
  catch error
    c.error "失敗:", error.message
    throw error