export { DocsLayout as Root } from  '@bestatic/layout'

# About the BeRun Platform

![BeRun](/berun.svg "BeRun")

The BeRun Platform is a blazing fast, modern, open source, approach to bundling and documenting.  
It lets you build React, Node.js and static HTML applications with shared development presets based
on best practices, batteries included but 100% configurable.

This provides consistency across projects, allows a zero-configuration, `create-react-app`
style start, while at the same times allows one to tweak small parts or big chunks
of the development and production build configuration.  

## Automated presets

Plugins in BeRun are called `presets` or `runners`.   There are `presets` included for React projects and static websites,
and `runners` included for Webpack, Fuse-Box, Babel, Jest, ESLint, Prettier and many other front-end tools.
There are runners in development planned for Parcel and other contemporary tools.

## Fluent-based interface

There are some great packaging tools out there, but the challenge we've found with many of them like `create-react-app` is that once you 
want to change something you have to `eject` the entire configuration.   Or you have to rewire 
the configuration with tools like `create-react-app-rewired`, but the rewiring of plugin requires
very specific hard-coded knowledge of the original configuration, and is not very scalable.

In contrast, BeRun uses a [`fluent interface`](https://en.wikipedia.org/wiki/Fluent_interface).   

``` js
  berun
    .use(babel)
    .use(webpack)
    .use(jestRunner)
    .use(polyfills)
    .when(ISPRODUCTION, b => b.use(webpack.terser))
    .use(webpack.ruleParser)
    .use(webpack.ruleMjs)
    :
```

As you can see it works by declarative composition, and reconfiguring an 
existing preset often means just a one or two line configuration in the included configuration file.
The base preset for `React` produces output equivalent to `create-react-app` (regularly updated) but 
allows fine-grained reconfiguration using named plugins, for example:

``` js
 berun.fusebox.plugin('Babel').tap(() => ({
        extensions: ['.js', '.jsx', '.mjs', '.ts', '.tsx']
      }))
```

## Bundler- and tool- independent

Our webpack fluent interface is based on the `webpack-chain` project by Mozilla.  
Maintaining a fluent interface to webpack is no
small feat, so we just include `webpack-chain` as a straight unmodified dependency and contribute the 
occasional pull request to the upstream project where we notice something is missing.   They
are on V5+ and its a pretty robust, light-weight and well-written architecture we think;  we based
our entire fluent architecture on the exact same concepts. 

However, rather than basing all builds on webpack, we view that as just one choice of packaging tool.
We've demonstrated independence for all runners by also including Fuse-Box from the beginning, and we'll be adding
additional bundlers like Rollup or Parcel as similar first class citizens.   
Most importantly, Jest, mdx-js, Prettier, in fact all such tools in BeRun are equal
first class citizens and all get their fluent interface in BeRun.   So once you've got the hang of configuring 
one tool, the others can be adjusted similarly.   This cuts down on masses of configuration files in 
your project directories, as nearly everything is configured in a single `berun.config.js` file.

## Platform for other tools

Having a standardized, fluent approach to configuration, and a unified task manager that includes
any bundler you want, makes it simple to build dedicated workflows on top of BeRun.   One such 
exmaple is BeStatic, a blazing-fast modern approach to static sites and JAMStack applications.    

### BeStatic 

![BeStatic](/bestatic.svg "BeStatic")

BeStatic is enabled by a couple of lightweight runners built for BeRun that turn it into a well-featured documentation
and static site generator.   It's like `Gatsby`, `Docususaurus` or `React-Static`, even a very light weight `Next.js`,
 but instead of being tied to a specific bundler and requiring separate installation of often conflicting versions
 it uses whatever bundler you might be using for your (other) applications and just integrates into a light
 weight flow with all the Hot Reloading and production builds that you are used to, with zero javsascript
 or dependencies in the generated output by default.

 And of course, if you need more capabilities of these other tools, you can just trade up to them when you are
 ready as there is almost no configuration of BeStatic that is wasted, just the raw documents and MD / MDX files.

### Sparky task manager included

![BeRun Sparky](/berun.svg "BeRun Sparky")*SPARKY INSIDE*

Since we are packaging tool agnostic, we also wanted to include a light-weight task manager to allow declarative
pipelines that can call any such tools.     We've lifted the light-weight but well-proven `Sparky` task manager 
from Fuse-Box and incorproated directly in BeRun (in its own dependency of course `@berun/sparky`)

### BeStyled and more

![BeStyled](/bestyled.svg "BeStyled")

BeRun was conceived to make React and React Native applications written with BeStyled easier to develop and 
consistent in building regardless of target platform (web, iOS, Android, etc).   Therefore it's no surprise that
BeRun will have runners that make deveoping such applications easier.   Think of it like `create-react-app` but where
the `react` can be anything (`react`, `react-native`, `react-with-styled-components` etc.) and the `app` can be `app`, 
`library`, `micro-service`, `serverless service` etc.

## Prior art

* [create-react-app](https://github.com/facebook/create-react-app) -- Widely used tool developed by Facebook to develop React apps with zero build configuration.   BeRun
uses the optimizations of Facebook's webpack, babel and jest configuration, but re-imagines it in a fluent, tweakable interface.

* [create-react-app-rewired](https://github.com/timarney/react-app-rewired) -- Patch tool for create-react-app that allows the configuration to be rewired;   we share this goal
but achieve it by creating the configuration in a composable way from the outset

* [webpack-chain](https://www.npmjs.com/package/webpack-chain) -- A chaining API to generate and simplify the modification of Webpack configurations.

* [neutrino](https://neutrinojs.org/) -- A light wrapper over webpack-chain and a rich ecosystem of configuration for the other build tools;  we took
much inspiration from here, but made all build tools first class citizens (not just Webpack) and we based our default
standards on Facebook `create-react-app` given the amount of time and effort they continue to invest in the webpack, jest and 
babel optimizations for that tool

* [x0](https://github.com/c8r/x0) -- A quick, no frills prototyping and development tool,  based on the principle of smart defaults. x0 is a batteries-included development tool with the most 
common settings enabled.

* [next.js](https://github.com/zeit/next.js/) -- Server-rendered by default, React framework based on Webpack

## License

MPL 2.0 for sub-projects forked/inspired by Mozilla's webpack-chain and this documentation;  Apache 2.0 for everything else.  