{"id":28754231,"url":"https://github.com/zeroasterisk/meteorrider","last_synced_at":"2025-06-17T01:08:01.909Z","repository":{"id":9810969,"uuid":"11792669","full_name":"zeroasterisk/MeteorRider","owner":"zeroasterisk","description":"PhoneGap/Cordova + Meteor integration approach \"DOM hijacking\", telling PhoneGap where to get content from, letting Meteor hijack your PhoneGap app's HTML/CSS/JS","archived":false,"fork":false,"pushed_at":"2015-04-06T14:48:00.000Z","size":412,"stargazers_count":183,"open_issues_count":14,"forks_count":28,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-05-02T05:54:53.690Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zeroasterisk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-07-31T14:24:41.000Z","updated_at":"2023-05-05T16:55:59.000Z","dependencies_parsed_at":"2022-09-04T19:10:41.427Z","dependency_job_id":null,"html_url":"https://github.com/zeroasterisk/MeteorRider","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/zeroasterisk/MeteorRider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2FMeteorRider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2FMeteorRider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2FMeteorRider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2FMeteorRider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zeroasterisk","download_url":"https://codeload.github.com/zeroasterisk/MeteorRider/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zeroasterisk%2FMeteorRider/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260269458,"owners_count":22983647,"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":[],"created_at":"2025-06-17T01:07:59.993Z","updated_at":"2025-06-17T01:08:01.895Z","avatar_url":"https://github.com/zeroasterisk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DEPRECATION NOTICE\n\nMeteor core now supports a better Meteor + Cordova integration approach.  \n\nThis project was useful while that didn't exist, but Meteor's integration is great, use it.\n\n* https://www.meteor.com/try/7\n* http://docs.meteor.com/#/full/Cordova-depends\n* http://docs.meteor.com/#/full/mobileconfigjs\n\n----\n\n# MeteorRider\n\nAn approach for integrating [PhoneGap/Cordova](http://phonegap.com/) + [Meteor](https://www.meteor.com/).\n\n*Your Meteor web app (real time everything), inside a Cordova shell (native APIs) = awesome!*\n\n# How it works\n\n* Cordova loads it's normal, compiled `www/index.html`\n * All normal, compiled Cordova JS loads *(this ensures Cordova API versions are maintained, decoupled from Meteor)*\n* MeteorRider\n * **Step 1) loading**\n  * MeteorRider looks in localStorage to see if we have cached the last requested HTML\n * **Step 2) requesting**\n  * MeteorRider does an AJAX request to your Meteor Server\n  * MeteorRider replaces paths in the HTML response to be full URLs\n * **(Step 3) replacing**\n  * MeteorRider **replaces** the DOM *(\"hijacking the DOM\")*\n  * MeteorRider stores the HTML for next time's loading screen\n* The DOM loads all the Meteor JS/CSS\n * *NOTE that all of Cordova's JS remains in the DOM (from before)*\n * *future-feature: planning on caching and inlining this*\n* Meteor connects via DDP to the Meteor Server\n\n![overview](./docs/img/how-meteorrider-works.png)\n\n## It's Easy\n\nIt might sound a bit complex, but really it's pretty simple.\n\nThis approach is good for the following reasons\n\n* The JS needed for whatever version of Cordova is always bundled with Cordova,\n  updating is easy.\n* All Cordova API and Plugins' remain available, because the Cordova JS is\n  loaded first, we just add to it.\n* Once setup you can mostly ignore Cordova and only update your Meteor app, all\n  updates get to the client FAST (no app updating needed)\n* iframes are the devil!\n\nIf you want an alternative, without the extra AJAX request try out\n\n* [Pack Meteor](https://github.com/SpaceCapsule/packmeteor) is a great way to\n  compile all of what you need to run meteor (client) on [Chrome Packaged Apps for Mobile](https://github.com/MobileChromeApps/mobile-chrome-apps) (etc)\n * upside: super-fast, all Meteor assets live local in the Mobile App\n * upside: build script gets all Meteor JS \u0026 assets *(well managed)*\n * upside: chrome APIs available if you do [Chrome Packaged Apps for Mobile](https://github.com/MobileChromeApps/mobile-chrome-apps)\n * upside: decent \"offline\" support\n * downside: slightly more complicated release proccess\n * downside: you have to re-release the mobile application for every update to your Meteor App\n * downside: you have coordinate your entire user base's apps for releases if your app changes (since they have an old version installed)\n* [Meteor Cordova Loader](https://github.com/andrewreedy/meteor-cordova-loader) is another great alternative, basically a super-lazy-loader option\n * upside: faster initial load, no Cordova initial load screen\n * upside: load script gets all Cordova core \u0026 plugin JS from Meteor *(well managed)*\n * downside: you can [basically never update versions of Cordova after release](https://github.com/andrewreedy/meteor-cordova-loader/issues/16) because client versions are unknown\n * downside: like above, you can never add or upgrade a plugin for the same reasons, the client \"version\" is lost\n * downside: no \"offline\" support *(though, MeteorRider doesn't offer much for that either)*\n\nFor more info, [a comparison of approaches](http://zeroasterisk.com/2013/08/22/meteor-phonegapcordova-roundup-fall-2013/)\n\n## Example Projects\n\n* https://github.com/zeroasterisk/MeteorRiderExample0 Cordova 3.5 Android (2 commits)\n * This is a very basic example, showing how easy it is to implement\n * You can edit the URL to the Meteor App and this will work as a totally functional shell for your app\n * You can add platforms like *iOS* in the normal Cordova way and be up and working on them in seconds\n* https://github.com/zeroasterisk/MeteorRiderExample-CrossWalk CrossWalk + Cordova 3.5 ~ Android (1 commit)\n * **Did you know?** [CrossWalk](https://crosswalk-project.org/#documentation/cordova) is the project behind\n   [Chrome Packaged Apps for Mobile](https://github.com/MobileChromeApps/mobile-chrome-apps), \n   taking **Chromium** to the mobile device *(so you aren't stuck with old-ass-WebKit on Android)*\n * this is definitely my recommendation for performance on Android\n * You can edit the URL to the Meteor App and this will work as a totally functional shell for your app\n * Only Android :(\n\n## Installation / Usage\n\n\u003e NPM installer package under consideration see\n\u003e [this npm package](https://github.com/poetic/meteor-rider) and\n\u003e [this discussion](https://github.com/zeroasterisk/MeteorRider/pull/20)\n\nThere are only a couple of files, and you can choose to manage them however you like...\n\n### Get the Code\n\n```\ncd tmp\ngit clone https://github.com/zeroasterisk/MeteorRider.git MeteorRider\n```\n\n----\n\n## On PhoneGap/Cordova - Setup\n\n\n### Option 1) Replace the whole index.html file\n\nYou do not have to replace the whole `index.html` file, but it's a reasonable \"fast start\".\n\n* `www/js/meteor-rider.js` is our tool for getting the Meteor HTML and taking over the DOM\n* `www/js/phonegapapp.js` is where you setup your application and initializer for MeteorRider\n * has a basic structure for handling events and firing up MeteorRider\n * has a stub for a test switcher, to bypass loading MeteorRider for testing on device only\n * *you can override any of this*\n\n```\ncd pathtoyourphonegap/assets/www/\ncp index.html index_old.html\ncp /tmp/MeteorRider/www/index.html index.html\ncp /tmp/MeteorRider/www/js/meteor-rider.js js/\n```\n\nThen edit `index.html` with the appropriate **config** (see Configuration)\n\n### Option 2) Edit the index.html file\n\nThere is very little that is \"required\" to fire up MeteorRider.\n\nThis is the minimum you want in your `index.html`\n\n        \u003cscript type=\"text/javascript\" src=\"js/meteor-rider.js\"\u003e\u003c/script\u003e\n        \u003cscript type=\"text/javascript\"\u003e\n          document.addEventListener('deviceready', function() {\n              MeteorRider.init(\"http://leaderboard.meteor.com/\");\n          }, false);\n        \u003c/script\u003e\n\nYou just need to call `MeteorRider.init()` when the `deviceready` Event is triggered.\n\n### MeteorRider.config \n\nHere is the default config\n\n    config: {\n      meteorUrl: '',\n      currentPath: '',\n      localStorage: true,\n      // step 1) loading text\n      doLoading: true,\n      // step 2) AJAX request\n      doRequest: true,\n      // step 3) AJAX response (or cache) replacing DOM\n      doReplace: true\n    },\n\nIf this is global variable is found, it sets the default config in MeteorRider\n\n    var __MeteorRiderConfig__ = {\n      meteorUrl:  \"http://leaderboard.meteor.com/\",\n      currentPath: \"/\",\n      localStorage: true\n    };\n\nYou can pass any part of the `config` into `MeteorRider.init()` like so:\n\n    MeteorRider.init({ meteorUrl: \"http://leaderboard.meteor.com/\", localStorage: false });\n\nYou can also just pass in a string, and it will be treated like the meteorUrl *(simplest config)*\n\n    MeteorRider.init(\"http://leaderboard.meteor.com/\");\n\n#### MeteorRider.config.meteorUrl (required)\n\nSet the `meteorUrl` property, it should be the full URL to your meteor app.\n\n\u003e NOTE: full public URLs work best.\n\u003e Localhost or internal IPs probably wont work.\n\u003e If Cordova can't load it, it won't work.\n\n----\n\n## On Meteor\n\nYou do not have to put anything in Meteor, but if you copy in this `startup.js` file, it will handle *hot code pushes* and reload inside PhoneGap/Cordova, without losing the phonegap context.\n\n```\ncd pathtoyourmeteorapp\ncp /tmp/MeteorRider/meteor/startup.js startup.js\n```\n\nObviously, the best bet is to look for the the Cordova APIs directly\n\n```\nif (_.isObject(device)) {\n  console.log(device.cordova);\n}\n```\n\nYou can also look for the `MeteorRider` JS object inside your Meteor app and use it as a means of basic knowledge about the client, and status.\n\nYou can also force the `localStorage` to be the \"loading\" screen on the next\npageload... (it should be the full HTML you want rendered)\n\n```\nMeteorRider.meteorHtml = '\u003c!DOCTYPE html\u003e\u003chtml\u003e\u003chead\u003e' +\n  '\u003clink rel=\"stylesheet\" href=\"http://leaderboard.meteor.com/6a545450449411b537bd96111c640ce7d7a1092e.css\"\u003e' +\n  '\u003cscript type=\"text/javascript\" src=\"http://leaderboard.meteor.com/9ebe61ab3cb3e1d4bcd16191207b9f1eb692d512.js\"\u003e\u003c/script\u003e' +\n  '\u003c/head\u003e\u003cbody\u003e' +\n    'My Cool Loading Content Here :)' +\n  '\u003c/body\u003e\u003c/html\u003e';\n\nMeteorRider.replaceStoreHtml();\n```\n\n----\n\n## Meteor Packages for PhoneGap/Cordova\n\nThere are probably many more than this list, [let me know about `em](https://twitter.com/zeroasterisk).\n\n### OAuth for Meteor + MeteorRider + PhoneGap/Cordova\n\nSadly this should \"just work\" out-of-the-box, but as of now, it is \n[frought](https://github.com/AdamBrodzinski/meteor-phonegap-oauth/pull/5)\nwith\n[peril](https://github.com/zeroasterisk/MeteorRider/issues/16).\n\nLuckily there is an excellent project alive which is a very easy `mrt add phonegap-oauth` away. \n\nCheck it out here [meteor-phonegap-oauth](https://github.com/AdamBrodzinski/meteor-phonegap-oauth)\n\n\n----\n\n## Common Problems / Tips\n\n**PhoneGap/Cordova Issues? Plugin Issues?**\n\n1. Stop `MeteorRider` (comment it out, or setup testing conditional bypass)\n2. Run whatever you're doing with just `index.html` and \"on device\" JS (without Meteor)\n3. Working locally but not with MeteorRider?  Enable MeteorRider again and look for a namespace collision...\n\n**Not Loading Meteor?**\n\n1. Check the URL, can Cordova get to it?\n2. Try loading a static file from your Meteor URL (from the `/public/` folder) as the `meteorUrl`.\n3. Check the console from Cordova (Android, iOS, etc)\n\n    MeteorRider requesting\n    MeteorRider url: http://example.com\n    MeteorRider response.status = 404\n\nYou can uncomment the lines in MeteorRider where it logs the `meteorHtml`\n  (the HTML content from Meteor).\n\n\n### PhoneGap/Cordova needs to be setup to allow access to Meteor\n\nIn older PhoneGap installs or if you've restrictred `\u003caccess\u003e`, may have to allow access to the Meteor app url/domain.  Refer to the configuration documentation for your version of PhoneGap.\n\nhttp://docs.phonegap.com/en/edge/guide_appdev_security_index.md.html#Security%20Guide\n\n```\n\u003caccess origin=\"*\" /\u003e\n```\n\n\nIn the Wild\n--------------\n\n* http://blonk.co/\n * https://www.discovermeteor.com/blog/blonk-building-tinder-for-jobs-with-meteor-for-mobile/\n* http://grigio.org/meteor_and_phonegap_cordova_3_x_build_native_app_android_and_ios\n* http://meteorpedia.org/read/Mobile_support\n* ??\n\nRoadmap / Goals\n--------------\n\nThe main goal is to provide a simple, fast, and standardized way to connect\nPhoneGap to Meteor.\n\nThe combination is very powerful, and I have high hope for the future.\n\nGoals:\n\n* PhoneGap version agnostic *(done)*\n* Meteor version agnostic *(mostly done)*\n* Device agnostic *(maybe done ? Android and iOS only ones experiemented with)*\n* Minimal configuration / setup *(done)*\n* Package installer\n\nTasks:\n\n* invesigate loading just the HEAD data from the AJAX reques\n* invesigate loading the JS files (from Meteor) via AJAX so that we know when completed and could trigger callbacks\n* implement a warning/alerting system for device/connection state (PhoneGap version dependancies?)\n* we may provide a means of setting up an \"offline\" page\n\nAuthors / Acknowledgements\n--------------\n\nThis is the \"Option 3\" approach I've been thinking about for a while.\n\nInspiration and collaboration from:\n\n* [Abigail](https://github.com/awatson1978): https://github.com/awatson1978/cordova-phonegap\n* [Morten](https://github.com/raix): https://github.com/raix/Meteor-Cordova\n* And [pull requests](https://github.com/zeroasterisk/MeteorRider/pulls?direction=desc\u0026page=1\u0026sort=created\u0026state=closed) from\n * [Daniel](https://github.com/DanyHunter)\n * [@cdoe](https://github.com/cdoe)\n * [Guillaume](https://github.com/silently)\n * [Marc](https://github.com/marbemac)\n\nI'd like to thank all of them for communicating with me while figuring out what my\noptions were and for collaboration on this project.\n\nBackground:\n\nhttp://prezi.com/ig9gjm11mwsi/from-zero-to-mobile-web-app-in-sixty-minutes/\n\nhttp://zeroasterisk.com/2013/08/22/meteor-phonegapcordova-roundup-fall-2013/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeroasterisk%2Fmeteorrider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzeroasterisk%2Fmeteorrider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzeroasterisk%2Fmeteorrider/lists"}