OfficialSite/docs/development.md

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 for details.

---

• Installation
• Usage
• Configuration
  • Environment Configuration
  • Development Configuration
    • paths option
    • paths.url option
    • paths.dest option
    • tasks option
    • server option
• Tasks
  • concats
  • scripts
  • styles
  • svgs

Installation

# Install dependencies from package.json
npm install

Usage

# Start development server, watch for changes, and compile assets
npm start

# Compile and minify assets
npm run build

See build.js and watch.js for details.

Configuration

For development, most configuration values for processing front-end assets are defined in the 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 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.

{
    "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.

{
    "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.

{
    "paths": {
        "dest": "./www"
    }
}

tasks option

Which assets and how they should be processed can be configured via the tasks setting:

{
    "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 section, below, for details.

server option

The development server (BrowserSync) can be configured via the server setting:

{
    "server": {
        "open": true,
        "https": {
            "key": "~/.config/valet/Certificates/{% paths.url %}.key",
            "cert": "~/.config/valet/Certificates/{% paths.url %}.crt"
        }
    }
}

Visit BrowserSync's documentation for all options.

Tasks

The boilerplate provides a handful of "tasks" for handling the most commonly processed assets.

concats

For concatenating multiple files.

Example:

{
    "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 for details.

scripts

For bundling and minifying modern JS/ES6 modules.

Example:

{
    "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 for details.

styles

For compiling and minifying Sass into CSS.

Example:

{
    "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 for details.

svgs

For transforming and minifying SVG files and generating spritesheets.

Example:

{
    "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 for details.