26-6-5 dsteem 개선 보고가 올라왔습니다.

steem-agora (86)in AVLE 일상 • 18 hours ago

암호화폐가 다시 바닥입니다. 아마도 자금이 모두 주식으로 쓸려들어가고 있기 때문이 아닌가 합니다. 돈은 돌고 도는 것이니 다시 암호화폐로 다시 들어오겠지요.
이런 상황에서 스팀의 개발은 지속되고 있습니다.
간밤에 @blaze.apps 가 개발자 도구인 dsteem의 개선작업을 하고 있다는 소식이 올라왔습니다.

https://steemit.com/steem-dev/@blaze.apps/dsteem-modernization-plan-final-phase-7

제미나이에게 한글로 번역하고 의미를 설명하라고 하니 아래와 같은 결과가 나왔습니다.
기초적인 작업이지만 매우 중요한 의미를 지니고 있군요. 이런 노력이 지속되고 있어서 매우 다행이라는 생각이 듭니다.

제시해주신 글은 오랫동안 업데이트되지 않았던 Steem 블록체인용 개발자 도구(SDK)인 dsteem 라이브러리를 현대화(Modernization)하는 8일간의 프로젝트 중 7일 차 작업 일지입니다.

개발자가 구형 도구들을 최신 표준으로 교체하며 겪은 과정, 성과, 그리고 오픈소스 유지보수에 대한 철학적인 교훈을 담고 있습니다.

이해하기 쉽게 전체 내용을 한글 번역과 핵심 의미 설명으로 나누어 정리해 드립니다.

1. 본문 한글 번역

7일 차: 짧고 명쾌한 작업. TypeDoc 0.13 → 0.28

(무려 15개의 마이너 버전을 건너뛰는 엄청난 업그레이드), 이전 Makefile에서 생성된 HTML 파일의 절대 경로를 수정하기 위해 필요했던 지저분한 sed 후처리 작업을 삭제하고, 이 모든 것을 단 4줄짜리 typedoc.json 설정 파일로 대체했습니다. API 문서가 현대적인 레이아웃으로 깔끔하게 재생성됩니다. 이 작업으로 현대화 계획의 모든 아키텍처 변경(Phase 0 계획)이 완료되어 기능적으로 완성되었습니다. 이제 다음 주에 있을 출시 의식만 남았습니다.

Day 1 — Phase 0: dsteem 현대화 계획
Day 2 — Phase 1: GitHub Actions를 이용한 CI 배관 작업
Day 3 — Phase 2: TSLint 폐기, ESLint 9 도입
Day 4 — Phase 3: TypeScript 3.1 → 5.6 업그레이드 + 엄격 모드(Strict Mode) 적용
Day 5 — Phase 4: @noble 암호화 라이브러리로 교체
Day 6 — Phase 5: tsup 도입, ESM/CJS 듀얼 빌드 지원, 불필요한 패키지 606개 삭제
Day 7 — Phase 6: Mocha 11, c8 코드 커버리지, Playwright 브라우저 테스트 도입
오늘 — Phase 7: TypeDoc 0.13 → 0.28 업그레이드 및 출시 준비 (현재 위치)
다음 주 — Phase 8: 정리 작업, README 최신화, v0.12.0 출시 및 npm 배포

TypeDoc이 멈춰 있던 이유

[email protected]은 2018년 v0.11.3 버전에 고정되어 있었습니다. 현재 최신 버전은 0.28.19입니다. 그동안 변경된 주요 사항은 다음과 같습니다.

0.13 (2018): --mode file 사용, 출력 HTML에 절대 파일 시스템 경로를 그대로 박아버림, 모든 설정에 CLI 플래그 필요.
0.20 (2021): typedoc.json 설정 파일 지원 추가.
0.22 (2021): --mode 삭제, "진입점(entry point)" 모델로 전환.
0.24 (2023): TypeScript 자체 타입 해석 엔진으로 전환.
0.25 (2023): 복잡한 플래그 대신 tsconfig.json 자동 감지.
0.28 (2025): 현대적인 반응형 테마, 제대로 된 검색 인덱스 지원, 절대 경로 유출 없음.

이전 Makefile 실행 스크립트는 다음과 같았습니다.

docs: $(SRC_FILES) node_modules
    typedoc --gitRevision master --target ES6 --mode file --out docs src
    find docs -name "*.html" | xargs sed -i '' 's~$(shell pwd)~.~g'
    ...

저 sed -i '' 문법은 BSD 계열(macOS 전용)입니다. 리눅스나 윈도우의 GNU sed에서는 이를 파일 이름으로 인식하여 진짜 ''라는 이름의 파일에 수정 결과를 써버립니다. 즉, 기존 문서 빌드는 오직 macOS에서만 작동했으며, 그 유일한 이유도 개발자 개인 PC 경로(/Users/jnordberg/dsteem)를 HTML에서 지우기 위한 임시방편(Hack) 때문이었습니다.

새로운 설정 (The New Setup)

이제 typedoc.json 파일 하나와 package.json에 "build:docs": "typedoc" 스크립트 한 줄만 추가하면 끝납니다. 현대적인 TypeDoc은 진입점을 자동 감지하고, 기존 tsconfig.json을 활용하며, 절대 경로를 남기지 않고, 반응형 테마와 검색창을 알아서 만들어 줍니다. 이제 플랫폼 상관없이 npm run build:docs 명령어로 어디서나 문서가 잘 생성됩니다.

현대화 완료 후 최종 상태 (요약)

프로덕션 의존성 패키지: 단 5개로 압축 (감사 완료된 순수 JS 암호화 라이브러리인 @noble 등 사용).
테스트/빌드 파이프라인: 오직 npm 스크립트로만 구동 (ESLint 9 오류 0개, Mocha 테스트 50개 통과, c8 테스트 커버리지 73.22%).
브라우저 번들 크기: 기존 782 KB에서 351 KB로 55% 감소.
호환성: 기존 v0.11.x 버전과 호환성 100% 유지(기존 코드가 안 깨짐), Node.js 22 버전 이상 지원.

🧠 일주일간의 메타 레슨 (핵심 교훈)

오래된 라이브러리를 현대화하는 작업은 화려하지 않습니다. 자랑할 만한 흥미로운 새 기능도 없고, 멋진 아키텍처 다이어그램도 없습니다. 도구를 바꾸고 아무것도 부서지지 않았는지 확인하는 지루한 일주일의 반복입니다.

하지만 이 작업은 Steem 생태계에서 개발하는 모든 이들에게 엄청난 가치를 줍니다. [email protected]을 사용하는 개발자들은 다음과 같은 이점을 얻습니다.

과거 암호화 모듈 빌드 시 발생하던 악명 높은 node-gyp 오류 지옥에서 벗어남.
제대로 작동하는 TypeScript 자동 완성(IntelliSense) 지원.
최신 번들러(Vite, esbuild 등)에서 편법 없이 바로 사용 가능.
예전 node_modules에 방치되어 있던 심각한 보안 취약점(CVE) 회피.
Node 22, 24, Bun, Deno 등 최신 런타임 환경에서 호환성 칩 없이 구동.

이것이 바로 가치입니다. 참신함이 아니라 '불편함의 제거'입니다. 제거된 불편함 덕분에 미래의 어떤 개발자가 "SDK가 너무 짜증 나서 Steem 개발 안 해"라며 떠나는 일을 막을 수 있습니다. 지루한 현대화 작업은 오픈소스 지속 가능성을 지탱하는 '화려하지 않은 절반의 노력'입니다.

2. 이 글이 가지는 기술적 의미 설명

이 글은 단순히 "문서 도구를 업데이트했다"는 뜻을 넘어, 기술 부채(Technical Debt)를 해결하는 모범적인 과정을 보여줍니다.

1. 크로스 플랫폼 호환성 확보

기존에는 과거 개발자가 macOS 환경에 맞춰서 작성해 둔 편법 스크립트(sed -i '') 때문에, 리눅스 서버나 윈도우 PC를 쓰는 다른 개발자들은 문서 조차 제대로 생성할 수 없었습니다. 도구를 최신화함으로써 "내 컴퓨터에서는 잘 되는데?" 문제를 해결하고 전 세계 어떤 환경에서도 빌드되도록 고쳤습니다.

2. 가볍고 안전한 코드로의 체질 개선

과거 자바스크립트 생태계의 골칫덩이였던 무거운 C++ 기반 암호화 모듈과 수백 개의 지저분한 패키지 의존성을 걷어냈습니다. 결과적으로 웹브라우저에서 다운로드해야 할 용량이 절반 이상(-55%) 줄어들었고, 오래된 코드에 잠재되어 있던 보안 취약점을 완전히 해결했습니다.

3. 하위 호환성 유지 (Zero Breaking Changes)

가장 중요한 점은 내부 뼈대를 완전히 싹 뜯어고쳤음에도 불구하고, 기존에 이 라이브러리를 쓰던 개발자들이 코드를 한 줄도 바꿀 필요가 없도록 기능을 완벽하게 유지(byte-compatible)했다는 점입니다.

4. 개발자 경험(DX)의 향상

최신 자바스크립트 트렌드(Vite, TypeScript, ESM 빌드 등)를 완벽히 지원하게 되었습니다. 이 라이브러리를 가져다 쓰는 후속 개발자들이 최신 도구를 사용해 스트레스 없이 쾌적하게 개발할 수 있는 환경을 만들어 준 것입니다.

#dsteem

18 hours ago in AVLE 일상 by steem-agora (86)

$38.83