h1. JavaScript Project Generator
h1. → 'newjs'
h2. What
A simple command-line tool to create the folders and helper files
for a new JavaScript project/library. As a bonus, you can quickly
create a website to promote your project.
When you start a new JavaScript library, how do you layout the source files,
the tests, the distribution files? Do you have support scripts to
generate distributions from source files? Run your JavaScript unit tests?
Generators to create new unit test HTML files?
*No? Me neither*, so I created the JavaScript Project Generator.
Once newjs has finished helping you write your source libraries,
write test HTML files, providing autotesting scripts to make TDD a piece of cake,
it finally helps you bundle all your source files into a single JavaScript file
for distribution.
What a nice helpful tool it is!
h2. Installing
Installation and maintenance of generated JavaScript projects
requires the installation of "Ruby":http://www.ruby-lang.org/ and "RubyGems":http://rubygems.org/.
The command-line application newjs is installed as below,
for any operating system (except the 'sudo' part - use as necessary):
sudo gem install newjs
h2. Getting started
To kick-off your new project/library, run the command-line app newjs:
$ newjs mylib
create config
create lib
create src
create script
create tasks
create test/assets
create test/assets/unittest.css
create test/assets/unittest.js
create test/assets/prototype.js
create tasks/javascript_test_autotest_tasks.rake
create tasks/environment.rake
create config/javascript_test_autotest.yml.sample
create lib/protodoc.rb
create README.txt
create Rakefile
create History.txt
create License.txt
create src/HEADER
create src/mylib.js
create script/rstakeout
create script/js_autotest
dependency install_rubigen_scripts
exists script
create script/generate
create script/destroy
Look at all that!
Unit testing uses the unittest.js library
developed within "prototypejs":http://www.prototypejs.org/. It should
also support JavaScript development using any non-prototype.js libraries.
Your raw, unconcatenated library/source files go in src/
Your unit test HTML files, go in test/ (see test generator below).
When you've got a new version to release, edit Rakefile and modify the
APP_VERSION string (see Distribution section below).
To merge your src/ files into a distribution file, see below.
h2. Generating test HTML files
If you are going to have a src/some_lib.js file, then you'll want a unit
test file(s). By default you'd call it test/some_lib_test.html.
And then what? Personally, I can never remember what basic HTML + JavaScript
goes in the test HTML files. I quite like the "javascript_test plugin":http://drnicwilliams.com/2008/01/04/autotesting-javascript-in-rails/ for "Ruby
on Rails":http://www.rubyonrails.org/, which allows you to generate a
test HTML stub. So I've included a version of it
here. That is, your JavaScript project comes with a generator to create new
test HTML files, ready to rock and roll.
$ script/generate javascript_test some_lib
exists test
create test/some_lib_test.html
Now edit test/some_lib_test.html and follow the comments
that tell you what to do to write your unit tests.
Want to name your test file something different? Specify the target
library as an additional parameter.
$ script/generate javascript_test my_library_tests some_lib
exists test
create test/my_library_tests_test.html
h2. Running unit tests
Each test HTML file should be self-executable: just open it in a target
browser. That is, to run the test/some_lib_test.html tests
in Firefox, open the file in Firefox.
It will print out a beautiful log success/error messages for each test.
h2. Distribution of library
Your project comes with the ability to concatenate all your src/*.js
files into a single file for distribution, as dist/project_name.js.
First, edit src/HEADER with information that will be included
at the top of the generated distribution file.
Second, edit src/project_name.js to include the names of
all the src/ files that will be concatenated together
in your required order.
Finally, run the command:
rake dist
h2. Create a website for your project
You can quickly create a clean, readable website for your project
that prominently displays the current version number (which is a
clickable link through to the download page), just like this page.
script/generate install_website
Now edit the generated website/index.txt file ("Textile":http://www.textism.com/tools/textile/ format).
To convert it to HTML, run:
rake website_generate
And open website/index.html in your browser to preview.
The project's version number is automatically inserted into the page
(change version numbers via APP_VERSION in Rakefile).
h3. Configuration of website upload
It is assumed you will upload your website files to rubyforge.org server.
To push files to an alternate server, modify the tasks/website.rake file.
To configure which rubyforge project to upload to, create config/website.yml.
There is an example in code/website.yml.sample.
An example might be:
host: nicwilliams@rubyforge.org
remote_dir: /var/www/gforge-projects/drnicutilities/drnic_js_test_helpers
Here, the files will be uploaded into the drnicutilities rubyforge
project, under a sub-directory drnic_js_test_helpers. This site
would be visible at "http://drnicutilities.rubyforge.org/drnic_js_test_helpers":http://drnicutilities.rubyforge.org/drnic_js_test_helpers
If your website lives in its own rubyforge project, then just specify the project
name, and the website will be uploaded into the root folder.
For example, the website would be available at "http://drnicutilities.rubyforge.org/":http://drnicutilities.rubyforge.org/ if your
configuration was:
host: nicwilliams@rubyforge.org
remote_dir: /var/www/gforge-projects/drnicutilities
h3. Uploading website to server
To upload the website (and its CSS etc) run:
rake website_upload
More commonly, to generate and upload the website:
rake website
h2. Screencast coming soon
A hard-core, "how to do JavaScript unit testing" screencast will
soon be published by "PeepCode":http://peepcode.com/. It will cost $9
and you'll love every minute of it.
Subscribe to PeepCode's blog for announcement details.
h2. Examples
The development of newjs was done in parallel with
"Dr Nic's JavaScript Test Helpers":http://drnicutilities.rubyforge.org/drnic_js_test_helpers/
(source: "git":http://github.com/drnic/drnic_js_test_helpers/tree/master).
Checkout this project to see examples of unit tests, configuration etc.
h2. Forum
"http://groups.google.com/group/javascript-project-generator":http://groups.google.com/group/javascript-project-generator
h2. How to submit patches
Read the "8 steps for fixing other people's code":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/ and for section "8b: Submit patch to Google Groups":http://drnicwilliams.com/2007/06/01/8-steps-for-fixing-other-peoples-code/#8b-google-groups, use the Google Group above.
The source project is a "Git":http://git.or.cz/ repository. See Dr Nic's "master branch":http://github.com/drnic/newjs/tree/master for clone/checkout details.
h2. License
This code is free to use under the terms of the MIT license.
h2. Contact
Comments are welcome. Send an email to "Dr Nic Williams":mailto:drnicwilliams@gmail.com via the "forum":http://groups.google.com/group/javascript-project-generator