Bun の Plugins で CSV ファイルを直接 import する

Bun のランタイムとバンドラの両方を拡張できる Plugins API を提供しています。この Plugin を使用することで、任意の拡張子のファイルのサポートを追加できます。例えば Bun の公式の動画では、Plugins API を使用して Rust ファイル（.rs）を直接 import できる仕組みも作れることが紹介されています。

Bun 1.0 is here

Bun 1.0 is here! Bun is an all-in-one JavaScript runtime & toolkit designed for speed, complete with a bundler, test runner, and Node.js-compatible package m...

www.youtube.com

使い方

Plugins API は JavaScript のオブジェクトとして定義されます。このオブジェクトは以下のプロパティを持ちます。

• name：Plugin の名前
• setup：ローダー処理を行う関数

例えば、.yaml ファイルを import するための Plugin を作成するには、以下のように定義します。

import { plugin } from "bun";
 
plugin({
  name: "YAML",
  async setup(build) {
    const { load } = await import("js-yaml");
    const { readFileSync } = await import("fs");
 
    // when a .yaml file is imported...
    build.onLoad({ filter: /.(yaml|yml)$/ }, (args) => {
 
      // read and parse the file
      const text = readFileSync(args.path, "utf8");
      const exports = load(text) as Record<string, any>;
 
      // and returns it as a module
      return {
        exports,
        loader: "object", // special loader for JS objects
      };
    });
  },
});

Plugins – Runtime | Bun Docs

Implement custom loaders and module resolution logic with Bun's plugin system.

bun.sh

setup 関数が返すオブジェクトの loader プロパティは以下の値を指定できます。

• js：JavaScript ファイルへトランスパイルする
• jsx：jsx を変換してからトランスパイルする
• ts：TypeScript を変換してからトランスパイルする
• tsx：tsx を変換してからトランスパイルする
• toml：toml ファイルを JavaScript オブジェクトに変換する
• json：json ファイルを JavaScript オブジェクトに変換する
• napi：ネイティブ Node.js アドオンをインポートする
• wasm：WebAssembly モジュールをインポートする
• object：JavaScript のオブジェクトを同等の ES モジュールに変換するプラグイン向けの特別なローダー

設定された Plugin は他のコードが実行されるよりも先に読み込まれる必要があります。これを実現するためには、bunfig.toml（Bun の設定ファイル）の preload オプションを使用します。

preload = ["./plugins/yaml.ts"]

テストが実行される前に Plugin を読み込みたい場合には、[test] セクションに preload オプションを設定します。

[test]
preload = ["./plugins/yaml.ts"]

CSV ファイルを直接 import する

それでは例として、Plugins API を使用して CSV ファイルを直接 import できるようにしてみましょう。npm によりいくつか Plugin のパッケージが公開されているので、それを使ってみましょう。bun-plugin-csv パッケージを使ってみます。

bun install bun-plugin-csv

Plugin を設定する plugins/csv.ts ファイルを作成します。

import csvPlugin from "bun-plugin-csv";
import { plugin } from "bun";
 
plugin(csvPlugin());

サードパーティの Plugin は慣例として、BunPlugin オブジェクトを返すファクトリ関数として実装されています。そのため、csvPlugin() という関数を呼び出して Plugin を設定します。

続いて bunfig.toml に Plugin を読み込むように設定します。

preload = ["./plugins/csv.ts"]

.csv ファイルに型定義を追加します。

/// <reference types="bun-plugin-csv/client" />

適当な CSV ファイルを作成しておきましょう。

name,age
Alice,18
Bob,20

index.ts で CSV ファイルを import してみます。

import users from "./users.csv"
 
for (let user of users) {
    console.log(user);
}

bun index.ts コマンドで実行してみると、確かに CSV ファイルが JavaScript のオブジェクトとして import できていることが確認できます。

bun index.ts
{
  name: "Alice",
  age: "18"
}
{
  name: "Bob",
  age: "20"
}

まとめ

• Plugins API を使用することで、任意の拡張子のファイルのサポートを追加できる
• Plugins API は name と setup の 2 つのプロパティを持ち、setup はローダー処理を行う関数を指定する
• Plugin が他のコードが実行されるよりも先に読み込まれるようにするには、bunfig.toml の preload オプションを使用する
• サードパーティの Plugin は慣例として、BunPlugin オブジェクトを返すファクトリ関数として実装されている