@@ -6,14 +6,16 @@ libs
 node_modules
 package
 platforms
-!tns-core-modules/platforms
+!nativescript-core/platforms
 reports
 tags
+temp
 
 # Files
 package-lock.json
 .DS_Store
 .nsbuildinfo
+tsdoc-metadata.json
 
 # IDEs and editors
 /.idea
@@ -23,6 +25,7 @@ package-lock.json
 *.launch
 .settings/
 .atom
+.ctags-exclude
 
 # IDE - VSCode
 .vscode/*
@@ -51,23 +54,20 @@ tscommand*.tmp.txt
 
 # Other
 *.js
+!tns-core-modules-package/**/*.js
 # https://github.com/NativeScript/nativescript-dev-webpack/issues/932
-!tns-core-modules/xml/xml.js
+!nativescript-core/xml/xml.js
 !tests/hooks/**/*.*
-!js-libs/**/*.*
-!css/**/*.*
-!css-value/**/*.*
-!fetch/**/*.*
-!apps/TelerikNEXT/lib/**/*.*
-!build/**/*.*
-.vs/
-
-.baseDir.ts
-.ctags-exclude
+!nativescript-core/js-libs/**/*.*
+!nativescript-core/cli-hooks/**/*.*
+!nativescript-core/css/**/*.*
+nativescript-core/css/parser.js*
+nativescript-core/css/system-classes.js*
+!nativescript-core/css-value/**/*.*
+!nativescript-core/fetch/**/*.*
+!nativescript-core/build/**/*.*
 
-TestRunResult.txt
-.testsapprun
+#generated by api-extractor
+nativescript-core/nativescript-core.d.ts 
 
-tns-core-modules.base.d.ts
-tns-core-modules.d.ts
-tns-core-modules.es6.d.ts
+.vs/
@@ -2,12 +2,13 @@ language: node_js
 node_js:
   - "node"
 script:
+- npm install
+- npm run tslint
+- npm run setup
+- npm run unit-test
+
 # circular references check
 - cd tests && npm i
 - node_modules/.bin/webpack --env.android
 - node_modules/.bin/webpack --env.ios
-# modules transpilation
-- cd ../tns-core-modules && npm i && cd ..
-- npm install
-- npm run tsc
-- npm run tslint
+
@@ -4,89 +4,115 @@ Development Workflow
 ## Project Structure
 
 The repository contains several packages and apps:
- - `tns-core-modules` - The core NativeScript TypeScript modules used to develop NativeScript apps
- - `tns-core-modules-widgets` - The native widgets (Java and Objective-C) used by the core NativeScript modules
- - `e2e/ui-tests-app` - UI app used for manual testing and automation
+ - `nativescript-core` - The core NativeScript TypeScript modules used to develop NativeScript apps. Produces `@nativescript/core` npm package
+ - `tns-core-modules-package` - Base for generating the `tns-core-modules` package (compatibility package for projects that still import code from `tns-core-modules`).
+ - `tns-core-modules-widgets` - The native widgets (Java and Objective-C) used by the core NativeScript modules. Produces `tns-core-modules-widgets` npm package
+ - `tns-platform-declarations` - TypeScript definitions for Android and iOS native APIs. Produces `tns-platform-declarations` npm package
+ - `tests` - Unit tests app for the `@nativescript/core` package. These test are executed as nativescript application on mobile device or emulator.
+ - `unit-test` - Node unit tests. These test validate parts of the framework that do not require the nativescript runtime and so can be executed in node environment 
  - `e2e` - applications and *e2e* tests
- - `tests` - Unit tests app for the `tns-core-modules`
- - `tns-platform-declarations` - TypeScript definitions for Android and iOS native APIs
+ - `e2e/ui-tests-app` - UI app used for manual testing and automation
+ - `apps` - legacy apps for testing
+ - `build` - scripts used for building and infrastructure
+ - `dist` - construction site for packing npm modules 
 
 Working with the repo is organized with npm scripts,
 go and read through the `scripts` section in the [package.json](./package.json).
 
 Managing dependencies:
+ - `tns-core-modules-widgets` depends on:
+    - no deps
+ - `@nativescript/core` depends on:
+    - `tns-core-modules-widgets`
+    - (devDep)`tns-platform-declarations`
  - `tns-core-modules` depends on:
-    - `tns-platform-declarations`
- - `e2e/ui-tests-app` depends on:
-    - `tns-platform-declarations`
-    - `tns-core-modules`
- - `e2e` depends on:
-    - `tns-core-modules`
- - `tests` depends on:
-    - `tns-platform-declarations`
-    - `tns-core-modules`
-
-> NOTE: `tns-core-modules` depends on `tns-core-modules-widgets`,
+    - `@nativescript/core`
+    - (devDep)`tns-platform-declarations`
 
 ## Initial Setup
 
-Clone (or fork/clone) the repo:
+Clone (or fork/clone) the repo and run setup script:
 
 ``` bash
 git clone https://github.com/NativeScript/NativeScript.git
+cd NativeScript 
+npm run setup
 ```
 
-Install dependencies:
-
-``` bash
-npm install
-```
-
-## Running Unit Tests
+## Running Unit Tests Application
+After the [initial setup](#initial-setup) you can run the tests with:
 
 ``` bash
 cd tests
 tns run android | ios
 ```
+You can do changes in the test app and `nativescript-core` and rely on HMR to re-run tests.
 
-## Running the UI Test App
+## Running the `e2e` Test Apps
 
-The UI test app is an ordinary NativeScript app that logs the test results on the go.
-After the [initial setup](#initial-setup) you can run the tests with:
+There are couple of application used for development and testing.
+The `ui-test-app` is the more frequently used for development and validation. It is an ordinary NativeScript app that logs the test results on the go.
+
+After the [initial setup](#initial-setup) run the e2e apps with:
 
 ``` bash
-cd e2e/ui-tests-app
+cd e2e/<app-name>
 
 # Run the Android app
-tns platform add android@next # NOTE: do not commit this change to package.json
+tns platform add android@next
 tns run android
 
 # Run the iOS app
-tns platform add ios@next # NOTE: do not commit this change to package.json
+tns platform add ios@next
 tns run ios
-
 ```
 
+>Note: NOTE: do not commit changes in the runtime versions to `e2e/<app-name>/package.json`
+
+---
+
 ## Running Another App
 
-1. Open the app, where you will use the module from the repository in the console.
-2. Add the `tns-core-modules` in the application via:
-```bash
-npm install --save <path to tns-core-modules>
-# Example: npm install --save ../NativeScript/tns-core-modules
+### TypeScript Applications
+Link both the `nativescript-core` folders and the generated compatibility package (`dist\tns-core-modules`):
+``` bash
+npm i <path-to-nativescript-repo>/nativescript-core --save
+npm i <path-to-nativescript-repo>/dist/tns-core-modules --save
 ```
-3. Run the app
-```bash
-tns run ios
-tns run android
+
+You can do changes in the app code and `nativescript-core` and rely on HMR to refresh the app.
+
+### JavaScript Applications
+Use the same steps as with TS application. However, the configuration of JS application does not include loading and transpiling TS code. You need to transpile the TS code in `nativescript-core` yourself. The following npm script will run tsc in watch mode in `nativescript-core` (run it in a separate terminal so that you can do `tns run` in parallel):
+
+``` bash
+npm run tsc-core-watch 
 ```
 
----
-**NOTE**
+### Angular Applications
+Linking `tns-core-modules` and `@nativescript/core` in **Angular applications** does not work at the moment. Check [#7905](https://github.com/NativeScript/NativeScript/issues/7905) for more details on the issue.
 
-Linking `tns-core-modules` in Angular app does not work at the moment. Check [#7905](https://github.com/NativeScript/NativeScript/issues/7905) for more details on the issue.
 
----
+## Building `tns-core-modules-widgets`
+You can the following npm script to build and link the `tns-core-modules-widgets` package.
+``` bash
+npm run setup-widgets
+```
+
+This script will build the `tns-core-modules-widgets` package and link it inside the `nativescript-core` so it will be used for running the tests and e2e apps.
+
+>Note: NOTE: do not commit changes in the `tns-core-modules-widgets` dependency in the `nativescript-core/package.json`
+
+## Running Node Unit Tests
+Run node unit tests with:
+```
+npm run unit-test
+```
+or run tests in watch mode:
+
+```
+npm run unit-test-watch
+```
 
 ## Platform declarations
 To update the platform declarations (the ios.d.ts-es) you can run: