Clarify ciBuild, forceProductionBuild, and package.json workflow in the Vaadin Docs

Đang mở
#4,853 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức phù hợp với người mới
45/100
Loại issue
Tài liệu
Độ rõ ràng
Khá rõ ràng
Mức độ hoạt động
Đình trệ

Hướng nghiên cứu

Tìm các trang và ví dụ trong Vaadin Docs mô tả ciBuild, forceProductionBuild, default bundles và các quy trình làm việc với package.json/package-lock.json. Bắt đầu bằng cách so sánh những giải thích đó với lỗi npm ci đã được báo cáo. Được xem là hoàn tất khi tài liệu nêu rõ ciBuild cần thiết hay không cần thiết trong những trường hợp nào, giải thích forceProductionBuild và các trade-off của nó, đồng thời đề cập đến các cảnh báo về lockfile và phiên bản npm.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

flow

Problem

Documentation doesn't clearly explain the corelation between ciBuild, forceProductionBuild, package.json/package-lock.json, and when to use which approach.

Common misconception causing build failures

Issue observed:

Users configure production profile with ciBuild=true by default (as shown in various examples),
but this causes builds to fail on CI for simple projects that use default bundles.

Error message:

npm error `npm ci` can only install packages when your package.json and package-lock.json...
Root cause:
  • Simple projects (no @NpmPackage, no 3rd-party components) use default bundles
  • Default bundles don't generate package.json/package-lock.json
  • Production profile examples often include ciBuild=true
  • This causes npm ci to fail because required json files don't exist
What users need to understand:

ciBuild=true is not a universal production setting - it's only needed when you have custom npm dependencies.

Key clarifications needed:

When to use ciBuild
  • when package.json and package-lock.json are committed to repository
  • Trade off: Developer must run frontend build WITHOUT ciBuild locally first, then commit the updated json files
When NOT to use ciBuild
  • When using default bundles (json files aren't even generated in this case)
  • Don't include package.json/package-lock.json in repository if build uses default bundles
About forceProductionBuild
  • it is a workaround for when automatic detection fails
  • potentially need to update package-lock.json with ciBuild
  • makes builds always slow, but ensures robust builds
  • Not recommended as default: Only for catching issues early or working around detection problems
Important warnings
  • If CI runs npm install without package-lock.json → vulnerable to npm malware and random problems
  • Different npm versions (from different Node.js versions) can cause slightly different package-lock.json files
  • This can lead to merge conflicts even when dependencies haven't changed
Ngôn ngữ chính
AsciiDoc
Star
38
Fork
225
Merge trung bình
17 giờ 38 phút
Pull request đã merge (30 ngày)
214

Chuẩn bị môi trường

  • Không có Dockerfile hay tệp Docker Compose
  • Có mẫu pull request
  • Không có hướng dẫn đóng góp

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của vaadin/docs

Tất cả issue của vaadin/docs

Issue tương tự

Thêm issue về Build System

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.