FormatArc의 데이터 변환 기능을 터미널과 Node.js 환경에서 그대로 사용할 수 있도록 npm 패키지로 제공합니다. 브라우저를 열지 않아도 터미널 명령어(CLI)나 Node.js 스크립트 안에서 JSON 정렬, YAML·CSV·Markdown·HTML 변환을 즉시 실행할 수 있습니다.
이 글에서는 CLI 도구로서의 사용법과 프로젝트에 의존성으로 추가해 API로 활용하는 방법을 소개합니다.
터미널을 열지 않고 한 번만 빠르게 변환하고 싶다면 웹 브라우저의 JSON 포맷터에 데이터를 붙여넣어 즉시 결과를 확인할 수 있습니다. 회원가입이나 로그인이 필요 없으며, 붙여넣은 데이터는 브라우저 외부로 전송되지 않습니다.
설치 방법
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 프로젝트의 패키지 의존성으로 추가해 코드 안에서 API로 호출하고 싶다면 다음 명령어로 설치합니다.
npm install formatarc
지원하는 도구 목록
명령은 모두 12개이며, 웹 버전 FormatArc와 동일한 변환 로직이 적용되어 있습니다. PDF는 0.3.0에, Qiita / Zenn 호환성 검사는 0.4.0에 추가되었습니다(npm 버전 기록새 탭에서 열립니다).
| 도구 이름 | 설명 |
|---|---|
json-format | JSON 정렬(Pretty-print) 및 문법 검증 |
yaml-to-json | YAML → JSON 변환 |
json-to-yaml | JSON → YAML 변환 |
csv-to-json | CSV → JSON 변환 (헤더 행 필요) |
json-to-csv | JSON → CSV 변환 (중첩된 키는 address.city 형태로 펼침) |
csv-to-markdown | CSV → 마크다운 표(GFM Table) 변환 |
markdown-to-csv | Markdown 표 → CSV 변환 |
markdown-to-html | Markdown → HTML 변환 |
html-to-markdown | HTML → Markdown 변환 |
pdf-to-markdown | 텍스트를 담고 있는 PDF의 본문을 Markdown으로 추출 |
qiita-to-zenn | Qiita 글의 Zenn 호환성 검사 |
zenn-to-qiita | Zenn 글의 Qiita 호환성 검사 |
qiita-to-zenn과 zenn-to-qiita는 변환 결과를 표준 출력으로, 문법 차이 보고를 표준 오류로 내보냅니다. 자동으로 해결할 수 없는 차이가 남아 있으면 종료 코드 1로 끝나므로, 글을 공개하기 전 CI 검사로 넣을 수 있습니다.
올바른 JSON 문법 규칙과 데이터 타입에 대한 자세한 내용은 JSON 작성법 가이드를 참고하세요.
CLI 사용법
CLI의 기본 명령어 구조는 다음과 같습니다.
formatarc <도구이름> [입력데이터]
입력 데이터를 전달하는 방식은 3가지가 있습니다.
1. 인수로 직접 전달
가장 단순하게 인라인 문자열을 인수로 넘기는 방식입니다.
formatarc json-format '{"name":"FormatArc","tools":["json","yaml","csv"]}'
출력 결과:
{
"name": "FormatArc",
"tools": [
"json",
"yaml",
"csv"
]
}
JSON을 가독성 높게 정렬하는 다양한 팁과 도구 활용법은 JSON 정렬 방법을 참고하세요.
2. 파일 경로 지정
파일 경로를 인수로 넘기면 파일 내용을 읽어 변환을 수행합니다.
formatarc yaml-to-json config.yaml
설정 파일 변환이나 CI/CD 배포 파이프라인 스크립트에 통합할 때 유용합니다.
3. 파이프로 표준 입력(stdin) 전달
파이프 연산자(|)를 사용해 이전 명령어의 출력을 표준 입력으로 넘겨 변환할 수 있습니다.
cat data.csv | formatarc csv-to-json
curl과 조합하면 API 응답을 터미널에서 즉시 보기 쉽게 정렬할 수 있습니다. jq나 Python 내장 도구를 따로 구성하지 않고도 한 줄로 JSON 응답을 정렬할 수 있습니다. jq나 Python을 활용한 다양한 터미널 정렬 방법은 curl JSON pretty print(정렬) 방법을 참고하세요.
curl -s https://api.example.com/data | formatarc json-format
Markdown 및 HTML 도구 활용 예시
CSV 데이터를 GitHub README나 문서에 넣을 마크다운 표로 빠르게 바꾸고 싶다면 csv-to-markdown이 유용합니다.
cat users.csv | formatarc csv-to-markdown
마크다운 문서를 HTML로 렌더링해 마크다운을 직접 지원하지 않는 블로그 플랫폼이나 이메일 템플릿에 붙여넣을 때 활용할 수 있습니다.
cat README.md | formatarc markdown-to-html > README.html
반대로 웹 페이지의 HTML에서 불필요한 태그를 걷어내고 깔끔한 마크다운 텍스트로 추출해 LLM 프롬프트에 전달하고 싶다면 html-to-markdown을 사용할 수 있습니다.
curl -s https://example.com/article | formatarc html-to-markdown
Node.js 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(오류 메시지 문자열) 두 개의 필드를 가진 객체입니다.
const result = convert("json-format", "{invalid json}");
if (result.error) {
console.error(result.error);
// JSON parse error: Expected property name or '}' ...
}
변환 중 오류가 발생하면 output은 빈 문자열이 되고 error에 오류 원인이 담깁니다. 성공하면 error는 빈 문자열이 됩니다. 자주 발생하는 구문 오류의 원인과 해결법은 JSON Parse Error 해결 방법을 참고하세요. 주석이 포함된 JSONC나 JSON5 파일의 처리 방법은 JSON 주석처리 방법을 참고하세요.
isValidTool 함수
사용자 입력이나 외부 변수에서 전달받은 문자열이 유효한 도구 이름인지 검증하는 타입 가드(Type Guard) 함수입니다.
import { convert, isValidTool } from "formatarc";
const toolName = process.argv[2];
if (isValidTool(toolName)) {
const result = convert(toolName, inputData);
console.log(result.output);
}
활용 예시: YAML 파일 일괄 JSON 변환 스크립트
디렉터리 내 여러 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나 코드 작성이 아닌 직관적인 웹 화면에서 빠르게 변환하고 싶다면 웹 버전 FormatArc를 사용할 수 있습니다. 모든 변환 처리는 브라우저 내부에서만 실행되며 데이터가 서버로 전송되지 않습니다. 브라우저 툴바에서 바로 변환하고 싶다면 FormatArc 크롬 확장프로그램을 참고하세요. 브라우저에서 JSON을 자동으로 정렬해 주는 확장 프로그램 비교는 크롬 JSON 포맷터 확장 프로그램 추천 비교를 참고하세요.
- JSON 포맷터 — JSON 정렬 및 문법 검증
- YAML JSON 변환기 — YAML을 JSON으로 변환
- JSON YAML 변환기 — JSON을 YAML으로 변환
- CSV JSON 변환기 — CSV를 JSON으로 변환
- CSV to Markdown 변환기 — CSV를 마크다운 표로 변환
- Markdown to HTML 변환기 — 마크다운을 HTML로 변환
- HTML to Markdown 변환기 — HTML을 마크다운으로 변환
자주 묻는 질문
formatarc npm 패키지는 오프라인 환경에서도 동작하나요?
네, 동작합니다. 글로벌 설치나 프로젝트 로컬 설치 후에는 외부 서버 통신 없이 로컬 런타임에서 모든 변환 로직이 실행되므로 인터넷 연결이 없는 오프라인 환경에서도 사용할 수 있습니다. npx의 경우 첫 실행 시 패키지 다운로드가 필요하지만, 캐시된 후에는 오프라인에서도 실행할 수 있습니다.
npx와 글로벌 설치 중 어떤 방식이 더 좋나요?
가끔 한두 번 변환하거나 CI 환경에서 별도 설치 단계를 생략하고 싶다면 npx formatarc가 편리합니다. 터미널 작업 중 수시로 JSON을 정렬하거나 파이프라인에서 반복 호출한다면 npm install -g formatarc로 설치해 npx 시작 지연 없이 바로 실행하는 것을 권장합니다.
CLI에서 대용량 파일도 변환할 수 있나요?
네, Node.js 프로세스가 다룰 수 있는 메모리 한도 내에서 파일 경로 지정이나 표준 입력 파이프를 통해 대용량 데이터도 안정적으로 처리할 수 있습니다.
웹 버전 FormatArc와 npm 패키지의 변환 결과가 일치하나요?
네, 완전히 동일합니다. FormatArc 웹 버전과 npm 패키지는 동일한 데이터 변환 및 검증 코어 로직을 공유하므로 브라우저에서 실행한 결과와 터미널에서 실행한 결과가 일치합니다.
관련 글
- 크롬 JSON 확장 프로그램 비교
- 크롬 확장프로그램으로 JSON·YAML·CSV 변환하기
- JSON 주석처리 방법
- JSON 정렬(Pretty Print) 방법
- JSON 파싱 오류 해결법
- JSON 작성법 가이드
정리
formatarcnpm 패키지를 사용하면 브라우저 없이 터미널에서 JSON·YAML·CSV·Markdown·HTML을 즉시 변환할 수 있습니다npx formatarc로 설치 없이 바로 실행하거나,npm install -g formatarc로 전역 설치해 CLI 명령어로 활용할 수 있습니다- Node.js 프로젝트에서
convert함수를 임포트해 스크립트나 자동화 파이프라인의 API로 사용할 수 있습니다 - 웹 UI에서 시각적으로 변환하고 싶다면 JSON 포맷터를 비롯한 웹 버전 도구를 활용하세요