{"id":14988343,"url":"https://github.com/apache/cordova-js","last_synced_at":"2025-04-25T14:49:17.970Z","repository":{"id":5688003,"uuid":"6898382","full_name":"apache/cordova-js","owner":"apache","description":"Apache Cordova JavaScript Bridge","archived":false,"fork":false,"pushed_at":"2025-03-28T22:12:44.000Z","size":12613,"stargazers_count":636,"open_issues_count":5,"forks_count":831,"subscribers_count":76,"default_branch":"master","last_synced_at":"2025-04-18T04:05:56.412Z","etag":null,"topics":["cordova","hacktoberfest","javascript","mobile","nodejs"],"latest_commit_sha":null,"homepage":"https://cordova.apache.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apache.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-11-28T08:00:22.000Z","updated_at":"2025-03-29T07:12:36.000Z","dependencies_parsed_at":"2024-06-17T18:32:31.331Z","dependency_job_id":"a05c1120-4182-44a5-9beb-060846359c15","html_url":"https://github.com/apache/cordova-js","commit_stats":{"total_commits":1836,"total_committers":112,"mean_commits":"16.392857142857142","dds":0.8393246187363834,"last_synced_commit":"ab52fd76714534d01fcb3773aa84c8c8d26e5a7f"},"previous_names":[],"tags_count":182,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apache%2Fcordova-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apache","download_url":"https://codeload.github.com/apache/cordova-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249594555,"owners_count":21296976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cordova","hacktoberfest","javascript","mobile","nodejs"],"created_at":"2024-09-24T14:16:34.192Z","updated_at":"2025-04-24T04:25:22.591Z","avatar_url":"https://github.com/apache.png","language":"JavaScript","readme":"\u003c!--\n#\n# Licensed to the Apache Software Foundation (ASF) under one\n# or more contributor license agreements.  See the NOTICE file\n# distributed with this work for additional information\n# regarding copyright ownership.  The ASF licenses this file\n# to you under the Apache License, Version 2.0 (the\n# \"License\"); you may not use this file except in compliance\n# with the License.  You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing,\n# software distributed under the License is distributed on an\n# \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n#  KIND, either express or implied.  See the License for the\n# specific language governing permissions and limitations\n# under the License.\n#\n--\u003e\n\n# cordova-js\n\n[![NPM](https://nodei.co/npm/cordova-js.png)](https://nodei.co/npm/cordova-js/)\n\n[![Node CI](https://github.com/apache/cordova-js/workflows/Node%20CI/badge.svg?branch=master)](https://github.com/apache/cordova-js/actions?query=branch%3Amaster)\n\nA unified JavaScript layer for [Apache Cordova](http://cordova.apache.org/) projects.\n\n## Project Structure\n\n  ```text\n  ./\n    |-build-tools/ ......... custom bundler for our CommonJS-like modules\n    |-pkg/ ................. generated platform cordova.js files\n    |\n    |-src/ ................. the code that makes up Cordova's JavaScript runtime\n    |  |-cordova.js ........ common Cordova stuff\n    |  |\n    |  |-common/ ........... base modules shared across platfoms\n    |  |  |-argscheck.js ... utility for type-checking arguments during runtime\n    |  |  |-base64.js ...... base64 utilites (toArrayBuffer \u0026 fromArrayBuffer)\n    |  |  |-builder.js ..... utilities to install a set of properties onto an object\n    |  |  |-channel.js ..... pub/sub implementation for custom framework events\n    |  |  |-init.js ........ bootstraps the Cordova platform, inject APIs and fire events\n    |  |  |-utils.js ....... closures, uuids, object, cloning, extending prototypes\n    |  |  |\n    |  |  '-exec/ .......... exec methods\n    |  |     '-proxy.js .... utility for adding and removing exec proxy methods\n    |  |\n    |  '-scripts/ .......... non-module JS that gets concatenated to cordova.\u003cplatform\u003e.js\n    |     |-bootstrap.js ... bootstrap the Cordova platform, inject APIs and fire events\n    |     '-require.js ..... module definition and require() implementation\n    |\n    '-tests/ ............... unit tests\n  ```\n\n## How It Works\n\nThe `build-tools/build.js` process is a Node.js script that concatenates all of the core Cordova plugins in this repository into a `cordova.\u003cplatform\u003e.js` file under the `pkg/` folder. It also wraps the plugins with a RequireJS-compatible module syntax that works in both browser and node environments. We end up with a `cordova.js` file that wraps each **Cordova** *plugin* into its own module.\n\n**Cordova** defines a `channel` module under `src/common/channel.js`, which is a *publish/subscribe* implementation that the project uses for event management.\n\nThe **Cordova** *native-to-webview* bridge is initialized in `src/scripts/bootstrap.js`. This file attaches the `boot` function to the `channel.onNativeReady` event - fired by native with a call to:\n\n  ```js\n  cordova.require('cordova/channel').onNativeReady.fire()\n  ```\n\nThe `boot` method does all the work.  First, it grabs the common platform definition (under `src/common/common.js`) and injects all of the objects defined there onto `window` and other global namespaces. Next, it grabs all of the platform-specific object definitions (as defined under `src/\u003cplatform\u003e/platform.js`) and overrides those onto `window`.\n\nFinally, it calls the platform-specific `initialize` function (located in the platform definition). At this point, Cordova is fully initialized and ready to roll. Last thing we do is wait for the `DOMContentLoaded` event to fire to make sure the page has loaded properly. Once that is done, Cordova fires the `deviceready` event where you can safely attach functions that consume the Cordova APIs.\n\n## Testing\n\nTests run in a bundled headless Chromium instance. They can be run with:\n\n  ```bash\n  npm test\n  ```\n\nFinal testing should always be done with the [Mobile Spec test application](https://github.com/apache/cordova-mobile-spec).\n\n## Creating a New Platform\n\nIn your platform repository:\n\n1. Create the `cordova-js-src` directory.\n\n2. Write a module that encapsulates your platform's `exec` method and call it `exec.js`. This file should be added into the `\u003cplatform-repo\u003e/cordova-js-src` directory which was created from step 1.\n\n    The `exec` method is a JavaScript function that enables communication from the platform's JavaScript environment into the platform's native environment. Each platform uses a different mechanism to enable this bridge. We recommend you check out the other platform `exec` definitions for inspiration.\n\n    The `exec` method has the following method signature: `function(success, fail, service, action, args)`\n\n    **Methods Arguments:**\n\n    * `success`: a success function callback\n    * `fail`: a failure function callback\n    * `service`: a string identifier that the platform can resolve to a native class\n    * `action`: a string identifier that the platform can resolve to a specific method inside the class pointed to by `service`\n    * `args`: an array of parameters to pass to the native method invoked by the `exec` call\n\n    It is required that new platform additions be as consistent as possible with the existing `service` and `action` labels.\n\n3. Define your platform definition object and name it `platform.js`. This file should be added into the `\u003cplatform-repo\u003e/cordova-js-src` directory which was created from step 1.\n\n    This file should export an object with the following properties:\n\n     * `id`: a string representing the platform. This should match the name of the `.js` file.\n     * `bootstrap`: A function that sets up the platform. Must fire the `onNativeReady` channel when done.\n     * `initialize`: an optional function that is called after the global scope setup is done (i.e. Cordova and all plugins are ready)\n\n    The following is a simple example of a platform definition:\n\n    ```js\n    module.exports = {\n        id: 'atari',\n        bootstrap: function() {\n            require('cordova/channel').onNativeReady.fire();\n        }\n    };\n    ```\n\n4. Bundle the modules from `cordova-js/src` and `\u003cplatform-repo\u003e/cordova-js-src` into a file that ends up in `\u003cplatform-project\u003e/platform_www/cordova.js`. This can be done in various ways. The following is recommended:\n    - Add `cordova-js` as a `devDependency`: `npm i -D cordova-js`\n    - Build `cordova.js` when preparing your platform's npm package. You can do that by adding the NPM `prepare` hook script to your `package.json`:\n      ```json\n      \"scripts\": {\n        \"prepare\": \"cordova-js build \u003e project-template/platform_www/cordova.js\",\n        // ...\n      }\n      ```\n    - During project creation, make sure that the `cordova.js` file created by the `prepare` script ends up where your platform expects it\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcordova-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapache%2Fcordova-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapache%2Fcordova-js/lists"}