diff --git a/README.md b/README.md index ff8ae96..8bb685c 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ ## Features -* Uses a custom, easily configured, wrapper [asset handler](docs/development.md). -* Uses [Sass] for a feature rich extension of CSS. -* Uses [ESBuild] for extremely fast processing of JS/ES6. +* Uses a custom [task runner](docs/development.md) for handling assets. +* Uses [BrowserSync] for fast development and testing in browsers. +* Uses [Sass] for a feature rich superset of CSS. +* Uses [ESBuild] for extremely fast processing of JS/ES modules. * Uses [SVG Mixer] for processing SVG files and generating spritesheets. * Uses [ITCSS] for a sane and scalable CSS architecture. * Uses [Locomotive Scroll] for smooth scrolling with parallax effects. -* Uses [BrowserSync] for fast development and testing in browsers. Learn more about [languages and technologies](docs/technologies.md). @@ -61,6 +61,9 @@ Then update the following files to suit your project: ## Installation ```sh +# Switch to recommended Node version from .nvmrc +nvm use + # Install dependencies from package.json npm install ``` @@ -68,7 +71,7 @@ npm install ## Development ```sh -# Watch for file changes and compile assets +# Start development server, watch for changes, and compile assets npm start # Compile and minify assets @@ -82,14 +85,14 @@ Learn more about [development and building](docs/development.md). * [Development and building](docs/development.md) * [Languages and technologies](docs/technologies.md) -[BrowserSync]: https://browsersync.io/ -[ESBuild]: https://esbuild.github.io/ +[BrowserSync]: https://npmjs.com/package/browser-sync +[ESBuild]: https://npmjs.com/package/esbuild [ITCSS]: https://itcss.io/ -[Locomotive Scroll]: https://github.com/locomotivemtl/locomotive-scroll -[modularJS]: https://github.com/modularorg/modularjs -[modularLoad]: https://github.com/modularorg/modularload +[Locomotive Scroll]: https://npmjs.com/package/locomotive-scroll +[modularJS]: https://npmjs.com/package/modujs +[modularLoad]: https://npmjs.com/package/modularload [Sass]: https://sass-lang.com/ -[SVG Mixer]: https://github.com/JetBrains/svg-mixer +[SVG Mixer]: https://npmjs.com/package/svg-mixer [Node]: https://nodejs.org/ [NPM]: https://npmjs.com/ [NVM]: https://github.com/nvm-sh/nvm diff --git a/docs/development.md b/docs/development.md index b7db3a0..1b6fae4 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,24 +1,13 @@ # Development -Essentially, the boilerplate uses: - -* [esbuild] for processing JS, -* [node-sass] for processing CSS, -* [svg-mixer] for processing SVG, -* [browsersync] for testing in browsers. - -See [technologies](./technologies.md) for details. - ---- - * [Installation](#installation) * [Usage](#usage) * [Configuration](#configuration) * [Environment Configuration](#environment-configuration) * [Development Configuration](#development-configuration) * [`paths` option](#paths-option) - * [`paths.url` option](#paths.url-option) - * [`paths.dest` option](#paths.dest-option) + * [`paths.url` option](#pathsurl-option) + * [`paths.dest` option](#pathsdest-option) * [`tasks` option](#tasks-option) * [`server` option](#server-option) * [Tasks](#tasks) @@ -27,9 +16,24 @@ See [technologies](./technologies.md) for details. * [`styles`](#styles) * [`svgs`](#svgs) +--- + +The boilerplate provides a custom, easily configured, and very simple, +task runner for [Node] to process assets and test quickly in browsers. + +Learn more about the boilerplate's [tasks](#tasks) below. + ## Installation +Make sure you have the following installed: + +* [Node] — at least 14.17, the latest LTS is recommended. +* [NPM] — at least 6.0, the latest LTS is recommended. + ```sh +# Switch to recommended Node version from .nvmrc +nvm use + # Install dependencies from package.json npm install ``` @@ -63,7 +67,7 @@ In fresh copy of the boilerplate, the root directory of your project will contain a [`loconfig.example.json`](../loconfig.example.json) file. > 💡 The boilerplate's default example customizes the development server -> with a custom SSL certificate. +> to use a custom SSL certificate. That file can be copied to `loconfig.local.json` and customized to suit your local environment. @@ -81,8 +85,10 @@ behaviour for processing front-end assets. #### `paths` option -The `paths` setting is primarily used for template tags to reference -any configuration properties, such as file paths, to reduce repetition. +The `paths` option defines URIs and file paths. + +It is primarily used for template tags to reference any configuration +properties to reduce repetition. Template tags are specified using `{% %}` delimiters. They will be automatically expanded when tasks process paths. @@ -98,8 +104,8 @@ automatically expanded when tasks process paths. "tasks": { "styles": [ { - "infile": "{% paths.styles.src %}/main.scss", // ./assets/styles/main.scss - "outfile": "{% paths.styles.dest %}/main.css" // ./www/assets/styles/main.css + "infile": "{% paths.styles.src %}/main.scss", // → ./assets/styles/main.scss + "outfile": "{% paths.styles.dest %}/main.css" // → ./www/assets/styles/main.css } ] } @@ -109,6 +115,7 @@ automatically expanded when tasks process paths. #### `paths.url` option The `paths.url` option defines the base URI of the project. + By default, it is used by the development server as a proxy for an existing virtual host. @@ -123,8 +130,9 @@ for an existing virtual host. #### `paths.dest` option The `paths.dest` option defines the public web directory of the project. + By default, it is used by the development server as the base directory -to serve the website from. +to serve the website from if a proxy URI is not provided. ```json { @@ -137,7 +145,7 @@ to serve the website from. #### `tasks` option Which assets and how they should be processed can be configured via -the `tasks` setting: +the `tasks` option: ```json { @@ -165,7 +173,7 @@ See [tasks](#tasks) section, below, for details. #### `server` option The development server (BrowserSync) can be configured via -the `server` setting: +the `server` option: ```json { @@ -184,12 +192,14 @@ for all options. ## Tasks -The boilerplate provides a handful of "tasks" for handling +The boilerplate provides a handful of tasks for handling the most commonly processed assets. ### `concats` -For concatenating multiple files. +A wrapper around [concat] (with optional support for globbing) for concatenating multiple files. + +By default, [tiny-glob] is installed with the boilerplate. Example: @@ -223,7 +233,7 @@ See [`concats.js`](../build/tasks/concats.js) for details. ### `scripts` -For bundling and minifying modern JS/ES6 modules. +A wrapper around [esbuild] for bundling and minifying modern JS/ES modules. Example: @@ -252,7 +262,10 @@ See [`scripts.js`](../build/tasks/scripts.js) for details. ### `styles` -For compiling and minifying Sass into CSS. +A wrapper around [node-sass] (and optionally [Autoprefixer] via [PostCSS]) +for compiling and minifying Sass into CSS. + +By default, [PostCSS] and [Autoprefixer] are installed with the boilerplate. Example: @@ -287,7 +300,8 @@ See [`styles.js`](../build/tasks/styles.js) for details. ### `svgs` -For transforming and minifying SVG files and generating spritesheets. +A wrapper around [SVG Mixer] for transforming and minifying SVG files +and generating spritesheets. Example: @@ -314,7 +328,15 @@ Example: See [`svgs.js`](../build/tasks/svgs.js) for details. -[browsersync]: https://browsersync.io/ -[esbuild]: https://esbuild.github.io/ -[node-sass]: https://github.com/sass/node-sass -[svg-mixer]: https://github.com/JetBrains/svg-mixer +[Autoprefixer]: https://npmjs.com/package/autoprefixer +[BrowserSync]: https://npmjs.com/package/browser-sync +[concat]: https://npmjs.com/package/concat +[esbuild]: https://npmjs.com/package/esbuild +[fast-glob]: https://npmjs.com/package/fast-glob +[glob]: https://npmjs.com/package/glob +[globby]: https://npmjs.com/package/globby +[Node]: https://nodejs.org/ +[node-sass]: https://npmjs.com/package/node-sass +[PostCSS]: https://npmjs.com/package/postcss +[SVG Mixer]: https://npmjs.com/package/svg-mixer +[tiny-glob]: https://npmjs.com/package/tiny-glob diff --git a/docs/technologies.md b/docs/technologies.md index 478da53..24dfed6 100644 --- a/docs/technologies.md +++ b/docs/technologies.md @@ -22,7 +22,7 @@ We use [node-sass] (LibSass) for processing and minifying SCSS into CSS. We also use [PostCSS] and [Autoprefixer] to parse our CSS and add vendor prefixes for experimental features. -#### CSS Architecture +### CSS Architecture The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS]. @@ -37,7 +37,7 @@ The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS] Learn more about [Inuit CSS](https://github.com/inuitcss/inuitcss#css-directory-structure). -#### CSS Naming Convention +### CSS Naming Convention We use a simplified [BEM] (Block, Element, Modifier) syntax: @@ -45,7 +45,7 @@ We use a simplified [BEM] (Block, Element, Modifier) syntax: * `.block_element` * `.-modifier` -#### CSS Namespacing +### CSS Namespacing We namespace our classes for more UI transparency: @@ -57,7 +57,7 @@ We namespace our classes for more UI transparency: Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/). -#### Example \#1 +### Example \#1 ```html
@@ -90,7 +90,7 @@ Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-co ## Scripts -We use [esbuild] for bundling and minifying JavaScript/ES6. +We use [esbuild] for bundling and minifying JavaScript/ES modules. [modularJS] is a small framework we use on top of ES modules. @@ -99,9 +99,9 @@ We use [esbuild] for bundling and minifying JavaScript/ES6. * Quickly set scoped events with delegation. * Simply select DOM elements scoped in their module. -[_source_](https://github.com/modularorg/modularjs#why) +[_source_](https://npmjs.com/package/modujs#why) -#### Example \#2 +### Example \#2 ```html
@@ -138,7 +138,7 @@ Learn more about [modularJS]. [modularLoad] is used for page transitions and lazy loading. -#### Example \#3 +### Example \#3 ```html