{"id":12157,"library":"total.js","title":"Total.js Framework","description":"Total.js is a full-stack, open-source Node.js framework designed for creating web applications, REST services, real-time applications, and IoT solutions. Written in pure JavaScript without external dependencies (beyond optional database connectors or specific modules), it aims for high performance and clean architecture, similar to MVC frameworks like Laravel or Django. The framework emphasizes backward compatibility, with version 3 (3.4.13 being a recent patch) receiving frequent updates and bug fixes. It includes a built-in web server, static file handling, powerful routing, an embedded NoSQL database (TextDB), image processing via GraphicsMagick or ImageMagick, WebSockets, a custom view engine, and a schema system for data validation and workflows. Total.js differentiates itself by providing a comprehensive, independent platform often used with its ecosystem of tools like Total.js Code Editor and CMS. While Total.js v3 is actively maintained, the project has transitioned to newer major versions (v4, `total4` on npm, and v5, `total5` on npm), which introduce significant architectural changes and target newer Node.js versions, although v3 continues to be supported for existing projects.","status":"maintenance","version":"3.4.13","language":"javascript","source_language":"en","source_url":"https://github.com/totaljs/framework","tags":["javascript","total","iot","framework","web","websocket","mvc","controller","view"],"install":[{"cmd":"npm install total.js","lang":"bash","label":"npm"},{"cmd":"yarn add total.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add total.js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { F } from 'total.js';","symbol":"total.js","correct":"const F = require('total.js');\n// or just:\nrequire('total.js');"},{"note":"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.","wrong":"import { ROUTE } from 'total.js'; ROUTE('GET /', ...);","symbol":"ROUTE","correct":"ROUTE('GET /', function() { /* ... */ });"},{"note":"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.","wrong":"import { F } from 'total.js';","symbol":"F","correct":"F.on('ready', () => console.log('Total.js is ready!'));"}],"quickstart":{"code":"const framework = require('total.js');\n\n// Start the framework in debug mode\n// In a typical Total.js setup, this would be in your main application file (e.g., app.js or index.js)\n// and the framework automatically scans for controllers, views, etc.\n// For a simple standalone script, you can explicitly call .http() or .https().\n\n// To run a full Total.js application, you'd usually have a directory structure\n// with 'controllers', 'views', 'schemas', etc., and then start it with:\n// require('total.js').http('debug');\n\n// For this quickstart, we'll demonstrate a simple route definition directly:\n\n// Define a simple GET route\nROUTE('GET /', function() {\n    // 'this' inside a route handler refers to the Controller instance\n    this.plain('Hello from Total.js!');\n});\n\nROUTE('GET /api/data', function() {\n    this.json({\n        message: 'This is some data from Total.js API',\n        timestamp: new Date()\n    });\n});\n\n// Listen on HTTP port 8000 (default for debug mode)\nframework.http('debug', { port: 8000 });\n\nconsole.log('Total.js application running in debug mode on http://127.0.0.1:8000');","lang":"javascript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":"<4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The `total.js` package is not installed in the project's `node_modules` or globally, or Node.js cannot resolve its path.","error":"Error: Cannot find module 'total.js'"},{"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.","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.","error":"TypeError: ROUTE is not a function"},{"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.","cause":"The underlying image processing library (GraphicsMagick or ImageMagick) required by Total.js's image handling features is not installed on the system path.","error":"Error: Image command 'convert' not found or not installed."}],"ecosystem":"npm"}