FormatArcかんたんデータ変換
JSONYAMLCSVnpmCLI

formatarc を npm パッケージとして使う — CLI・API の導入ガイド

formatarc は npm パッケージとしても使えます。npx でインストール不要の即時実行、CLI でのファイル変換、Node.js プロジェクトへの組み込み方法を解説します。

FormatArc JSON Formatter の実行結果

FormatArc のデータ変換機能が npm パッケージになりました。ブラウザを開かなくても、ターミナルや Node.js スクリプトから JSON 整形・YAML/CSV 変換が使えます。

この記事では、CLI としての使い方と、プロジェクトに組み込んで API として使う方法を紹介します。

インストール

npx で即時実行（インストール不要）

一度きりの変換なら npx が手軽です。パッケージのインストールは不要で、コマンドを打つだけで動きます。

npx formatarc json-format '{"name":"FormatArc","version":1}'

グローバルインストール

頻繁に使うなら、グローバルにインストールしておくと npx の起動待ちがなくなります。

npm install -g formatarc

インストール後は formatarc コマンドがそのまま使えます。

formatarc json-format '{"name":"FormatArc","version":1}'

プロジェクトへの追加

Node.js プロジェクトの依存パッケージとして追加する場合はこちらです。

npm install formatarc

対応しているツール

4 種類の変換に対応しています。Web 版の FormatArc と同じ機能がそのまま使えます。

ツール名 内容
json-format JSON の整形・バリデーション
yaml-to-json YAML → JSON 変換
json-to-yaml JSON → YAML 変換
csv-to-json CSV → JSON 変換（ヘッダー行が必要）

CLI での使い方

CLI の基本構文は以下のとおりです。

formatarc <ツール名> [入力]

入力の渡し方は 3 つあります。

1. 引数で直接渡す

formatarc json-format '{"name":"FormatArc","tools":["json","yaml","csv"]}'

出力はこうなります。

{
  "name": "FormatArc",
  "tools": [
    "json",
    "yaml",
    "csv"
  ]
}

2. ファイルを指定する

formatarc yaml-to-json config.yaml

ファイルパスを渡すと、中身を読み取って変換します。CI/CD のパイプラインに組み込むときに便利です。

3. パイプで標準入力から渡す

cat data.csv | formatarc csv-to-json

curl と組み合わせれば、API レスポンスをそのまま整形できます。

curl -s https://api.example.com/data | formatarc json-format

API として使う

Node.js のコードから直接呼び出すこともできます。変換処理を自動化したい場合や、自作ツールに組み込みたい場合に向いています。

convert 関数

convert は、ツール名と入力文字列を受け取って変換結果を返します。

import { convert } from "formatarc";

const result = convert("json-format", '{"a":1,"b":2}');
console.log(result.output);
// {
//   "a": 1,
//   "b": 2
// }

戻り値は output（変換結果）と error（エラーメッセージ）の 2 つのフィールドを持つオブジェクトです。

const result = convert("json-format", "{invalid json}");
if (result.error) {
  console.error(result.error);
  // JSON parse error: Expected property name or '}' ...
}

エラー時は output が空文字列になり、error にメッセージが入ります。成功時は error が空文字列になります。

isValidTool 関数

ユーザー入力などから受け取った文字列が有効なツール名かどうかを判定する型ガード関数です。

import { convert, isValidTool } from "formatarc";

const toolName = process.argv[2];

if (isValidTool(toolName)) {
  const result = convert(toolName, inputData);
  console.log(result.output);
}

使用例：YAML ファイルを一括で JSON に変換する

import { convert } from "formatarc";
import { readFileSync, writeFileSync } from "fs";
import { globSync } from "fs";

const files = globSync("configs/*.yaml");

for (const file of files) {
  const yaml = readFileSync(file, "utf-8");
  const result = convert("yaml-to-json", yaml);

  if (result.error) {
    console.error(`${file}: ${result.error}`);
    continue;
  }

  const outPath = file.replace(/\.yaml$/, ".json");
  writeFileSync(outPath, result.output);
  console.log(`${file} → ${outPath}`);
}

ブラウザで使いたい場合

CLI やコードではなく、ブラウザ上で手軽に変換したい場合は Web 版の FormatArc が使えます。データはすべてブラウザ内で処理されるため、外部にデータが送信されることはありません。

関連ツール

JSON 整形