@vsaas/loopback-boot

@vsaas/loopback-boot is a fork of loopback-boot focused on keeping LoopBack 3 style bootstrapping working while reducing maintenance overhead.

The goal of this fork is practical compatibility for common upstream use cases, not byte-for-byte preservation of the original package. The internals were intentionally simplified and modernized:

• TypeScript source with build output in dist/
• English-only messages
• no i18n catalogs or strong-globalize
• no browser bundling support
• several legacy dependencies removed or replaced
• modern tooling with tsdown, vitest, and oxlint
• callback-compatible APIs that continue to work with Promise and async/await

Installation

npm install @vsaas/loopback-boot

If you are also using the related forks, pair it with @vsaas/loopback.

Quick start

const loopback = require('@vsaas/loopback');
const boot = require('@vsaas/loopback-boot');

const app = loopback();

boot(app, __dirname, function (err) {
  if (err) throw err;

  app.use(loopback.rest());
  app.listen(3000);
});

Scope

This package still provides the main capabilities existing loopback-boot users expect:

• loading and merging application config files
• datasource, model, mixin, middleware, and component boot phases
• boot script discovery and execution
• compatibility with convention-based LoopBack 3 application layouts

If you are migrating an existing codebase, the intent is that the public API should feel familiar even though the implementation is leaner.

Dynamic Config Values

Boot-time datasource, middleware, component, and model config values can interpolate dynamic placeholders.

• ${NAME} resolves from process.env.NAME first and then app.get('NAME')
• ${file:/run/secrets/name} reads the value from a UTF-8 file, which is useful for Docker secrets and other mounted secret files

This works both for full-string values and inside larger strings such as URLs.

Supported Surface

The supported API for application code is intentionally narrow:

• the main module entrypoint: require("@vsaas/loopback-boot")
• boot(app, options, callback)
• boot.compile(options, callback)
• boot.execute(app, instructions, callback)
• boot.Bootstrapper
• boot.PluginBase

For low-level integrations, the package also exports these documented subpaths:

• @vsaas/loopback-boot/bootstrapper
• @vsaas/loopback-boot/utils

LoopBack 3 application layout conventions are also treated as public compatibility requirements. In particular, boot-time config that references subpaths from @vsaas/loopback such as common/models, server/models, common/mixins, server/mixins, and server/middleware/* is considered supported application-facing behavior.

Not Supported As Stable API

The following are implementation details and may change as the fork evolves:

• imports from src/*, dist/*, or non-exported lib/* files
• cross-package internal calls between workspace packages when they bypass the documented entrypoints above
• browser bundling APIs from upstream loopback-boot
• legacy internal dependency behavior kept only for historical implementation reasons

In other words: the public LoopBack application surface should remain compatible, but internal package-to-package wiring inside this monorepo is free to change when it improves maintainability or correctness.

Notes for Fork Users

• This is a maintained fork, not the upstream package.
• Messages are English-only by design.
• Browser-specific boot bundling APIs were intentionally removed.
• Legacy internals and dependencies were removed where they were easy to replace without changing the public API.
• The test entrypoint is vitest, while the large legacy suite still runs underneath for compatibility.

Development

npm run build
npm run typecheck
npm run lint
npm test

License

MIT. See LICENSE.