docs: Add Incremental Build Vitepress docs

JIRA: CPOUI5FOUNDATION-1205

Author: maxreichmann

internal/documentation/docs/pages/Builder.md

@@ -14,6 +14,63 @@ For every type there is a set of default tasks. You can disable single tasks usi
   <VPButton class="no-decoration" text="📚 API Reference" href="https://ui5.github.io/cli/v5/api/index.html"/>
 </div>
 
+## Incremental Build and Caching
+
+Starting with UI5 CLI v5, UI5 project building integrates the **Incremental Build**. This architectural change brings significant benefits while introducing some behavioral differences compared to previous versions. Instead of rebuilding everything from scratch, the UI5 Builder tracks which resources have changed and which build tasks need to be re-executed:
+
+### How It Works
+
+When you start a project build with `ui5 build`:
+
+1. **Cache Population and Reuse**: The UI5 CLI builds your project caching build results and metadata
+1. **File Watching**: When Watch Mode is enabled, the CLI monitors your source files for changes and triggers automatic rebuilds (see [Watch Mode](#watch-mode) section)
+1. **Incremental Rebuilds**: When a rebuild is triggered, only relevant tasks are re-executed and cached results from unrelated ones are used
+1. **Cached Results**: Build outputs are cached to gain performance during subsequent builds
+
+### Build Cache Control
+
+You can control the build cache behavior using the `--cache` option:
+
+- `--cache Default` (default): Use the cache if available, create it if missing
+- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid
+- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD)
+- `--cache Off`: Disable caching entirely and always perform a full rebuild
+
+Example:
+```sh
+ui5 build --cache Off
+```
+In this scenario, when a source file change is made, always perform a full rebuild (even if this source version already existed sometime ago).
+
+::: warning Important
+Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case.
+:::
+
+For more details on server caching, see the [UI5 Server documentation](./Server.md).
+
+### Watch Mode
+
+The `ui5 build` command supports a `--watch` flag that monitors source files for changes and automatically triggers incremental rebuilds:
+
+```sh
+ui5 build --watch
+```
+
+When watch mode is enabled:
+- Source files in your project are monitored for changes
+- Incremental rebuilds are triggered automatically when changes are detected
+- Only affected tasks are re-executed
+
+::: tip
+Watch mode monitors your source files only. Changes to configuration files (`ui5.yaml`, `package.json`) or custom task implementations require restarting the build command.
+:::
+
+::: info Info
+For `ui5 serve`, this behavior is always turned on automatically.
+:::
+
+TODO: check this section again once it's implemented
+
 ## Tasks
 Tasks are specific build steps to be executed during build phase.
 

internal/documentation/docs/pages/Configuration.md

@@ -662,6 +662,9 @@ A project can also configure alternative default ports. If the configured port i
 
 The default and configured server ports can always be overwritten with the CLI parameter `--port`.
 
+
+TODO: Add Live Reload configuration once it's implemented
+
 ## Extension Configuration
 
 ::: details Example

internal/documentation/docs/pages/Overview.md

@@ -3,6 +3,20 @@ When developing a UI5 project on your local system, you should use the UI5 Serve
 
 However, you might have good reasons to also use the UI5 Builder during development. In such cases, feel free to let us know! Maybe your use case could be covered by a future enhancement of the UI5 Server.
 
+## Incremental Build and Caching
+
+Starting with UI5 CLI v5, both `ui5 serve` and `ui5 build` use the **Incremental Build** to improve performance:
+
+- Build results are cached and reused across builds and server sessions
+- Only modified resources and affected build tasks are reprocessed
+- The server automatically watches source files and triggers rebuilds when changes are detected
+- Custom build tasks from dependencies execute automatically — no manual middleware configuration needed
+
+For more details, see:
+- [UI5 Server: Incremental Build and Caching](./Server.md#incremental-build-and-caching)
+- [UI5 Builder: Incremental Build and Caching](./Builder.md#incremental-build-and-caching)
+- [Migration Guide: Incremental Build](./updates/migrate-v5.md#incremental-build)
+
 ## Project Dependencies
 
 UI5 CLI differentiates between "framework dependencies" and "project dependencies".

internal/documentation/docs/pages/Server.md

@@ -23,6 +23,66 @@ Please be aware of the following risks when using the server:
 
 :::
 
+
+## Development Server
+
+Starting with UI5 CLI v5, the development server integrates with the **Incremental Build**. This architectural change brings significant benefits while introducing some behavioral differences compared to previous versions.
+
+### How It Works
+
+When you start the server with `ui5 serve`:
+
+1. **On-Demand Building**: The server builds your project only when a request comes in, and only if no cache exists or the cache is stale
+1. **File Watching**: The server monitors your source files for changes
+1. **Incremental Rebuilds**: When changes are detected and a new request is sent, an automatic rebuild is triggered containing only relevant build tasks
+1. **Live Reload**: If live reload is enabled, the browser automatically refreshes once a rebuild completes (see [Live Reload](#live-reload) section)
+1. **Cached Results**: Build outputs are cached to gain performance during subsequent builds
+
+### Benefits
+
+- **Faster Subsequent Builds**: The incremental build cache significantly speeds up rebuilds after the first run
+- **Automatic Dependency Task Execution**: Custom build tasks defined in your project's dependencies (libraries, modules) are now executed automatically during the build. You no longer need to configure custom middleware to handle these tasks.
+- **Theme Pre-Compilation**: Themes are now pre-compiled by the `buildThemes` task during the build, improving performance (see [Removed Middleware](#standard-middleware) section)
+
+### Server Cache Control
+
+You can control the build cache behavior using the `--cache` option:
+
+- `--cache Default` (default): Use the cache if available, create it if missing
+- `--cache Force`: Only use the cache; fail if the cache is unavailable or invalid
+- `--cache ReadOnly`: Use existing cache but don't update it (useful for CI/CD)
+- `--cache Off`: Disable caching entirely and always perform a full rebuild
+
+Example:
+```sh
+ui5 serve --cache Off
+```
+In this scenario, when a source file change is made and a request comes in, always perform a full rebuild (even if this source version already existed sometime ago).
+
+::: warning Important
+Build caches created by `ui5 build` and `ui5 serve` are **separate and cannot be mixed**. Each command maintains its own cache optimized for its specific use case.
+:::
+
+For more details on build caching, see the [UI5 Builder documentation](./Builder.md).
+
+### Watch Mode Behavior
+
+The server automatically watches your source files and triggers rebuilds when changes are detected:
+
+- **Monitored files**: All files in your project's source directories (`src/`, `webapp/`, `test/`, etc.)
+- **Not monitored**: Configuration files (`ui5.yaml`, `package.json`), custom task implementations, and dependency files
+
+::: tip
+Changes to configuration files or custom tasks require a server restart to take effect.
+:::
+
+### Live Reload
+
+When Live Reload is enabled, the server automatically triggers a rebuild (utilizing caches) and notifies connected browsers to automatically refresh the page. This feature requires:
+
+TODO: Add explanation once live reload is implemented (CLI option + yaml config)
+TODO: Mention that this supersedes ui5-livereload-middleware
+
 ## Standard Middleware
 
 ::: info Removed Middleware
@@ -87,6 +147,12 @@ Answers all non-read requests (POST, PUT, DELETE, etc.) that have not been answe
 ### serveIndex
 In case a directory has been requested, this middleware renders an HTML with a list of the directory's content.
 
+## Standard Tasks
+With UI5 CLI v5, a set of Standard Tasks is executed during a server build...
+(excluding "minify", "generateLibraryPreload", "generateComponentPreload", "generateBundle")
+TODO: Add list/table of standard tasks for ui5 serve (similar to Builder docs) with reference to the API docs (for more info)
+TODO: Add --exclude-task explanation once and whether it's merged: "You may exclude unnecessary tasks to speed up development even more: ui5 serve --exclude-task enhanceManifest
+
 ## SSL Certificates
 When starting the UI5 Server in HTTPS- or HTTP/2 mode, for example by using UI5 CLI parameter `--h2`, you will be prompted for the automatic generation of a local SSL certificate if necessary.
 

internal/documentation/docs/pages/extensibility/CustomServerMiddleware.md

@@ -34,6 +34,33 @@ There can be optional configuration parameters which are passed directly to the
 
 An optional mountPath for which the middleware function is invoked can be provided. It will be passed to the `app.use` call (see [express API reference](https://expressjs.com/en/4x/api.html#app.use)).
 
+### With Incremental Build
+
+**Change in UI5 CLI v5:** The development server now integrates with the incremental build system. When a request comes in, the server builds the project on-demand (if no cache exists or the cache is stale) before serving resources.
+
+- **Custom build tasks from dependencies execute automatically**: If your reusable library or module defines custom build tasks, they will be executed during the build phase. You no longer need to configure custom middleware at the root project level to handle tasks from dependencies.
+
+- **Middleware receives pre-built resources**: The `resources` parameter passed to your middleware implementation provides access to fully built resources, including outputs from all build tasks (both standard and custom).
+
+#### Accessing Build Outputs in Middleware
+
+The `resources` readers provided to your middleware return pre-built resources:
+
+```js
+export default function({resources, log}) {
+    return async function (req, res, next) {
+        // This returns the built resource, including all task transformations
+        const resource = await resources.all.byPath(req.path);
+        
+        if (resource) {
+            const content = await resource.getString();
+            // The content has already been processed by all build tasks
+        }
+        next();
+    }
+}
+```
+
 ### Execution order
 
 Note that middleware configurations are applied in the order they are defined. When referencing another custom middleware, it has to be defined *before* that reference.

internal/documentation/docs/pages/extensibility/CustomTasks.md

@@ -103,6 +103,108 @@ task:
   path: lib/tasks/renderMarkdownFiles.js
 ```
 
+## Incremental Build Support
+
+Starting with UI5 CLI v5, the UI5 Builder supports **incremental builds** by caching task data. Custom tasks can opt into this behavior to improve performance.
+
+### How Incremental Builds Work for Tasks
+
+1. **First Execution**: The task runs normally and its outputs are cached
+1. **Resource Tracking**: The build system tracks which resources the task reads and writes
+1. **Cache Validation**: On subsequent builds, if the task's inputs haven't changed, the cached outputs are reused and the task is skipped
+1. **Incremental Execution**: If only some inputs changed, the task can optionally process only those changed resources (see [supportsDifferentialBuilds()](#supportsDifferentialBuilds()) below)
+
+### Making Your Task Cache-Aware (Differential Builds)
+
+Custom build tasks can now optionally support **differential builds** by implementing the following new features.
+
+::: info Info
+When a task supports differential builds, it is the task author's responsibility to ensure correctness. Specifically, if a task's output for resource A depends on the content of resource B, the task must account for this when processing only the changed resources. Tasks that cannot reliably determine such cross-resource dependencies should not enable differential build support. For example, bundling tasks — where the output depends on the content of many input resources — may not support differential builds until a more robust solution is available.
+:::
+
+#### `supportsDifferentialBuilds()`
+
+TODO: Check this section again
+
+Indicates whether your task can process only changed resources:
+
+```js
+/**
+ * Indicates whether this task can perform differential builds
+ * 
+ * @returns {boolean} True if the task can process only modified resources
+ */
+export function supportsDifferentialBuilds() {
+    return true;  // This task can process only changed files
+}
+```
+
+When this returns `true`, your task's main function receives an additional parameter indicating which resources have changed. The task can then process only those resources instead of all resources.
+
+#### `determineBuildSignature({log, options})`
+
+TODO: Check this section again
+
+Returns `undefined` or an arbitrary string representing the build signature for the task. This can be used to incorporate task-specific configuration files into the build signature of the project, causing the cache to be invalidated if those files change. The string should not be a hash value (the build signature hash is calculated later). If `undefined` is returned, or if the method is not implemented, it is assumed that the task's cache remains valid until relevant input resources change.
+
+This method is called once at the beginning of every build. The return value is used to calculate a unique signature for the task based on its configuration. This signature is then incorporated into the overall build signature of the project.
+
+```js
+/**
+ * Determines the build signature for this task
+ * 
+ * Configuration changes that affect output should be reflected in this signature
+ * 
+ * @param {object} parameters
+ * @param {@ui5/logger/Logger} parameters.log Logger instance
+ * @param {object} parameters.options Task options from ui5.yaml
+ * @returns {Promise<string | undefined>} Build signature string
+ */
+export async function determineBuildSignature({log, options}) {
+    return "TODO:";
+}
+```
+
+**Example use case:** A TypeScript compilation task that includes the TypeScript version and `tsconfig.json` settings in its signature, so the cache is invalidated when compiler settings change.
+
+#### `determineExpectedOutput({workspace, dependencies, log, options})`
+
+TODO: Check this section again
+
+Declares which resources the task is expected to produce. This allows the build system to detect and remove stale outputs when the task stops producing files it previously created.
+
+This method is called right before the task is being executed. It is used to detect stale output resources that were produced in a previous execution of the task, but are no longer produced in the current execution. Such stale resources must be removed from the build output to avoid inconsistencies.
+
+```js
+/**
+ * Determines which resources this task is expected to produce
+ * 
+ * @param {object} parameters
+ * @param {module:@ui5/fs.DuplexCollection} parameters.workspace Reader/Writer for project resources
+ * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader for dependency resources
+ * @param {@ui5/logger/Logger} parameters.log Logger instance
+ * @param {object} parameters.options Task options from ui5.yaml
+ * @returns {Promise<Array<string>>} Array of resource paths this task will produce
+ */
+export async function determineExpectedOutput({workspace, dependencies, log, options}) {
+    // Return the paths of resources this task will create
+    const sourceFiles = await workspace.byGlob("**/*.ts");
+    return sourceFiles.map(resource => 
+        resource.getPath().replace(/\.ts$/, ".js")
+    );
+}
+```
+
+**Example use case:** A code generator that creates JavaScript files from TypeScript sources. If a `.ts` file is deleted, the corresponding `.js` file should also be removed.
+
+### Best Practices for Cache-Aware Tasks
+
+1. **Keep tasks deterministic**: Given the same inputs, always produce the same outputs
+2. **Use `determineBuildSignature`**: Include all configuration that affects output in the build signature
+3. **Opt into differential builds carefully**: Only set `supportsDifferentialBuilds = true` if your task can safely process files independently
+4. **Declare expected outputs**: Implement `determineExpectedOutput` if your task generates new files (not just modifies existing ones)
+5. **Test cache behavior**: Verify that your task produces identical results whether running from cache or fresh execution
+
 ## Task Implementation
 
 A custom task implementation needs to return a function with the following signature: