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

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.

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

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.

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.

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

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.

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, 17th February 2008
Theme extended from Paul Battley