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 fc1ccda..0000000 --- a/docs/book/v1/how-tos/bundle-static-modules.md +++ /dev/null @@ -1,44 +0,0 @@ -# Bundle Static Modules - -> Prerequisite software: Node.js v20 (minimum supported version) - -[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`. - -> 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 -``` diff --git a/docs/book/v1/how-tos/manage-assets.md b/docs/book/v1/how-tos/manage-assets.md index a685d09..9ed60e2 100644 --- a/docs/book/v1/how-tos/manage-assets.md +++ b/docs/book/v1/how-tos/manage-assets.md @@ -1,46 +1,81 @@ -# Manage Assets +# Assets and the Vite build -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 `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`: -While the `images` and `fonts` folders are copied as is, the `js` and `scss` 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. + ## Browser caching of `js` and `css` One thing of note is that browsers cache the `js` and `css` files. @@ -50,9 +85,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. diff --git a/mkdocs.yml b/mkdocs.yml index 8e6194f..28ec386 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 site_name: light site_description: "Dotkernel Light" repo_url: "https://github.com/dotkernel/light"