The primary goal of RaveJS is to make it amazingly simple to create sophisticated, modern web apps. To help you achieve this, we ask only three things of you:
- Use bower and npm to manage your application and all of its third-party libraries and frameworks.
- Save all bower and npm metadata by specifying the
--savecommand line flag. - Use Rave Starters, Rave Extensions, and Rave Integration packages to integrate with frameworks and add capabilities.
Why bower and npm?
Package managers provide a consistent environment. Rave relies on the package manager to put predictable files into well-known locations.
Why save the metadata?
Metadata allows rave to automatically discover the installed packages, discover their details, and respond accordingly with no configuration and with no machinery.
Why use Rave Starters, Rave Extensions, and Rave Integration packages?
These rave-specific packages provide community-driven patterns, capabilities, and conveniences that preserve Rave's goals to eliminate configuration and machinery.
Since rave-specific packages don't require any code changes to your code or to third-party frameworks and libraries, you are free to uninstall them, replace them with an alternative, or roll your own at any time.
To get started with Rave, you need to have the following, typical web development tools pre-installed:
- a recent release of node.js
- a recent release of bower and/or npm (comes with node.js)
- any static web server (some Rave Starters already come with one)
For a minimally-opinionated Starter, begin here.
For an AngularJS-centric starter, begin here.
Don't see a Starter for your favorite stack? Create one!
Check out the Quick Start using Bower or the Quick Start using npm.
Rave uses the metadata in the top-level bower.json or package.json files
to create a package for your application's modules. The specifics of this
package depend on the Rave Starter you used or -- if you started
from scratch -- the choices you made when
running bower init or npm init.
Many Rave Starters call the application package, "app", which means your app's modules will reside in the "app/" module namespace and the "app/" directory under the web root.
How you build your application depends on which frameworks and libraries you have chosen, of course. The format in which you author your modules -- AMD, node, or ES6 -- does not depend on the frameworks. Every package, including your app's package, may have a different format. However, each package must be authored in the same format. Therefore, you must author all of your app's modules in the same format.
AMD, node, and ES6 use module namespace patterns that mimic unix-style file paths and urls. Therefore, your module namespaces will mirror your directory structures. For instance, if you have partitioned your app into three components named "home", "settings", and "detail", your modules should be organized into three sub-spaces: "app/home/", "app/settings/", and "app/detail". These will naturally reside in similarly named directories:
app
+ detail
+ home
+ settings
When referencing modules from within your application, use relative names. When referencing modules in other packages, always use absolute names! For example, the following code illustrates how to import a sibling module, called "controller" (within your app) and a third-party module, named "when/lift", that resides in a third-party package.
var controller = require('./controller');
var lift = require('when/lift');For a more complete introduction to JavaScript modules, check out the Learning modules series on know.cujojs.com.
TBD
Next, search for Rave Extensions on bower or npm. Rave Extensions add capabilities and glue code that may be needed by your favorite framework or library.
Install any other packages you plan to use via bower or npm and
*don't forget to use the --save option when installing!
By default, your app requires only a static web server to run. Stand up a web server that can serve the directory where your app's bower.json or package.json file reside. Then, point your favorite browser at the url for this directory.
For instance, if you're using serv,
your application resides in the projects/myApp folder, and you would
like to serve files over port 8080, type:
cd projects/myApp
serv 8080Then open your browser to http://locahost:8080.
You don't have to configure transpilers, file watchers, build tools, etc. Your application configures and assembles itself from the metadata and source code it discovers in the directories under the web root.
We call this responsive mode since your application responds automatically to any changes in the metadata or application code. Just reload the browser and the application is up to date.
By default, your application runs in quiet mode. However, it's super
easy to turn on debug mode. Simply add a "data-debug" attribute to the
<html> tag in your HTML. Debug mode turns on many useful features, logs
more exceptions, and checks for common mistakes.
Most Rave Starters are configured for debug mode out of the box.
You'll typically want to switch back to quiet mode before deploying your application, of course.
Learn more about debugging in the debugging document.
When in responsive mode, lots of computation happens at run time in the browser. This is perfectly fine and hardly perceptible most of the time when running on your development machine. However, this mode is totally unacceptable in production. Eventually, you must build your app.
Switching to built mode is just a single command (TBD: Summer 2014). Virtually all of the run-time computation that was happening in the browser is pre-computed during the build process. Your app is leaner, faster, and closer to what will be eventually deployed to production.
However, now your development environment is more complex. Unlike in responsive mode, the compiling, transforming, and concatenation must happen before the code arrives at the browser. Fortunately, Rave and Rave Extensions automatically configure compilers, transformers, concatenators, minifiers, and file watchers. You don't need to do this manually.
Built mode is not a one-way street. Go back to the simplicity of responsive mode at any time with a single command (TBD: Summer 2014).
More importantly, you can control how your app is built. Rave Starters come with an opinionated set of build tools, but you can uninstall any of them and replace them with Rave Extensions with build tools that assemble your application the way you prefer.
Don't like SASS? Install a Rave Extension that supports LESS or Stylus or pure OOCSS instead.
Testing isn't easy, but it should be. We plan to simplify your testing process, too: unit testing, functional testing, continuous integration, even TDD strategies. Would you like to integrate buster.js/sinon with Sauce Labs? Install a Rave Extension for that combo.
We're aiming for the end of 2014. Stay tuned!
Once you've coded, built, and tested your app. It's time to deploy it. Deployment should be brain-dead simple. Install a Rave Extension to deploy to Cloud Foundry or Heroku, for instance.
As with testing, we're aiming for the end of 2014 for this functionality. Can't wait? Help us out!