Braze

Orchestrator of re-useable HTML components to generate a static site without having to rewrite common code.

How to install

Install globally

Run the command anywhere:

npm install -g braze

sudo prefix might be required on some computers.

Install in a project

Run the command:

npm install --save braze

Usage

Configuration File

Start by creating a configuration file to tell braze where your components and HTML pages are. The command braze init (global) or npx braze init (one-time run) can be used to generate a generic braze config file in the current directory.

Make sure the braze.js file is in your project root.

Example braze.js file:

module.exports = {
    // Static HTML files that use your components
    pagesDir: "./pages",

    // Directory to output compiled files to
    outputDir: "./dist",

    // Location of your .html component files (optional)
    componentsDir: "./components",

    // optional additonal properties to use in context when compiling
    props: {
        "appTitle": "The best app"
    },

    // if you want the output to be minified or not
    minifyOutput: true,

    helpers: {
        ucase: (string) => string.toUpperCase(),
    },
}

Components

To use a define component use handlebars syntax like so:

{{ navigation }}
{{ header }}

Where the string used between the {{}} is the base file name. For example the component file name navigation.html will available as navigation.

Components support all Handlebars syntax including loops. For example:

braze.js

module.exports = {
    "props": {
        "people": ["Sam", "John", "Alex"]
    }
}

component HTML file

<ul>
    {{#each people}}
        <li>{{this}}</li>
    {{/each}}
</ul>

Building

When ready to compile your pages with the components run the braze command (if installed globally):

braze build

Or create a package.json script (if installed at project level):

{
    "name": "my-project",
    "scripts": {
        "start": "node app.js",
        "build": "braze build"
    }
}

and run the command npm run build.

Watching for Changes

Use the command braze watch in the project directory to watch the source files and re-build on detected change.

Using Helpers

To use helper functions in your HTML pages, define functions in your braze.js file like so:

{
    props: {
        name: 'John',
    },
    helpers: {
        ucase: (string) => string.toUpperCase(),
    }
}

and in your HTML:

{{ ucase name }}