I recently posted on the state of native desktop apps in HTML5 and mentioned that at my company we chose to use Brackets-Shell as our native app solution. I want to go more in-depth into what brackets is and why we chose it as our solution. This will be the first of a series of posts dedicated to brackets-shell and customizing it for your native HTML desktop applications.
Brackets Shell is what allows Brackets to be run as a desktop application. It takes Chromium Embedded Framework (CEF) and adds some extras along with an excellent build tool. The brackets-shell app is so well done, it made it easy for a web-developer like me to get my first ever C++ pull request accepted (I took credit for that whole pull request, but the windows portion was done by my good friend, Jordan).
I’m glad you asked:
Now on to the good stuff.
The first thing you will want to do is test the shell to see if your HTML application runs in it. The quickest route to doing this is to download the latest Brackets editor and install it. The installer installs the brackets-shell along with the brackets HTML application. If you remove the HTML app then the when you run the brackets shell it will ask you for the location of your index.html file. If you choose your own index.html file from your own application, brackets shell will open that.
To remove the brackets HTML app on Windows, browse to the Brackets folder in your Program Files directory. Inside the Brackets folder there is a folder named ‘www’. Rename or delete that folder, then run Brackets. The file dialog will open prompting you to select your own index.html file.
On OSX, open the terminal and browse to your application directory. Applications in OSX are actually folders, and in terminal you can view their content. CD into the Brackets Sprint [sprint number].app folder and continue to the Contents directory. Inside there you will see the www folder. Delete or rename it and then run brackets. You will see the file dialog prompting you to select your own index.html file.
If your app runs well in brackets-shell your next step is to setup your computer to build brackets-shell. This is where the shell really shines. They have an amazing Grunt setup that allows you to run the build in one command. Brackets provides some great instructions on setting up your box here. Once you are setup, run `grunt build` from the command line and it should create a full build of brackets shell for you. So awesome.
This is where things get fun. Let’s make the shell be a full-on desktop app for our own software. Make sure you have followed the instructions for getting setup to build brackets-shell and then take these next steps:
Now you are all setup. To see what grunt commands you have available type in `grunt –help` at your terminal
> grunt --help Available tasks full-build Alias for "git", "create-project", "build", "build-branch", "build-num", "build-sha", "stage", "package" tasks. installer Alias for "full-build", "build-installer" tasks. build Build shell executable. Run 'grunt full-build' to update repositories, build the shell and package www files. build-mac Build mac shell build-win Build windows shell git Pull specified repo branch from origin * build-branch Write www repo branch to config property build.build-branch build-num Compute www repo build number and set config property build.build-number build-sha Write www repo SHA to config property build.build-sha stage Stage release files stage-mac Stage mac executable files stage-win Stage win executable files package Package www files write-config Update version data in www config.json payload build-installer Build installer build-installer-mac Build mac installer build-installer-win Build windows installer set-sprint Update occurrences of sprint number for all native installers and binaries cef Download and setup CEF cef-clean Removes CEF binaries and linked folders cef-download Download CEF, see curl-dir config in Gruntfile.js cef-extract Extract CEF zip cef-symlinks Create symlinks for CEF node Download Node.js binaries and setup dependencies node-win Setup Node.js for Windows node-mac Setup Node.js for Mac OSX and extract node-clean Removes Node.js binaries create-project Create Xcode/VisualStudio project setup Alias for "cef", "node", "create-project" tasks. jshint Validate files with JSHint. * copy Copy files. * clean Clean files and folders. * curl Download files from the internet via grunt. * curl-dir Download collections of files from the internet via grunt. * default Alias for "setup", "build" tasks.
Look at all that goodness! So many Grunt commands at your disposal all ready to go.
The first thing you need to do is run the cef command, which will download Chromium Embedded Framework and prep it for your build. Type `grunt cef` in your terminal and you should see something like this:
$ grunt cef Running "cef" task Running "cef-download" task Downloading http://dev.brackets.io/cef/cef_binary_3.1453.1255_macosx.zip. This may take a while... Running "curl-dir:cef-mac" (curl-dir) task Files "downloads/cef_binary_3.1453.1255_macosx.zip" created. Running "cef-clean" task Running "cef-extract" task Running "cef-symlinks" task Done, without errors.
Now do the same thing for node.js by typeing `grunt node` in the terminal:
$ grunt node Running "node" task Downloading node-v0.8.20-darwin-x86.tar.gz. This may take a while... Running "curl-dir:node-mac" (curl-dir) task Files "downloads/node-v0.8.20-darwin-x86.tar.gz" created. Running "node-clean" task Running "node-mac" task Done, without errors.
Now you are ready to do a full-build. To do that (yup, you guessed it) type `grunt full-build`. It will take a bit of time, and will end with a warning:
Warning: Unable to read "installer/mac/staging/Brackets.app/Contents/www/config.json" file (Error code: ENOENT). Use --force to continue.
Don’t worry about the warning, if you made it that far you made a full build! You can check out your newly-built app in the brackets-shell/installer/(mac or win, depending on your OS)/staging folder. Run it and make sure it loads your index.html file by default now. (it shouldn’t prompt you to locate an index.html file, it should just open and run the one from your html application)
You probably noticed your new application’s name was “brackets” and that your icon for the app was the brackets logo. You don’t want that, so let’s change the name of your app to “Awesome”.
There are a couple of places you will need to change to get your app name changed:
1. Gruntfile.js – change the build name
2. appshell/config.h – Change the app-name for windows and osx
3. appshell_config.gypi – Change the app-name as well
Now just type `grunt full-build` at the terminal and it will create a build with your app and name the app “awesome”
For basic HTML apps that you just need a shell for, this might be all you need. But this is only the beginning of what you can do with brackets-shell. Over the next few weeks I will be posting new tutorials showing how you can:
As always, let me know if you have any comments or questions!