Node-webkit-bootstrap
This Ruby gem provides a framework for bootstraping, running, building and testing your node-webkit applications.
How to install?
Clone this repository, run bundle install
and then rake install
to add to your system. You can then add node-webkit-bootstrap
to the Gemfile in your source repository, as described below.
How to use?
node-webkit-bootstrap
provides a set of rake
tasks that automatize the following:
- Downloading
node-webkit
- Preparing a runtime directory
- Bundling a stand-alone version of your app
- Running tests using
node-webkit
Basic Layout
Here is a typical layout:
(root)
|-- Gemfile
|-- Rakefile
|-- app/{index.html, js/, ...}
|-- vendor/arch/win/ia32/win.js
|-- vendor/arch/osx/ia32/osx.js
|-- vendor/node-webkit-bootstrap/node-webkit/win/ia32/foo.dll
|-- vendor/node-webkit-bootstrap/node-webkit/osx/ia32/Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/libfoo.so
|-- test/{index.html, js, ...}
With:
% cat Gemfile
(...)
gem "node-webkit-bootstrap", "~> 1.0.0"
% cat Rakefile
(...)
require "node-webkit-bootstrap/rake"
NodeWebkitBootstrap::Rake.register do |config|
config.app = "my-awesome-app"
config.nw_version = "0.5.1"
config.rake_namespace = "nwapp"
here = File.expand_path "..", __FILE__
config.app_path = "#{here}/app"
config.test_path = "#{here}/test"
config.run_package = {
name: config.app,
main: "index.html",
window: {
toolbar: true,
width: 660,
height: 500
}
}
config.build_package = {
name: config.app,
main: "index.html",
window: {
toolbar: false,
width: 660,
height: 500
}
}
config.test_package = {
name: config.app,
main: "index.html",
window: {
show: false
}
}
end
This configures the following rake tasks:
% rake -T
(...)
rake nwapp:build[platform] # Build my-awesome-app (platform is one of: "win", "linux", "osx" or "all", default: "all").
rake nwapp:download[version] # Download latest node-webkit code (default version: 0.4.2).
rake nwapp:run # Run my-awesome-app.
rake nwapp:test # Run my-awesome-app tests.
Downloading node-webkit
The download
task fetches node-webkit
binaries and create various tmp/node-webkit/#{platform}/#{arch}
.
Available platforms and architectures are:
# format: platform => [architectures]
{ linux: [:ia32, :x64],
osx: [:ia32],
win: [:ia32] }
Running the download task yields:
% rake my-awesome-app:download
(...)
Downloading node-wekbit binary for osx ia32
Downloading https://s3.amazonaws.com/node-webkit/v0.4.2/node-webkit-v0.4.2-osx-ia32.zip to tmp/node-webkit-v0.4.2-osx-ia32.zip
Decompressing tmp/node-webkit-v0.4.2-osx-ia32.zip
(...)
Extracting Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/node-webkit Helper
Extracting Contents/Frameworks/node-webkit Helper.app/Contents/PkgInfo
Extracting Contents/Info.plist
Extracting Contents/MacOS
Extracting Contents/MacOS/node-webkit
Extracting Contents/PkgInfo
Extracting Contents/Resources
Extracting Contents/Resources/nw.icns
Vendoring Contents/Frameworks/node-webkit Framework.framework/Libraries/ffmpegsumo.so
Vendoring Contents/Frameworks/node-webkit Helper.app/Contents/MacOS/libfoo.so
Done!
Downloading node-wekbit binary for win ia32
(...)
All the files from node-webkit
's archive are thus extracted and the libfoo.so
file is picked
from the vendor/node-webkit-bootstrap/node-webkit/osx/ia32
folder.
All files placed in to a vendor/node-webkit-bootstrap/node-webkit/#{platform}/#{arch}
folder
will likewise be added to the corresponding node-webkit
's directory. You can use this directory
to add all files you want to override from node-webkit
upstream's files, such
as for instance the OSX application package description files.
Please note that, by default. node-webkit-bootstrap
will vendor GPL versions of the ffmpeg
library to gain proper multimedia playback.
Running your app
Executing the run
task runs your application files using the node-webkit
binary
appropriate for your architecture:
% rake my-awesome-app:run
(...)
tmp/node-webkit/osx/ia32/Contents/MacOS/node-webkit tmp/node-webkit-bootstrap/my-awesome-app-run
[35457:0315/152311:ERROR:renderer_main.cc(179)] Running without renderer sandbox
(...)
The path to your app is given by config.app_path
in your Rakefile
above. Also, a
package.json
file is generated using data from config.run_package
in your Rakefile
.
Building your app
Executing the build
task generates bundled versions of your application:
% rake my-awesome-app:build
touch tmp/node-webkit-bootstrap/my-awesome-app-run
Creating build/my-awesome-app-osx-ia32.nw
Adding index.html
Adding package.json
Adding vendor
Adding vendor/arch/osx/ia32
Adding vendor/arch/osx/ia32/osx.js
Adding vendor/js
Adding vendor/js/jquery.js
Creating build/my-awesome-app-osx-ia32.zip
Adding my-awesome-app.app/Contents
Adding my-awesome-app.app/Contents/Frameworks
Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework
Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework/Libraries
Adding my-awesome-app.app/Contents/Frameworks/node-webkit Framework.framework/Libraries/ffmpegsumo.so
(...)
Adding my-awesome-app.app/Contents/Resources/app.nw
Adding my-awesome-app.app/Contents/Resources/nw.icns
(...)
As you can see, the task will first create a build/my-awesome-app-osx-ia32.nw
archive.
Here again, a package.json
file is generated using data from config.build_package
in your Rakefile
.
In the case where you app has a vendor/arch
directory, the nw
archive for a given
platform
and arch
only contains files under vendor/arch/#{platform}/#{arch}
.
You can use this option to vendor architecture-specific files inside the nw
archive.
Finally, the nw
archive is bundled together, according to each platform's technique
and a build/my-awesome-app-#{platform}-#{arch}.zip
file is created that you should
be able to distribute.
Testing
Executing the test
task works exactly as with the run
task except that the files specified
by config.test_path
in your Rakefile
are used instead of config.app_path
. Likewise, a package.json
file is created using data from config.test_package
in your Rakefile
.
You can use this task to run your tests in a specific node-webkit
testing app.
Server-side tests
In the case where most of your application's code is delivered by a server, you can
also use node-webkit-bootstrap
for testing it.
This is particularly useful because in this case your app's code is likely to have node-specific code
such as require("os")
which cannot be properly tested without node-webkit
.
Similarly to the case of your app, you have to include node-webkit-bootstrap
in your Gemfile
.
Then you add the following to your Rakefile
:
% cat Rakefile
(...)
require "node-webkit-bootstrap/rake"
NodeWebkitBootstrap::Rake.register ["test"] do |config|
config.app = "nw"
here = File.expand_path "..", __FILE__
config.test_path = "#{here}/test"
config.test_package = {
name: config.app,
main: "index.html",
window: {
show: false
}
}
end
In this case, node-webkit-bootstrap
will only add a test
task:
% rake -T
(...)
rake nw:test # Run nw tests.
You can use this task to run your tests on the server side.
Dynamically generated main
You can also dynamically generate your application's main pages. This is particularly
useful if, for instance, some URIs in the page are different whether you are in production
(build
) or development (run
).
When declaring the package
variables in Rakefile
, you can also pass a lambda
for the main file, in which case, this lambda
will the executed with the destination
path as its first argument. It should write this file at destination path and return
the file's name.
For instance:
build_main =
lambda do |path|
filename = "#{path}/index.html"
File.open filename, "w" do |file|
file.write content
end
"index.html"
end
config.build_package = {
name: "My Awesome App",
main: build_main,
...
Finally, if you need to tell node-webkit-bootstrap
of new dependencies when building runtime, build
or test, you can add rake tasks files dependencies to config.build_deps
, for instance here:
config.build_deps = ["/path/to/template/for/index.html"]