How can I create a gulp command to build documentation using jsdoc?
I don't want to use the gulp-jsdoc package, as it is not maintained. And the package I had been using to call it from the command line, gulp-shell, is on the gulp blacklist.
Use node's built-in child_process like this:
var child_exec = require('child_process').exec;
gulp.task('docs', function(done) {
child_exec('node ./node_modules/jsdoc/jsdoc.js ./lib -c ./jsdoc.json', undefined, done);
});
(This example assumes you have a config file ./jsdoc.json, but it's easy to change the calling syntax.)
Related
It would make sense for me to use some of gulp modules/plugins independently. E.g.: I have installed gulp-less globally (npm install --global gulp-less) and want to use it instead of lessc in the manner like grunt-less -options ./my/css/folder or grunt less -options ./my/css/folder. But my attempt end with an error message:
$ gulp less ./css/
Using gulpfile ~/temp/gulptest/gulpfile.js
Task 'less' is not in your gulpfile
Please check the documentation for proper gulpfile formatting
Ideally I also would like to use gulp plugins outside of any project as independent tools.
How to run gulp modules outside of the build context?
If this option is not provided: Is there a workaround?
Put in your gulpfile.js:
gulp.task('less', function () {
// as you wish
})
I would like to know if its possible to get the git version for my package.json
What i want to achieve is that i don't need to bump the version manually.
There is something like that in Java with gradle f.e.
https://github.com/palantir/gradle-git-version
It is using git describe to get the latest tag of the git repo and if it contains new commits/changes the repo is marked as dirty. On the dirty check it automatically returns the next development version for gradle.
I didn't find anything like that for gulp
Yes.
Check this npm module https://www.npmjs.com/package/git-version-json
You can use gulp-replace and git-version-json
use git-version-json to generate the json variable.
use gulp-replace to replace the version
As below:
var gulp = require('gulp');
var replace = require('gulp-replace');
var GitVersionJson = require('git-version-json');
// automatic use git-rev in version field of package.json
gulp.task('npm-git-rev', [GitVersionJson.task], ()=>{
return gulp.src('package.json')
.pipe(replace(/(\"version\"\s*:\s*\"\d+\.\d+\.)(\d+)(\")/,
"$1" + GitVersionJson.gitVer.rev + "$3"))
.pipe(gulp.dest('.'))
});
run it with gulp npm-git-rev
I want to run an index.js file as a part of my gulp process. I could add node index.js through something like gulp-shell as described in this thread (How to run bash commands in gulp?) but it seems there should be an easier way.
I figured there would be a plugin called gulp-node or something to do this but it doesn't exist. How do others do it without turning your initial script into a gulp plugin, which seems intrusive?
You can use var data = require('./path/to/index') to load/run the index.js module in your Gulp task and send any exported information to data. You can read more about require and Node.js modules here.
Is it possible to install a node module, installed via npm, and then require it from a casperjs script?
(I see lots of posts and tools for running casper or phantom from inside node.js, but that is not what I'm trying to do.)
The casperjs docs seem to say it is possible, but only show with hand-written toy modules that don't really do anything. The real-world module I'm trying to install is imap, but at this point I cannot get any module to work, even built-in ones like net. Simple example:
npm install imap
echo "var test = require('imap');" > test.js
casperjs test.js
Gives me:
CasperError: Can't find module imap
/usr/local/src/casperjs/bin/bootstrap.js:263 in patchedRequire
test.js:1
(I can see the imap module from npm ls, and I can use it fine from a node.js script.)
Or alternatively with a built-in module:
echo "var test = require('net');" > test.js
casperjs test.js
Complains "Can't find module net"
I have npm --version of 1.4.14 and nodejs --version of v0.10.29. Are either of those too old, I wonder? (Casper is 1.1.0-beta, and Phantom is 1.9.7, both of which are the latest versions.)
PhantomJS and SlimerJS (the engines that are used for CasperJS) are not Node.js modules. They can be installed through npm for convenience. They have a different base infrastructure of modules which is distinct from Node.js.
You will not be able to use imap or any module that depends on the net module. As Fanch points out, there are modules that can work inside the phantomjs runtime.
If a module only uses some functionality of some native node.js module, you could try to change the implementation to use the API that phantomjs provides. I don't think this is easy though. Most of the time you will run into a wall.
In the case of imap, it is pretty hopeless. You cannot even re-implement the require("net").Socket, because WebSockets are not supported in phantomjs (at least in 1.9.7).
Here an example with the colors module :
var colors = require('colors');
casper.test.begin('\n*Colors module*\n', function suite(test) {
casper.start()
.thenOpen('https://www.google.fr/', function() {
console.log("test require\n".zebra);
console.log("test require\n".rainbow);
console.log("test require\n".red.underline.bold);
})
.run(function() {
test.done();
});
});
node-modules
colors
testnode.js
casperjs test testnode.js
output :
It seems it's not as simple when the required module has dependencies.
In my case, I wanted to load underscorejs. Underscore is a series of functions and don't have complicated interactions with javascript objects, so there is no problem just requiring the javascript file and then having access to its functions.
I started by finding the root to my nodejs installation (from the CLI):
node --help
Which led me to finding my node path:
echo $NODE_PATH
Which was at:
/usr/local/lib/node_modules/
Underscore was at
/usr/local/lib/node_modules/underscore/underscore.js
So my final require statement in my CasperJS script was.
var _ = require('/usr/local/lib/node_modules/underscore/underscore.js');
Now in my script I test to see if underscorejs is loaded:
this.echo(_.now());
And I see the current time.
CAVEAT: Since this is running asynchronously, if you put your _.now() statement right after the require, it will give you an undefined object error. As a note, I'm using Casper 1.1, which uses PhantomJS's native require() function. If you are using < Casper 1.1, I don't think require will work.
UPDATE:
Since this is the case, I use CasperJS then() function to load my utilities synchronously, making sure to declare my variables within the global scope. Here's how that looks:
//at the top of the file-ish, declare variables that will hold loaded libraries.
var utils, _;
var casper = require('casper').create(); //create casper
casper.start('http://example.com'); //start casper at URL.
casper.then(function loadRequires(){ //load the requirements
utils = require('utils', function(){this.echo('utils loded')});
_ = require('/usr/local/lib/node_modules/underscore/underscore.js');
});
casper.then(function myAwesomeStuff() {
this.echo(_.now()); //now, access the loaded requirements
utils.dump('this stuff is soooo awesome!!!!!!!!!!!!!!!!!!!!');
//do stuff on the page you opened in the start function here.
);
});
You can read more about the Casper prototype and the then() method at the API docs: http://casperjs.readthedocs.org/en/latest/modules/casper.html#casper-prototype
I have used CoffeeScript for a while. Now I need to write a npm package, can I write it in CoffeeScript, or I should compile CoffeeScript into JavaScript?
I'm going to suggest that you write your package in coffeescript, but only publish it in javascript. I do it like this:
coffeescript code goes in src
code is compiled to lib
src is committed to my git repo, lib is in my .gitignore
lib is published to npm, src is in my .npmignore
the coffee-script package is in my devDependencies
You can take a look at a simple package of mine, refix, for inspiration:
https://github.com/linus/refix
npm install refix
You can write NPM modules in coffeescript, but in order for them to be usable by JS users they must be compiled to JS before you publish on NPM.
package.json makes this easy with their prepublish script hook which runs the specified script before you publish. Heres an example of a prepublish NPM hook in zombie.js
https://github.com/assaf/zombie/blob/master/package.json#L16
If a lot of your modules have coffee-script in their devDependencies, it's useful to just globally install coffee-script instead of install it for each module (which takes much longer).
coffee-build is a global version manager for coffee-script.
Just add these 2 scripts to your package.json:
{
"name": "my-coffee-module",
"scripts": {
"build": "coffee-build -v 1.11.x -b -o js src",
"postinstall": "npm run build"
}
}
Notice how -v 1.11.x is not an exact version, which allows implicit upgrades.
The only downfall is that users must npm install -g coffee-build before they can install your module.
I have written npm packages in CoffeeScript from scratch. I encourage you to use CoffeScript for node as well as for the Browser. However, before you can use or publish your module, you have to compile the source CoffeeScript to JavaScript. That should not hold you back from using CoffeeScript, though.
Tip: While developing, use coffee -cw yourfile.coffee (command line) to watch the file for changes and compile on save.
While I'm not sure if it's the best approach, technically it is possible to write your package mostly in CoffeeScript.
Basically, you can write a JS file that simply wraps the coffee command, like so:
bin/howl.coffee
console.log 'Awwwooooo!'
bin/howl.js
#!/usr/bin/env node
var path = require('path');
var exec = require('child_process').exec;
var coffee = path.resolve(__dirname, '../node_modules/coffee-script/bin/coffee');
var howl = path.resolve(__dirname, './howl.coffee');
var command = coffee + ' ' + howl;
exec(command, function(error, stdout) {
if (error) { throw error };
console.log(stdout);
});
Running node howl.js (or simply howl when it's installed globally) will now output Awwooooo!. You can do things like require other CoffeeScript files and access arguments by passing them from the JavaScript "wrapper" to the CoffeeScript.
Anyway, there may be reasons not to do this, but it has worked for me so far so figured I'd submit this for an additional perspective.
For a simple example project using this technique, check out https://www.github.com/joshuabc/packdown.