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

[SebastianKuehnau]

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