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

Aperta
#4,853 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
45/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Ferma

Direzione di ricerca

Individua le pagine e gli esempi di Vaadin Docs che descrivono ciBuild, forceProductionBuild, default bundles e i workflow con package.json/package-lock.json. Inizia confrontando queste spiegazioni con il fallimento segnalato di npm ci. Il lavoro è completo quando la documentazione indica chiaramente quando ciBuild è necessario o non necessario, spiega forceProductionBuild e i suoi trade-off e tratta gli avvisi relativi al lockfile e alla versione di npm.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

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
Lingua principale
AsciiDoc
Stelle
38
Fork
225
Merge medio
17h 38m
PR unite (30g)
214

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di vaadin/docs

Tutte le issue di vaadin/docs

Issue simili

Altre issue su Build System

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.