Syncer란?
파일 변경 감지
Entity, Model, Types 파일 변경 추적Checksum 기반 효율적 감지
자동 코드 생성
타입, 스키마, API 클라이언트 생성Template 기반 생성
HMR 지원
개발 중 실시간 반영파일 무효화 및 재로드
멀티 타겟 동기화
web, app 등 여러 프로젝트 동기화자동 파일 복사
Syncer의 동작 흐름
감시 대상 파일
Syncer가 변경을 추적하는 파일 패턴입니다:| 파일 타입 | 패턴 | 용도 |
|---|---|---|
| Entity | src/application/**/*.entity.json | 데이터 구조 정의 |
| Types | src/application/**/*.types.ts | 타입 정의 |
| Model | src/application/**/*.model.ts | 비즈니스 로직 |
| Frame | src/application/**/*.frame.ts | 프레임 로직 |
| Functions | src/application/**/*.functions.ts | 유틸 함수 |
| Generated | src/application/sonamu.generated.ts | 생성된 베이스 파일 |
| Config | src/sonamu.config.ts | Sonamu 설정 |
| Workflow | src/application/**/*.workflow.ts | 워크플로우 정의 |
| i18n | src/i18n/**/*.ts | 다국어 파일 |
파일 패턴:
file-patterns.ts에서 관리되며, checksum으로 변경 감지수동 동기화
개발 서버 없이 수동으로 동기화할 수 있습니다.자동 동기화 (HMR)
개발 서버 실행 중에는 파일 변경이 자동으로 감지되고 동기화됩니다.Syncer 이벤트
Syncer는 EventEmitter로 이벤트를 발생시킵니다.| 이벤트 | 발생 시점 | 사용 예시 |
|---|---|---|
onHMRCompleted | HMR 완료 시 | 후속 작업 트리거 |
Syncer 액션
파일 변경 유형에 따라 다른 액션이 실행됩니다.1. Entity 변경 (handleEntityChange)
Entity 파일이 변경되면 스키마를 재생성합니다.
트리거: *.entity.json 파일 변경
액션:
- EntityManager 재로드
- 새 Entity면
*.types.ts생성 - 스키마 파일 생성:
sonamu.generated.tssonamu.generated.sso.ts
- 타겟에 파일 복사
2. Types/Functions/Generated 변경
타입 파일이 변경되면 타겟에 복사합니다. 트리거:*.types.ts, *.functions.ts, *.generated.ts 변경
액션:
- 변경된 파일 목록 수집
- 각 타겟(
web,app)에 복사 sonamuimport를./sonamu.shared로 변경
sonamu.shared.ts: web/app에는 sonamu 패키지가 없으므로, 공통 유틸리티를 shared 파일로 제공합니다.
3. Model/Frame 변경
Model 파일이 변경되면 API 클라이언트를 재생성합니다. 트리거:*.model.ts, *.frame.ts 변경
액션:
- Model, Types, APIs 재로드
- API 클라이언트 생성 (
services.generated.ts) - HTTP 테스트 파일 생성 (
sonamu.generated.http) - SSR 파일 재생성 (
queries.generated.ts,entry-server.generated.tsx)
4. Config 변경
설정 파일이 변경되면 환경 변수를 동기화합니다. 트리거:sonamu.config.ts 변경
액션:
.sonamu.env파일 생성/업데이트- 각 타겟에 복사
web/.sonamu.env
5. Workflow 변경
워크플로우 파일이 변경되면 재로드합니다. 트리거:*.workflow.ts 변경
액션: 워크플로우 재로드 및 동기화
6. i18n 변경
다국어 파일이 변경되면 SD 파일을 재생성합니다. 트리거:src/i18n/**/*.ts 변경
액션:
- Locale 파일을 타겟에 복사
sd.generated.ts생성 (api, web, app)
Checksum 기반 변경 감지
Syncer는 파일의 checksum을 저장하여 효율적으로 변경을 감지합니다.- 파일 내용의 SHA-256 해시 계산
- 저장된 checksum과 비교
- 다르면 변경으로 판단
- 동기화 후 checksum 갱신
- 빠른 변경 감지 (파일 내용 비교 불필요)
- 정확한 변경 추적 (timestamp 영향 없음)
- 여러 파일 동시 변경 처리
Syncer API
Syncer는 프로그래밍 방식으로 사용할 수 있습니다.수동 동기화
템플릿 생성
모듈 로드
Syncer 설정
sonamu.config.ts에서 Syncer 동작을 설정할 수 있습니다.
api/src/sonamu.config.ts
개발 워크플로우
Syncer를 활용한 일반적인 개발 흐름입니다:1
개발 서버 시작
2
Entity 정의
Sonamu UI에서 Entity를 정의하거나
.entity.json 파일을 수정합니다.자동 실행:*.types.ts생성sonamu.generated.ts갱신sonamu.generated.sso.ts갱신- 타겟에 파일 복사
3
Model 작성
비즈니스 로직을 Model에 작성하고
@api 데코레이터를 추가합니다.자동 실행:services.generated.ts갱신sonamu.generated.http갱신- SSR 파일 갱신
4
프론트엔드 개발
생성된 API 클라이언트와 Types를 사용하여 UI를 개발합니다.
5
실시간 반영
Model이나 Entity를 수정하면 HMR로 즉시 반영됩니다.브라우저 새로고침 없이 변경사항 확인 가능!
문제 해결
Syncer가 동작하지 않을 때
파일이 생성되지 않음
파일이 생성되지 않음
확인 사항:
- 개발 서버가 실행 중인지 확인
- 파일이 감시 대상 패턴에 포함되는지 확인
- Checksum 파일 삭제 후 재시도
타겟에 파일이 복사되지 않음
타겟에 파일이 복사되지 않음
확인 사항:
sonamu.config.ts의sync.targets확인- 타겟 디렉토리 존재 확인
- 타겟 디렉토리에
src/services/디렉토리 생성
HMR이 느림
HMR이 느림
최적화 방법:
- Node.js 최신 버전 사용 (v22+)
- SSD 사용 (HDD는 느림)
- 불필요한 파일 제외
- TypeScript 프로젝트 분리 (monorepo)
import 에러 발생
import 에러 발생
원인:
sonamu import가 ./sonamu.shared로 변환되지 않음해결: