create-mashup-app/README.md

# Create Mashup App

Application bootstrapper and build abstraction for rapid prototyping of Targetprocess UI mashups & integration mashups.

Main philosophy is _'run 1 command and start hacking'_.

While your build is performed by `create-mashup-app`, you are guaranteed to have a stable and tried build and dev server configuration that just works (hopefully) out of the box and covers most of the cases.

In other words, you:

- don't have to be familiar with [`tau.mashups`](https://dev.targetprocess.com/docs/create-first-mashup) API
- don't need to write long and tiresome typescript, babel, PostCSS and other configurations
- don't need to bang your head against the wall thinking about how to exclude modules provided by mashup API from your resulting bundle.

Moreover, you can build your front-end code and serve it statically from a separate server instance running in the cluster, and manage mashup deployments by yourself.

### What's included

- [`babel 7`](https://github.com/rollup/rollup-plugin-babel) with latest `env` and `react` presets for using latest ES stuff and JSX, respectively. Just create a `.babelrc` in your root if you want to customize it.
- [TypeScript](https://www.typescriptlang.org/) via [`@babel/preset-typescript`](https://babeljs.io/docs/en/babel-preset-typescript) that works out of the box. You can also specify your own `tsconfig.json`.
- [`postcss`](https://github.com/egoist/rollup-plugin-postcss) for your CSS-related stuff, with a sprinkle of useful plugins for importing, nesting, variables, mixins and basically everything else you might want to expect from modern CSS. It also has [css modules](https://github.com/css-modules/css-modules) enabled, and appends name and version from your `package.json` to each CSS class you import so that you avoid polluting global CSS scope. It also has `inject` option set to `true`, so any styles you import magically appear as style tags on the page. Having your own `postcss.config.js` (or `.postcssrc` or any other supported config format) in root allows you to specify your own configuration.
- Entry point wrapper for your code that calls `tau.mashups` API for you behind the scenes, adds all dependencies you list, and replaces `import`s of modules with appropriate TP mashup dependencies you mark with `provideModule`.
- Tree-shaking that works out of the box and fast build times brought to you by [rollup](https://rollupjs.org).
- (beta) Code splitting support and minimal external chunks loader for your mashup. You can use dynamic `import()` syntax anywhere in your code - just make sure to provide correct `baseUrl` that points to a location where your chunks are avaliable.

### Installation

Install globally (to generate new application):

```bash
> npm install -g create-mashup-app
```

Install as dependency (to handle build and dev server):

```bash
> cd <your-project-folder>
> npm install --save-dev create-mashup-app
```

### Usage

#### Create new app from scratch:

```bash
> create-mashup-app generate [folder]
```

This command generates a barebones mashup, with all build configuration abstracted away behind `create-mashup-app` dependency.

3 templates are supported as of the moment:

- **minimal**

`package.json`, [`mashup.json`](#mashupjson) and nothing else but your code in `src/index.js`. Bare minumum for when you need to start fresh, or when you're implimenting something relatively simple.

- **react**

Generates a bit more complex mashup with dummy react component that gets inserted into `document` when mashup is loaded. Includes a configured test environment and 1 dummy test, basic rules for linting and useful commands for executing them in `package.json`.

- **typescript**

Same as minimal, but with support for typescript enabled via [custom webpack config transform](#custom-webpack-config), appropriate `tsconfig.json` and `index.ts` as entry point.

#### Build existing app:

```bash
> create-mashup-app build [folder] [--no-minify] [--no-dependency-replace] [--target=mashup] [--baseUrl=<url>]
```

This assumes that `[folder]` or current directory has correct mashup config.

Build output is written to `dist` folder in `[folder]`.

Build by default assumes that created mashup is used as an integration, i.e. has an integration on TP side that registers js file produced in build as `registerExternalModule`.

If you want to build a mashup to be included directly into TP straight away, you can use `--target=mashup` with `create-mashup-app build`, or specify `"target": "mashup"` in your `mashup.json`.

If your mashup uses dynamic imports and code splitting, be sure to provide correct `--base-url` of your chunks.

#### Run development server on existing app:

```bash
> create-mashup-app devServer [folder] [--port <port>] [--no-minify] [--no-dependency-replace]
```

This assumes that `[folder]` or current directory has correct mashup config.

Dev server serves your `dist` directory statically. As such, any previous build assets may be overwritten.

#### Mashup configuration

Your app should provide mashup configuration in any of the ways supported by [`cosmiconfig`](https://github.com/davidtheclark/cosmiconfig), i.e. via:

- `mashup` property in your `package.json`
- `.mashuprc`/`.mashuprc.json`/`.mashuprc.yaml`/`mashuprc.yml` file
- `.mashuprc.js` or `mashup.config.js` file that exports an object

`mashup.config.js` is the root configuration file for your mashup while it's controlled by `create-mashup-app`. It is generated automatically when you create a new app, and consumed every time you build or run dev server with `create-mashup-app` on an existing app.

A typical mashup config will look like this:

```json
{
    "name": "My Awesome Mashup",
    "moduleName": "tp3/integrations/my-awesome-mashup",
    "entry": "src/index.js",
    "dependencies": [
        {"mashupDependency": "react", "provideModule": "react"},
        {"mashupDependency": "tp3/api/settings/v1"},
        {"mashupDependency": "Underscore", "provideModule": "underscore"},
        ...
    ]
}
```

Below is the breakdown for each of the fields:

- `name` - This is the visible user-friendly name for your mashup. It will only be used as mashup name in Mashup Manager, so feel free to choose whatever you seem fit.

- `moduleName` - This is module identifier for your mashup. While there are no theoretical boundaries on what you can use as module name, you should try to provide a technically succint namespaced value here.

- `entry` - This field points to the entry point of your mashup. Typically, mashups are created by calling `tau.mashups.addDependency(...).addMashup('awesome-mashup', function(dependency) {...})`. `create-mashup-app`, however, abstracts that API away, by using dependencies from your mashup.json, simplifying their usage and adding support for bundle module replacement. The file specified in `entry` **must** contain a **named export function `initialize`**:

```js
export function initialize() {
  console.log('I am a mashup!');
}
```

or

```js
module.exports = {
  initialize() {
    console.log('I am a mashup that is afraid of using ES2015 import/export!');
  }
};
```

This function is called when your mashup and all of its dependencies are loaded.

- `dependencies` - An array of your mashup dependencies. The list of all avaliable dependencies can be found in targetprocess [`publicModules.registry.js`](https://github.com/TargetProcess/TP/blob/develop/Code/Main/Tp.Web/JavaScript/tau/scripts/tp/publicModules.registry.js) You can specify each dependency as a string or as an object with `mashupDependency` key:

```js
...
"dependencies": [
    "react",
    {"mashupDependency": "tp3/api/settings/v1"}
]
...
```

All mashup dependencies are available for importing as if they were regular modules. If you have a module with the same name you are importing from node_modules, it will be replaced:

```js
import TpSettings from 'tp3/api/settings/v1';
import React from 'react';
...
```

You can additionally specify `provideModule` key for your dependency object to create a different alias for that particular mashp module:

```js
...
"dependencies": [
    {"mashupDependency": "Underscore", "provideModule": "underscore"},
    {"mashupDependency": "react", "provideModule": "tp-react"},
    {"mashupDependency": "tp3/api/settings/v1", "provideModule": "@targetprocess/api/settings"}
]
...
import _ from 'underscore'; // TP module 'Underscore' is used
import React from 'react';  // react from your own node_modules is used
import TpReact from 'tp-react'; // TP module 'react' is used
import SettingsApi from '@targetprocess/api/settings';  // TP module 'tp3/api/settings/v1' is used
```

When your code is bundled normally, all node_modules imports are included with your bundle. For example, with the above code you get **entire** `react` codebase in your bundle.

Some library dependencies, including `react` and `react-dom`, are already provided by TP mashup API, so carrying your own copy of React or jQuery with your mashup is very inefficient.

#### Tree-shaking

As of 2.0, `create-mashup-app` uses rollup for bundle generation, which statically analyzes your code for imports and exports. Refer to `https://rollupjs.org/guide/en#tree-shaking` for more details.

If your bundle size is still too large, you can try to use `pureExternalModules` and `propertyReadSideEffects` rollup config options (more on them [here](https://rollupjs.org/guide/en#danger-zone)) to perform more aggressive tree-shaking.

#### Code splitting

Code splitting occurs whenever you use dynamic import statement in your code. Each dynamic import spawns a separate chunk that will be loaded on runtime when requested.
`create-mashup-app` bundles a tiny dependency loader with your code that can load dynamic imports. It also requires that you build your app with `--basePath` argument and specify a correct URL where your dynamically-loaded chunks are available.

Code splitting will also produce commons chunks, i.e. chunks with code that is imported by several of dynamically-loaded modules. Since there is no way to verify if commons chunk is used by your entry point chunk as of 2.0, all commons chunks are inlined with your entry point bundle, and reused lated by all dynamically loaded chunks.

**(hopefully temporary) Code splitting assumes that webpage has a correct implementation of A+ Promises available from `window.Promise`. If you cannot make sure Promise is polyfilled, avoid using dynamic imports in your code.**

#### ~~Providing public API~~ (temporarily broken as of 2.0 release)

A mashup created by `create-mashup-app` can register public modules which can be used by other mashups. In order to provide one or more public modules, you need to perform a few things:

1. Create a module which will be exposed publicly e.g. `src/api/mashup-public-api.js` with the following content:

```js
export default {
  sayHello() {
    console.log('hello from mashup public API');
  }
};
```

2. Create a javascript file which provides all public API modules exposed by the mashup, e.g. a file `src/api/index.js` with the following content:

```js
export default {
  'tau/api/hello/v1': () => require('./mashup-public-api').default
  // any other public modules can go here
};
```

Keys of the exported objects are the names of the modules which can be used by other mashups.

**Please note that this file should not have any dependencies in a form of `require` or `import` statements (the file is loaded and evaluated before dependencies specified in `mashup.json` are initialized)**

3. Add `publicApi` property in the `mashup.json` file:

```json
{
    ...
    "publicApi": "src/api/index.js"
    ...
}
```

Now you can use this module in another mashup:

```js
tau.mashups.addDependency('tau/api/hello/v1').addMashup(function(api) {
  api.sayHello();
});
```

#### Customizing

`create-mashup-app` is quite narrow in the way of customizing your build process. **This is intentional**. The basic idea is that you get a default configuration that just works, along with some best practices on how to handle your mashup integration.

##### Custom `.babelrc`

You can place `.babelrc` file in your root folder and provide your own [babel configuration](https://babeljs.io/docs/usage/babelrc/). Note that doing so will override default presets, so you'll have to include `env`, `react` and other transforms you consider useful for your app.

`create-mashup-app` uses babel 7. Make sure you use correct plugin versions, e.g. `@babel/plugin-proposal-object-rest-spread` and not `babel-plugin-transform-object-rest-spread`.

##### Custom PostCSS config

Much like `.babelrc`, you can provide your own custom [postcss config](https://github.com/michael-ciniawsky/postcss-load-config) in any manner you seem fit. Preferred way is through `postcss.js.config`.

##### Custom rollup config

_Customizing rollup config generally goes a bit against the main philosophy of `create-mashup-app`. It's fine for smaller tweaks, like adding new plugins, but if you need to drastically customize build process, consider using [`eject`](#eject) instead._

You can specify `configTransform` property in mashup config that points to JS file:

```json
{
    ...
    "configTransform": "./webpack.config.transform.js",
}
```

or you can provide it as a function in `mashup.config.js`/`.mashuprc.js`:

```js
module.exports = {
    name: '...',
    ...
    configTransform: function(config) {
        ...
    }
}
```

Config transform will be invoked with basic rollup config object as parameter and is expected to return a new, transformed rollup config.

For example, if youo want to add `rollup-plugin-string`, you can do it with the following transform:

```js
const string = require('rollup-plugin-string');

module.exports = function(config) {
  return {
    ...config,
    plugins: [
      ...config.plugins,
      string({
        include: '**/*.html'
      })
    ]
  };
};
```

##### Eject

**Eject is currently not supported, but will be added in future versions.**

`create-mashup-app eject` will remove `create-mashup-app` from your package dependencies, transfer all required transitive dependencies to your own `package.json` and will generate all configuration files required to run build and dev server without it, much like eject in `create-react-app`.

This is irreversible.