Created JavaScript in EGroupware apps (markdown)

JavaScript-in-EGroupware-apps.md

@@ -0,0 +1,34 @@
+## JavaScript / TypeScript in EGroupware
+> Our framework automatic loads for the current app automatic the JavaScript file $app/js/app.(min.)js.
+
+### Native ES6 module import and [RollupJS](https://rollupjs.org/guide/en/)
+EGroupware master / next release after 21.1 moves from our privious LAB.js based loading and a require method for our TypeScript, to using native ES6 module import and [RollupJS](https://rollupjs.org/guide/en/).
+
+Our developer-install update script ```./install-cli.php``` runs the following commands now after ```git pull``` for all repos:
+- ```compose install``` already the case since some time
+- ```npm install``` ---- " ----
+- ```grunt``` ---- " ----
+- ```npm run build``` running new ```rollup -c```
+
+> Use ```npm run build:watch``` or click on the green run icon in package.json opened in PHPStorm to automatic build changed files for developing.
+
+#### Please note the following about ES6 modules:
+* the always **use strict** mode
+* **this** is undefined, use window instead eg. for wrapping
+
+### Migrating your TypeScript app.ts
+
+* fix import statements in TypeScript (they are not only to make tsc happy, but make sure dependencies get loaded and in scope)
+* no longer commit the generated .js script, as it only gives a lot of conflicts AND needs to be regenerated by rollup for every change in the whole EGroupware (not just your app!)
+* use the commits from our default apps as an example what's required
+* switch off automatic TS compiling in PHPStorm, it has to happen using RollupJS (```npm run build:watch```)
+
+### Migrating your old JavaScript app.js
+
+* preferable migrate your app.js to TypeScript using our [migration script](https://github.com/EGroupware/egroupware/blob/master/doc/js2ts.php)
+* if you don't want to migrate to TS right now, change the ```*egw:uses``` annotations to import statements [like in the following commit for mail app.js](https://github.com/EGroupware/egroupware/commit/771d6c727f6fa456c7c05223c0558a5fbf474b99#diff-6cd838ed2d76c319cb6c8c26db22a936598b3f4bf0daf486b02340789beb2108)
+* make sure your app.js is "use strict" compatible, as this is the default for JavaScript modules
+
+### Using the same app with 21.1 and master
+
+If your app does not use a 21.1 branch and need to run in master and 21.1 AND already uses TypeScript, you need to keep the in 21.1 generated app.js and regenerate it in 21.1 when you change something in app.ts. RollupJS in master will rebuild it anyway, you only have to deal with the conflicts, if developing with multiple developers ;)