Trails.js Web Application Framework

Common errors

• Error: Cannot find module 'trails'

  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.
  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.

• TypeError: TrailsApp is not a constructor

  cause Attempting to use ES Modules `import` syntax (`import TrailsApp from 'trails'`) with the `trails` package, which is primarily a CommonJS module.
  fix Use CommonJS `require` syntax: `const TrailsApp = require('trails')` to correctly import the TrailsApp class.

• ReferenceError: Controller is not defined

  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.
  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')`.

Warnings

• breaking 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.
  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.
• deprecated 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.
  Fix: Remove `trailpack-core` from your dependencies. Its features are now part of the main `trails` package.
• deprecated 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.
  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.
• gotcha 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.
  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.

Install

• npm install trails npm
• yarn add trails yarn
• pnpm add trails pnpm

Imports

• TrailsApp
  wrong:

  import TrailsApp from 'trails'

  correct:

  const TrailsApp = require('trails')

  Trails.js is primarily a CommonJS framework. The main 'trails' package exports the TrailsApp class, which is used to instantiate and bootstrap your application.
• Controller
  wrong:

  class MyController extends Controller { ... }

  correct:

  const { Controller } = require('trails')

  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.
• Service
  wrong:

  class MyService extends Service { ... }

  correct:

  const { Service } = require('trails')

  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.

Quickstart

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.

#!/usr/bin/env sh
# First, install the global tools needed to scaffold a Trails app
npm install -g yo generator-trails

# Create a new Trails project (choose a 'web' or 'api' template)
yo trails my-trails-app
cd my-trails-app

# Example of a simple controller (api/controllers/HelloController.js)
# Note: `Controller` is implicitly available via the framework context.
printf "'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

# Example of adding a route (config/routes.js)
# Add this route to the `module.exports.routes` object in config/routes.js
# {\n#   '/hello': {\n#     handler: 'HelloController.greet',\n#     method: 'GET'\n#   }\n# }

# Now, run your Trails application
node server.js

# Open your browser or use curl to visit http://localhost:3000/hello