This repo is heavily based on @NathanWalker's Plugin Seed. Thanks, Nathan!
The NativeScript plugin seed is built to be used as a starting point by NativeScript plugin developers. To bootstrap your plugin development execute the following:
git clone https://github.com/NativeScript/nativescript-plugin-seed nativescript-yourplugin
where nativescript-yourplugin
is the name of your plugin.cd nativescript-yourplugin/src
npm run postclone
npm run demo.ios
or npm run demo.android
to run the demo.The NativeScript plugin seed is built to be used as a starting point by NativeScript plugin developers. What does the seed give you out of the box?
.gitignore
to keep GitHub tidy .npmignore
to ensure everyone is happy when you publish your plugin to NPM.Folder/File name | Description |
---|---|
demo | The plugin demo source code (optional during postclone setup) |
demo-angular | The plugin demo source code (optional during postclone setup) |
src | The plugin source code |
src/platform/android | Plugin Android specific configuration |
src/platform/ios | Plugin ios specific configuration |
src/README | Your plugin README stub explaining how other developers can use your plugin in their applications. Used when you publish your plugin to NPM. On postclone step, the README in the root is replaced with this one. |
src/scripts | The postclone script run when you execute npm run postclone . Feel free to delete it after you have executed the postclone step from the Getting started section |
publish | Contains a shell script to create and publish your package. Read more on creating a package and publishing in the Publish to NPM section |
git clone https://github.com/NativeScript/nativescript-plugin-seed nativescript-yourplugin
to clone the plugin seed repository into the nativescript-yourplugin
folder where nativescript-yourplugin
is the name of your plugin..nativescript-yourplugin/src
folder using cd nativescript-yourplugin/src
npm run postclone
to:
src
foldersrc
folderNow you can continue with the development of your plugin by using the Development setup described below.
NOTE: The plugin seed is updated to use the latest version of NativeScript. If you are not ready to upgrade, you can checkout a tagged version that is compatible with your NativeScript version.
For easier development and debugging purposes continue with the following:
Open a command prompt/terminal, navigate to src
folder and run npm run demo.ios
, npm run demo.android
, npm run demo-angular.ios
, npm run demo-angular.android
to run the demo applications created during postclone
.
Now go and make a change to your plugin. It will be automatically applied to the demo project.
NOTE: Any changes that you need to make in a native library used in your plugin or in any other files inside src/platforms
directory such as Info.plist or AndroidManifest.xml can't be directly reflected in the demo applications. You need to use npm run demo.reset
or npm run demo-angular.reset
and run the application again.
You will want to create these folders and files in the src
folder in order to use native APIs:
platforms --
ios --
Podfile
android --
include.gradle
Doing so will open up those native apis to your plugin :)
Take a look at these existing plugins for how that can be done very simply:
It's highly recommended to generate typings for the native libraries used in your plugin. By generating typings you'll be able to see what APIs exactly are exposed to Javascript and use them easily in your plugin code
demo/typings/x86_64
and copy the d.ts
files that you plan to use in your plugin to src/platforms/ios/typings
src/references.d.ts
and add a reference to each of the files added to src/platforms/ios/typings
NOTE: Swift APIs that are not exported to Objective-C are not supported. This means that you can only call APIs from JavaScript that are visible to the Objective-C runtime. This include all Objective-C APIs and only the subset of all Swift APIs that are exposed to Objective-C. So, to use a Swift API (class/function/method etc.) from NativeScript, first make sure that it can be used from Objective-C code. For more information which Swfit APIs can be exposed to Objective-C, see here.
src/platforms/android/typings
. Feel free to rename the generated files for readablity.src/references.d.ts
and add a reference to each of the files added to src/platforms/android/typings
Sometimes you may need to wipe away the src/node_modules
, demo/node_modules
and demo/platforms
folders to reinstall them fresh.
npm run clean
to wipe those clean then you can can run npm i
to install fresh dependencies.Sometimes you just need to wipe out the demo's platforms
directory only:
npm run demo.reset
or npm run demo-angular.reset
to delete the application's platforms
directory only.Sometimes you may need to ensure plugin files are updated in the demo:
npm run plugin.prepare
will do a fresh build of the plugin then remove itself from the demo and add it back for assurance.In order to add unit testing to the demo applications and in relation to test your plugin inside of them you should follow our latest guide here.
When you have everything ready to publish:
src/package.json
publish
and execute publish.sh
(run chmod +x *.sh
if the file isn't executable)If you just want to create a package, go to publish
folder and execute pack.sh
. The package will be created in publish/package
folder.
NOTE: To run bash script on Windows you can install GIT SCM and use Git Bash.
The plugin structure comes with a fully functional .travis.yml file that deploys the testing app on Android emulator and iOS simulator to make sure that those apps start correctly while your plugin is linked to them. All you have to do, after cloning the repo and implementing your plugin and tests, is to sign up at https://travis-ci.org/. Then enable your plugin's repo on "https://travis-ci.org/profile/<your github user>" and that's it. Next time a PR is opened or change is committed to a branch TravisCI will trigger a build testing the code.
To properly show current build status you will have to edit the badge at the start of the README.md file so it matches your repo, user and branch.
We love PRs! Check out the contributing guidelines. If you want to contribute, but you are not sure where to start - look for issues labeled help wanted
.
Please, use github issues strictly for reporting bugs or requesting features. For general questions and support, check out Stack Overflow or ask our experts in NativeScript community Slack channel.