Overrides and customization

Owner: configuration and composition in @bitakit/core; discovery options in bitakit.config.ts.

Choose the smallest existing mechanism for the change:

All discovery options live in bitakit.config.ts and are typed by defineBitaKit.

Override configurationCopy Anchor Link

// bitakit.config.ts
import { defineBitaKit } from '@bitakit/discovery';

export default defineBitaKit({
  configOverrides: {
    todos: { actions: { list: { pageSize: 50 } } },
  },
});

This assumes the todos plugin from configuration. Defaults and overrides resolve before services start. Objects merge; arrays replace; undefined preserves defaults. A duplicate config leaf in two source files is an error, not an override.

Cap availabilityCopy Anchor Link

// bitakit.config.ts
export default defineBitaKit({
  actions: {
    overrides: { 'todos.clear': { enabled: false } },
  },
});

Discovery maps actions.overrides to the runtime's actionOverrides. A false cap wins over any function-valued result; true does not override the action's own guards. Visibility and availability remain UI and execution concerns, not server authorization.

An app does not replace a plugin's action in place. Cap it, add the app's own action, or change the plugin; every caller keeps the original ID.

Turn local plugins on or offCopy Anchor Link

// bitakit.config.ts
export default defineBitaKit({
  plugins: {
    autoEnable: true,
    overrides: { demo: { enabled: false } },
  },
});

Every folder under the plugin directory is a plugin and is enabled by default. autoEnable: false turns off all of them unless an override enables one; overrides sets single plugins by ID. A disabled plugin contributes nothing: no services, actions, pages, slots or settings. To keep a plugin but cap one of its actions, use actions.overrides instead.

Opt out of automatic package loadingCopy Anchor Link

// bitakit.config.ts
export default defineBitaKit({
  packages: { '@bitakit/quick-search': false },
});

packages: false disables all package discovery. Local plugins still use the configured plugin directory. Disabling package discovery removes its generated imports, styles and public types; it does not uninstall the dependency.

Change a service's public nameCopy Anchor Link

// src/plugins/todos/services/clock.ts
import { defineService } from '@bitakit/core';

export default defineService(() => ({ now: () => new Date() }), { exposeAs: 'tools.clock' });

The service keeps its ID todos.clock and gains the alias services.tools.clock; both names mean the same instance in every plugin. Omit exposeAs unless a flat or shared name is deliberate; two services with the same name fail at startup. provides: contract adds a contract alias such as auth instead.

Replace a plugin from the hostCopy Anchor Link

BitaKitProvider accepts additionalPlugins: an entry with an existing ID replaces that plugin in place, a new ID appends. Use it to pass a configured instance of a package plugin instead of its discovered default:

<BitaKitProvider additionalPlugins={[shellPlugin({ navigationSlot: 'shell.navigation' })]}>
  {children}
</BitaKitProvider>

This sets the explicit slot Shell renders. To use a different name, declare that Action slot and place the intended Actions there. Keep the array stable across renders. The lower-level plugins prop still means replacement, not append. Persisting settings on a server needs no replaced plugin: one service with provides: settingsStorage fulfils the settings.storage contract for every plugin's settings.

Understand replacement versus additionCopy Anchor Link

For the provider's actions, plugins, interceptors and providers props, omission inherits the generated selection, an explicit array replaces that selection and [] selects none. An explicit actions list replaces declarative actions, including plugin actions; those plugins' services and setup still run. These are host composition options, not a second plugin lifecycle.