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 -a "Dr Nic" -e "drnicwilliams@gmail.com" -u "http://mylib.rubyforge.org"
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 tasks/deploy.rake
create config/javascript_test_autotest.yml.sample
create lib/protodoc.rb
create lib/jstest.rb
create Rakefile
create README.txt
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/unit/ (see test generator below).
Your functional test HTML files, go in test/functional/ (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. Unit testing
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.
h3. Generating test HTML files
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 unit_test some_lib
create test/unit
create test/unit/some_lib_test.html
Now edit test/unit/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 unit_test my_library_tests some_lib
exists test/unit
create test/unit/my_library_tests_test.html
h3. 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. Functional tests
End-to-end functional tests will test the final distribution file(s), rather than
the src/ files.
As shown below, your src/ files will be merged into (commonly) one
distribution file - a merging of your source files.
h3. Generating test HTML files
To create functional tests, there is another generator:
$ script/generate functional_test basic_usage
create test/functional
create test/functional/basic_usage_test.html
h3. Running functional tests
rake test_functionals
The generated HTML file uses the dist/mylib.js file. So, if
you are running these tests it is best to use the rake test_functionals
as it pre-builds the distribution files first.
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
Two files are added into the dist/ folder:
$ ls dist/
drnic_js_test_helpers-0.5.0.js drnic_js_test_helpers.js
One with a version number, and one without.
h3. Upload library to rubyforge
Assuming you don't really care where your package/library is uploaded
and made available for downloading, newjs projects comes
pre-built ready to upload them to rubyforge.
First, you'll need a rubyforge account.
Second, create a rubyforge project. It can take 12-48hrs for confirmation
to come back.
Third, use the rubyforge command-line app to
store your rubyforge project information locally.
$ rubyforge setup # first time only
$ rubyforge login
$ rubyforge config
$ rubyforge create_package project_name project_name
Note, if you are placing your JavaScript project within an existing
rubyforge project, then the two project_name values
are different:
# The rubyforge project name (e.g. drnicutilities)
# The JavaScript project/library name (e.g. drnic_js_test_helpers)
Finally, each time you want to release a new version of your library you do
two things:
# Update Rakefile's APP_VERSION value to the new version number
# Run rake release VERSION=X.Y.Z
Your files are now available for download via rubyforge.org.
If you use the generated website (below), it comes with a link to these
files when you click the large version number (e.g. "Get Version X.Y.Z").
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