Preact Boilerplate

Yet another Preact Boilerplate

This time with a MobX, Bootstrap 4, Fontawesome, unit tests, integration tests, continuous integration, code analysis, code style and a nice setup flow.

Basic layout

The module is bootstrapped via src/start which checks for login if required.

Then src/main is called. This module loads all MobX stores which handles all states and application data. The main modules also takes care of routing so you are able to deeplink to all application states like a regular webpage.

This is just an example of how this boilerplate is designed and supposed to work:

                         ---------        - - - - -
                        |  Start  |- - - |  Login  |
                         ---------        - - - - -
                             |
                        -----------      --------
                       |   main    |    |  MobX  |
                       | (router)  |----| Stores |
                        -----------      --------
                             |
                             | (path routing)
             ------------------------------------
            |                |                   | 
      -------------    --------------    ----------------
     |  /index     |  | /products    |  | /products/123  |
     |  Frontpage  |  | Product list |  | Product detail |
      -------------    --------------    ----------------

Helper modules in use

MobX MobX is a battle tested library that makes state management simple and scalable by transparently applying functional reactive programming (TFRP). The philosophy behind MobX is very simple:

Anything that can be derived from the application state, should be derived. Automatically. Which includes the UI, data serialization, server communication, etc.

Bootstrap 4

Bootstrap is an open source toolkit for developing with HTML, CSS, and JS. Quickly prototype your ideas or build your entire app with our Sass variables and mixins, responsive grid system and extensive prebuilt components.

Fontawesome 5.8.1

Professionally Designed + Pixel-Perfect Each and every symbol is designed from scratch against guidelines and standards forged from years of experience of illustrating and designing icons. The result is a consistent look and feel that spans thousands of icons across three unique styles.

Jest A browser JavaScript testing toolkit. Jest is used by Facebook to test all JavaScript code including React applications. One of Jest's philosophies is to provide an integrated "zero-configuration" experience.

ESLint ESLint is a code style linter for programmatically enforcing your style guide.

Istanbul A Javascript code coverage tool written in JS.

Travis Travis CI is a hosted continuous integration service. It is integrated with GitHub and offers first class support for many languages.

Retire Scanner detecting the use of JavaScript libraries with known vulnerabilities.

Before you start

Install preact-cli from this repo: https://github.com/developit/preact-cli

$ npm install -g preact-cli

Getting started

Create your new widget repo or just create your folder.
Copy the files you need from this repo:

$ npm run install-widget -- --dir <my-new-widget-dir>

Then jump into your new widget dir:

$ cd <my-new-widget-dir>

Install dependencies

$ npm install

Run the widget in dev mode:

$ npm run start
// You can see your live widget here `http://localhost:56789/`

Now you are ready to start developing your groundbreaking new widget.

A nice thing to have running while you are developing are ESlint:

$ npm run eslint-watch

And if you are an ACE-programmer you also have unit test running live:

$ npm run test-watch

Tips & tricks

Router

As the first step in development you have to choose if you are going to us the Router or not. This depends if you are developing a widget that are going to be used alone or on a page with more widgets.

Alone or full page widget: Use the Router.

const USE_ROUTER = true;

Multiple small widgets: Do not use the Router.

const USE_ROUTER = false;

This setting is located in src/components/main/index.js

Login

The next step is to decide if you require login or not in your app.

const REQUIRE_LOGIN = false;

This setting is located in src/components/start/index.js

Inside the login component you can find an example login script.

General Preact stuff

Create a new widget

// Create preact boilerplate
$ preact create widget boilerplate
$ cd boilerplate/
$ npm install

Development

When you are running in dev mode you can see your application here: http://localhost:8080

# To start a development live-reload server:
$ npm run start

Build a release

# To create a production build (in ./build):
$ npm run build

Production server

# To start a production HTTP/2 server:
$ npm run serve

Howto upgrade modules

$ sudo npm install -g npm-check-updates
$ ncu -u -a
$ npm install --no-optional

Versioning

For transparency and insight into the release cycle, releases will be numbered with the follow format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

Breaking backwards compatibility bumps the major
New additions without breaking backwards compatibility bumps the minor
Bug fixes and misc changes bump the patch

For more information on semantic versioning, please visit http://semver.org/.

Contributions and feedback:

We ❤️ contributions and feedback.

If you want to contribute, please check out the CONTRIBUTING.md file.

If you have any question or suggestion create an issue.

Bug reports should always be done with a new issue.

5orenso/preact-boilerplate