설정

Oxfmt는 바로 실행할 수 있지만, 대부분의 팀은 로컬·편집기·CI에서 일관된 포맷을 위해 설정 파일을 커밋합니다.

이 페이지에서는 프로젝트 설정에 초점을 맞춥니다 — 포맷 옵션, 무시 패턴, 실험적 기능입니다.

설정 파일 만들기

현재 디렉터리에 시작용 설정을 만들려면:

oxfmt --init

Oxfmt는 포맷 대상 파일이 있는 디렉터리부터 위로 거슬러 올라가며 다음 파일을 찾습니다.

• .oxfmtrc.json
• .oxfmtrc.jsonc
• oxfmt.config.ts

포맷하는 파일과 가장 가까운 설정이 적용됩니다. 즉, 프로젝트 트리 여러 레벨에 다른 설정을 둘 수 있습니다.

예를 들어 저장소 전체용 루트 설정과 하위 디렉터리 전용 설정:

my-repo/
├── oxfmt.config.ts         # 저장소 기본값
├── src/
│   └── app.ts              # 루트 설정 사용
└── packages/
    └── fancy-app/
        ├── .oxfmtrc.json   # 이 패키지용 덮어쓰기
        └── index.ts        # packages/fancy-app/.oxfmtrc.json 사용

중첩 설정이 필요 없으면 --disable-nested-config로 현재 작업 디렉터리에서만 위로 찾습니다. 파일마다 설정을 찾지 않아도 되어 더 빠릅니다.

-c로 설정을 명시하면 중첩 조회도 꺼집니다. .json, .jsonc, .ts, .mts, .cts, .js, .mjs, .cjs 형식 모두 허용됩니다.

oxfmt -c path/to/yourconfig.json

최소 JSON 설정 예시:

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80
}

JavaScript / TypeScript 설정 파일은 기본 내보내기를 사용합니다. defineConfig는 선택 사항이지만 타입 검사와 에디터 자동완성에 도움이 됩니다.

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

설정 파일 형식

설정은 JSON 객체입니다. 자주 쓰이는 최상위 필드는 다음과 같습니다.

• printWidth: 줄 너비 제한(기본: 100)
• tabWidth: 들여쓰기당 공백 수(기본: 2)
• useTabs: 스페이스 대신 탭(기본: false)
• semi: 세미콜론 추가(기본: true)
• singleQuote: 작은따옴표 사용(기본: false)
• trailingComma: 여러 줄 구조에서 끝 쉼표(기본: "all")
• ignorePatterns: 포맷에서 제외할 글로브 패턴
• sortImports: import 정렬(기본: 꺼짐)
• sortTailwindcss: Tailwind 클래스 정렬(기본: 꺼짐)
• sortPackageJson: package.json 필드 정렬(기본: 켜짐)

전체 필드 목록은 설정 파일 참고를 보세요.

JSON 스키마

편집기 검증·자동완성을 위해 $schema 필드를 추가합니다.

.oxfmtrc.json

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json"
}

.editorconfig

Oxfmt가 읽는 .editorconfig 속성:

• end_of_line → endOfLine
• indent_style → useTabs
• indent_size → tabWidth
• max_line_length → printWidth
• insert_final_newline → insertFinalNewline

루트 섹션과 글로브 기반 덮어쓰기 모두 지원합니다.

[*]
indent_size = 4

[*.{js,ts}]
indent_size = 2

Oxfmt는 현재 디렉터리에서 가장 가까운 .editorconfig만 사용합니다.

• root = true는 무시됩니다.
• 중첩 .editorconfig는 병합되지 않습니다.

Overrides

특정 파일에 다른 포맷 옵션을 적용하려면 overrides 필드를 사용합니다.

.oxfmtrc.json

{
  "printWidth": 100,
  "overrides": [
    {
      "files": ["*.test.js", "*.spec.ts"],
      "options": {
        "printWidth": 120
      }
    },
    {
      "files": ["*.md", "*.html"],
      "excludeFiles": ["*.min.js"],
      "options": {
        "tabWidth": 4
      }
    }
  ]
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 100,
  overrides: [
    {
      files: ["*.test.js", "*.spec.ts"],
      options: {
        printWidth: 120,
      },
    },
    {
      files: ["*.md", "*.html"],
      excludeFiles: ["*.min.js"],
      options: {
        tabWidth: 4,
      },
    },
  ],
});

각 override 항목:

• files(필수): 매칭할 글로브 패턴
• excludeFiles(선택): 이 override에서 제외할 글로브
• options: 적용할 포맷 옵션

글로브 패턴은 Oxfmt 설정 파일이 있는 디렉터리를 기준으로 해석됩니다.

우선순위

옵션은 다음 순서로 적용됩니다(낮은 것부터):

1. 기본값
2. 설정 파일 루트 옵션
3. 설정 파일 overrides 옵션
4. 미설정 필드에 대해 .editorconfig에서 지원하는 옵션으로 보완

Oxfmt 전용 옵션

insertFinalNewline

포맷된 파일 끝에 마지막 줄바꿈을 넣을지 여부입니다. 기본은 true입니다.

Prettier에서 오래 요청된 기능이며, 일부 환경(예: Salesforce)은 후행 줄바꿈을 없애기도 합니다.

printWidth

Oxfmt 기본값은 printWidth: 100(Prettier는 80)입니다. 이유는 다음과 같습니다.

• 타입 어노테이션 때문에 TypeScript 코드가 길어짐
• import 문에 지정자가 많은 경우가 많음
• 모던 디스플레이는 넓음
• 줄바꿈이 적을수록 LLM 토큰이 줄어듦

Prettier 기본값에 맞추려면:

.oxfmtrc.json

{
  "printWidth": 80
}

oxfmt.config.ts

import { defineConfig } from "oxfmt";

export default defineConfig({
  printWidth: 80,
});

다음 단계

• 무시 파일: 무시 파일·패턴, .gitignore와 .prettierignore 활용.
• 인라인 무시 주석: 특정 코드만 억제.
• 설정 파일 참고: 전체 스키마와 필드 설명.
• CLI 참고: 플래그 전체 목록.