sails

library1.11.1jsnpmunverified

Sails.js is an MVC-based Node.js web framework designed for building custom, enterprise-grade applications, particularly those requiring real-time features using WebSockets. It aims to provide a Rails-like developer experience but with a data-oriented approach suitable for modern APIs. The current stable version is 1.5.17, with patch releases occurring periodically to address dependencies and minor fixes. Major version updates, like the transition to v1.0, introduced significant breaking changes, prioritizing developer experience over strict backward compatibility. Sails differentiates itself through its convention-over-configuration philosophy, automatic RESTful API generation, integrated ORM (Waterline) with multi-database support, and native Socket.io integration for real-time communication. It also embraced `async/await` syntax from v1.0 onwards, streamlining asynchronous code.

web-framework database http-networking

npm install sails

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SAILS

sails

web-frameworkjavascriptv1.11.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Sails (for programmatic use)

✓ const Sails = require('sails').constructor;

✗ import Sails from 'sails';

For programmatic interaction (e.g., in tests or scripts), instantiate `Sails` using its constructor to avoid singleton issues and to manage multiple app instances. Direct `import` syntax is not natively supported for the core framework in Node.js applications unless a transpiler like Babel is used.

sails (global instance)

✓ const sails = require('sails');

✗ import sails from 'sails';

Within a running Sails application (e.g., in controllers, services, or models), a singleton `sails` instance is automatically available, often globally. `require('sails')` will return this singleton instance. Using `import` directly for `sails` in application code might require Babel or other transpilation for full ESM support.

Model access (e.g., User)

✓ const User = sails.models.user; // Or simply `User` if globals are enabled

✗ import { User } from '../api/models/User';

In a Sails application, models are typically accessed via the global `sails.models` object (e.g., `sails.models.mything`) or, by default, directly as global variables (e.g., `Mything`) if `sails.config.globals.models` is `true`. Direct file imports for models are generally not the idiomatic Sails way.

This quickstart demonstrates how to set up a new Sails.js project using its CLI, generate basic model and controller files, lift the application, and then programmatically interact with the lifted app's models from an external script.

```bash # Install Sails CLI globally npm install sails -g # Create a new Sails project sails new my-sails-app --no-template cd my-sails-app # Generate a simple User model sails generate model User name:string email:string # Generate a UserController sails generate controller User --actions 'find,create' # Lift the Sails application (start the server) sails lift # --- Example of programmatic interaction (after lifting) --- # In a separate script, e.g., `test.js`: # const Sails = require('sails').constructor; # const sailsApp = new Sails(); # # sailsApp.lift({ log: { level: 'warn' } }, async (err) => { # if (err) { # console.error('Error lifting Sails app:', err); # return; # } # console.log('Sails app lifted successfully!'); # # try { # // Access a model and create a record # const User = sailsApp.models.user; // Access the model instance # const newUser = await User.create({ # name: 'Alice Smith', # email: 'alice@example.com' # }).fetch(); # console.log('Created user:', newUser); # # // Find all users # const users = await User.find(); # console.log('All users:', users); # } catch (queryErr) { # console.error('Database query error:', queryErr); # } finally { # sailsApp.lower((lowerErr) => { # if (lowerErr) console.error('Error lowering Sails app:', lowerErr); # else console.log('Sails app lowered.'); # }); # } # }); ```

sails --version

Debug

Known issues

breakingUpgrading to Sails v1.0 from any v0.x version involved significant breaking changes, including changes to configuration (especially datastores), model definitions (e.g., `autoPK` removed), and the results of `.create()`, `.update()`, and `.destroy()` methods. Many core hooks became direct dependencies.

fix

Refer to the official Sails.js upgrade guides (e.g., 'Upgrading to Sails v1.0') and consider using the `sails upgrade` tool. Migrate your application incrementally, addressing database configuration, model attribute definitions, and asynchronous API usage.

affects: <1.0

gotchaWhen programmatically lifting Sails applications, such as for testing, environment variables like `.sailsrc` settings are not automatically applied. Additionally, running multiple Sails app instances in the same process with globals enabled can lead to collisions.

fix

Pass configuration overrides directly to the `.lift()` or `.load()` methods. For `.sailsrc` specific configurations, use `require('sails/accessible/rc')('sails')` and pass them in. Disable unnecessary hooks and globals (`globals: false`) when running multiple instances or in test environments.

affects: >=0.10.0

breakingSails v1.0+ fully embraces `async/await` for asynchronous operations. While traditional `.exec()` with callbacks is still supported, mixing styles or neglecting error handling with promises (`.then().catch()`) can lead to unhandled rejections and instability.

fix

Standardize on `async/await` for all asynchronous model methods and other operations. Ensure proper `try/catch` blocks are used. If using `.then()` chains, always include a `.catch()` to prevent unhandled promise rejections.

affects: >=1.0.0

gotchaFrom v1.3.1, an update to the `machine-as-action` dependency included a reminder about escaping strings with dynamic data when injected into views or responses, indicating a potential XSS vulnerability if not handled correctly.

fix

Always sanitize and escape user-provided or dynamic data before rendering it in views or sending it in HTTP responses to prevent Cross-Site Scripting (XSS) attacks. Utilize templating engine auto-escaping features or specific sanitization libraries.

affects: >=1.3.1

deprecatedThe `sails.services` object, while still accessible, has been superseded by 'helpers' since Sails v1.0. The new 'Actions2' syntax for controllers also streamlines definition and validation.

fix

For new logic, use 'helpers' instead of 'services'. Adopt the 'Actions2' syntax for new controller actions to benefit from automatic parameter validation and clear exit definitions.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot set headers after they are sent to the client

Attempting to send multiple HTTP responses for a single request, often due to improper `res.send()` or `res.json()` usage after another response has already been sent, or due to unhandled errors that implicitly send a default response.

fix

Ensure that each request handler (action, policy, middleware) sends only one response. Use `return` before `res.send()`, `res.json()`, `res.serverError()`, etc., to prevent further code execution after a response has been dispatched. Implement robust error handling.

Error: An app failed to lift. (Usually means a hook threw an error)

A common startup error in Sails, indicating an issue during the application bootstrap or hook initialization phase. This can be due to misconfigured database connections, invalid model definitions, syntax errors in config files, or unhandled exceptions in bootstrap logic.

fix

Check server logs for more specific error messages from individual hooks, models, or configurations. Verify database connection settings in `config/datastores.js` and model definitions for correctness. Review the `config/bootstrap.js` file for any problematic logic. Incrementally comment out hooks or custom logic to isolate the problematic component.

E_UNIQUE: A uniqueness constraint was violated

Attempting to create or update a record with a value for an attribute that has been defined with a `unique: true` constraint, and that value already exists in the database.

fix

Before creating or updating, perform a check to see if a record with the unique value already exists. Handle the `E_UNIQUE` error specifically in `try/catch` blocks or promise `.catch()` handlers, providing appropriate feedback to the user or logic to resolve the conflict.

Upgrade

Version history

1.11.1latest on npm

Audit

Dependencies

expressrequiredCore HTTP server and middleware layer.

socket.iorequiredCore for real-time communication features.

waterlinerequiredThe ORM for database interactions, with a robust adapter system.

noderequiredRuntime environment. Requires Node.js >= 0.10.0, but v1.0+ requires Node.js >= 4.x.

Agent activity

16 hits · last 30 days

node