Help wanted: Create documentation on requiring Velocity

[julianshapiro]

Browserify/RequireJS, etc. With and without Velocity's jQuery shim.

I know the basics but I feel like someone would know better than me.

I'll then polish it up and add it to the official docs.

[fattenap]

Documentation is not my strong point. Here you go. Feel free to do with it what you will :)

When using browserify to bundle Velocity you require the relevant Velocity module

i.e.
var $ = require(velocity-animate/jquery.velocity);
Or using the shim
var Velocty = require(velocity-animate/velocity)

When you run browserify ./index.js > bundle.js the output bundle includes jQuery. If you would like to exclude jQuery from your bundle you must set the --exclude or -u option, which omits a file from the output bundle. So running browserify ./index.js -u jquery > bundle.js creates a bundle that does not include jQuery.

For jquery.velocity there is still a dependency on jQuery, so jQuery will need to be available on the window object in the browser, most likely via a <script> tag. The shim version, however, does not depend on jQuery, so will work without jQuery. If jQuery happens to be available, the shim will default to using jQuery proper.

n.b. When using the shim you will most likely want to use the --exclude or -u option. That way your bundle will work with or without jQuery being available.

[LukeChannings]

AMD/RequireJS implementation needs to be fixed up a little, see #238. But this is how it should work:

(I'm also not so good at documentation.)

RequireJS-based project with jQuery

Configuration:

requirejs.config({
    baseUrl: 'js',
    paths: {
        jquery: 'vendor/jquery'
    },
    deps: ['vendor/velocity']
})

Having vendor/velocity as a base dependency ensures that jQuery.fn is extended. This means any module can use Velocity in a standard way like this:

define(['jquery'], function($) {

    $('.foo').velocity({opacity: 0}, {display: 'none'})
})

Or, to use the Velocity utility function:

define(['vendor/velocity'], function(velocity) {
    velocity(
        document.querySelector('.foo'),
        {opacity: 0},
        {display: 'none'}
    )
})

RequireJS-based build without jQuery

Configuration:

requirejs.config({
    baseUrl: 'js',
    paths: {
        velocity: 'vendor/velocity-nojquery' // jQuery shim + velocity
    }
})

Module example:

define(['velocity'], function(velocity) {
    velocity(
        document.querySelector('.foo'),
        {opacity: 0},
        {display: 'none'}
    )
})

[julianshapiro]

Thanks, Luke and Frank. I will get to work on formalizing this.

[fab1an]

I have problems with the velocityui pack. No matter how I configure requirejs it complains that it's loaded BEFORE velocity.

[julianshapiro]

You're shimming velocity as a dependency of velocity ui?

[fab1an]

Yes. I have to add that it works except when I'm bundling it.

[ydaniv]

Then this is a problem in your r.js config. Perhaps your static paths are different then your static URLs? In that case you'll need define all your paths in the r.js config and not load it from requirejs config.

We'll close this issue but feel free to post a pen/fiddle with your configs and perhaps I can help you trace it down.

@julianshapiro close.

[fab1an]

It worked before updating velocity.

After upgrading velocity 0.0.14 -> 0.11.9 and velocity.ui 0.1.0 -> 4.1.3 it broke.

I'm using gulp with the gulp-requirejs (2.1.8). plugin. Requirejs > 2.1.10 has a "wrapShim" option which might make velocityui in it's current incarnation work, but I can't update. There are four (!) gulp plugins for that job now, and it took me 3 hours to make that one work. I tried the others which support newer require.js versions but could not make them work.

I just wrapped the velocityui file in a define() call, can't afford to lose more time to this.

[fab1an]

And thanks for your efforts of course! :)

[julianshapiro]

@ydaniv: should I wrap velocity ui in module loading IFFE's? i can put on my to-do list for this week

[ydaniv]

@julianshapiro I don't think that's needed.

@fab1an see here - as of 2.1.11 you can tell r.js to wrap shimmed deps which have intermediate AMD dependencies of their own.

Please give it a try and let us know, if no go I'll research this more thoroughly.
Thanks!

[fab1an]

@ydaniv Like i said above: I can't update to 2.1.11 without breaking my build-system, cause I would have to switch plugins. I wrap it myself for now.

[ydaniv]

@fab1an just tested it myself with 2.1.14 and looks like you're right. Every way I try to configure it the define() wrap for velocity.ui inserted by r.js is always placed after the file's source. I guess we'll have to wrap it in a UMD.

[julianshapiro]

@fab1an this should be fixed now. i've wrapped velocity ui in a module. thanks for your patience.

[fab1an]

Thank you!