한국어 | English | 中文 | Español | 日本語
정밀하게 번들을 줄입니다.
Legolas는 npm으로 배포되는 Rust 기반 CLI입니다. 최신 웹 프로젝트에서 번들 무게 문제를 찾기 위해 소스 가져오기 분석, 잠금 파일 검사, 선택적 번들 산출물 증거, 예산 게이트, 기계가 읽을 수 있는 출력을 함께 제공합니다.
- Next.js, Vite, Webpack, Rollup, Astro, Nuxt, React, Vue, Svelte 프로젝트의 프레임워크와 프로젝트 형태
- JavaScript, TypeScript, JSX, TSX, Vue, Svelte 파일의 정적 가져오기와 동적 가져오기
- 차트, 에디터, 아이콘, SDK, 애니메이션, 지도, 모니터링, UI 계열의 무거운 클라이언트 의존성
- npm, pnpm, Yarn 잠금 파일에서 발견되는 중복 패키지 버전
- 넓은 아이콘 가져오기, 루트 유틸리티 가져오기, 반복되는 지역화 하위 경로 가져오기 같은 트리 셰이킹 위험
- 라우트, 대시보드, 모달, 에디터, 지도, 차트 영역의 지연 로딩 후보
- 브라우저 영역이 Node 전용 모듈을 가져오는 경우 같은 서버/클라이언트 경계 경고
- Webpack
stats.json, esbuild/Rollupmeta.json등 알려진 위치의 번들 산출물
Legolas의 절감 추정치는 우선순위를 정하기 위한 방향성 신호입니다. 실제 배포 영향은 프로젝트의 번들 분석기와 성능 텔레메트리로 확인하세요.
의존성을 추가하지 않고 바로 실행할 수 있습니다.
npx @jeremyfellaz/legolas scan .
npx @jeremyfellaz/legolas visualize .
npx @jeremyfellaz/legolas optimize .프로젝트 개발 의존성으로 설치할 수도 있습니다.
npm install -D @jeremyfellaz/legolas
npx legolas scan .npm 패키지는 Node.js >=18.17을 요구합니다. 포함된 Rust 바이너리는 macOS arm64/x64, glibc 기반 Linux x64, Windows x64를 지원합니다.
| 명령어 | 용도 | 자주 쓰는 옵션 |
|---|---|---|
scan |
의존성, 잠금 파일, 가져오기, 산출물, 경계 경고를 포함한 전체 분석 보고서 | [path], --config, --lang ko|en, --json, --sarif, --write-baseline, --baseline, --regression-only |
visualize |
추정 의존성 무게와 중복 패키지 압력을 텍스트 막대로 표시 | [path], --config, --lang ko|en, --limit |
optimize |
난이도, 신뢰도, 대상 파일, 권장 수정안을 포함한 우선순위 작업 목록 | [path], --config, --lang ko|en, --top, --json, --baseline, --regression-only |
budget |
번들 상태 예산 규칙 평가 | [path], --config, --lang ko|en, --json, --baseline, --regression-only |
ci |
예산 실패 시 종료 코드 1을 반환하는 CI용 게이트 |
[path], --config, --lang ko|en, --json, --sarif, --baseline, --regression-only |
기본 도움말과 텍스트 리포트 언어는 한국어입니다. 영어 출력이 필요하면 --lang en을 사용하세요. 정확한 CLI 계약은 legolas help로 확인할 수 있습니다.
npx @jeremyfellaz/legolas help앱을 스캔합니다.
npx @jeremyfellaz/legolas scan ./apps/storefront자동화에서 사용할 JSON을 출력합니다.
npx @jeremyfellaz/legolas scan ./apps/storefront --json스캔 결과를 SARIF로 출력합니다.
npx @jeremyfellaz/legolas scan ./apps/storefront --sarif기준선을 만들고 비교합니다.
npx @jeremyfellaz/legolas scan ./apps/storefront --write-baseline ./legolas-baseline.json --json
npx @jeremyfellaz/legolas scan ./apps/storefront --baseline ./legolas-baseline.json --regression-only --json예산 회귀가 있으면 CI를 실패시킵니다.
npx @jeremyfellaz/legolas ci ./apps/storefront --baseline ./legolas-baseline.json --regression-only --sarifLegolas는 프로젝트 루트의 legolas.config.json을 자동으로 찾습니다. --config로 설정 파일을 직접 지정할 수도 있습니다.
{
"scan": {
"path": "src",
"ignorePatterns": ["generated/**", "!generated/keep.ts"]
},
"visualize": {
"limit": 12
},
"optimize": {
"top": 7
},
"budget": {
"rules": {
"potentialKbSaved": {
"warnAt": 40,
"failAt": 80
},
"duplicatePackageCount": {
"warnAt": 2,
"failAt": 4
},
"dynamicImportCount": {
"warnAt": 1,
"failAt": 0
}
}
}
}소스 스캔은 프로젝트의 .gitignore와 루트 .legolasignore도 반영합니다. scan.ignorePatterns는 프로젝트 루트 기준 POSIX 스타일 경로 패턴이며 .gitignore처럼 ! 예외 패턴을 사용할 수 있습니다.
potentialKbSaved와 duplicatePackageCount는 최댓값 규칙입니다. 실제 값이 커질수록 나쁩니다. dynamicImportCount는 최솟값 규칙입니다. 동적 가져오기가 너무 적으면 경고나 실패가 발생할 수 있습니다.
scan --json과optimize --json은 docs/schema/analysis.v1.schema.json에 문서화된legolas.analysis.v1을 출력합니다.budget --json은 docs/schema/budget.v1.schema.json에 문서화된legolas.budget.v1을 출력합니다.ci --json은 docs/schema/ci.v1.schema.json에 문서화된legolas.ci.v1을 출력합니다.scan --sarif와ci --sarif는 docs/schema/sarif.v1.json에 문서화된 SARIF2.1.0을 출력합니다.
JSON 출력은 top-level reportSummary를 포함합니다. SARIF 출력은 runs[0].properties.reportSummary에 같은 요약을 담습니다. 이 summary에는 language, verdictKey, confirmedInitialPayloadKbSaved, directionalOpportunityKb, estimatedLcpImprovementMs, topActions가 포함됩니다.
--json과 --sarif는 함께 사용할 수 없습니다. ci는 예산 규칙 실패 시 0이 아닌 종료 코드를 반환합니다.
scan은 프로젝트 요약, 판정, 확정 초기 페이로드 절감, 방향성 정리 여지, 다음 작업, 증거, 발견 항목 그룹을 보여줍니다.
Legolas scan for basic-parity-app
프로젝트 루트: <PROJECT_ROOT>
모드: heuristic
프레임워크: Vite, React
패키지 매니저: pnpm
스캔: 소스 파일 1개, import 패키지 4개
판정: 큰 폭 절감 가능
확정 초기 페이로드 절감: 약 348 KB (LCP 약 731 ms 개선 추정)
방향성 정리 여지: 약 366 KB
Top next actions:
1. chart.js 초기 번들 무게 검토 [난이도: 어려움 | 신뢰도: 높음 | ~160 KB]
권장 수정: lazy-load - Register only the chart primitives you use and lazy load dashboard surfaces.
대상: src/Dashboard.tsx
evidence: src/Dashboard.tsx | specifier: chart.js | static import; Charting code is often only needed on a subset of screens.
2. chart.js 지연 로딩 [난이도: 보통 | 신뢰도: 낮음 | ~120 KB]
evidence: src/Dashboard.tsx | specifier: chart.js | route-like UI surface matched `dashboard` keyword
가장 무거운 의존성:
- chart.js (160 KB) [높음 신뢰도]: Charting code is often only needed on a subset of screens. 1개 파일에서 import됨.
확정 초기 페이로드 절감은 소스 import 또는 번들 산출물 증거로 초기 페이로드 영향이 확인된 항목만 합산합니다. Lockfile-only 중복은 이 confirmed/LCP 수치에 포함하지 않고 방향성 정리 여지의 dependency hygiene 신호로만 다룹니다. 개발/테스트 전용 중복도 LCP 개선치가 아니라 dependency hygiene 정리 작업으로 표시됩니다.
optimize는 발견 항목을 우선순위 작업으로 바꿉니다.
Legolas optimize for basic-parity-app
Top next actions:
1. chart.js 초기 번들 무게 검토 [난이도: 어려움 | 신뢰도: 높음 | ~160 KB]
권장 수정: lazy-load - Register only the chart primitives you use and lazy load dashboard surfaces.
대상: src/Dashboard.tsx
evidence: src/Dashboard.tsx | specifier: chart.js | static import; Charting code is often only needed on a subset of screens.
budget은 각 규칙의 통과, 경고, 실패 상태를 보여줍니다.
Legolas budget for basic-parity-app
전체 상태: Fail
규칙 결과:
- potentialKbSaved: Fail (actual: 348, warnAt: 40, failAt: 80)
- duplicatePackageCount: Pass (actual: 1, warnAt: 2, failAt: 4)
- dynamicImportCount: Fail (actual: 0, warnAt: 1, failAt: 0)
cargo run -p legolas-cli -- help
cargo test --workspace기여자 워크플로우는 cargo run -p legolas-cli -- ...를 기준으로 합니다. npm 패키지는 vendor/<triple>/legolas[.exe]에 포함된 컴파일된 Rust 바이너리를 실행합니다. 릴리스 패키징 과정에서 vendor 바이너리를 준비한 뒤에는 npm run pack:check로 패키지 구성을 검증합니다.
- 라이선스: MIT
- 기여 안내: CONTRIBUTING.md
- 행동 강령: CODE_OF_CONDUCT.md
- 보안 정책: SECURITY.md
- 후원: GitHub Sponsors