Total.js Framework

Common errors

• Error: Cannot find module 'total.js'

  cause The `total.js` package is not installed in the project's `node_modules` or globally, or Node.js cannot resolve its path.
  fix Ensure `total.js` is installed locally in your project: `npm install total.js` or globally if using its CLI tools: `npm install -g total.js`. Also, verify your `index.js` or `app.js` file is in the correct location or the `require` path is accurate.

• TypeError: ROUTE is not a function

  cause The Total.js framework was not properly initialized before `ROUTE` (or other globals like `F`, `CONTROLLER`) was called, meaning these global functions are not yet exposed.
  fix Ensure `require('total.js')();` or `require('total.js').http('debug');` is called at the very beginning of your main application entry file (`app.js` or `index.js`), before any routes or controllers are defined. The framework needs to bootstrap itself to expose its globals.

• Error: Image command 'convert' not found or not installed.

  cause The underlying image processing library (GraphicsMagick or ImageMagick) required by Total.js's image handling features is not installed on the system path.
  fix Install GraphicsMagick or ImageMagick on your operating system. For Debian/Ubuntu, use `sudo apt-get install graphicsmagick` or `sudo apt-get install imagemagick`. For other OS, refer to their respective package managers or installation guides.

Warnings

• breaking Total.js v4 and v5 are separate NPM packages (`total4` and `total5`) and are not directly backward compatible with Total.js v3. Upgrading requires migration, although some functionality is maintained.
  Fix: For new projects, consider `total4` or `total5` for modern Node.js features and ongoing development. For existing v3 projects, stick to `total.js` and be aware of the `total.js` v3 documentation. Migrating to v4/v5 involves installing `total4`/`total5` and adapting to changes in routing, NoSQL, and potentially other core components.
• gotcha Total.js heavily relies on global functions and objects (e.g., `ROUTE`, `CONTROLLER`, `F`, `SCHEMA`, `U`) once the framework is initialized. This differs significantly from module-based Node.js development and can lead to potential global namespace pollution or confusion for developers accustomed to explicit ES Modules imports.
  Fix: Familiarize yourself with the Total.js documentation regarding its global API and recommended project structure. Adhere to the framework's conventions for defining routes, controllers, and other components rather than attempting to `import` these globals.
• gotcha The framework expects a specific directory structure (e.g., `controllers`, `views`, `schemas`, `public`) for automatic loading of application components. Deviating from this structure without explicit configuration can lead to modules not being found or processed.
  Fix: Always follow the recommended Total.js project structure for clarity and automatic component discovery. If a custom structure is necessary, consult the documentation for manual configuration options for controllers, views, and other elements.
• gotcha Image processing features rely on external system dependencies like GraphicsMagick or ImageMagick, which are not installed via NPM. These must be installed manually on the server where the Total.js application runs.
  Fix: Ensure GraphicsMagick or ImageMagick are installed and configured correctly on your server's operating system (e.g., `sudo apt-get install graphicsmagick` on Debian/Ubuntu, or using a package manager for other OS). Check Total.js documentation for specific requirements and troubleshooting.
• deprecated Total.js v3 is a CommonJS-first framework. While Node.js increasingly supports ES Modules (ESM), Total.js v3's internal architecture and public API are designed around CommonJS `require()` and globals. Direct `import` statements for core Total.js functionalities will not work without transpilation or specific Node.js configuration for hybrid modules, which is generally not the intended usage for v3.
  Fix: Continue using CommonJS `require()` for the Total.js framework itself. For application-specific modules within a Total.js v3 project, use `require()` for consistency. If you need ESM, consider migrating to Total.js v4 or v5, which may offer better ESM compatibility, or use a build tool like Webpack/Rollup if you need to transpile ESM to CJS for your application code.

Install

• npm install total.js npm
• yarn add total.js yarn
• pnpm add total.js pnpm

Imports

• total.js
  wrong:

  import { F } from 'total.js';

  correct:

  const F = require('total.js');
  // or just:
  require('total.js');

  Total.js v3 is a CommonJS module. It's typically `require`d in the main application file (e.g., `index.js` or `app.js`) to initialize the framework. It often exposes global functions and objects (like `F`, `ROUTE`, `CONTROLLER`, `SCHEMA`) after initialization, making explicit imports for most features unnecessary within application logic files.
• ROUTE
  wrong:

  import { ROUTE } from 'total.js'; ROUTE('GET /', ...);

  correct:

  ROUTE('GET /', function() { /* ... */ });

  ROUTE is a global function exposed by the Total.js framework for defining HTTP routes. It is not imported directly but is available in the global scope once the framework is initialized.
• F
  wrong:

  import { F } from 'total.js';

  correct:

  F.on('ready', () => console.log('Total.js is ready!'));

  F is a global object representing the Total.js framework instance, providing access to various utilities, configurations, and core functionalities. Like ROUTE, it's globally available after framework initialization.

Quickstart

This quickstart demonstrates how to initialize the Total.js framework, start a basic HTTP server, and define two simple GET routes that respond with plain text and JSON respectively, using the global `ROUTE` function and `framework.http()` method.

const framework = require('total.js');

// Start the framework in debug mode
// In a typical Total.js setup, this would be in your main application file (e.g., app.js or index.js)
// and the framework automatically scans for controllers, views, etc.
// For a simple standalone script, you can explicitly call .http() or .https().

// To run a full Total.js application, you'd usually have a directory structure
// with 'controllers', 'views', 'schemas', etc., and then start it with:
// require('total.js').http('debug');

// For this quickstart, we'll demonstrate a simple route definition directly:

// Define a simple GET route
ROUTE('GET /', function() {
    // 'this' inside a route handler refers to the Controller instance
    this.plain('Hello from Total.js!');
});

ROUTE('GET /api/data', function() {
    this.json({
        message: 'This is some data from Total.js API',
        timestamp: new Date()
    });
});

// Listen on HTTP port 8000 (default for debug mode)
framework.http('debug', { port: 8000 });

console.log('Total.js application running in debug mode on http://127.0.0.1:8000');