From c7e62277a61aa2238e80c867f3b5247f0041e28d Mon Sep 17 00:00:00 2001 From: Halil ibrahim Kalkan Date: Tue, 19 Jun 2018 10:03:56 +0300 Subject: [PATCH] Client-Side-Package-Management revised. --- .../Client-Side-Package-Management.md | 26 +++++++++---------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/AspNetCore/Client-Side-Package-Management.md b/docs/AspNetCore/Client-Side-Package-Management.md index 20fb378ab1..8eba440fe4 100644 --- a/docs/AspNetCore/Client-Side-Package-Management.md +++ b/docs/AspNetCore/Client-Side-Package-Management.md @@ -4,13 +4,13 @@ ABP framework can work any type of client side package management system. Even y However, ABP framework best works with **NPM/Yarn**. It provides tools to make it easier to work with and built-in modules are configured to work with NPM/Yarn by default. -Finally, we suggest the [**Yarn**](https://yarnpkg.com/) over the NPM since it's faster, more stable and also compatible with the NPM. +Finally, we suggest the [**Yarn**](https://yarnpkg.com/) over the NPM since it's faster, stable and also compatible with the NPM. ### @ABP NPM Packages ABP is a modular platform. Every developer can create modules and the modules should work together in a **compatible** and **stable** state. -One challenge problem is **versions of the depended NPM packages**. What if two different module use the same JavaScript library but its different (and potentially incompatible) versions. +One challenge is the **versions of the depended NPM packages**. What if two different module use the same JavaScript library but its different (and potentially incompatible) versions. To solve the versioning problem, we created a **standard set of packages** those depends on some common third-party libraries. Some example packages are [@abp/jquery](https://www.npmjs.com/package/@abp/jquery), [@abp/bootstrap](https://www.npmjs.com/package/@abp/bootstrap) and [@abp/font-awesome](https://www.npmjs.com/package/@abp/font-awesome). You can see the **list of packages** from the [Github repository](https://github.com/volosoft/abp/tree/master/npm/packs). @@ -19,13 +19,13 @@ The benefit of a **standard package** is: * It depends on a **standard version** of a package. Depending on this package is **safe** because all modules depend on the same version. * It contains the gulp task to copy library resources (js, css, img... files) from the **node_modules** folder to **wwwroot/libs** folder. See the *Mapping The Library Resources* section for more. -Depending on a standard package is easy. Just add it to your **package.json** file as you normally add a package. +Depending on a standard package is easy. Just add it to your **package.json** file as you normally add a package. Example: ````json { ... "dependencies": { - "@abp/bootstrap": "^0.3.1" + "@abp/bootstrap": "^1.0.0" } } ```` @@ -34,7 +34,7 @@ It's suggested to depend on a standard package instead of directly depending on #### Package Installation -After depending on a npm package, all you should do is to run the yarn command from the command line to install the packages: +After depending on a NPM package, all you should do is to run the **yarn** command from the command line to install all the packages and their dependencies: ```` yarn @@ -44,7 +44,7 @@ You can instead use the `npm install` but the [Yarn](https://yarnpkg.com/) is su #### Package Contribution -If you need a third-party NPM package that is not in the standard set of packages, you can create a Pull Request on the Github repository. A pull requests that follows these rules are accepted: +If you need a third-party NPM package that is not in the standard set of packages, you can create a Pull Request on the Github [repository](https://github.com/volosoft/abp). A pull request that follows these rules is accepted: * Package name should be named as `@abp/package-name` for a `package-name` on NPM (example: `@abp/bootstrap` for the `bootstrap` package). * It should be the **latest stable** version of the package. @@ -58,21 +58,18 @@ See current standard packages for examples. Using NPM packages and NPM/Yarn tool is the de facto standard for client side libraries. NPM/Yarn tool creates a **node_modules** folder in the root folder of your web project. -Next challenge is to copying needed resources (js, css, img...) files from the node_modules into a folder inside the **wwwroot** folder to make it accessible to the clients/browsers. +Next challenge is copying needed resources (js, css, img... files) from the node_modules into a folder inside the **wwwroot** folder to make it accessible to the clients/browsers. -ABP defines Gulp based tasks to **copy resources** from **node_modules** to **wwwroot/libs** folder. Each **standard package** (see the *@ABP NPM Packages* section) defines the mapping for its own files. So, most of times, you only configure dependencies. +ABP defines a [Gulp](https://gulpjs.com/) based task to **copy resources** from **node_modules** to **wwwroot/libs** folder. Each **standard package** (see the *@ABP NPM Packages* section) defines the mapping for its own files. So, most of times, you only configure dependencies. The **startup templates** are already configured to work all these out of the box. This section will explain the configuration options. #### Resource Mapping Definition File -An application defines a JavaScript file named `abp.resourcemapping.js` which is formatted as in the example below: +An module should define a JavaScript file named `abp.resourcemapping.js` which is formatted as in the example below: ````js module.exports = { - imports: [ - "./node_modules/@abp/bootstrap/abp.resourcemapping.js" - ], aliases: { "@node_modules": "./node_modules", "@libs": "./wwwroot/libs" @@ -86,7 +83,6 @@ module.exports = { } ```` -* **imports** section defines the dependencies of the application. This example depends on the @abp/bootstrap standard package and it knows how to copy bootstrap resources (js, css... files) into the wwwroot/libs/bootstrap folder. * **aliases** section defines standard aliases (placeholders) those can be used in the mapping paths. **@node_modules** and **@libs** are required (by the standard packages), you can define your own aliases to reduce duplication. * **clean** section is a list of folders to clean before copying the files. * **mappings** section is a list of mappings of files/folders to copy. This example does not copy any resource itself, but depends on a standard package. @@ -108,7 +104,9 @@ Once you properly configure the `abp.resourcemapping.js` file, you can run the g gulp ```` -When you run the gulp, all related packages will copy their own resources into the **wwwroot/libs** folder. Running yarn & gulp again is only necessary if you make a change in your dependencies in the **package.json** file. +When you run the gulp, all packages will copy their own resources into the **wwwroot/libs** folder. Running yarn & gulp again is only necessary if you make a change in your dependencies in the **package.json** file. + +> When you run the Gulp command, dependencies of the application are resolved using the package.json file. The Gulp task automatically discovers and maps all resources from all dependencies (recursively). #### See Also