Edit Page

Creating an Installable Hook

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:

Choose a name for your new hook. It must not conflict with any of the core hook names.
Create a new folder on your system with the name 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.
Create a 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 a 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.
Write your hook code in 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).

Specifying the internal name Sails uses for your hook (advanced)

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

Testing your new hook

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:

Add Sails as a devDependency in your hook’s package.json file:
```
"devDependencies": {
   "sails": "~0.11.0"
}
```
Install Sails as a dependency of your hook with npm install [email protected] or npm link sails (if you have Sails installed globally on your system).
Install Mocha on your system with npm install -g mocha, if you haven’t already.
Add a 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;
     });

 });

Run the test with mocha -R spec to see full results.
See the Mocha docs for a full reference.

Publishing your hook

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!

Is something missing?

If you notice something we've missed or could be improved on, please follow this link and submit a pull request to the sails-docs repo. Once we merge it, the changes will be reflected on the website the next time it is deployed.

Documentation

Concepts

Built with Love

The Sails framework is maintained by a web & mobile studio in Austin, TX, with the help of our contributors. We created Sails in 2012 to assist us on Node.js projects. Naturally we open-sourced it. We hope it makes your life a little bit easier!