API conventions and runtime boundaries

Package modules#

The packages use native ES modules and publish JavaScript plus TypeScript declarations under dist/. Import from the documented package entry points rather than internal source paths such as @veap/database/src/model.

Server and client entry points#

Several packages intentionally split server and client APIs:

• @veap/auth/server exposes server-oriented auth APIs and crypto helpers.
• @veap/auth/client exposes React context and hooks.
• @veap/intl/server exposes request-aware locale detection, message loading, the server provider and translation getter.
• @veap/intl/client exposes client React hooks and the client provider.
• @veap/plugins/server exposes server actions, registry, router and server-rendered widgets.
• @veap/plugins/client exposes client widget/extension components.
• @veap/plugins/router exposes route-tree utilities.
• @veap/database/migrations and /relations expose specialized database modules.

Use server entry points only in server code. Keep @veap/database, filesystem storage and secret-bearing auth/mail services out of Client Components.

Global state#

The inspected kernel container and several services are attached to globalThis to survive repeated module evaluation/HMR. This is convenient in a long-lived Node.js process, but it is not the same as request-scoped dependency injection. Do not put per-user state into singleton services or assume separate requests have separate containers.

Configuration patterns#

• ApplicationBuilder.use() registers a provider class, provider instance, or factory callback.
• register() should register bindings; boot() runs after all providers have registered.
• Providers may initialize external resources in boot() and should release persistent resources in shutdown().
• A package may augment the ApplicationBuilder interface with convenience methods such as withMail(), withSettings() or withPlugins() when its composition module is imported. The base kernel by itself does not define every package-specific method.

Version discipline#

The package ecosystem is pre-1.0 in the inspected source snapshot. Pin compatible versions, use a lockfile, and verify type declarations before relying on any API outside the examples in this documentation.