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

オープン
#4,853 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
45/100
issue の種類
ドキュメント
明瞭さ
おおむね明確
活発さ
停滞

調査の方向性

ciBuild、forceProductionBuild、default bundles、package.json/package-lock.json を使ったワークフローについて説明している Vaadin Docs のページと例を見つけてください。まず、それらの説明を報告された npm ci の失敗と比較します。ciBuild が必要または不要な場合をドキュメントで明確に示し、forceProductionBuild とそのトレードオフを説明し、lockfile と npm バージョンに関する警告を扱えていれば完了です。

索引モデルが issue の本文から書いたものです。

説明

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
主要言語
AsciiDoc
スター
38
フォーク
225
平均マージ
17時間 38分
マージ済み PR(30日)
214

環境構築

  • Dockerfile・Docker Compose ファイルなし
  • プルリクエストのテンプレートあり
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

vaadin/docs のほかの issue

vaadin/docs の issue をすべて見る

似ている issue

Build System の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。