BitaKit Core
Framework-independent plugins, services, Actions, events, settings and lifecycle management. Core works in Node.js and the browser without React or a router. React bindings, discovery, visual plugins and provider integrations are separate packages.
Install
npm install @bitakit/core
For a new application, npx @bitakit/create-app my-app connects the packages for you
(Node.js 24 or newer). The handbook describes the 0.2 API in this checkout; use matching
package versions or the local package workflow
when trying unpublished changes.
Start with one service
In a discovery-enabled app, create src/plugins/counter/services/value.ts:
import { defineService } from '@bitakit/core';
export default defineService(({ store }) => {
const state = store({ count: 0 });
return { state, increment: () => state.set((s) => ({ count: s.count + 1 })) };
});
Discovery names it counter.value. Continue with the
Counter learning path
to add an Action and a page. Installing Core alone does not scan folders or render UI.
For a headless program, follow manual composition.
Developer handbook
The handbook is maintained once in the documentation website's source. The links below
resolve within a repository checkout and follow the branch viewed on GitHub. Run
npm run dev:docs from the repository root to read the rendered handbook at
http://localhost:3002/docs. A public documentation address is not configured yet.
| Topic | Guide |
|---|---|
| Services and cleanup | Service reference |
| Actions and React bindings | Action reference |
| Events and interception | Events, Interceptors |
| Files and developer configuration | Discovery, Configuration |
| Extension points and preferences | Slots, Settings |
| Runtime updates and diagnostics | Runtime management |
| Enable, disable, add and remove plugins | Plugin manager |
| Activate a trusted package catalog | Package manager |
| Authentication contract | Client authentication |
| Test a plugin folder | Testing |
| Standalone example | To-do walkthrough; runnable JavaScript files in examples/ |
Plugins are trusted application code. Core is not a sandbox, package installer or remote marketplace. Services own state and resources; the host owns routing, persistence providers and server authorization.
Metadata and provenance
src/metadata.ts owns the pure public-field projection shared by build tools and runtime.
projectPluginMetadataSources accepts ordered { value, location } sources so tools can name
actual diagnostic sources without changing the field validators. Included folder provenance
bindings preserve existing plugin metadata before package fallbacks.
src/inspection/plugin-origin.ts binds host evidence to definitions and projects membership
and groups; src/inspection/inventory.ts supplies serializable static/live inspection.
See the identity and metadata reference.
License
MIT. Third-party dependencies retain their own licenses.
Complete cohort replacement
Host-only runtime.plugins.replace(ids, nextPlugins, { expectedRevision?, preserve? }) validates
an entire proposed composition before stopping any old owner. plugins.preview({ operation: 'replace', ids, plugins, ...options }) uses the same planner. Supply every owned descendant;
external dependents and outside ID collisions are refused. Empty old/new sets support addition
or removal. Providers, foundational services and other composition restrictions still return
restart-required. Cleanup is awaited; failed cleanup blocks reuse. A startup failure can leave
candidate definitions installed with failed lifecycle state; this API does not silently roll
back. Optional @bitakit/packages coordinates artifact recovery. Core never downloads or
persists code, and reconcilePlugins retains its existing narrower compatibility contract.