JavaScript Project Generator

→ ‘newjs’

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!

Installing

Installation and maintenance of generated JavaScript projects requires the installation of Ruby and RubyGems.

The command-line application newjs is installed as below, for any operating system (except the ‘sudo’ part – use as necessary):

sudo gem install newjs

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. 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.

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 for Ruby on Rails, 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

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.

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.

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:

1. The rubyforge project name (e.g. drnicutilities)
2. 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:

1. Update Rakefile’s APP_VERSION value to the new version number
2. 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”).

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 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).

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

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/ if your configuration was:

host: nicwilliams@rubyforge.org
remote_dir: /var/www/gforge-projects/drnicutilities

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

Screencast coming soon

A hard-core, “how to do JavaScript unit testing” screencast will soon be published by PeepCode. It will cost $9 and you’ll love every minute of it.

Subscribe to PeepCode’s blog for announcement details.

Examples

The development of newjs was done in parallel with Dr Nic’s JavaScript Test Helpers (source: git).

Checkout this project to see examples of unit tests, configuration etc.

Forum

http://groups.google.com/group/javascript-project-generator

How to submit patches

Read the 8 steps for fixing other people’s code and for section 8b: Submit patch to Google Groups, use the Google Group above.

The source project is a Git repository. See Dr Nic’s master branch for clone/checkout details.

License

This code is free to use under the terms of the MIT license.

Contact

Comments are welcome. Send an email to Dr Nic Williams via the forum

Dr Nic Williams, 15th February 2008
Theme extended from Paul Battley