@ -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:
* **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).
Halil ibrahim Kalkan
8 years ago