docs: Add Incremental Build Vitepress docs#1404
Conversation
JIRA: CPOUI5FOUNDATION-1205
maxreichmann
force-pushed
the
feat/incremental-build-documentation
branch
from
8c2f154 to
4fedc7e
Compare
- Drop phrase "Incremental Build" and use "Build Cache" instead - Remove "Starting with v5" everywhere except migration guide - Restructured migration guide section - Refactor Custom task, Builder and Server pages - Remove TODOs & Drop changes for unrelated pages
| } | ||
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Which additional parameter does the function receive?
| The following code snippets show examples for custom task implementations. | ||
|
|
||
| ### Example: lib/tasks/renderMarkdownFiles.js | ||
| #### Example: lib/tasks/renderMarkdownFiles.js |
There was a problem hiding this comment.
What about updating the example to show how to make use of supportsDifferentialBuilds? I would say that this should be the new best practice, so we should not highlight the old way anymore, at least not in the cases where supportsDifferentialBuilds can be used.
| ::: | ||
|
|
||
| ::: info | ||
| 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). |
There was a problem hiding this comment.
This is currently true, but only because build and serve use a different set of tasks (serve passes excludedTasks: ["minify", "generateLibraryPreload", "generateComponentPreload", "generateBundle"]), so the existing cache is not re-used. If both use the same set of tasks, the cache is shared, as they both use the same build process under the hood.
| ## Standard Middleware | ||
|
|
||
| ::: info Removed Middleware | ||
| The `serveThemes` middleware has been removed in UI5 CLI v5. Theme compilation is now handled by the `buildThemes` build task during the incremental build, which pre-compiles all theme CSS files. The resulting CSS files (including `library.css`, `library-RTL.css`, `library-parameters.json`, and CSS Variables resources) are served via the `serveResources` middleware, providing the same functionality with better performance through build-time compilation and caching. |
There was a problem hiding this comment.
Please also update this section (rephrase incremental build) and potentially others, that were recently introduced.
|
|
||
| With this feature, **build tasks are executed in server sessions**. For this reason, some custom middleware might be obsolete or cause problems. Projects utilizing such might need to adapt their configuration. | ||
|
|
||
| E.g. Middleware for browser live reloads is obsolete and can be removed. Also, middleware for Typescript transpilation is not required anymore (as long as the respective task is still set up). |
There was a problem hiding this comment.
-
The most prominent difference is that the server now actually runs a build. So any middleware that performed work which also a task did, becomes obsolete. This is not limited to TypeScript. I think this fact should also be mentioned in the beginning (
Build Cache). The simplification and making most (custom) middleware obsolete is one of the main reasons for this feature. We should highlight that. -
Live reload will be implemented via feat: Add liveReload #1407, and that PR already includes a hint for that.
-
It should be mentioned that middleware for non-build purposes such as proxies are not affected by this, and still a valid use case for a custom middleware
2 participants
JIRA: CPOUI5FOUNDATION-1205
This PR adds documentation for the IB feature and its subfeatures up to this point in time. Docu for future ones (e.g. the watch mode) will be handled during their respective items.