An experiment to make HTML5 apps DRY(Don't Repeat Yourself) and Clean
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
tools
.gitignore
.jshintrc
Gruntfile.js
LICENSE
README.md
package.json

README.md

This is TopGap

TopGap lets you write Chrome apps and compile them into native apps. PhoneGap for the desktop. HTML5 already works wonderfully on laptops and PCs, so it's a great choice for building "write once, run many" apps targeting — Windows, OSX, and Linux. And a TopGap app also lets you distribute your app through Chrome and reach another growing desktop OS: Chrome OS. That said, TopGap apps don't need Chrome to be installed or running. They are regular binary executables, they can run in the background, and can even be configured to start when the system boots.

BTW TopGap is orders of magnitude less ambitious than PhoneGap. We're scratching our own itch here, doing just enough work to let us make a cross-platform app with it. You're welcome to extend it further for your own needs though.

How does TopGap work?

TopGap leverages Node-Webkit, a tool for building native apps with NodeJS and the DOM. The real value TopGap adds is letting you build such apps from a Chrome project, and with Node's runtime being based on Chromium, the compatibility is strong.

To achieve this, TopGap transforms your project's Chrome config into Node-Webkit config. When your project is running as a Node-Webkit app, it will be making Chrome API calls which would normally cause an error. But TopGap also ships with adapters to simulates and intercept (monkey-patch) Chrome API calls, and handle them in a platform-agnostic Node runtime. For example, calls to chrome.storage are intercepted and routed to localstorage, which Node-Webkit can handle just fine. You could of course write your own storage adapter to instead use a native solution, or even customise it for each native OS.

Note: This is an early release with but a handful of Chrome APIs supported. Contributionss for further APIs are welcome.

Getting Started

Let's start building a native version of your Chrome App. Installation is easy. Just follow the instructions below.

0. Requirements: NodeJS

Install node.js version >=0.10.x

1. Install TopGap

$ npm install -g git://github.com/playerfm/topgap.git#0.1-stable

Now's a good time for a chai. This may take a few minutes as it needs to pull down dependencies.

2. Build it!

$ git clone https://github.com/playerfm/dashboard.git  # clones topgap demo chrome app project.
$ topgap build dashboard /tmp/dashboard                # build and set the build directory to /tmp/output-dir

That's it! Now you'll have builds for all platforms (OSx, Win, Linux32|64) binaries at /tmp/dashboard directory, running the sample Dashboard Chrome app natively.

Usage

Usage: topgap [commands] [options]

       topgap build /home/me/dashboard /tmp/native-dashboard

Description:

       Topgap command-line tool to build chrome app to native desktop app

Commands:

       build <src> <dest>          builds the chrome app project to native app
       run <src>                   run native desktop app on fly
       update                      updates topgap and npm modules
       version                     display topgap version
       help                        help and usage information

Options:

       -h, --help                  output usage information

Examples:

      $ topgap build /path/to/app /path/to/output/build
      $ topgap build --help
      $ topgap run /path/to/app
      $ topgap run .
      $ topgap update

Manifest.json

Add desktop window config on manifest.json file.

{
...,

  "native": {
    "version": "0.9.2",
    "main": "src/index.html",
    "window": {
      "toolbar": false,
      "show": false,
      "width": 520,
      "height": 350,
      "icon": "icons/icon_128x128.png"
    }
  }
}

How to Contribute

Chome API Library

If you want to contribute Chrome APIs for Topgap. This is the right place to start. Node-webkit Chrome APIs are located at ./lib/chrome directory.

Available APIs at the moment are the following:

  • Storage API
  • Alarms API
How to add new API

Let's say you want to add chrome.window api.

  1. Clone this project

  2. Create a chrome window file like ./lib/chrome/window.js

  3. Assign the window to chrome variable here;

    // ./lib/nodewebkit/inject-start.js
    ...
    chrome.window = require('../chrome/window');
    ...
    
  4. Submit a pull request

License

MIT license