Ionic 프로젝트의 핵심 설정 파일, ionic.config.json 완벽 가이드

Ionic 프로젝트를 시작하면 루트 디렉토리에 ionic.config.json 파일이 생성된다. 이 파일은 프로젝트의 기본 설정을 담고 있는데, 많은 개발자들이 이 파일의 역할을 제대로 모르고 넘어간다.

이 글에서는 ionic.config.json 파일의 모든 속성과 실제 사용 사례를 설명한다.

목차

• 1. ionic.config.json이란?
• 2. 기본 구조와 속성
• 3. 각 속성 상세 설명
• 4. 실제 프로젝트 예제
• 5. 주의사항과 팁

---

1. ionic.config.json이란?

ionic.config.json은 Ionic CLI가 프로젝트를 인식하고 관리하기 위해 사용하는 설정 파일이다. 이 파일이 없으면 Ionic CLI는 프로젝트를 제대로 인식하지 못할 수 있다.

💡 중요: 이 파일은 Ionic CLI가 자동으로 생성하지만, 수동으로 수정해서 프로젝트에 맞게 커스터마이징할 수 있다.

1.1 파일 위치

프로젝트 루트 디렉토리에 위치한다:

mycarbon/
├── ionic.config.json  ← 여기!
├── package.json
├── src/
└── ...

1.2 파일 생성 시점

다음 명령어로 Ionic 프로젝트를 생성하면 자동으로 생성된다:

ionic start [projectName] [template]

또는 Angular CLI로 생성한 프로젝트에 Ionic을 추가할 때도 생성된다:

npm install -g @ionic/cli
ionic integrations enable capacitor

---

2. 기본 구조와 속성

ionic.config.json의 기본 구조는 다음과 같다:

{
  "name": "[projectName]",
  "integrations": {
    "capacitor": {}
  },
  "type": "angular"
}

2.1 최소 필수 속성

• name: 프로젝트 이름 (필수)
• type: 프로젝트 타입 (필수) - "angular", "react", "vue" 등

⚠️ 주의: name과 type은 반드시 있어야 한다. 없으면 Ionic CLI가 프로젝트를 인식하지 못한다.

---

3. 각 속성 상세 설명

3.1 name (프로젝트 이름)

프로젝트의 이름을 지정한다. 이 이름은 Ionic CLI 명령어에서 사용되며, 앱 식별자로도 활용된다.

{
  "name": "탄소제로"
}

💡 팁: 한글 이름도 가능하지만, 패키지 이름이나 앱 ID로 사용할 때는 영문으로 변환하는 것이 좋다.

3.2 type (프로젝트 타입)

사용하는 프레임워크를 지정한다. 현재 지원하는 타입:

타입	설명
"angular"	Angular 프레임워크 사용
"react"	React 프레임워크 사용
"vue"	Vue.js 프레임워크 사용

{
  "type": "angular"
}

3.3 integrations (통합 설정)

Ionic과 통합할 네이티브 플랫폼이나 도구를 설정한다.

3.3.1 Capacitor 통합

가장 많이 사용하는 통합이다. Capacitor를 사용하면 iOS/Android 네이티브 앱을 빌드할 수 있다.

{
  "integrations": {
    "capacitor": {}
  }
}

Capacitor 설정을 더 자세히 지정할 수도 있다:

{
  "integrations": {
    "capacitor": {
      "enabled": true,
      "appId": "[appId]",
      "appName": "[appName]"
    }
  }
}

💡 참고: 대부분의 경우 빈 객체 {}로 충분하다. 실제 설정은 capacitor.config.json 파일에서 관리한다.

3.3.2 Cordova 통합 (레거시)

Cordova를 사용하는 경우 (현재는 권장하지 않음):

{
  "integrations": {
    "cordova": {}
  }
}

⚠️ 주의: Cordova는 더 이상 권장되지 않는다. 새 프로젝트는 Capacitor를 사용하자.

3.4 기타 선택 속성

다음 속성들은 선택사항이지만, 특정 상황에서 유용하다:

3.4.1 app_id (앱 ID)

앱의 고유 식별자. Capacitor나 Cordova에서 사용한다:

{
  "app_id": "[appId]"
}

3.4.2 watchPatterns (파일 감시 패턴)

Ionic CLI가 감시할 파일 패턴을 지정한다:

{
  "watchPatterns": [
    "src/**/*",
    "!src/**/*.spec.ts"
  ]
}

---

4. 실제 프로젝트 예제

실제 프로덕션 환경에서 사용하는 ionic.config.json 예제를 보자.

4.1 기본 Angular + Capacitor 프로젝트

가장 일반적인 설정이다:

{
  "name": "[projectName]",
  "integrations": {
    "capacitor": {}
  },
  "type": "angular"
}

4.2 커스텀 설정이 포함된 프로젝트

더 많은 설정이 필요한 경우:

{
  "name": "[projectName]",
  "integrations": {
    "capacitor": {
      "enabled": true
    }
  },
  "type": "angular",
  "app_id": "[appId]",
  "watchPatterns": [
    "src/**/*.ts",
    "src/**/*.html",
    "src/**/*.scss"
  ]
}

4.3 React 프로젝트 예제

React를 사용하는 경우:

{
  "name": "[projectName]",
  "integrations": {
    "capacitor": {}
  },
  "type": "react"
}

4.4 Vue 프로젝트 예제

Vue.js를 사용하는 경우:

{
  "name": "[projectName]",
  "integrations": {
    "capacitor": {}
  },
  "type": "vue"
}

---

5. 주의사항과 팁

5.1 파일 수정 시 주의사항

• JSON 문법 준수: JSON 형식이므로 쉼표, 따옴표 등을 정확히 작성해야 한다.
• name 변경 시 주의: name을 변경하면 일부 CLI 명령어가 영향을 받을 수 있다.
• type 변경 금지: type은 프로젝트 생성 후 변경하면 안 된다. 다른 프레임워크로 전환하려면 새 프로젝트를 만들어야 한다.

5.2 Git 관리

ionic.config.json은 버전 관리에 포함시켜야 한다:

# .gitignore에 추가하지 말 것!
git add ionic.config.json
git commit -m "Add ionic.config.json"

💡 팁: 이 파일은 프로젝트 설정이므로 팀원들과 공유해야 한다. .gitignore에 추가하지 말자.

5.3 자주 하는 실수

5.3.1 JSON 문법 오류

마지막 속성 뒤에 쉼표를 넣으면 안 된다:

// ❌ 잘못된 예
{
  "name": "[projectName]",
  "type": "angular",  // ← 마지막 속성 뒤 쉼표
}

// ✅ 올바른 예
{
  "name": "[projectName]",
  "type": "angular"
}

5.3.2 type 값 오타

type 값은 정확히 지정해야 한다:

// ❌ 잘못된 예
{
  "type": "Angular"  // 대소문자 구분!
}

// ✅ 올바른 예
{
  "type": "angular"  // 소문자
}

5.4 디버깅 팁

Ionic CLI가 프로젝트를 인식하지 못할 때:

1. 1ionic.config.json 파일이 루트 디렉토리에 있는지 확인
2. 2JSON 문법 오류가 없는지 확인 (JSON Validator 사용)
3. 3name과 type 속성이 있는지 확인
4. 4Ionic CLI 버전 확인: ionic --version

5.5 최적화 팁

• 최소한의 설정만 유지: 필요한 속성만 남기고 나머지는 제거하자. 기본값으로 충분한 경우가 많다.
• watchPatterns 활용: 대용량 프로젝트에서 불필요한 파일 감시를 줄이려면 watchPatterns를 설정하자.
• 팀 표준화: 팀 내에서 ionic.config.json 형식을 표준화하면 협업이 수월해진다.

---

마무리

ionic.config.json은 작은 파일이지만 Ionic 프로젝트의 핵심 설정을 담고 있다. 이 파일을 제대로 이해하고 관리하면 프로젝트 설정이 훨씬 수월해진다.

대부분의 경우 기본 설정으로 충분하지만, 특수한 요구사항이 있을 때는 이 가이드를 참고해서 커스터마이징하자.

✅ 핵심 요약:

• name과 type은 필수 속성
• Capacitor 통합은 integrations.capacitor로 설정
• JSON 문법을 정확히 지켜야 함
• 버전 관리에 포함시켜야 함