Registry / web-framework / total.js

total.js

JSON →
library3.4.13jsnpmunverified

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.

web-frameworkdatabasehttp-networkingcommunicationdata
npm install total.js
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · TOTAL.JS
T
total.js
web-frameworkjavascriptv3.4.13
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.

total.js
✓ const F = require('total.js'); // or just: require('total.js');
✗ import { F } from '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
✓ ROUTE('GET /', function() { /* ... */ });
✗ import { ROUTE } from 'total.js'; ROUTE('GET /', ...);
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
✓ F.on('ready', () => console.log('Total.js is ready!'));
✗ import { F } from 'total.js';
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.

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');
Debug
Known issues
breakingTotal.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.
affects: >=3.x
gotchaTotal.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.
affects: >=3.0.0
gotchaThe 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.
affects: >=3.0.0
gotchaImage 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.
affects: >=3.0.0
deprecatedTotal.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.
affects: <4.0.0
Errors
Common errors & fixes
Error: Cannot find module 'total.js'
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
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.
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.
Upgrade
Version history
3.4.13latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
OpenAI (training)
1
Resources
githubhttps://github.com/totaljs/framework ↗
packagehttps://www.npmjs.com/package/total.js ↗
homepagehttps://www.totaljs.com ↗
total.js — npm install total.js · libregistry