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

Abierto
#4,853 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
3/5
Tiempo estimado
1-2 días
Aptitud para principiantes
45/100
Tipo de issue
Documentación
Claridad
Bastante claro
Estado de actividad
Estancado

Línea de trabajo

Localiza las páginas y ejemplos de Vaadin Docs que describen ciBuild, forceProductionBuild, default bundles y los flujos de trabajo con package.json/package-lock.json. Empieza comparando esas explicaciones con el fallo reportado de npm ci. Se considerará terminado cuando la documentación indique claramente cuándo ciBuild es necesario o innecesario, explique forceProductionBuild y sus trade-offs, y cubra las advertencias sobre el lockfile y la versión de npm.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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
Lenguaje dominante
AsciiDoc
Estrellas
38
Forks
225
Merge medio
17 h 38 min
PR fusionados (30 d)
214

Preparar el entorno

  • Sin Dockerfile ni archivo de Docker Compose
  • Tiene una plantilla de pull request
  • Sin guía de contribución

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de vaadin/docs

Todos los issues de vaadin/docs

Issues similares

Más issues de Build System

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.