{"id":12161,"library":"trails","title":"Trails.js Web Application Framework","description":"Trails.js is a modern, community-driven web application framework for Node.js, currently at version 3.2.2. It emphasizes a convention-based, API-driven design philosophy, inspired by frameworks like Ruby on Rails and Grails. Trails.js accelerates development through scaffolding provided by Yeoman and extends its capabilities via 'Trailpacks'—modular extensions that integrate existing ecosystem tools like Hapi, Express, Waterline, or Knex. The framework supports microservices architectures and is designed to work across Windows, Mac, and Linux, requiring Node.js 7.6.0 or newer. Its release cadence is stable, with major version updates occurring less frequently, focusing on stability and core enhancements.","status":"active","version":"3.2.2","language":"javascript","source_language":"en","source_url":"https://github.com/trailsjs/trails","tags":["javascript","framework","platform","microservices","ecosystem","rest","api","rails","grails"],"install":[{"cmd":"npm install trails","lang":"bash","label":"npm"},{"cmd":"yarn add trails","lang":"bash","label":"yarn"},{"cmd":"pnpm add trails","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Trails.js is primarily a CommonJS framework. The main 'trails' package exports the TrailsApp class, which is used to instantiate and bootstrap your application.","wrong":"import TrailsApp from 'trails'","symbol":"TrailsApp","correct":"const TrailsApp = require('trails')"},{"note":"While Trails v2.0+ made core classes like Controller globally available within the framework's runtime context, explicitly requiring them offers better clarity, IDE support, and ensures compatibility in environments where globals might not be reliably accessible.","wrong":"class MyController extends Controller { ... }","symbol":"Controller","correct":"const { Controller } = require('trails')"},{"note":"Similar to Controller, the Service base class for creating application services is best imported explicitly using CommonJS `require` for improved code readability and maintainability, despite potential global availability.","wrong":"class MyService extends Service { ... }","symbol":"Service","correct":"const { Service } = require('trails')"}],"quickstart":{"code":"#!/usr/bin/env sh\n# First, install the global tools needed to scaffold a Trails app\nnpm install -g yo generator-trails\n\n# Create a new Trails project (choose a 'web' or 'api' template)\nyo trails my-trails-app\ncd my-trails-app\n\n# Example of a simple controller (api/controllers/HelloController.js)\n# Note: `Controller` is implicitly available via the framework context.\nprintf \"'use strict'\\n\\nmodule.exports = class HelloController extends Controller {\\n  greet (request, reply) {\\n    reply.send('Hello from Trails.js!')\\n  }\\n}\" > api/controllers/HelloController.js\n\n# Example of adding a route (config/routes.js)\n# Add this route to the `module.exports.routes` object in config/routes.js\n# {\\n#   '/hello': {\\n#     handler: 'HelloController.greet',\\n#     method: 'GET'\\n#   }\\n# }\n\n# Now, run your Trails application\nnode server.js\n\n# Open your browser or use curl to visit http://localhost:3000/hello","lang":"javascript","description":"This quickstart demonstrates how to scaffold a new Trails.js application using Yeoman, create a basic controller, define a route, and start the server to serve a simple 'Hello World' response."},"warnings":[{"fix":"Ensure your application code accounts for these classes potentially being global, or explicitly import them using `require('trails').ClassName` for better control and clarity.","message":"With Trails v2.0, built-in Trails `Error` objects and resource classes (`Model`, `Controller`, `Service`, `Policy`) became globally accessible within the framework context. This changed how these core components were managed and accessed.","severity":"breaking","affected_versions":">=2.0"},{"fix":"Remove `trailpack-core` from your dependencies. Its features are now part of the main `trails` package.","message":"The `trailpack-core` module was deprecated in v2.0, with its functionality merged directly into the Trails core. Installing `trailpack-core@2.0` results in a no-op.","severity":"deprecated","affected_versions":">=2.0"},{"fix":"Discontinue use of these individual packages. The functionality is now available directly through the main `trails` package, often via `require('trails').ClassName` or implicitly within the framework's runtime.","message":"Individual modules like `trails-model`, `trails-service`, `trails-policy`, and `trails-controller` were merged into Trails core in v2.0 and deprecated as standalone packages.","severity":"deprecated","affected_versions":">=2.0"},{"fix":"Upgrade your Node.js environment to version 7.6.0 or newer. Use a tool like `nvm` (Node Version Manager) to easily manage multiple Node.js versions.","message":"Trails.js requires Node.js version 7.6.0 or higher. Running with older Node.js versions will lead to syntax errors or unexpected behavior due to unsupported language features.","severity":"gotcha","affected_versions":"<7.6.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `trails` is listed in your project's `package.json` and run `npm install`, or, for a new project, use `npm install -g yo generator-trails` followed by `yo trails` to scaffold an application.","cause":"The `trails` package is not installed as a dependency in your project or the global `npm install -g trails` was not followed by `yo trails` to generate an application.","error":"Error: Cannot find module 'trails'"},{"fix":"Use CommonJS `require` syntax: `const TrailsApp = require('trails')` to correctly import the TrailsApp class.","cause":"Attempting to use ES Modules `import` syntax (`import TrailsApp from 'trails'`) with the `trails` package, which is primarily a CommonJS module.","error":"TypeError: TrailsApp is not a constructor"},{"fix":"Ensure your controller file is located in the `api/controllers` directory of your Trails.js application. If using outside the framework's discovery mechanism, explicitly import `const { Controller } = require('trails')`.","cause":"This error typically occurs when a custom controller file extends `Controller` but is either not being loaded by the Trails.js framework or the `Controller` base class is not explicitly imported in a non-framework context.","error":"ReferenceError: Controller is not defined"}],"ecosystem":"npm"}