Sails.js

Sails.js is an API-driven framework for building realtime Node.js web applications using MVC conventions. Built on top of Express.js and Socket.io, Sails provides a robust foundation for creating scalable web APIs and full-stack applications with automatic REST API generation, real-time communication, and a flexible hook system.

Package Information

Package Name: sails
Version: 1.5.15
License: MIT
Homepage: https://sailsjs.com

Node.js Support: >= 0.10.0
NPM Support: >= 1.4.0

Installation:

npm install sails -g

Core Imports

CommonJS (Default)

// Get the singleton Sails instance
const sails = require('sails');

// Get the Sails constructor for creating new instances
const Sails = require('sails').Sails;
// or
const Sails = require('sails').constructor;

// Create a new app instance
const app = new Sails();

ESM (ES6 Modules)

import sails from 'sails';
import { Sails } from 'sails';

// Create new instance
const app = new Sails();

Basic Usage

Creating and Starting a Sails Application

const sails = require('sails');

// Lift the Sails application
sails.lift({
  port: 3000,
  environment: 'development'
}, (err) => {
  if (err) throw err;
  console.log('Sails app lifted successfully!');
});

Basic Route Definition

const sails = require('sails');

// Define routes programmatically
sails.get('/hello', (req, res) => {
  return res.json({ message: 'Hello, World!' });
});

sails.post('/users', 'UserController.create');

// Lift the application
sails.lift();

Architecture

Sails.js follows a modular architecture built around several key components:

Core Components

• Application Lifecycle: Methods for starting, stopping, and managing the app lifecycle
• HTTP Router: Flexible routing system supporting REST conventions and custom routes
• Actions System: Controller actions and standalone action functions
• Hook System: 18+ built-in hooks providing core functionality (HTTP, sessions, security, etc.)
• Configuration: Unified configuration system with environment-specific settings
• CLI Tools: 16+ command-line tools for development and deployment

MVC Pattern

• Models: Data layer with ORM integration (typically Waterline)
• Views: Template rendering with multiple engine support
• Controllers: Request handling and business logic

Extension Points

• Custom Hooks: Extend Sails functionality through the hook system
• Services: Global utility functions and business logic
• Policies: Middleware for authorization and request preprocessing
• Helpers: Reusable utility functions with machine-based interfaces

Application Lifecycle

The Sails application lifecycle is managed through core methods that handle startup, shutdown, and configuration:

// Lift (start) the application
sails.lift(configOverride?: Dictionary, done?: Function): Sails

// Lower (stop) the application  
sails.lower(options?: {delay?: Number, hardShutdown?: Boolean}, cb?: Function): void

// Load app without starting servers (internal)
sails.load(configOverride?: Dictionary, cb?: Function): void

Key Features:

• Graceful startup and shutdown sequences
• Configuration override support
• Event-driven lifecycle with 'lifted' and 'lower' events
• Child process management and cleanup

Application Lifecycle

HTTP Routing

Sails provides a powerful routing system that supports both programmatic and configuration-based route definitions:

// HTTP method routing
sails.get(path: String, action: String|Function): Sails
sails.post(path: String, action: String|Function): Sails
sails.put(path: String, action: String|Function): Sails  
sails.delete(path: String, action: String|Function): Sails
sails.all(path: String, action: String|Function): Sails

// Router instance methods
sails.router.bind(path: String|RegExp, bindTo: String|Object|Function, verb?: String, options?: Dictionary): void
sails.router.flush(routes?: Dictionary): void
sails.router.reset(): void

Key Features:

• RESTful routing conventions
• Route parameter extraction and validation
• Middleware chaining and policies
• Blueprint route auto-generation

HTTP Routing

Actions System

Sails uses a flexible action system for handling requests, supporting both traditional controller methods and standalone action functions:

// Action management
sails.registerAction(action: Function|Dictionary, identity: String, force?: Boolean): void
sails.getActions(): Dictionary
sails.reloadActions(cb?: Function): void

// Route discovery
sails.getRouteFor(target: String|Dictionary): {url: String, method: String}  
sails.getUrlFor(target: String|Dictionary): String

Key Features:

• Machine-compatible action definitions
• Dynamic action registration and reloading
• Route-to-action mapping and discovery
• Input validation and output formatting

Actions System

Built-in Hooks

Sails includes 18+ built-in hooks that provide core framework functionality:

// Hook lifecycle (for custom hooks)
Hook.defaults(): Dictionary
Hook.configure(): void  
Hook.loadModules(cb: Function): void
Hook.initialize(cb: Function): void

Core Hooks:

• HTTP: Server management and middleware
• Blueprints: Automatic REST API generation
• Security: CORS and CSRF protection
• Session: Session management and stores
• Views: Template engine integration
• Logger: Logging system setup
• Services: Service auto-loading
• Policies: Policy enforcement
• I18n: Internationalization support

Built-in Hooks

Configuration System

Sails provides a unified configuration system that merges settings from multiple sources:

// Configuration access
sails.getRc(namespace?: String): Dictionary
sails.config: Dictionary

Configuration Sources (in order of precedence):

1. Command-line arguments
2. Environment variables (SAILS_*)
3. Local .sailsrc files
4. Global .sailsrc files
5. Default configuration

Key Features:

• Environment-specific configuration
• Configuration validation and normalization
• Runtime configuration access

Configuration

CLI Commands

Sails provides a comprehensive set of command-line tools for development and deployment:

# Core commands
sails new [path]           # Create new Sails application
sails lift                 # Start the application  
sails generate [type]      # Generate code components
sails console             # Interactive REPL with app context

# Development commands  
sails debug               # Start with debugger (Node v5-)
sails inspect             # Start with inspector (Node v6+)
sails run [script]        # Run custom scripts

# Utility commands
sails test                # Run tests
sails www                 # Compile assets to www folder
sails upgrade             # Upgrade Sails application  
sails deploy              # Deploy application

CLI Commands

Events System

Sails inherits from EventEmitter and provides a rich event system for lifecycle management:

// Core lifecycle events
sails.on('lifted', callback)      // App successfully started
sails.on('lower', callback)       // App shutdown initiated  
sails.on('ready', callback)       // App ready (internal)

// Router events
sails.on('router:before', callback)  // Before route binding
sails.on('router:after', callback)   // After route binding
sails.on('router:reset', callback)   // Router reset

Key Features:

• Lifecycle event hooks
• Router event notifications
• Custom event support
• Hook-level event handling

Events System

Request Simulation

Sails provides built-in request simulation for testing and development:

// Virtual request simulation
sails.request(opts: {url: String, method?: String, params?: Dictionary, headers?: Dictionary}, cb?: Function): MockClientResponse
sails.request(address: String, params?: Dictionary, cb?: Function): MockClientResponse

Use Cases:

• Unit and integration testing
• Development without HTTP server binding
• Internal service communication

Key Constants and Utilities

// Asset detection pattern
sails.LOOKS_LIKE_ASSET_RX: RegExp  // /^[^?]*\/[^?\/]+\.[^?\/]+(\?.*)?$/

// Utility methods for debugging and serialization
sails.inspect(): String  // Custom inspection output for console.log/util.inspect
sails.toString(): String  // String representation of Sails app instance
sails.toJSON(): Dictionary  // JSON-serializable summary of the app instance

// Development validation methods
sails.isLocalSailsValid(sailsPath: String, appPath: String): Boolean  // Check if local Sails installation is valid
sails.isSailsAppSync(appPath: String): Boolean  // Check if directory contains a valid Sails app

Getting Started

1. Install Sails globally: npm install -g sails
2. Create new app: sails new my-app
3. Navigate to app: cd my-app
4. Lift the app: sails lift
5. Visit: http://localhost:1337

For detailed API documentation, configuration options, and advanced usage patterns, refer to the comprehensive sub-documentation linked above.