LoopBack 3.x Framework

Common errors

• Error: Cannot find module 'loopback-datasource-juggler'

  cause The core `loopback-datasource-juggler` package is missing from your project's `node_modules`.
  fix Install it explicitly: `npm install loopback-datasource-juggler` or ensure it's in your `package.json` dependencies and run `npm install`.

• TypeError: app.boot is not a function

  cause You are attempting to call `app.boot` directly, but `boot` is a function exported by the separate `loopback-boot` package, not a method on the `loopback` app object.
  fix Ensure `loopback-boot` is installed (`npm install loopback-boot`) and then require and use it: `const boot = require('loopback-boot'); boot(app, __dirname, callback);`

• Access to XMLHttpRequest at 'http://localhost:3000/api/models' from origin 'http://localhost:4200' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause Cross-Origin Resource Sharing (CORS) is not properly configured or enabled on your LoopBack API server, preventing requests from different origins.
  fix Enable CORS middleware in your `server.js` or `middleware.json` by adding `app.use(loopback.cors());` or configuring it in `middleware.json`.

Warnings

• deprecated LoopBack 3.x is in Maintenance LTS mode and has passed its End-Of-Life (EOL) date in December 2020. It receives only critical bug fixes and security patches. New feature development and active support have ceased.
  Fix: Plan and execute migration of applications to LoopBack 4, which is the current and actively developed version of the framework. Refer to the official migration guide at `loopback.io/doc/en/lb4/migration-overview.html`.
• breaking The `loopback-datasource-juggler` package, which is core to LoopBack's data handling, was moved from `peerDependencies` to `dependencies` in LoopBack 3.0. This might affect existing project setups that relied on `peerDependencies` behavior.
  Fix: Ensure `loopback-datasource-juggler` is correctly listed as a direct dependency in your `package.json` and installed via `npm install` or `yarn add`.
• breaking Major breaking changes exist between LoopBack 2.x and 3.0. These include API changes, configuration updates, and dependency shifts requiring careful migration.
  Fix: Thoroughly review the LoopBack 3.0 Release Notes and Migration Guide at `loopback.io/doc/en/lb3/3.0-Release-Notes.html` and `loopback.io/doc/en/lb3/Migrating-to-3.0.html` before upgrading.
• gotcha Older versions of LoopBack 3.x had a bug in `User.prototype.verify` that incorrectly concatenated query-string components, potentially leading to malformed verification links or unexpected redirect behavior.
  Fix: Upgrade to the latest available patch version of LoopBack 3.x (e.g., 3.28.1 or higher) to ensure `querystring.stringify` is correctly used for link generation.

Install

• npm install loopback npm
• yarn add loopback yarn
• pnpm add loopback pnpm

Imports

• loopback
  wrong:

  import loopback from 'loopback';

  correct:

  const loopback = require('loopback');

  LoopBack 3.x primarily uses CommonJS module syntax due to its release era. The 'loopback' object is the primary entry point for the framework.
• app.Model
  wrong:

  import { Model } from 'loopback';

  correct:

  const MyModel = loopback.Model.extend('MyModel', { /* ... */ });

  The base Model class is accessed as a property of the main `loopback` application object, not as a direct named export.
• app.boot
  wrong:

  loopback.boot(app, __dirname);

  correct:

  const boot = require('loopback-boot');
  boot(app, __dirname, function(err) { /* ... */ });

  Application bootstrapping is handled by the separate `loopback-boot` package, which takes the main `loopback` app instance as an argument.

Quickstart

This quickstart initializes a basic LoopBack 3.x application, sets up the server to listen on a port, and defines a simple root endpoint. It demonstrates the fundamental structure of a LoopBack 3 `server.js` file, using `loopback` and `loopback-boot` to start the application.

const loopback = require('loopback');
const boot = require('loopback-boot');
const path = require('path');

const app = module.exports = loopback();

app.start = function() {
  // Start the web server
  return app.listen(function() {
    app.emit('started');
    const baseUrl = app.get('url').replace(/\/$/, '');
    console.log('Web server listening at: %s', baseUrl);
    if (app.get('loopback-component-explorer')) {
      const explorerPath = app.get('loopback-component-explorer').mountPath;
      console.log('Browse your REST API at %s%s', baseUrl, explorerPath);
    }
  });
};

// Bootstrap the application (configures models, datasources, middleware)
boot(app, __dirname, function(err) {
  if (err) throw err;

  // Start the server if `$ node server.js` is run directly
  if (require.main === module) {
    app.start();
  }
});

// Example: Define a simple root endpoint
app.get('/', (req, res) => {
  res.send('LoopBack 3.x application is running!');
});