Modal-test-package NPM

React / Mobx / Typescript / Webpack / Starter Template

Part 0 - Repo preparation

Prepare empty repo for your application (example MyAwesomeApp is used here)

$ git clone git@ssh.dev.azure.com:v3/oriflame/BoilerPlates/react-mobx-typescript-starter-template MyAwesomeApp
$ cd MyAwesomeApp
$ git remote rename origin boilerplate
$ git remote add origin git@ssh.dev.azure.com:v3/oriflame/MyAwesomeApp
$ git push -u origin --all

Part I – Webpack

For building (and developing) React App, we use Webpack. Our goal is to build the app into two parts – a small loader called index.js, which will load the rest of the application.

Configuration files

webpack.config.js – this file is default webpack configuration file. It merges appropriate files based on the selected mode (production/development).
webpack/* - the rest of configuration files – common.js for all modes, and specific files for each configuration - development.js, production.js.

Development mode

In this mode, we start WebpackDevServer on port 3000. This one is set-up to overcome struggles with API Gateway and possible CORS problems. It's highly suggested not to change it.

The important directory is ./public – we load static assets from here – e.g. mockup files for APIs.

Production mode

The whole built application is placed in the ./build directory.

Used webpack plugins

Plugins are one of the most important parts of webpack, they determine the whole build process. Here is a list of used plugins with a short description:

ForkTsCheckerWebpackPlugin – runs typescript type checking in a separate thread, so we have a smaller and quicker building, especially during development.
StyleLintPlugin – Lints yours .css files. Configuration can be found in ./.stylelintrc.
HtmlWebpackPlugin – this creates index.html for your application, based on template in ./src/assets/index.html. Required for development and can be used to standalone run your application after build process.
ErrorOverlayPlugin – only used in dev mode. Nicely prints build errors in browser window.
DefinePlugin – based on mode and your .env files, this plugin create process.env variables that can be used in your app. Be very cautions when updating env files - incorrect settings can break whole environment.
MiniCssExtractPlugin – extracts all CSS files during production build to ./build/css directory.
CleanWebpackPlugin – this plugin removes contents of ./build directory before each build

Keeping low amount of plugins helps with webpack performance and maintains faster compile times.

Supported file extensions

Webpack can be configured to support various number of file extensions. For processing any file extension, you have to define so-called loaders, that will process this extension. It can be one loader, or whole chain of loaders. Often you want run different loaders in production and development modes – e.g. CSS files are usually handled separately.

*(.module).css – CSS files. They can be used as modules, or as a global files (for example, when you want to include fonts). In production, we use cssnano to minimize them. In both modes they are processed by PostCSS (postcss.config.js configuration file) and Autoprefixer (see browserslist variable in package.json).
*.eoff, *.ttf and other fonts files – will be copied to ./build/static/fonts directory. No other processing.
*.png, *.svg and other images – if smaller than 8k, they will be inline included in files that required them. The bigger ones will be copied into ./build/static/images directory.
*.ts(x) files – Typescript files. We use locally installed typescript (see package.json for it's current version). Main configuration files are tsconfig.json for compiler configuration and tslint.json for linter. You can configure your editor to use this configuration for it's linting. Otherwise you can run linter with npm run tslint command.

Commiting files

On every commit you make, tslint and stylelint are run to check all project files. Using these linting tools in your IDE will help development and spead-up work when commiting.

Part II – application

In this repo, there is also included small example application. As you can see, we use app_loader.ts file, that loads the application itself.

This file will be generated as an index.js, and the rest of files will have names with content hash in them.

You can also load dynamically other parts of application, to split app to smaller files. This can be done for example in Routes.tsx file.

CSS modules

It is recommended to use CSS modules with BEM naming for your React components. Example implementation is in Header.tsx component.

MobX stores

Your application may use MobX stores to store its application data. We included sample LocalizationStore for you.

Part III – Online integration

Once you have your application build, place the files to some static file hosting - in Oriflame, we usually use AzureWebsite or Azure Blobb storage. Then include index.js in your CsHtml view - see example bellow.

Warning! Be sure to set no caching for index.js file. On the contrary, the rest of the files should have set some strong caching.

Example of integration in .cshtml:

<div id="social-media-library-root" data-api-url="@Model.ApiUrl" data-app-url="@Model.AppUrl" data-tenant="@Model.Tenant"></div>

The identification of div (in this example it is id, but you can use eg. class) must be unique for your application and must be the same ase used in AppRender.tsx. This div can be also used as a "proxy" to pass variables to your application - see data-tenant attribute for example.

@Html.Optimization().Requires("JsTokenService")

Here you can include Online libraries you need for your application, like TokenService.

@Scripts.RenderFormat(@"<script src=""{0}"" defer></script>", Model.AppEntryScriptUrl)

And finally, include your application's index.js URL. Be sure to use "defer" attribute, so your script is run 1) asynchronously, and 2) after all scripts from Online.

Part IV – Configuration manager

TODO

Part V – Recommended editor settings

The recommended editor is VS Code and here is list of required and "nice to have" plugins:

EditorConfig for VS Code – required. Thanks to this plugin we all will share the same settings as tabs, line endings and so on.
TSLint – recommended for linting your files. To have the same results as project's linting, you need to switch from VS Code Typescript to our workspace version – just open any .ts/x file, and click on TS version in bottom bar (right side). This shows popup where you can select which version you would like to use.
Visual Studio IntelliCode – this is quite handy intellicode for code completion.
Typescript React code snippets – collection of snippets, that can speed up your coding. See plugin page for all shortcuts.
TypeScript Importer – This plugin tries to import needed libraries as you write your code. Handy.
Trailing Spaces – highlights empty spaces. Also, can be configured to trim them on the save, which is cool. Just open Settings page in VS Code and search for "trim" to enable this option.
Git History – nice tool to show history of your files
Bracket Pair Colorizer 2 – Each level of indentation has it's own color of brackets.
TsAutoReturnType – can add return type of function(s). Nice when dealing with complex return types.