formatarc npm — ターミナルで JSON / YAML / CSV を変換（npx 対応）

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

この記事では、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

対応しているツール

7 種類の変換に対応しています。Web 版の FormatArc と同じ機能がそのまま使えます（v0.2.0 で Markdown 系 3 ツールを追加）。

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 レスポンスをそのまま整形できます。jq や python -m json.tool との比較は curl で JSON を整形する 3 つの方法 にまとめています。

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

Markdown 系ツールの使用例

CSV をそのまま GitHub README やドキュメントに貼り付けたい場合は csv-to-markdown が便利です。

cat users.csv | formatarc csv-to-markdown

Markdown を HTML に変換してブログプラットフォームに貼り付ける用途にも使えます。

cat README.md | formatarc markdown-to-html > README.html

逆に、Web ページの HTML を Markdown に整形して LLM に渡したい場合は html-to-markdown が役立ちます。

curl -s https://example.com/article | formatarc html-to-markdown

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}`);
}

関連記事

• JSON 整形の方法 — JSON を読みやすく整形するテクニック
• JSON Parse Error の解決方法 — よくある構文エラーの原因と対処法
• JSON の書き方ガイド — 正しい JSON を書くための基本
• JSON 整形の Chrome 拡張おすすめ比較 — ブラウザで自動整形する方法
• FormatArc Chrome 拡張の使い方 — CLI ではなくブラウザで同じ変換を使いたい場合

ブラウザで使いたい場合

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

• JSON Formatter — JSON の整形・検証
• YAML to JSON — YAML から JSON への変換
• JSON to YAML — JSON から YAML への変換
• CSV to JSON — CSV から JSON への変換
• CSV to Markdown — CSV から Markdown テーブルへの変換
• Markdown to HTML — Markdown から HTML への変換
• HTML to Markdown — HTML から Markdown への変換