Installable hooks are custom Sails hooks that reside in an application’s node_modules
folder. They are useful when you want to share functionality between Sails apps, or publish your hook to NPM to share it with the Sails community. If you wish to create a hook for use in just one Sails app, see creating a project hook instead.
To create a new installable hook:
sails-hook-<your hook name>
. The sails-hook-
prefix is optional but recommended for consistency; it is stripped off by Sails when the hook is loaded.package.json
file in the folder. If you have npm
installed on your system, you can do this easily by running npm init
and following the prompts. Otherwise, you can create the file manually, and ensure that it contains at minimum the following:{
"name": "sails-hook-your-hook-name",
"version": "0.0.0",
"description": "a brief description of your hook",
"main": "index.js",
"sails": {
"isHook": true
}
}
If you use npm init
to create your package.json
, be sure to open the file afterwards and manually insert the sails
key containing isHook: true
.index.js
in accordance with the hook specification.Your new folder may contain other files as well, which can be loaded in your hook via require
; only index.js
will be read automatically by Sails. Use the dependencies
key of your package.json
to refer to any dependencies that need to be installed in order for your hook to work (you may also use npm install <dependency> --save
to easily save dependency information to package.json
).
In certain cases, especially when using a scoped NPM package to override a core Sails hook, you will want to change the name that Sails uses internally when it loads your hook. You can use the sails.hookName
configuration option in your package.json
file for this. The value should be the name you want to be loaded into the sails.hooks
dictionary, so you generally will not want a sails-hooks-
prefix. For example, if you have a module @mycoolhooks/sails-hook-sockets
that you wish to use to override the core sails-hook-sockets
module, the package.json
might look like:
{
"name": "@mycoolhooks/sails-hook-sockets",
"version": "0.0.0",
"description": "my own sockets hook",
"main": "index.js",
"sails": {
"isHook": true,
"hookName": "sockets"
}
}
Before you distribute your installable hook to others, you’ll want to write some tests for it. This will help ensure compatibility with future Sails versions and significantly reduce hair-pulling and destruction of nearby objects in fits of rage. While a full guide to writing tests is outside the scope of this doc, the following steps should help get you started:
devDependency
in your hook’s package.json
file:"devDependencies": {
"sails": "~0.11.0"
}
npm install sails
or npm link sails
(if you have Sails installed globally on your system).npm install -g mocha
, if you haven’t already.test
folder inside your hook’s main folder.Add a basic.js
file with the following basic test:
var Sails = require('sails').Sails;
describe('Basic tests ::', function() {
// Var to hold a running sails app instance
var sails;
// Before running any tests, attempt to lift Sails
before(function (done) {
// Hook will timeout in 10 seconds
this.timeout(11000);
// Attempt to lift sails
Sails().lift({
hooks: {
// Load the hook
"your-hook-name": require('../'),
// Skip grunt (unless your hook uses it)
"grunt": false
},
log: {level: "error"}
},function (err, _sails) {
if (err) return done(err);
sails = _sails;
return done();
});
});
// After tests are complete, lower Sails
after(function (done) {
// Lower Sails (if it successfully lifted)
if (sails) {
return sails.lower(done);
}
// Otherwise just return
return done();
});
// Test that Sails can lift with the hook in place
it ('sails does not crash', function() {
return true;
});
});
mocha -R spec
to see full results.Assuming your hook is tested and looks good, and assuming that the hook name isn’t already in use by another NPM module, you can share it with world by running npm publish
. Go you!