Rewrite README
And split sections from README into dedicated documentation files. Added: - "Features" section to summarize the boilerplate's architecture. - "Getting Started" section to describe how to create a project from the boilerplate. - "Development" documentation to describe how NPM dependencies, configuring assets and tasks. - "Technologies" documentation to describe CSS, JS, Locomotive Scroll, ModularLoad, ModularJS. Changed: - Moved section "Configuration" to 'docs/development.md'. - Moved sections "Styles", "Scripts", "Page transitions", and "Scroll detection" to 'docs/technologies.md'. TODO: - Move "Environment configuration" section from "Development" to 'feature/local-config' branch.
This commit is contained in:
Chauncey McAskill
320
docs/development.md
Normal file
320
docs/development.md
Normal file
@@ -0,0 +1,320 @@
|
||||
# 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)
|
||||
* [`tasks` option](#tasks-option)
|
||||
* [`server` option](#server-option)
|
||||
* [Tasks](#tasks)
|
||||
* [`concats`](#concats)
|
||||
* [`scripts`](#scripts)
|
||||
* [`styles`](#styles)
|
||||
* [`svgs`](#svgs)
|
||||
|
||||
## Installation
|
||||
|
||||
```sh
|
||||
# Install dependencies from package.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```sh
|
||||
# Start development server, watch for changes, and compile assets
|
||||
npm start
|
||||
|
||||
# Compile and minify assets
|
||||
npm run build
|
||||
```
|
||||
|
||||
See [`build.js`](../build/build.js) and [`watch.js`](../build/watch.js)
|
||||
for details.
|
||||
|
||||
## Configuration
|
||||
|
||||
For development, most configuration values for processing front-end assets
|
||||
are defined in the [`loconfig.json`](../loconfig.json) file that exists at
|
||||
the root directory of your project.
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
If any configuration options vary depending on whether your project is
|
||||
running on your computer, a collaborator's computer, or on a web server,
|
||||
these values should be stored in a `loconfig.local.json` file.
|
||||
|
||||
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.
|
||||
|
||||
That file can be copied to `loconfig.local.json` and customized to suit
|
||||
your local environment.
|
||||
|
||||
Your `loconfig.local.json` _should not_ be committed to your project's
|
||||
source control.
|
||||
|
||||
> 💡 If you are developing with a team, you may wish to continue
|
||||
> including a `loconfig.example.json` file with your project.
|
||||
|
||||
### Development Configuration
|
||||
|
||||
The boilerplate provides a few configuration settings to control the
|
||||
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.
|
||||
|
||||
Template tags are specified using `{% %}` delimiters. They will be
|
||||
automatically expanded when tasks process paths.
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"paths": {
|
||||
"styles": {
|
||||
"src": "./assets/styles",
|
||||
"dest": "./www/assets/styles"
|
||||
}
|
||||
},
|
||||
"tasks": {
|
||||
"styles": [
|
||||
{
|
||||
"infile": "{% paths.styles.src %}/main.scss", // ./assets/styles/main.scss
|
||||
"outfile": "{% paths.styles.dest %}/main.css" // ./www/assets/styles/main.css
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `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.
|
||||
|
||||
```json
|
||||
{
|
||||
"paths": {
|
||||
"url": "locomotive-boilerplate.test"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `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.
|
||||
|
||||
```json
|
||||
{
|
||||
"paths": {
|
||||
"dest": "./www"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### `tasks` option
|
||||
|
||||
Which assets and how they should be processed can be configured via
|
||||
the `tasks` setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"tasks": {
|
||||
"scripts": [
|
||||
{
|
||||
"includes": [
|
||||
"./assets/scripts/app.js"
|
||||
],
|
||||
"outfile": "./www/assets/scripts/app.js"
|
||||
}
|
||||
],
|
||||
"styles": [
|
||||
{
|
||||
"infile": "./assets/styles/main.scss",
|
||||
"outfile": "./www/assets/styles/main.css"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
See [tasks](#tasks) section, below, for details.
|
||||
|
||||
#### `server` option
|
||||
|
||||
The development server (BrowserSync) can be configured via
|
||||
the `server` setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"open": true,
|
||||
"https": {
|
||||
"key": "~/.config/valet/Certificates/{% paths.url %}.key",
|
||||
"cert": "~/.config/valet/Certificates/{% paths.url %}.crt"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Visit [BrowserSync's documentation](https://browsersync.io/docs/options)
|
||||
for all options.
|
||||
|
||||
## Tasks
|
||||
|
||||
The boilerplate provides a handful of "tasks" for handling
|
||||
the most commonly processed assets.
|
||||
|
||||
### `concats`
|
||||
|
||||
For concatenating multiple files.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"concats": [
|
||||
{
|
||||
"label": "Application Vendors",
|
||||
"includes": [
|
||||
"{% paths.scripts.src %}/vendors/*.js",
|
||||
"node_modules/focus-visible/dist/focus-visible.min.js",
|
||||
"node_modules/vue/dist/vue.min.js",
|
||||
"node_modules/vuelidate/dist/vuelidate.min.js",
|
||||
"node_modules/vuelidate/dist/validators.min.js"
|
||||
],
|
||||
"outfile": "{% paths.scripts.dest %}/app/vendors.js"
|
||||
},
|
||||
{
|
||||
"label": "Public Site Vendors",
|
||||
"includes": [
|
||||
"{% paths.scripts.src %}/vendors/*.js",
|
||||
"node_modules/focus-visible/dist/focus-visible.min.js"
|
||||
],
|
||||
"outfile": "{% paths.scripts.dest %}/site/vendors.js"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See [`concats.js`](../build/tasks/concats.js) for details.
|
||||
|
||||
### `scripts`
|
||||
|
||||
For bundling and minifying modern JS/ES6 modules.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"scripts": [
|
||||
{
|
||||
"label": "Application Dashboard JS",
|
||||
"includes": [
|
||||
"{% paths.scripts.src %}/app/dashboard.js"
|
||||
],
|
||||
"outfile": "{% paths.scripts.dest %}/app/dashboard.js"
|
||||
},
|
||||
{
|
||||
"label": "Public Site JS",
|
||||
"includes": [
|
||||
"{% paths.scripts.src %}/site/main.js"
|
||||
],
|
||||
"outfile": "{% paths.scripts.dest %}/site/main.js"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See [`scripts.js`](../build/tasks/scripts.js) for details.
|
||||
|
||||
### `styles`
|
||||
|
||||
For compiling and minifying Sass into CSS.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"styles": [
|
||||
{
|
||||
"label": "Text Editor CSS",
|
||||
"infile": "{% paths.styles.src %}/app/editor.scss",
|
||||
"outfile": "{% paths.styles.dest %}/app/editor.css"
|
||||
},
|
||||
{
|
||||
"label": "Application Dashboard CSS",
|
||||
"infile": "{% paths.styles.src %}/app/dashboard.scss",
|
||||
"outfile": "{% paths.styles.dest %}/app/dashboard.css"
|
||||
},
|
||||
{
|
||||
"label": "Public Site Critical CSS",
|
||||
"infile": "{% paths.styles.src %}/site/critical.scss",
|
||||
"outfile": "{% paths.styles.dest %}/site/critical.css"
|
||||
},
|
||||
{
|
||||
"label": "Public Site CSS",
|
||||
"infile": "{% paths.styles.src %}/site/main.scss",
|
||||
"outfile": "{% paths.styles.dest %}/site/main.css"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See [`styles.js`](../build/tasks/styles.js) for details.
|
||||
|
||||
### `svgs`
|
||||
|
||||
For transforming and minifying SVG files and generating spritesheets.
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"svgs": [
|
||||
{
|
||||
"label": "Application Spritesheet",
|
||||
"includes": [
|
||||
"{% paths.images.src %}/app/*.svg"
|
||||
],
|
||||
"outfile": "{% paths.svgs.dest %}/app/sprite.svg"
|
||||
},
|
||||
{
|
||||
"label": "Public Site Spritesheet",
|
||||
"includes": [
|
||||
"{% paths.images.src %}/site/*.svg"
|
||||
],
|
||||
"outfile": "{% paths.svgs.dest %}/site/sprite.svg"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
207
docs/technologies.md
Normal file
207
docs/technologies.md
Normal file
@@ -0,0 +1,207 @@
|
||||
# Technologies
|
||||
|
||||
* [Styles](#styles)
|
||||
* [CSS Architecture](#css-architecture)
|
||||
* [CSS Naming Convention](#css-naming-convention)
|
||||
* [CSS Namespacing](#css-namespacing)
|
||||
* [Example](#example-1)
|
||||
* [Scripts](#scripts)
|
||||
* [Example](#example-2)
|
||||
* [Page transitions](#page-transitions)
|
||||
* [Example](#example-3)
|
||||
* [Scroll detection](#scroll-detection)
|
||||
* [Example](#example-4)
|
||||
|
||||
## Styles
|
||||
|
||||
[SCSS][Sass] is a superset of CSS that adds many helpful features to improve
|
||||
and modularize our styles.
|
||||
|
||||
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
|
||||
|
||||
The boilerplate's CSS architecture is based on [Inuit CSS][inuitcss] and [ITCSS].
|
||||
|
||||
* `settings`: Global variables, site-wide settings, config switches, etc.
|
||||
* `tools`: Site-wide mixins and functions.
|
||||
* `generic`: Low-specificity, far-reaching rulesets (e.g. resets).
|
||||
* `elements`: Unclassed HTML elements (e.g. `a {}`, `blockquote {}`, `address {}`).
|
||||
* `objects`: Objects, abstractions, and design patterns (e.g. `.o-layout {}`).
|
||||
* `components`: Discrete, complete chunks of UI (e.g. `.c-carousel {}`).
|
||||
* `utilities`: High-specificity, very explicit selectors. Overrides and helper
|
||||
classes (e.g. `.u-hidden {}`)
|
||||
|
||||
Learn more about [Inuit CSS](https://github.com/inuitcss/inuitcss#css-directory-structure).
|
||||
|
||||
#### CSS Naming Convention
|
||||
|
||||
We use a simplified [BEM] (Block, Element, Modifier) syntax:
|
||||
|
||||
* `.block`
|
||||
* `.block_element`
|
||||
* `.-modifier`
|
||||
|
||||
#### CSS Namespacing
|
||||
|
||||
We namespace our classes for more UI transparency:
|
||||
|
||||
* `o-`: Object that it may be used in any number of unrelated contexts to the one you can currently see it in. Making modifications to these types of class could potentially have knock-on effects in a lot of other unrelated places.
|
||||
* `c-`: Component is a concrete, implementation-specific piece of UI. All of the changes you make to its styles should be detectable in the context you’re currently looking at. Modifying these styles should be safe and have no side effects.
|
||||
* `u-`: Utility has a very specific role (often providing only one declaration) and should not be bound onto or changed. It can be reused and is not tied to any specific piece of UI.
|
||||
* `s-`: Scope creates a new styling context. Similar to a Theme, but not necessarily cosmetic, these should be used sparingly—they can be open to abuse and lead to poor CSS if not used wisely.
|
||||
* `is-`, `has-`: Is currently styled a certain way because of a state or condition. It tells us that the DOM currently has a temporary, optional, or short-lived style applied to it due to a certain state being invoked.
|
||||
|
||||
Learn about [namespacing](https://csswizardry.com/2015/03/more-transparent-ui-code-with-namespaces/).
|
||||
|
||||
#### Example \#1
|
||||
|
||||
```html
|
||||
<div class="c-block -large">
|
||||
<div class="c-block_layout o-layout">
|
||||
<div class="o-layout_item u-1/2@from-medium">
|
||||
<div class="c-block_heading o-h -medium">Heading</div>
|
||||
</div>
|
||||
<div class="o-layout_item u-1/2@from-medium">
|
||||
<a class="c-block_button o-button -outline" href="#">Button</a>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
```scss
|
||||
.c-block {
|
||||
&.-large {
|
||||
padding: rem(60px);
|
||||
}
|
||||
}
|
||||
|
||||
.c-block_heading {
|
||||
@media (max-width: $to-medium) {
|
||||
.c-block.-large & {
|
||||
margin-bottom: rem(40px);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Scripts
|
||||
|
||||
We use [esbuild] for bundling and minifying JavaScript/ES6.
|
||||
|
||||
[modularJS] is a small framework we use on top of ES modules.
|
||||
|
||||
* Automatically init visible modules.
|
||||
* Easily call other modules methods.
|
||||
* Quickly set scoped events with delegation.
|
||||
* Simply select DOM elements scoped in their module.
|
||||
|
||||
[_source_](https://github.com/modularorg/modularjs#why)
|
||||
|
||||
#### Example \#2
|
||||
|
||||
```html
|
||||
<div data-module-example>
|
||||
<div data-example="main">
|
||||
<h2>Example</h2>
|
||||
</div>
|
||||
<button data-example="load">More</button>
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
import { module } from 'modujs';
|
||||
|
||||
export default class extends module {
|
||||
constructor(m) {
|
||||
super(m);
|
||||
|
||||
this.events = {
|
||||
click: {
|
||||
load: 'loadMore'
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
loadMore() {
|
||||
this.$('main')[0].classList.add('is-loading');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Learn more about [modularJS].
|
||||
|
||||
## Page transitions
|
||||
|
||||
[modularLoad] is used for page transitions and lazy loading.
|
||||
|
||||
#### Example \#3
|
||||
|
||||
```html
|
||||
<nav>
|
||||
<a href="/">Home</a>
|
||||
<a href="/page" data-load="transitionName">Page</a>
|
||||
</nav>
|
||||
<div data-load-container>
|
||||
<img data-load-src="assets/images/hello.jpg">
|
||||
</div>
|
||||
```
|
||||
```js
|
||||
import modularLoad from 'modularload';
|
||||
|
||||
this.load = new modularLoad({
|
||||
enterDelay: 300,
|
||||
transitions: {
|
||||
transitionName: {
|
||||
enterDelay: 450
|
||||
}
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
Learn more about [modularLoad].
|
||||
|
||||
## Scroll detection
|
||||
|
||||
[Locomotive Scroll][locomotive-scroll] is used for elements in viewport
|
||||
detection and smooth scrolling with parallax.
|
||||
|
||||
#### Example \#4
|
||||
|
||||
```html
|
||||
<div data-module-scroll>
|
||||
<div data-scroll>Trigger</div>
|
||||
<div data-scroll data-scroll-speed="1">Parallax</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
```js
|
||||
import LocomotiveScroll from 'locomotive-scroll';
|
||||
|
||||
this.scroll = new LocomotiveScroll({
|
||||
el: this.el,
|
||||
smooth: true
|
||||
});
|
||||
````
|
||||
|
||||
Learn more about [Locomotive Scroll][locomotive-scroll].
|
||||
|
||||
[Autoprefixer]: https://autoprefixer.github.io/
|
||||
[BEM]: https://bem.info/
|
||||
[BrowserSync]: https://browsersync.io/
|
||||
[esbuild]: https://esbuild.github.io/
|
||||
[inuitcss]: https://github.com/inuitcss/inuitcss
|
||||
[ITCSS]: https://itcss.io/
|
||||
[locomotive-scroll]: https://github.com/locomotivemtl/locomotive-scroll
|
||||
[modularJS]: https://github.com/modularorg/modularjs
|
||||
[modularLoad]: https://github.com/modularorg/modularload
|
||||
[node-sass]: https://github.com/sass/node-sass
|
||||
[PostCSS]: https://postcss.org/
|
||||
[Sass]: https://sass-lang.com/
|
||||
[svg-mixer]: https://github.com/JetBrains/svg-mixer
|
||||
[Node]: https://nodejs.org/
|
||||
[NPM]: https://npmjs.com/
|
||||
[NVM]: https://github.com/nvm-sh/nvm
|
||||
Reference in New Issue
Block a user