BroilerKit

BroilerKit is a framework for quickly developing web apps with modern technologies and deploying them to a scalable, production-ready environment! You can write both frontend and backend in TypeScript (powered by Webpack). You write your front-end with React framework, and server-side rendering (SSR) is supported by default!

You deploy your production-ready web app to Amazon Web Services cloud platform, with minimal setup and very low costs! The hosting is almost free (but not free) on low-traffic sites.

(Disclaimer: By using this utility you are taking the full responsibility for any incurring expenses.)

Feature highlights

• Write all your code, both front-end and backend, in TypeScript
• Easily create a full-featured REST API as your backend and database models
• Your React-based front-end is rendered on server-side by default
• Easily add the user log in to your app with Facebook and Google authentication
• No server maintenance: everything will run on AWS platform serverless solutions

Other features

• Lint your code style with ESLint
• Polyfill Promise, Symbol and other ES6 features for browsers that do not support them
• Automatically bundle any images from your HTML, Pug, or Markdown files.
• Automatically optimize images losslessly for minimal size
• Generate favicons and related asset files from a single icon image file, and insert references to the HTML pages
• Refer to your current GIT version with __COMMIT_HASH__, __VERSION__ and __BRANCH__ constants

Deployment features

• Host your backend on serverless AWS Lambda functions through AWS API Gateway
• Deploy your compressed, production-ready React front-end to AWS platform, hosted on S3, served globally through CloudFront, and managed with CloudFormation
• Server-side rendering of the React front-end
• Make your app available on your custom domain (required)
• Your app is served using HTTPS! Creation of required certificates are done automatically with Amazon Certificate Manager
• Host static assets on separate cookieless domain with infinite caching, for maximum performance scoring and reliability
• Separate stages for your releases, e.g. the production version (prod) and the development version (dev)

What do I need?

To use this utility, you need the following:

• Your own domain for your web app. You can buy one, e.g, from GoDaddy.
• An Amazon Web Services account. You can get started with AWS Free Tier.

Command line tools

The BroilerKit contains a lot of command line utilities to initialize, deploy, manage and inspect your app! You can run these commands with npx. You can print out the help for the available commands:

$ npx broilerkit --help
broilerkit <command>

Commands:
  broilerkit init [directory]      Bootstrap your app with Broilerplate template.    [aliases: pull]
  broilerkit deploy <stage>        Deploy the web app for the given stage.
  broilerkit undeploy <stage>      Deletes the previously deployed web app.
  broilerkit logs <stage> [since]  Print app logs.
  broilerkit compile <stage>       Compile the web app.                             [aliases: build]
  broilerkit preview <stage>       Preview the changes that would be deployed.
  broilerkit describe <stage>      Describes the deployed resources.
  broilerkit serve [stage]         Run the local development server.
  broilerkit db <command>          Manage database tables

Options:
  --appConfigPath  Path to the app configuration                        [string] [default: "app.ts"]
  --debug          Compile assets for debugging                                            [boolean]
  --no-color       Print output without colors                                             [boolean]
  --help           Show help                                                               [boolean]
  --version        Show version number                                                     [boolean]

Creating a web app

To start developing a new web app, first create a GIT repository for it:

git init myapp
cd myapp

Then it is recommended that you apply the Broilerplate template to your project:

npx broilerkit init

If installing fails on OSX you may try to install libpng with Homebrew.

Configuring the app

Remember to add your project metadata to the package.json, for example, name, author, description.

You should change the configuration in app.ts according to your web app's needs.

• name: A distinct name of your app. Recommended to be in lower case and separate words with dashes, because the name will be used in Amazon resource names and internal host names.
• stages: Configuration for each different stage that your app has. By default there are dev stage for a development version and prod stage for the production version. You should change the serverRoot and assetsRoot to the domain names that you would like to use for each stage. There is also a special stage local that is used for the locally run development server.

Running locally

To run the app locally, start the local HTTP server and the build watch process:

npx broilerkit serve

Then navigate your browser to the website address as defined in your local stage configuration, which is http://localhost:1111/ by default!

The web page is automatically reloaded when the app is re-built.

Deployment

Prerequisities

Set up AWS credentials

First, create a user and an access key from AWS Identity and Access Management Console.

Then you need to set up your AWS credentials to your development machine. This can be done with aws-cli command line tool, which you may need to install first:

# Install if not already installed
pip install awscli
# Optional: enable command line completion
complete -C aws_completer aws
# Configure your credentials
aws configure

Running deployment

Deployments are run with the following command:

npx broilerkit deploy <stage>

For example, to deploy the development version to the dev stage:

npx broilerkit deploy dev

To deploy the production version to the prod stage:

npx broilerkit deploy prod

The deployment will build your app files, and then upload them to Amazon S3 buckets. It will also use CloudFormation to set up all the required backend, Lambda functions, databases, SSL certificates, etc.

The assets (JavaScript, CSS, images) are uploaded with their names containing hashes, so they won't conflict with existing files. They will be cached infinitely with HTTP headers for maximum performance. The uploaded HTML files are cached for a shorter time.