# J-Component 업데이트 가이드

> J-Component 라이브러리 버전 업데이트 방법 안내

> 💡 **처음 설치하시나요?** → [설치 가이드](./INSTALLATION_GUIDE.md)를 먼저 확인하세요.

## 📋 목차

1. [배포 방식 확인](#배포-방식-확인)
2. [Standard 방식 업데이트 (파일 복사)](#standard-방식-업데이트-파일-복사)
3. [NPM 방식 업데이트 (패키지 설치)](#npm-방식-업데이트-패키지-설치)
4. [업데이트 후 확인](#업데이트-후-확인)
5. [문제 해결](#문제-해결)

---

## 배포 방식 확인

업데이트 전에 현재 사용 중인 배포 방식을 확인하세요:

- **Standard 방식 (파일 복사)**: `src/components/` 디렉토리에 파일이 직접 복사되어 있는 경우
- **NPM 방식 (패키지 설치)**: `package.json`에 `@j-solution/components`가 설치되어 있는 경우

---

## Standard 방식 업데이트 (파일 복사)

### 1. 버전 확인

#### 현재 설치된 버전 확인

```bash
# VERSION 파일 확인
cat VERSION

# 또는 README.md에서 버전 정보 확인
cat README.md | grep "Package v"
```

#### 최신 버전 확인

원본 저장소에서 최신 버전을 확인하세요:

- **저장소**: https://github.com/JWMS-Solutions/J-Component
- **릴리즈 노트**: 저장소의 `RELEASE_NOTES.md` 파일 참고
- **패키지 경로**: `packages/latest/standard/`

> **v1.0.0부터**: `namespaced` 버전은 지원되지 않습니다. 네임스페이스 기능이 필요한 경우 `npm` 패키지 방식을 사용하세요. `standard` 버전은 계속 지원됩니다.

### 2. 최신 패키지 다운로드

#### 방법 1: Git Sparse Checkout (권장)

```bash
# 임시 디렉토리에 패키지 다운로드
mkdir -p temp-package
cd temp-package

# Standard 버전 다운로드
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/JWMS-Solutions/J-Component.git .
git sparse-checkout set packages/latest/standard
```

#### 방법 2: GitHub 웹 인터페이스

GitHub 웹 인터페이스에서 `packages/latest/standard/` 디렉토리를 ZIP으로 다운로드

### 3. 버전 확인

```bash
# VERSION 파일 확인
cat temp-package/packages/latest/standard/VERSION

# README.md에서 변경사항 확인
cat temp-package/packages/latest/standard/README.md
```

### 4. 기존 패키지 백업 (선택)

```bash
# 현재 패키지가 설치된 경로로 이동
cd <패키지-설치-경로>

# 백업 생성
cp -r . ../backup-$(date +%Y%m%d)
```

### 5. 패키지 교체

```bash
# 기존 패키지 제거 (필요한 파일만 선택적으로 제거)
# 주의: README.md, VERSION, USAGE_GUIDE.md, UPDATE_GUIDE.md는 유지 가능

# 새 패키지 복사
cp -r temp-package/packages/latest/standard/src/* <패키지-설치-경로>/src/
cp temp-package/packages/latest/standard/README.md <패키지-설치-경로>/
cp temp-package/packages/latest/standard/VERSION <패키지-설치-경로>/
cp temp-package/packages/latest/standard/USAGE_GUIDE.md <패키지-설치-경로>/
cp temp-package/packages/latest/standard/UPDATE_GUIDE.md <패키지-설치-경로>/
```

### 6. 빌드 및 테스트

```bash
# 프로젝트 루트로 이동
cd <프로젝트-루트>

# 빌드 테스트
npm run build
# 또는
pnpm run build

# 개발 서버 실행
npm run dev
# 또는
pnpm run dev
```

### 7. 변경사항 커밋

```bash
git add <패키지-설치-경로>
git commit -m "chore: j-component v{버전} 업데이트"
```

---

## NPM 방식 업데이트 (패키지 설치)

### 1. 버전 확인

#### 현재 설치된 버전 확인

```bash
# package.json에서 확인
npm list @j-solution/components
# 또는
pnpm list @j-solution/components

# 또는 node_modules에서 직접 확인
cat node_modules/@j-solution/components/package.json | grep '"version"'
```

#### 최신 버전 확인

- **npm 레지스트리**: `npm view @j-solution/components version`
- **저장소**: https://github.com/JWMS-Solutions/J-Component
- **릴리즈 노트**: 저장소의 `RELEASE_NOTES.md` 파일 참고

### 2. 최신 버전으로 업데이트

#### npm 레지스트리에서 설치된 경우

```bash
# 최신 버전으로 업데이트
npm install @j-solution/components@latest
# 또는
pnpm add @j-solution/components@latest

# 또는 특정 버전으로 업데이트
npm install @j-solution/components@1.0.1
# 또는
pnpm add @j-solution/components@1.0.1
```

#### 로컬 파일로 설치된 경우

```bash
# 로컬 경로의 최신 버전으로 업데이트
npm install file:../JLIS-Component/jwms-portal-frontend/dist/npm
# 또는
pnpm add file:../JLIS-Component/jwms-portal-frontend/dist/npm

# 또는 tarball 사용
npm install ../JLIS-Component/jwms-portal-frontend/dist/npm/j-components-1.0.1.tgz
# 또는
pnpm add ../JLIS-Component/jwms-portal-frontend/dist/npm/j-components-1.0.1.tgz
```

---

## 업데이트 후 확인

### Standard 방식 (파일 복사)

1. **버전 확인**
   ```bash
   cat VERSION
   ```

2. **파일 존재 확인**
   ```bash
   ls -la src/components/atoms/
   ```

3. **빌드 테스트**
   ```bash
   npm run build
# 또는
pnpm run build
   npm run dev
# 또는
pnpm run dev
   ```

### NPM 방식 (패키지 설치)

1. **버전 확인**
   ```bash
   npm list @j-solution/components
# 또는
pnpm list @j-solution/components
   ```

2. **peerDependencies 확인**
   ```bash
   npm list vue vue-router pinia
   ```
   
   필요한 버전:
   - `vue`: `^3.5.22`
   - `vue-router`: `^4.6.0`
   - `pinia`: `^3.0.3`

3. **타입 체크**
   ```bash
   npm run type-check
   # 또는
   pnpm run type-check
   # 또는
   npx vue-tsc --noEmit
   ```

4. **빌드 테스트**
   ```bash
   npm run dev
# 또는
pnpm run dev
   npm run build
# 또는
pnpm run build
   ```

---

## 문제 해결

### Standard 방식 (파일 복사)

#### Import 오류 발생 시

1. **별칭 확인**
   ```bash
   # vite.config.ts 확인
   grep -A 5 "alias" vite.config.ts
   
   # tsconfig.json 확인
   grep -A 5 "paths" tsconfig.json
   ```

2. **경로 확인**
   ```bash
   # 컴포넌트 폴더 존재 확인
   ls -la src/components/atoms/
   ```

3. **빌드 캐시 클리어**
   ```bash
   rm -rf node_modules/.vite
   rm -rf dist
   npm run dev
# 또는
pnpm run dev
   ```

#### 컴포넌트가 렌더링되지 않을 때

1. **Tailwind 설정 확인**
   ```bash
   # tailwind.config.js에 컴포넌트 경로 포함 확인
   grep "components" tailwind.config.js
   ```

2. **CSS 변수 확인**
   - `src/assets/styles/themes.css` 또는 메인 CSS 파일에 `--radius` 변수 포함 확인
   - 브라우저 개발자 도구에서 CSS 변수 값 확인:
     ```javascript
     getComputedStyle(document.documentElement).getPropertyValue('--radius')
     ```

### NPM 방식 (패키지 설치)

#### 업데이트 후 문제가 발생한 경우

1. **의존성 재설치**
   ```bash
   rm -rf node_modules package-lock.json
   npm install
   # 또는
   pnpm install
   ```

2. **TypeScript 서버 재시작**
   - VS Code: `Ctrl+Shift+P` → "TypeScript: Restart TS Server"

3. **빌드 캐시 클리어**
   ```bash
   rm -rf node_modules/.vite
   rm -rf dist
   npm run build
# 또는
pnpm run build
   ```

#### 버전 충돌 발생 시

1. **peerDependencies 버전 확인**
   ```bash
   npm list vue vue-router pinia
   ```

2. **호환되는 버전으로 업데이트**
   - `@j-solution/components`의 `package.json`에서 `peerDependencies` 확인
   - 필요한 패키지 버전 업데이트

### 공통 문제

#### 버전 충돌 발생 시

1. **의존성 버전 확인**
   ```bash
   # package.json 확인
   cat package.json | grep -A 10 "dependencies"
   ```

2. **호환되는 버전으로 업데이트**
   - README.md의 의존성 목록 확인
   - 필요한 패키지 버전 업데이트

---

## ⚙️ 설정 파일 확인

업데이트 후 다음 설정 파일들이 올바르게 설정되어 있는지 확인하세요:

### Standard 방식 (파일 복사)

#### Vite 프로젝트

**`vite.config.ts`**:
```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
})
```

#### TypeScript

**`tsconfig.json`** 또는 **`tsconfig.app.json`**:
```json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
```

#### Tailwind CSS

**`tailwind.config.js`**:
```js
export default {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
    "./src/components/**/*.{vue,js,ts}",
  ],
  // ... 기타 설정
}
```

### NPM 방식 (패키지 설치)

#### Tailwind CSS

**`tailwind.config.js`**:
```js
export default {
  content: [
    "./index.html",
    "./src/**/*.{vue,js,ts,jsx,tsx}",
    "./node_modules/@j-solution/components/**/*.{vue,js,ts}",
  ],
  // ... 기타 설정
}
```

#### CSS 자동 포함

**NPM 패키지는 CSS가 자동으로 포함됩니다.** 별도로 CSS를 import할 필요가 없습니다:

```ts
// 컴포넌트만 import하면 CSS가 자동으로 포함됨
import { JButton } from '@j-solution/components'
// CSS는 자동으로 포함됨 - 별도 import 불필요
```

> 💡 **참고**: 만약 CSS가 적용되지 않는다면, 프로젝트의 빌드 설정을 확인하세요. 일부 번들러는 CSS를 자동으로 포함하지 않을 수 있습니다. 그 경우 수동으로 import할 수 있습니다:
> ```ts
> import '@j-solution/components/assets/styles/j-components.css'
> import '@j-solution/components/assets/styles/themes.css'
> ```

> 💡 **설정 파일 상세 내용이 필요하신가요?** → [설치 가이드](./INSTALLATION_GUIDE.md)의 설정 섹션을 참고하세요.

---

## 📚 참고 자료

- **원본 저장소**: https://github.com/JWMS-Solutions/J-Component
- **설치 가이드**: [INSTALLATION_GUIDE.md](./INSTALLATION_GUIDE.md)
- **사용 가이드**: [USAGE_GUIDE.md](./USAGE_GUIDE.md)
- **패키지 소개**: `packages/latest/standard/README.md` (Standard 방식 - 파일 복사)
- **릴리즈 노트**: 원본 저장소의 `RELEASE_NOTES.md`

---

**마지막 업데이트**: 2025년 12월  
**문서 버전**: v1.0.1