Skip to content

Commit 318023b

Browse files
ikoevskaikoevska
committed
Reworking Plugins.md
1 parent 16e3f3c commit 318023b

File tree

1 file changed

+183
-38
lines changed

1 file changed

+183
-38
lines changed

‎PLUGINS.md

Lines changed: 183 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,153 @@
11
PLUGINS
22
=========
33

4-
NativeScript plugin is a npm package that consist of the following:
4+
Starting with NativeScript CLI 1.1.0, you can develop or use custom plugins in your NativeScript projects.
55

6-
* Metadata about the package itself: name, version, supported runtime versions, etc.
7-
* CommonJS module(one or many) that expose the native API via a single JavaScript API.
8-
* Native libraries and resources.
6+
* [What Are NativeScript Plugins](#what-are-nativescript-plugins)
7+
* [Create a Plugin](#create-a-plugin)
8+
* [Directory Structure](#directory-structure)
9+
* [Package.json Specification](#package-json-specification)
10+
* [Install a Plugin](#install-a-plugin)
11+
* [Valid Plugin Sources](#valid-plugin-sources)
12+
* [Installation Specifics](#installation-specifics)
13+
* [Manual Steps After Installation](#manual-steps-after-installation)
14+
* [Use a Plugin](#use-a-plugin)
15+
* [Remove a Plugin](#remove-a-plugin)
16+
* [Removal Specifics](#removal-specifics)
17+
* [Manual Steps After Removal](#manual-steps-after-removal)
18+
19+
## What Are NativeScript Plugins
20+
21+
A NativeScript plugin is any npm package, published or not, that exposes a native API via JavaScript and consists of the following elements.
22+
23+
* A `package.json` file which contains the following metadata: name, version, supported runtime versions, dependencies and others. For more information, see the [Package.json Specification](#package-json-specification) section.
24+
* One or more CommonJS modules that expose a native API via a single JavaScript API. For more information about Common JS modules, see the [CommonJS Wiki](http://wiki.commonjs.org/wiki/CommonJS).
25+
* `AndroidManifest.xml` and `Info.plist` which describe the permissions and features required or used by your app for Android and iOS, respectively.
26+
27+
The plugin must have the directory structure, described in the [Directory Structure](#directory-structure) section.
28+
29+
## Create a Plugin
30+
31+
If the NativeScript framework does not expose a native API that you need, you can develop a custom plugin which exposes the required functionality. When you develop a custom plugin, keep in mind the following requirements.
32+
33+
* The plugin must be a valid npm package.
34+
* The plugin must expose a built-in native API. Currently, you cannot expose native APIs available via custom native libraries.
35+
* The plugin must be written in JavaScript and must comply with the CommonJS specification.
36+
* The plugin directory structure must comply with the specification described below.
37+
* The plugin must contain a valid `package.json` which complies with the specification described below.
38+
* The plugin must contain `AndroidManifest.xml` and `Info.plist` file which describe any platform-specific settings such as required permissions.
39+
40+
### Directory Structure
41+
42+
NativeScript plugins which consist of one CommonJS module must have the following directory structure.
943

10-
A package json file has the following structure:
1144
```
12-
{
13-
"name": "myplugin",
14-
"version": "0.0.1",
15-
"nativescript": {
16-
"platforms": {
17-
"ios": "1.0.0",
18-
"android": "1.1.0"
19-
}
20-
}
21-
}
45+
MyPlugin/
46+
├── index.js
47+
├── package.json
48+
└── platforms/
49+
├── android/
50+
│ └── AndroidManifest.xml
51+
└── ios
52+
└── Info.plist
2253
```
23-
`nativescript` key is a mandatory section for a NativeScript plugin. `platforms` section describes the supported runtime versions for each platform.
2454

25-
A plugin directory has the following structure:
55+
NativeScript plugins which consist of multiple CommonJS modules must have the following directory structure.
56+
2657
```
27-
myPlugin/
28-
-- index.js
29-
-- package.json
30-
-- platforms
31-
-- Android
32-
-- myjar.jar
33-
-- Android.manifest
34-
-- iOS
35-
-- myFramework.framework
36-
-- Info.plist
58+
MyPlugin/
59+
├── MyModule1/
60+
│ ├── index1.js
61+
│ ├── package.json
62+
│ └── platforms/
63+
│ ├── android/
64+
│ │ └── AndroidManifest.xml
65+
│ └── ios
66+
│ └── Info.plist
67+
└── MyModule2/
68+
├── index2.js
69+
├── package.json
70+
└── platforms/
71+
├── android/
72+
│ └── AndroidManifest.xml
73+
└── ios
74+
└── Info.plist
3775
```
3876

39-
You can use `platforms` folder and place platform specific files in each platform directory.
77+
* `index.js`: This file is the CommonJS module which exposes the native API. You can use platform-specific `*.platform.js` files. For example: `index.ios.js` and `index.android.js`. During the plugin installation, the NativeScript CLI will copy the platform resources to their correct platform destination in the `platforms` directory of your project.
78+
* `package.json`: This file contains the metadata for your plugin. It sets the supported runtimes, the plugin name and version and any dependencies. The `package.json` specification is described in detail below.
79+
* `platforms\android\AndroidManifest.xml`: This file describes any specific configuration changes required for your plugin to work. For example: required permissions. For more information about the format of `AndroidManifest.xml`, see [App Manifest](http://developer.android.com/guide/topics/manifest/manifest-intro.html).<br/>During the plugin installation, the NativeScript CLI will merge the plugin `AndroidManifest.xml` with the `AndroidManifest.xml` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues.
80+
* `platforms\ios\Info.plist`: This file describes any specific configuration changes required for your plugin to work. For example: required permissions. For more information about the format of `Info.plist`, see [About Information Property List Files](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html).<br/>During the plugin installation, the NativeScript CLI will merge the plugin `Info.plist` with the `Info.plist` for your project. The NativeScript CLI will not resolve any contradicting or duplicate entries during the merge. After the plugin is installed, you need to manually resolve such issues.
81+
82+
Currently, you cannot add any platform-specific resources other than `AndroidManifest.xml` and `Info.plist` in the `platforms` directory of the plugin.
83+
84+
### Package.json Specification
85+
86+
Every NativeScript plugin should contain a valid `package.json` file in its root. This `package.json` file must meet the following requirements.
87+
88+
* It must comply with the [npm specification](https://docs.npmjs.com/files/package.json).<br/>The `package.json` must contain at least `name` and `version` pairs. You will later use the plugin in your code by requiring it by its `name`.
89+
* It must contain a `nativescript` section which describes the supported NativeScript runtimes and their versions. This section can be empty. If you want to define supported platforms and runtimes, you can nest a `platforms` section. In this `platforms` section, you can nest `ios` and `android` key-value pairs. The values in these pairs must be valid runtime versions.
90+
* If the plugin depends on other npm modules, it must contain a `dependencies` section as described [here](https://docs.npmjs.com/files/package.json#dependencies).<br/>The NativeScript CLI will resolve the dependencies during the plugin installation.
4091

41-
Here is an example.
92+
#### Package.json Example
4293

43-
Let you say that you have the following `Android.manifest` file in `platforms\android\` folder in your plugin:
94+
The following is an example of a `package.json` file for a NativeScript plugin which supports the 1.0.0 version of the iOS runtime and the 1.1.0 version of the Android runtime.
95+
96+
```
97+
{
98+
"name": "myplugin",
99+
"version": "0.0.1",
100+
"nativescript": {
101+
"platforms": {
102+
"ios": "1.0.0",
103+
"android": "1.1.0"
104+
}
105+
}
106+
}
107+
```
108+
109+
## Install a Plugin
110+
111+
To install a plugin for your project, inside your project, run the following command.
112+
113+
```Shell
114+
tns plugin add <Plugin>
44115
```
116+
117+
### Valid Plugin Sources
118+
119+
You can specify a plugin by name in the npm registry, local path or URL. The following are valid values for the `<Plugin>` attribute.
120+
121+
* A `<Name>` or `<Name>@<Version>` for plugins published in the npm registry.
122+
* A `<Local Path>` to the directory which contains the plugin files and its `package.json` file.
123+
* A `<Local Path>` to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.
124+
* A `<URL>` which resolves to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.
125+
* A `<git Remote URL>` which resolves to a `.tar.gz` archive containing a directory with the plugin and its `package.json` file.
126+
127+
### Installation Specifics
128+
129+
The installation of a NativeScript plugin mimics the installation of an npm module.
130+
131+
The NativeScript CLI takes the plugin and copies it to the `app\tns_modules` directory inside your project. During this process, the NativeScript CLI resolves any dependencies described in the plugin `package.json` file and adds the plugin to the project `package.json` file in the project root.
132+
133+
Next, the NativeScript CLI runs `$ tns prepare` for all platforms configured for the project. During this operation, the CLI copies the plugin to the `tns_modules` subdirectories in the `platforms\android` and `platform\ios` directories in your project. If your plugin contains platform-specific `JS` files, the CLI copies them to the respective platform subdirectory and renames them by removing the platform modifier. Finally, the CLI merges the plugin `AndroidManifest.xml` and `Info.plist` files with `platforms\android\AndroidManifest.xml` and `platforms\ios\Info.plist` in your project.
134+
135+
> **IMPORTANT:** Currently, the merging of the platform configuration files does not resolve any contradicting or duplicate entries.
136+
137+
#### AndroidManifest.xml Merge Example
138+
139+
The following is an example of a plugin `AndroidManifest`, project `AndroidManifest.xml` and the resulting merged file after the plugin installation.
140+
141+
**The Plugin Manifest**
142+
143+
```XML
45144
<?xml version="1.0" encoding="UTF-8"?>
46145
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
47146
package="com.example.android.basiccontactables"
48147
android:versionCode="1"
49148
android:versionName="1.0" >
50-
51-
<uses-sdk
149+
150+
<uses-sdk
52151
android:minSdkVersion="19"
53152
android:targetSdkVersion="21" />
54153

@@ -87,8 +186,9 @@ Let you say that you have the following `Android.manifest` file in `platforms\an
87186
</manifest>
88187
```
89188

90-
and the default `Android.manifest` file in your app in `platforms\android\` folder.
91-
```
189+
**The Project Manifest Located in `platforms\android\`**
190+
191+
```XML
92192
<?xml version="1.0" encoding="utf-8"?>
93193
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
94194
package="org.nativescript.test"
@@ -124,8 +224,9 @@ and the default `Android.manifest` file in your app in `platforms\android\` fold
124224
</manifest>
125225
```
126226

127-
The produced result xml will be:
128-
```
227+
**The Merged Manifest Located in `platforms\android\`**
228+
229+
```XML
129230
<?xml version="1.0" encoding="utf-8"?>
130231
<manifest
131232
xmlns:android="http://schemas.android.com/apk/res/android" package="org.nativescript.test" android:versionCode="1" android:versionName="1.0">
@@ -140,8 +241,8 @@ The produced result xml will be:
140241
<uses-permission android:name="android.permission.CALL_PHONE"/>
141242
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
142243
<!--
143-
Some comment here
144-
-->
244+
Some comment here
245+
-->
145246
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
146247
<application android:name="com.tns.NativeScriptApplication" android:allowBackup="true" android:icon="@drawable/icon" android:label="@string/app_name" android:theme="@style/AppTheme">
147248
<activity android:name="com.tns.NativeScriptActivity" android:label="@string/title_activity_kimera" android:configChanges="keyboardHidden|orientation|screenSize">
@@ -156,4 +257,48 @@ The produced result xml will be:
156257
</manifest>
157258
```
158259

260+
### Manual Steps After Installation
261+
262+
After the installation is complete, you need to open `platforms\android\AndroidManifest.xml` and `platforms\ios\Info.plist` in your project and inspect them for duplicate or contradicting entries. Make sure to preserve the settings required by the plugin. Otherwise, your app might not build or it might not work as expected, when deployed on device.
263+
264+
## Use a Plugin
265+
266+
To use a plugin inside your project, you need to add a `require` in your app.
267+
268+
```JavaScript
269+
var myPlugin = require("myplugin");
270+
```
271+
272+
This will look for a `myplugin` module with a valid `package.json` file in the `tns_modules` directory. Note that you must require the plugin with the value for the `name` key in the plugin `package.json` file.
273+
274+
## Remove a Plugin
275+
276+
To install a plugin for your project, inside your project, run the following command.
277+
278+
```Shell
279+
tns plugin remove <Plugin>
280+
```
281+
282+
You must specify the plugin by the value for the `name` key in the plugin `package.json` file.
283+
284+
### Removal Specifics
285+
286+
The removal of a NativeScript plugin mimics the removal of an npm module.
287+
288+
The NativeScript CLI removes any plugin files from the `app\tns_modules` directory inside your project. During this process, the NativeScript CLI removes any dependencies described in the plugin `package.json` file and removes the plugin from the project `package.json` file in the project root.
289+
290+
> **IMPROTANT:** This operation does not remove files from the `platforms\android` and `platforms\ios` directories and does not unmerge the `AndroidManifest.xml` and `Info.plist` files.
291+
292+
### Manual Steps After Removal
293+
294+
After the plugin removal is complete, you need to run the following command.
295+
296+
```Shell
297+
tns prepare <Platform>
298+
```
299+
300+
Make sure to run the command for all platforms configured for the project. During this operation, the NativeScript CLI will remove any leftover plugin files from your `platforms\android` and `platforms\ios` directories.
301+
302+
Next, open your `platforms\android\AndroidManifest.xml` and `platforms\ios\Info.plist` files and remove any leftover entries from the plugin `AndroidManifest.xml` and `Info.plist` files.
159303

304+
Finally, make sure to update your code not to use the uninstalled plugin.

0 commit comments

Comments
 (0)