diff --git a/docs/book/v1/how-tos/bundle-static-modules.md b/docs/book/v1/how-tos/bundle-static-modules.md deleted file mode 100644 index 9da338a..0000000 --- a/docs/book/v1/how-tos/bundle-static-modules.md +++ /dev/null @@ -1,61 +0,0 @@ -# Bundle Static Modules - -## Summary - -How to install and run the Vite build that compiles Dotkernel Light's front-end assets into the `public` folder. - -## Details - -> Prerequisite software: Node.js `^20.19.0 || >=22.12.0` (per `package.json`) - -[Vite](https://vite.dev/) is a frontend dev tool we use: - -- To avoid network bottlenecks that can occur when your application has a lot of separate scripts and style sheets. -- To concatenate and compress (uglify) `.css` and `.js` files -- To preprocess `.scss` files into `.css`. -- To copy the `fonts` and `images` used in your project, from the `assets` folder to the `public` folder. - -First you need to install dependencies into the `node_modules` directory by running this command: - -```shell -npm install -``` - -If everything ran ok, you should see a new root folder named `node_modules` where all the npm packages are installed. -If `npm install` fails, this could be caused by user permissions for npm. -Our recommendation is to install npm through `Node Version Manager`. - -The `watch` command compiles the components then monitors the source files and triggers their recompilation when one of them is changed: - -```shell -npm run watch -``` - -Initially, Vite is configured to delete and rebuild the contents of these folders from the `public` folder: - -- css -- fonts -- images -- js - -The folders are populated from their counterparts in `src/App/assets`, with one exception: images are copied into `public/images/app/`, not `public/images/` directly, so template references look like `{{ asset('images/app/logo.svg') }}`. `fonts` has no such prefix and is copied flat into `public/fonts/`. See `vite.config.js` for the exact mapping. - -> Make sure to not edit anything inside the four public folders manually. -> Other files and folders in the public folder will be left as is. - -An alternative to the `watch` command is `build` which simply compiles the components, overwriting as needed: - -```shell -npm run build -``` - -## FAQ - -**Q: What is the minimum Node.js version Dotkernel Light supports?** -A: `^20.19.0 || >=22.12.0`, as declared in `package.json`'s `engines` field. - -**Q: What's the difference between `npm run watch` and `npm run build`?** -A: `watch` recompiles automatically whenever a source file changes; `build` compiles once. - -**Q: Can I edit the compiled files under `public/css`, `public/js`, `public/fonts` or `public/images` directly?** -A: No — Vite deletes and rebuilds those four folders on every run, from their counterparts in `src/App/assets`. diff --git a/docs/book/v1/how-tos/manage-assets.md b/docs/book/v1/how-tos/manage-assets.md index c86b432..98a9ba9 100644 --- a/docs/book/v1/how-tos/manage-assets.md +++ b/docs/book/v1/how-tos/manage-assets.md @@ -1,4 +1,4 @@ -# Manage Assets +# Assets and the Vite build ## Summary @@ -6,47 +6,91 @@ Where asset source files live, where Vite builds and copies them to, and how to ## Details -If you haven't already done so, make sure `npm` is installed. -You can keep it running during your updates with `npm run watch` or run this command after the edits are completed `npm run build`. +Assets are the static files used by your content: images, fonts, JavaScript, and SCSS. +[Vite](https://vite.dev/) compiles and copies them from `src/App/assets` into the `public` folder, which is the only folder the web server serves. -## What are assets? +> Prerequisite software: Node.js. +> `package.json` declares `"engines": { "node": "^20.19.0 || >=22.12.0" }`, so you need Node 20.19 or later on the 20.x line, or Node 22.12 or later. +> Earlier 20.x releases satisfy "Node 20" and still fail the install. -Assets are various files used by your content: +We use Vite: -- Images, -- Fonts, -- JavaScript codes, -- SCSS. +- To avoid network bottlenecks that can occur when your application has a lot of separate scripts and style sheets. +- To concatenate and compress (uglify) `.css` and `.js` files. +- To preprocess `.scss` files into `.css`. +- To copy the `fonts` and `images` used in your project, from the `assets` folder to the `public` folder. -## Assets source and destination +## Install the dependencies -The source of these files is the `src/App/assets/` folder: +First install the dependencies into the `node_modules` directory: -- src/App/assets/images -- src/App/assets/fonts -- src/App/assets/js -- src/App/assets/scss +```shell +npm install +``` + +If everything ran ok, you should see a new root folder named `node_modules` where all the npm packages are installed. +If `npm install` fails, this could be caused by user permissions for npm. +Our recommendation is to install npm through `Node Version Manager`. + +## Build the assets + +The `fonts` folder is copied flat into `public/fonts/`, but the `images` folder is copied under an extra `app/` segment - `src/App/assets/images/icon/hand.svg` becomes `public/images/app/icon/hand.svg`, not `public/images/icon/hand.svg`. +See `vite.config.js` for the exact mapping. +The `js` and `scss` files are minimized. + +The `build` command compiles the components, overwriting as needed: + +```shell +npm run build +``` + +The `watch` command compiles the components, then monitors the source files, and triggers their recompilation when one of them is changed: -The `npm` script processes these files and copies or builds files under the `public` folder. +```shell +npm run watch +``` + +## Source and destination -> You should not manage the items from the above folders manually. -> The `npm` script will delete/replace the files when run. +The source of these files is the `src/App/assets/` folder. +The destinations are not symmetrical - the `js` and `scss` trees are bundled into a single file each, and `images` lands in a subfolder of `public/images`: -The `fonts` folder is copied flat into `public/fonts/`, but the `images` folder is copied under an extra `app/` segment — `src/App/assets/images/icon/hand.svg` becomes `public/images/app/icon/hand.svg`, not `public/images/icon/hand.svg`. See `vite.config.js` for the exact mapping. The `js` and `scss` files are minimized: +| Source | Destination | What happens | +|-------------------------|----------------------|-----------------------------------------------| +| `src/App/assets/scss` | `public/css/app.css` | compiled from SCSS and minified into one file | +| `src/App/assets/js` | `public/js/app.js` | bundled and minified into one file | +| `src/App/assets/fonts` | `public/fonts/` | copied as is | +| `src/App/assets/images` | `public/images/app/` | copied as is | -- `scss` files are minimized under `public/css/app.css`. -- `js` files are minimized under `public/js/app.js`. +The `images/app/` destination is the one that catches people out: a file at `src/App/assets/images/logo.png` is served from `public/images/app/logo.png`, not `public/images/logo.png`. -The above items are by default used in the `src/App/templates/layout/default.html.twig` file. +Reference the built files in your templates with `asset()`: ```twig -... +Logo + ``` +The first two are used by default in `src/App/templates/layout/default.html.twig`. + > The source and destination folders are configured in the `vite.config.js` file. +## Do not edit the `public` folder by hand + +Treat `public/css`, `public/js`, `public/fonts` and `public/images/app` as build output. +Edit the matching files under `src/App/assets` and rebuild, or your change will be overwritten the next time anyone runs the build. + +The build overwrites the files it produces, but it does not currently clear these folders first. +A file you remove from `src/App/assets` therefore stays behind in `public` until you delete it yourself, and a renamed asset leaves its old copy in place. +If you need a clean result, delete the generated folders before rebuilding. + +`public/` also holds files Vite never touches at all: `index.php` (the application's entry point), `.htaccess`, and `robots.txt.dist`. +Neither `npm run build` nor `npm run watch` creates, deletes, or modifies them. +Vite's output directory (`public/`) sits outside its project root (`src/`), so by default Vite refuses to empty or otherwise manage anything there beyond the specific files its own plugins write - the compiled `css/app.css` and `js/app.js`, and the `fonts`/`images` copies. +You can edit `.htaccess` or `robots.txt.dist` freely; a rebuild will never revert them. + ## Browser caching of `js` and `css` One thing of note is that browsers cache the `js` and `css` files. @@ -56,9 +100,9 @@ A simple solution to force the browsers to download the newer version of the fil Whenever you commit changes to those files, make sure to increase the value of the `v` parameter. ```twig - + ... - + ``` > The values 3 and 5 are provided as an example. @@ -67,10 +111,10 @@ Whenever you commit changes to those files, make sure to increase the value of t ## FAQ **Q: Where do image assets actually end up after the build?** -A: Under `public/images/app/`, not `public/images/` directly — the `images` copy target in `vite.config.js` adds an `app/` segment that `fonts` doesn't. +A: Under `public/images/app/`, not `public/images/` directly - the `images` copy target in `vite.config.js` adds an `app/` segment that `fonts` doesn't. **Q: How do I force browsers to fetch an updated CSS or JS file?** A: Add or increment a `?v=` query parameter on the asset URL, for example `app.css?v=3`. **Q: Should I edit files directly under `public/css`, `public/js`, `public/fonts` or `public/images`?** -A: No — the `npm` script deletes and rebuilds those folders from `src/App/assets/` on every run. +A: No - the `npm` script overwrites the files it produces, but it does not clear these folders first, so your manual edit may survive until the matching source file changes, then disappear unpredictably. diff --git a/mkdocs.yml b/mkdocs.yml index 38743e5..272afdd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -21,13 +21,12 @@ nav: - "Running the Application": v1/installation/running-the-application.md - "FAQ": v1/installation/faq.md - How to: - - "Bundle Static Modules": v1/how-tos/bundle-static-modules.md - "Routing": v1/how-tos/routing.md - "Create Pages": v1/how-tos/create-pages.md - "Set Up Twitter and OpenGraph Cards": v1/how-tos/twitter-opengraph-cards.md - "Edit the Top Menu": v1/how-tos/edit-top-menu.md - "Edit the Footer": v1/how-tos/edit-footer.md - - "Manage Assets": v1/how-tos/manage-assets.md + - "Assets and the Vite build": v1/how-tos/manage-assets.md - Upgrading: - "Upgrading from 1.0 to 1.5": v1/upgrading/UPGRADE-1.5.md site_name: light