패키지 CLI
pkgs/ 아래의 패키지, 즉 프레임워크(akanjs)와 CLI 같은 도구 패키지를 만들고 빌드하고 검증하는 명령 여섯 가지입니다. 앱·라이브러리 명령보다 낮은 수준이므로, 제품 코드에는 그쪽 명령을 씁니다.이 페이지에서 쓰는 말
용어설명
패키지
akanjs, @akanjs/cli처럼 pkgs/ 아래에서 자기 package.json을 가진 폴더입니다.dist
dist/pkgs/<pkg>/에 생기는 빌드 결과로, 압축해서 배포하는 대상이 이 폴더입니다.exports
패키지를 설치한 쪽이 쓸 수 있는 import 경로와, 각 경로가 여는 파일을 적는
package.json 항목입니다.npm pack --dry-run
배포하면 올라갈 파일과 크기를 보여 주되, 압축 파일은 만들지 않습니다.
보통의 순서
akan create-package --name renderer로pkgs/renderer/를 만듭니다.package.json과index.ts는 직접 추가합니다.- 코드를 작성하고
akan test renderer로 테스트합니다. akan build-package renderer가dist/pkgs/renderer/를 만듭니다.akan verify-dist-package renderer로 배포 전에 그 폴더를 검사합니다.
명령마다 바꾸는 것
명령
소스
루트 tsconfig
빌드 결과
확인
version
지금 쓰는
akanjs 버전을 출력합니다.sync-package
패키지 하나의 import를 스캔해 빠르게 점검합니다.
추가와 제거
create-package
✓
✓
pkgs/에 새 폴더를 만들고 import 경로를 등록합니다.remove-package
✓
✓
폴더와 import 경로를 지웁니다.
빌드와 배포
build-package
✓
✓
dist 폴더를 만들고 의존성 목록을 적습니다.
verify-dist-package
배포 전에 dist 폴더를 검사합니다.
✓바뀜그대로
패키지를 지정하는 법
[pkg]를 받는 네 명령은 모두 같은 방식으로 패키지를 찾습니다.
- 패키지는
pkgs/아래 경로로 지정합니다.akanjs,@akanjs/cli,create-akan-workspace처럼 씁니다. 생략하거나 잘못 적으면 목록에서 고릅니다. package.json이 있는 폴더만 패키지로 봅니다.create-package로 막 만든 폴더에는 아직 없으니, 다른 명령을 쓰기 전에 추가합니다.
패키지를 지우거나 빌드하기 전에 커밋해 두세요.
remove-package는 pkgs/<pkg>/를 확인 없이 지우고, build-package는 pkgs/<pkg>/package.json을 다시 씁니다.관련 페이지
version
akanjs 버전을 akanjs@<version> 한 줄로 출력합니다.
패키지 릴리스, 업그레이드, 프레임워크 유지보수 전에 현재 버전을 확인할 때 씁니다.형식
참고
이름설명
기본 출처
지금 실행 중인 CLI가 찾거나 의존하는
akanjs의 버전입니다.USE_AKANJS_PKGS=true
대신 이 워크스페이스의
pkgs/akanjs/package.json을 읽습니다.akan --version
CLI 자신의 버전을 출력하는 별개의 플래그입니다.
버전 불일치
CLI와
node_modules/akanjs 버전이 다르면 모든 명령이 경고하고 akan update를 권합니다.예시
create-package
새 패키지 폴더를
pkgs/<name>/에 만들고, 루트 tsconfig.json에 import 경로를 등록합니다.
폴더에는 tsconfig.json만 생기므로 package.json과 index.ts는 직접 추가합니다.형식
옵션
--nameString-n
소문자로 바꾸고 공백을
-로 바꾼 패키지 이름이며, 생략하면 입력을 받습니다.참고
이름설명
tsconfig.json
새로 생긴
pkgs/<name>/tsconfig.json은 ../../tsconfig.json으로 루트 설정을 확장합니다.스코프가 붙은 이름
@scope/x 같은 이름이면 그 extends를 ../../../tsconfig.json으로 직접 고칩니다.paths
루트에
<name> → ./pkgs/<name>/index.ts, <name>/* → ./pkgs/<name>/*를 추가합니다.references
루트
tsconfig.json에 references가 있으면 ./pkgs/<name>/tsconfig.json도 추가합니다.예시
remove-package
pkgs/<pkg>/ 폴더 전체를 확인 없이 지우고, 루트 tsconfig.json에서 그 항목을 뺍니다.
패키지를 더는 동기화하거나 빌드·검증하지 않을 때 씁니다.형식
인자
pkgString
akanjs, @akanjs/cli처럼 pkgs/ 아래 패키지 경로이며, 생략하면 목록에서 고릅니다.참고
이름설명
tsconfig.json
paths에서 <pkg>와 <pkg>/*를, references에서 그 항목을 지웁니다.남는 것
dist/pkgs/<pkg>/의 이전 빌드와, 다른 코드에 남은 그 패키지의 import입니다.예시
sync-package
패키지 하나의 import를 스캔해 쓰고 있는 npm 패키지와
pkgs/의 다른 패키지를 찾습니다.
파일은 바꾸지 않고 스캔 성공 여부만 출력하므로, import를 고친 뒤 빠르게 점검할 때 씁니다.형식
인자
pkgString
akanjs, @akanjs/cli처럼 pkgs/ 아래 패키지 경로이며, 생략하면 목록에서 고릅니다.참고
이름설명
npm 패키지
루트
package.json의 dependencies나 devDependencies에 있는 import만 셉니다.의존성 기록
의존성을
pkgs/<pkg>/package.json에 적는 단계는 build-package입니다.예시
build-package
패키지 하나를
dist/pkgs/<pkg>/에 빌드합니다. 배포하거나 다른 패키지가 로컬에서 가져다 쓰는 폴더입니다.
패키지를 고친 뒤, 그 빌드 결과를 다른 곳에서 쓰기 전에 실행합니다.형식
인자
pkgString
akanjs, @akanjs/cli처럼 pkgs/ 아래 패키지 경로이며, 생략하면 목록에서 고릅니다.참고
이름설명
빈 폴더에서 시작
먼저
dist/pkgs/<pkg>/를 지우므로, 이전 빌드의 파일이 남지 않습니다.의존성
import한 패키지를 루트가 고정한 버전으로
pkgs/<pkg>/package.json에 적습니다.devDependencies
타입만 가져오는 import와
build.ts 안의 import는 devDependencies로 갑니다.pkgs/의 다른 패키지
루트에 없는
pkgs/의 다른 패키지를 import하면 그 패키지 자신의 version을 씁니다.버전 누락
루트
package.json에 버전이 없는 import가 있으면 멈추니, 루트에 추가한 뒤 다시 빌드합니다.선택적 peer 의존성
peerDependenciesMeta에서 optional로 표시한 패키지는 의존성 목록에서 뺍니다.build.ts
pkgs/<pkg>/build.ts가 있으면 Bun이 그 파일을 실행하고, dist 폴더는 그 스크립트가 씁니다.build.ts가 없으면
소스를 dist로 복사하고, 그 안에
package.json과 tsconfig.json을 씁니다.만들어지는 package.json
type: module, index.ts 루트 export, engines.bun을 넣고, 소스 쪽에도 똑같이 씁니다.README
README.md와 README.ko.md가 있으면 dist로 복사합니다.예시
verify-dist-package
dist/pkgs/<pkg>/의 빌드 결과를 검사한 뒤 npm pack dry run으로 크기를 잽니다.
build-package 다음, 배포 전에 실행합니다. 깨진 export map을 처음 설치하는 사람보다 먼저 여기서 잡습니다.형식
인자
pkgString
akanjs, @akanjs/cli처럼 pkgs/ 아래 패키지 경로이며, 생략하면 목록에서 고릅니다.참고
이름설명
빌드 먼저
dist/pkgs/<pkg>/package.json이 없으면 바로 실패하니, build-package를 먼저 실행합니다.이름과 버전
dist의
package.json에 이 패키지의 이름과 version이 있어야 합니다.공개 배포
publishConfig.access가 public이어야 합니다.README
dist에
README.md와 README.ko.md가 둘 다 있어야 합니다.bin
bin 항목이 .ts 소스를 가리키면 안 됩니다.exports
패키지가 자기 자신의 하위 경로를 import하면, 그 경로마다
exports를 거쳐 실제 파일에 닿아야 합니다.exports 고치기
대상 경로에 확장자나
index.ts를 붙여 주지 않으므로, 파일은 "./*": "./*.ts", 폴더는 "./name": "./name/index.ts"가 필요합니다.확장자가 붙은 import
"./*.ts": "./*.ts"를 넣어 두면 이미 .ts로 끝나는 경로에 확장자가 두 번 붙지 않습니다.akanjs
akanjs는 추가로, 루트 export의 types가 ./types/ 안을 가리켜야 합니다.결과
파일 개수와 압축 크기(바이트)를 출력할 뿐, 파일을 쓰거나 배포하지는 않습니다.
npm
크기는
npm pack --dry-run으로 재므로 PATH에 npm이 있어야 합니다.배포 패키지 네 개
도움말에 없는
akan verify-akan-publish-packages는 Akan.js가 배포하는 패키지 네 개를 검사합니다.네 개의 목록
akanjs, @akanjs/cli, @akanjs/devkit, create-akan-workspace입니다.서로 간 import
네 개를 함께 검사하면, 서로의 하위 경로를 import한 것도 상대 패키지의
exports로 확인합니다.예시