Kiwii is a lightweight unopinionated HTML5 Hybrid Mobile App framework. Kiwii relies on Backbone to build your MVC web application. It relies on Backbone.Radio for messaging, React for viewing and Ratchet and Font-Awesome for styling. However, you are not forced to use these technologies for messaging and styling. With a little effort, you can replace them by your preferred solutions.
And of course, Kiwii relies on Cordova to convert your web application into a Mobile Hybrid Application.
Kiwii is just Backbone! Kiwii aims at providing a very thin framework to reduce the overhead and thus to get a very fast Mobile Hybrid Application. And, Kiwii aims at providing a totally transparent framework without magic behind the curtains. With Kiwii we want to keep the framework as simple as possible. We want the developer to understand what it does.
If you are familiar with Backbone, Kiwii is really easy to use. If you aren't, you need to learn Backbone first as Kiwii is just a minimal glue around Backbone to facilitate its use.
Kiwii is shipped with a running minimalist webapp having a few pages and a vertical responsive menu. You can immediately start building your webapp from this skeleton.
Besides, Kiwii includes a CLI script,
kiwii.js, to assist you on adding a new module (§ Add a new module).
Kiwii uses Gulp to build a distribution version.
You can easily get your first Kiwii webapp running in a couple of minutes by just typing a few command lines. But first, you need to create an empty folder. It will contain your webapp.
Then, you have to install the Kiwii package globally. Open a terminal session and type the command:
npm install kiwii -g
If you don't have the rights to install Kiwii globally, you can install it locally in your project. Open a terminal session, move to your working directory - the empty folder you created - and type the following command:
npm install kiwii
Now populate your empty folder and create your first web app:
// populate kiwii populate -n myapp // Or, if you installed the package locally: ./node_modules/kiwii/bin/kiwii.js populate -n myapp // Install Node.js packages npm install // Build your first webpapp npm run build
Your working directory should contain now a set of files and a folder
public that contains the webapp.
As your webapp is just the HTML file
Do it and you will see your webapp running. that's all!
Kiwii webapp organization closely matches the Backbone structure. The webapp consists of one HTML file
public/index.html, one CSS file
The file style.css imports a set of dependent CSS files (see the file). These CSS files define the general styling (Ratchet) and the font used (Font-Awesome) plus the styling specific to each Backbone module (see below).
Thus, the basic structure of Kiwii webapp is:
public |_ index.html |_ css | |_ style.css |_ js |_ main.js |_ router.js
At this basic structure, we add Kiwii Backbone modules.
There is a specific Backbone module that build the app by aggregating all the
React components together.
public |_ app |_ app.js | |_ components | |_ header.js | |_ menu.js | |_ body.js | |_ footer.js | |_ layout.js | |_ css | |_ header.css | |_ menu.css | |_ body.css | |_ footer.css | |_ models | |_ appModel.js | |_ views |_ appView.js
components contains all the React components to aggregate together to build the app.
header.js, menu.js, body.js and footer.js are the basic React components and
layout.js is the composite React component.
app.js is the interface of the module and
appView.js contains the code for rendering the app (
The other specific views (home, settings, legal, etc.) are under
public |_ pages |_ home |_ home.js | |components | |_ body.js | |_ css | |_ home.css | |_ models | |_ homeModel.js | |_ views |_ homeView.js
pages contains a set of folders. Each folder is a Kiwii Backbone module.
A Kiwii Backbone module consists of an interface, a view, a model, a React component and a style sheet.
The interface (here home.js) is the link with the other parts of the webapp. It sends and listens messages from the router/controller. It updates the model (here homeModel.js) and the view (here homeView.js). Models and Views have no link with the outside. They must go through the interface.
The React component (here body.js) contains the JSX structure of the page to display.
The style sheet (here home.css) defines what style to apply to this specific page.
Kiwii provides three commands to build and run your webapp:
- npm run build,
- npm run watch,
- npm run app,
public/js/wapp.js. This file is attached to
npm run watch, as its name lets think, launches a script that watches the files of your project. If one file is modified, it automatically updates
npm run app creates an HTTP server listening on port 3000 and launches your default browser with the URL
http://localhost:3000. You should see your webapp running in it.
Add a new module
When you want to add a new page, a new Kiwii Backbone module, to your project, you don't need to create all files and folders manually. You just need to type:
kiwii add -n <new_module_name> -p 'public/pages' // Or, if installed locally: ./node_modules/kiwii/bin/kiwii.js add -n <new_module_name> -p 'public/pages'
The script creates a skeleton for the new Kiwii Backbone module. Then, you just need to fill the views and models functions and to complete the template and the style sheet.
When your module is ready to be tested, you need to instantiate it in
Create a distribution version
Kiwii provides two commands to build and run your webapp:
- npm run makedist,
- npm run dist,
But, before building a distribution version, you need to install the gulp module globally if it isn't done yet.
npm install -g email@example.com
When done, you can build your distribution version. Type:
npm run makedist: it will create a folder
npm run dist: it creates an HTTP server listening on port 3000 and it launches your default browser with the URL
http://localhost:3000. You should see your distribution webapp running in it.
Create a Mobile Hybrid Application
Now that your Kiwii webapp is ready, you can convert it to a Mobile Hybrid Application thanks to Cordova. If you aren't familiar with Cordova learn it first otherwise you won't understand what is described below.
First, install Cordova if it is not done yet. Type
npm install -g cordova
Then, create a new empty directory, open a terminal, go to this directory and type:
cordova create myapp
Go to myapp directory, throw away the folder
_dist and rename it
Create a browser platform
Now we are going to test the Hybrid Application into the browser. We need to install the browser platform by typing the command (from myapp directory):
cordova platform add browser
Then run the Hybrid Application:
cordova run browser
Your Hybrid Application runs now at the address
Create an IOS Application
Be aware, you can create an IOS app only from a Mac OS X platform with Xcode tools installed.
If you are on a Mac and you have Xcode installed, type the command:
cordova platform add ios
Add the plugins:
cordova plugin add cordova-plugin-device cordova plugin add cordova-plugin-console cordova plugin add cordova-plugin-geolocation cordova plugin add cordova-plugin-statusbar
Build the IOS Application:
cordova build ios
Then go to
myapp/platforms/ios/ and double click the file
HelloCordova.xcodeproj. It launches Xcode. When the Xcode application is opened, select the menu
Product -> Run. Xcode will open the IOS Simulator and you will see your IOS Hybrid Mobile App running!