ndx-framework

Common errors

• Error: Cannot find module 'coffeescript'

  cause The CoffeeScript compiler, required to run or build the application, is not installed or not accessible in the current environment.
  fix Install CoffeeScript globally or ensure it's a project dependency: `npm install -g coffeescript`.

• 'grunt' is not recognized as an internal or external command, operable program or batch file.

  cause The Grunt CLI (command-line interface) is not installed globally on the system, which is necessary to run development and build tasks.
  fix Install the Grunt CLI globally: `npm install -g grunt-cli`.

• Error: listen EADDRINUSE :::3000

  cause Another process is already occupying the default port (3000) that ndx-framework attempts to use.
  fix Stop the conflicting process, or specify a different port using the `PORT` environment variable (e.g., `PORT=4000 grunt`).

• ReferenceError: ndx is not defined

  cause Attempting to access the `ndx` object before it has been properly initialized or made available within the current scope by the framework.
  fix Ensure your code executes within the framework's lifecycle or, if external, explicitly `const ndx = require('ndx-framework');` and reference the variable.

• Error: [$injector:unpr] Unknown provider: SomeServiceProvider

  cause An AngularJS (Angular 1) service or dependency specified in the frontend application could not be located or injected by the AngularJS injector.
  fix Verify that `SomeService` (or the missing provider) is correctly defined and registered as an AngularJS module, and that all its own dependencies are met.

Warnings

• breaking The framework relies heavily on severely outdated and unmaintained technologies such as AngularJS 1, CoffeeScript, and Grunt. These dependencies are incompatible with modern Node.js versions and pose significant security risks and operational challenges.
  Fix: Migration to a modern, actively maintained framework is strongly recommended. Attempting to run this framework on current Node.js versions will likely result in numerous dependency resolution and runtime errors.
• gotcha ndx-framework uses non-standard languages (CoffeeScript, Pug, Stylus) that require specific build tooling and introduce a learning curve. Modern JavaScript development typically uses plain JavaScript/TypeScript, HTML, and CSS/Sass.
  Fix: Developers must be proficient in CoffeeScript, Pug, and Stylus, or integrate robust build pipelines to transpile these languages to standard web formats.
• gotcha The built-in `ndxdb` database is primarily in-memory. For persistent data storage, it explicitly requires configuration for S3, which introduces external cloud dependency and specific setup.
  Fix: Carefully configure S3 for data persistence, or integrate a different database via `ndx-database-engine` if more traditional persistent storage is needed.
• gotcha The framework's primary interaction model is through its command-line interface (`ndx-framework`) and `grunt` tasks. Direct `node app.js` execution or standard Node.js module loading might bypass critical initialization steps.
  Fix: Always use the provided `ndx-framework` CLI and `grunt` commands for initialization, development, and building to ensure proper environment setup and task execution.
• gotcha Security-related environment variables like `SESSION_SECRET` are critical for encryption and session management. Failing to set a strong, unique secret exposes the application to security vulnerabilities.
  Fix: Always set a long, random, and unique `SESSION_SECRET` in production environments. Understand the implications of `SKIP_IP_ENCRYPT` before disabling token IP encryption.

Install

• npm install ndx-framework npm
• yarn add ndx-framework yarn
• pnpm add ndx-framework pnpm

Imports

• ndx
  wrong:

  import ndx from 'ndx-framework';

  correct:

  const ndx = require('ndx-framework');

  The framework primarily uses CommonJS `require()` syntax. The 'ndx' object is the main entry point for configuration and module management within a scaffolded application.
• serverConfig
  wrong:

  import { config } from 'ndx-server';

  correct:

  const serverConfig = require('ndx-server').config;

  Environment variables are often exposed via `ndx-server`, a core dependency. Direct ES module imports are not supported.
• App

  const app = ndx.createApp();

  After requiring the main 'ndx' object, application instances are typically created via methods exposed on it, like `createApp()` (inferred pattern).

Quickstart

Demonstrates the initial global installation of the ndx-framework CLI, scaffolding a new application, and starting it in development mode with Grunt.

npm install -g ndx-framework
ndx-framework --init
ndx-framework --create --appname=myNdxApp
cd myNdxApp
grunt
# Access your app at http://localhost:3000

# To build for production:
# grunt build