This document is the first tutorial on Bkb. We will use Webpack, SASS and TypeScript. I chose Webpack and SASS because these tools are widely used. I propose TypeScript but JavaScript developers will easily remove TypeScript syntax and packages.

However, I did not cover in this document the case of an HTML template engine, because their use is too different from one engine to another.

In a new directory:

# Create the file "package.json"
npm init
# Install Bkb and Webpack
npm install -D bkb webpack webpack-cli
# Install SASS with Webpack
npm install -D node-sass sass-loader css-loader mini-css-extract-plugin
# Install TypeScript with Webpack
npm install -D typescript ts-loader @types/webpack

With Bkb, a component is a part of the application. It can be anything: a form, a service, the model, are all components. We suggest to make a directory for each component.

So, create the directory src/HelloWorld/. Then, create the following file:

// src/HelloWorld/index.ts
require("./HelloWorld.scss")
import { Dash } from "bkb"
import FirstApp from "../FirstApp"

export default class HelloWorld {
  readonly el: HTMLElement

  constructor(private dash: Dash<FirstApp>) {
    this.el = document.createElement("p")
    this.el.classList.add("HelloWorld")
    this.el.innerText = "Hello, World!"
  }
}

A component is almost a POJO. You are free to make the members you want. The only special thing is, it has to be instanciated by the Bkb API. And Bkb passes a dash object as the constructor's first parameter. The dash will be the link between your component and the framework.

For this very simple component, we don't use the dash. The constructor just creates a static paragraph and exposes it as an el member.

Notice also the require("./HelloWorld.scss") at the first line. We use the Webpack capability to bundle SCSS files. You can create the corresponding SCSS file:

// src/HelloWorld/HelloWorld.scss
.HelloWorld {
  color: green;
  font-size: 1.5rem;
}

With Bkb, an application is a special component: it is the root component in the tree of Bkb components. Because it is a component, you can create a new directory src/FirstApp/.

Put the following file:

// src/FirstApp/index.ts
require("./FirstApp.scss")
import { AppDash, LogEvent } from "bkb"
import HelloWorld from "../HelloWorld"

export default class FirstApp {
  readonly el: HTMLElement

  constructor(private dash: AppDash<FirstApp>) {
    dash.listenTo<LogEvent>("log", ev => {
      console.log(`[${ev.level}]`, ...ev.messages)
    })

    this.el = document.createElement("section")
    this.el.classList.add("FirstApp")
    
    let helloWorld = dash.create(HelloWorld)
    this.el.appendChild(helloWorld.el)
  }
}

The application constructor receives a special Dash of type: AppDash. It is a dash with additional API.

Look at the constructor. In the first lines, we listen to the log event. It is important to do that because an error detected in Bkb will not be printed elsewhere. Bkb just emits a log event on the root component.

After that, the component HelloWorld is created with the Bkb API: dash.create(HelloWorld). Its member el is appended to an element <section>.

The SCSS file of our application component:

// src/FirstApp/FirstApp.scss
body {
  background-color: #EEE;
}

.FirstApp {
  background-color: #FFF;
  margin: 0 auto;
  max-width: 750px;
  padding: 50px 30px;
}

Create the following file:

// src/index.ts
require("./reset.scss")
import { createApplication } from "bkb"
import FirstApp from "./FirstApp"

function startup() {
  let placeHolder = document.querySelector(".js-app")
  if (placeHolder) {
    let app = createApplication(FirstApp)
    placeHolder.appendChild(app.el)
  }
}

document.addEventListener("DOMContentLoaded", startup)

At the first line, a file reset.scss is referenced. Please create the file src/reset.scss with your own CSS reset.

The startup code finds the element .js-app in the DOM, then create the application with the Bkb API: createApplication(FirstApp). Then, the application el member is appended to the DOM.

We need a small HTML file at the root of the project:

<!-- first-app.html -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>First App</title>
  <link rel="stylesheet" href="dist/main.css">
  <script src="dist/main.js" defer></script>
</head>
<body>
  <div class="js-app"></div>
</body>
</html>

It is just a blank page with an empty <div> as a placeholder for the application.

Create the TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {
    "module": "es6",
    "target": "es2017",
    "lib": [
      "dom",
      "es2015",
      "es2016",
      "es2017"
    ],
    "moduleResolution": "node",
    "sourceMap": true,
    "strict": true,
    "noImplicitAny": false
  },
  "exclude": [
    "../node_modules"
  ]
}

Create the Webpack configuration:

// webpack.config.js
const MiniCssExtractPlugin = require("mini-css-extract-plugin")

module.exports = {
  mode: "development",
  devtool: "source-map",
  resolve: {
    extensions: [".ts", ".js"]
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        exclude: /node_modules/,
        use: {
          loader: "ts-loader"
        }
      },
      {
        test: /\.scss$/,
        use: [
          MiniCssExtractPlugin.loader,
          "css-loader",
          "sass-loader"
        ]
      }
    ]
  },
  plugins: [
    new MiniCssExtractPlugin()
  ]
}

It is ready. Build it:

./node_modules/.bin/webpack

Then, you can directly open the file first-app.html (as a local file) in your browser.