@bitakit/core 0.1.1 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +89 -40
- package/assets/bitakit-banner.png +0 -0
- package/assets/bitakit-logo-dark.svg +11 -0
- package/assets/bitakit-logo.svg +11 -0
- package/docs/reference.md +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,27 +1,74 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/assets/bitakit-banner.png" alt="BitaKit — Your app. Your building blocks. An AI-friendly composition layer for modern applications." width="1024">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# BitaKit Core
|
|
2
6
|
|
|
3
|
-
**
|
|
7
|
+
**Build bigger apps from smaller, pluggable features — together with your team and AI.**
|
|
8
|
+
|
|
9
|
+
BitaKit gives **developers and AI coding assistants a shared structure** for building
|
|
10
|
+
applications. Organize a feature into a plugin, put reusable behavior in services,
|
|
11
|
+
and expose operations through actions. Each piece has a clear home, a clear role,
|
|
12
|
+
and typed connections to the rest of your app.
|
|
13
|
+
|
|
14
|
+
**Keep Next.js, TanStack Start, or your own stack.** BitaKit adds feature organization
|
|
15
|
+
and shared lifecycle management alongside your framework. You keep control of your
|
|
16
|
+
routes, UI, business rules, and data.
|
|
17
|
+
|
|
18
|
+
## Contents
|
|
19
|
+
|
|
20
|
+
- [Install](#install)
|
|
21
|
+
- [Why add BitaKit?](#why-add-bitakit)
|
|
22
|
+
- [How the pieces fit](#how-the-pieces-fit)
|
|
23
|
+
- [Try a To-do plugin](#try-a-to-do-plugin)
|
|
24
|
+
- [Type safety that follows your feature](#type-safety-that-follows-your-feature)
|
|
25
|
+
- [React to events](#react-to-events)
|
|
26
|
+
- [What belongs outside Core?](#what-belongs-outside-core)
|
|
27
|
+
- [Go deeper](#go-deeper)
|
|
28
|
+
- [License](#license)
|
|
29
|
+
|
|
30
|
+
## Install
|
|
4
31
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
32
|
+
```sh
|
|
33
|
+
npm install @bitakit/core
|
|
34
|
+
```
|
|
8
35
|
|
|
9
|
-
|
|
10
|
-
Start, not a replacement for them. Its explicit plugin, service, and action
|
|
11
|
-
conventions give people and AI coding assistants a shared structure to work with.
|
|
36
|
+
Core works in **Node.js and the browser**, without React or a router.
|
|
12
37
|
|
|
13
|
-
|
|
38
|
+
Starting a new application? Let the generator connect the packages for you:
|
|
14
39
|
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
- **Names beside implementations:** the workspace `exposeAs` service option supplies the typed app-facing name directly; discovery defaults it from the file.
|
|
19
|
-
- **Flexible authoring:** flat and nested contribution files resolve to the same logical paths; explicit composition remains available.
|
|
20
|
-
- **Owned lifecycle:** one runtime coordinates dependencies, registrations and cleanup.
|
|
40
|
+
```sh
|
|
41
|
+
npx @bitakit/create-app my-app
|
|
42
|
+
```
|
|
21
43
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
44
|
+
The generator requires Node.js 24 or newer. Choose Next.js or experimental TanStack
|
|
45
|
+
Start, then select the optional features you want. React bindings and framework
|
|
46
|
+
adapters are available as separate packages.
|
|
47
|
+
|
|
48
|
+
## Why add BitaKit?
|
|
49
|
+
|
|
50
|
+
Your framework handles pages and rendering. As an app grows, you also need a clear
|
|
51
|
+
way to organize features, share behavior, connect dependencies, and clean up resources.
|
|
52
|
+
BitaKit gives those pieces a common structure.
|
|
53
|
+
|
|
54
|
+
- **Smaller pieces. Clearer ownership.** Keep a feature's services and actions together
|
|
55
|
+
in a plugin. Teams can work on focused parts of the app with explicit connections
|
|
56
|
+
between them.
|
|
57
|
+
- **A shared language for humans and AI.** Predictable files and typed contracts make
|
|
58
|
+
it easier to describe a change, give an AI assistant focused context, and review
|
|
59
|
+
its work. The same conventions guide both developers and coding assistants.
|
|
60
|
+
- **Pluggable features.** Compose the capabilities your app needs. Add a plugin,
|
|
61
|
+
configure its defaults, or replace supported contributions through the same APIs.
|
|
62
|
+
- **Less repeated wiring.** With discovery configured, file paths supply names and
|
|
63
|
+
generated types. Core handles startup, dependencies, registration, and cleanup.
|
|
64
|
+
- **Type-safe connections.** Service methods, action inputs and results, and known
|
|
65
|
+
event payloads carry their types to callers. Your editor helps you connect the pieces.
|
|
66
|
+
- **Your stack stays yours.** Start with headless Core. Add React bindings, settings,
|
|
67
|
+
an app shell, or provider integrations when they help your product.
|
|
68
|
+
|
|
69
|
+
**Room to grow.** As your app and team grow, keep changes focused on small features
|
|
70
|
+
with explicit dependencies. This is about scaling your codebase and collaboration;
|
|
71
|
+
performance and infrastructure remain choices for your application.
|
|
25
72
|
|
|
26
73
|
## How the pieces fit
|
|
27
74
|
|
|
@@ -56,20 +103,9 @@ Core manages the lifecycle of plugin-created services. A service that acquires
|
|
|
56
103
|
resources can supply disposal logic. Core does not automatically save data to a
|
|
57
104
|
database or subscribe your UI to service changes.
|
|
58
105
|
|
|
59
|
-
## Install
|
|
60
|
-
|
|
61
|
-
```sh
|
|
62
|
-
npm install @bitakit/core
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
The example below uses Node.js and no UI. For a React application, bindings live
|
|
66
|
-
in `@bitakit/ui`; framework-specific integration lives in `@bitakit/next` or
|
|
67
|
-
`@bitakit/tanstack`. Those packages are separate from Core and are being prepared
|
|
68
|
-
for publication. TanStack support is experimental.
|
|
69
|
-
|
|
70
106
|
## Try a To-do plugin
|
|
71
107
|
|
|
72
|
-
Follow the [To-do tutorial](docs/todo-tutorial.md) to run three actions: create a
|
|
108
|
+
Follow the [To-do tutorial](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/todo-tutorial.md) to run three actions: create a
|
|
73
109
|
task, list tasks, and delete a task. Each action lives in its own file:
|
|
74
110
|
|
|
75
111
|
```text
|
|
@@ -93,12 +129,25 @@ memory and is lost on restart.
|
|
|
93
129
|
With a configured framework adapter, contribution files can instead live under
|
|
94
130
|
`src/plugins/todos/services` and `src/plugins/todos/actions`. Its build integration
|
|
95
131
|
generates registration and types. Installing Core alone does not scan folders.
|
|
96
|
-
See [file contributions](docs/file-contributions.md) for the exact conventions.
|
|
132
|
+
See [file contributions](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md) for the exact conventions.
|
|
133
|
+
|
|
134
|
+
## Type safety that follows your feature
|
|
135
|
+
|
|
136
|
+
Define a service once, then use its method types wherever you call it. Discovery
|
|
137
|
+
connects supported files to typed service access, action IDs, and configuration.
|
|
138
|
+
Shared service keys let separate packages agree on the same contract.
|
|
139
|
+
|
|
140
|
+
Use `exposeAs` when you want a custom public service name; otherwise discovery uses
|
|
141
|
+
the file path. Known event names and payloads are connected through `EventMap`.
|
|
142
|
+
|
|
143
|
+
Unknown action IDs remain allowed unless strict mode is enabled. TypeScript checks
|
|
144
|
+
code; validate external data and authorize requests at your application boundaries.
|
|
145
|
+
See the [type-safety guide](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md)
|
|
146
|
+
for examples.
|
|
97
147
|
|
|
98
148
|
## React to events
|
|
99
149
|
|
|
100
|
-
|
|
101
|
-
published Core 0.1.0 release. Each runtime owns one event service. Services emit
|
|
150
|
+
Available since Core 0.1.1, each runtime owns one event service. Services emit
|
|
102
151
|
notifications after updating their data; actions declare `events` and `onEvent`.
|
|
103
152
|
|
|
104
153
|
With file discovery configured, IDs can be omitted:
|
|
@@ -155,7 +204,7 @@ asynchronous. Core owns subscriptions created in action `setup` and service
|
|
|
155
204
|
`create`, including cleanup after failed setup. No manual unsubscribe is needed.
|
|
156
205
|
For dynamic subscriptions, `setup` still offers `events.watch`. React components use `useWatchEvent` from `@bitakit/ui`.
|
|
157
206
|
|
|
158
|
-
See [events and action setup](docs/events.md) for payload typing, errors, async
|
|
207
|
+
See [events and action setup](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/events.md) for payload typing, errors, async
|
|
159
208
|
cancellation, and the distinction from observable-service `watch`.
|
|
160
209
|
|
|
161
210
|
## What belongs outside Core?
|
|
@@ -169,14 +218,14 @@ Plugins are trusted application code. Core is not a sandbox or a remote plugin m
|
|
|
169
218
|
|
|
170
219
|
## Go deeper
|
|
171
220
|
|
|
172
|
-
- [Runnable To-do example](examples/todos.mjs)
|
|
173
|
-
- [Core reference](docs/reference.md): configuration, typed services, actions, lifecycle, and advanced integration.
|
|
174
|
-
- [File contributions and configuration](docs/file-contributions.md): discovery and folder conventions.
|
|
175
|
-
- [
|
|
221
|
+
- [Runnable To-do example](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/examples/todos.mjs)
|
|
222
|
+
- [Core reference](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/reference.md): configuration, typed services, actions, lifecycle, and advanced integration.
|
|
223
|
+
- [File contributions and configuration](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/file-contributions.md): discovery and folder conventions.
|
|
224
|
+
- [npm package](https://www.npmjs.com/package/@bitakit/core)
|
|
176
225
|
|
|
177
226
|
## License
|
|
178
227
|
|
|
179
|
-
[MIT](LICENSE). Third-party dependencies retain their own licenses.
|
|
228
|
+
[MIT](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/LICENSE). Third-party dependencies retain their own licenses.
|
|
180
229
|
|
|
181
|
-
See [client authentication](docs/auth.md) for the shared provider contract, externally
|
|
182
|
-
configured login/logout paths, UI bindings and an adapter template
|
|
230
|
+
See [client authentication](https://cdn.jsdelivr.net/npm/@bitakit/core@0.1.2/docs/auth.md) for the shared provider contract, externally
|
|
231
|
+
configured login/logout paths, UI bindings and an adapter template.
|
|
Binary file
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<g clip-path="url(#clip0_2271_10)">
|
|
3
|
+
<path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="white"/>
|
|
4
|
+
<path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
|
|
5
|
+
</g>
|
|
6
|
+
<defs>
|
|
7
|
+
<clipPath id="clip0_2271_10">
|
|
8
|
+
<rect width="300" height="130" fill="white"/>
|
|
9
|
+
</clipPath>
|
|
10
|
+
</defs>
|
|
11
|
+
</svg>
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<svg width="300" height="130" viewBox="0 0 300 130" fill="none" xmlns="http://www.w3.org/2000/svg">
|
|
2
|
+
<g clip-path="url(#clip0_2269_3)">
|
|
3
|
+
<path d="M6 30H15V76C15 81.2667 16.3333 85.3667 19 88.3C21.7333 91.1667 25.4667 92.6 30.2 92.6C35.1333 92.6 39 91.2 41.8 88.4C44.6 85.5333 46 81.4 46 76C46 70.8667 44.4667 66.8333 41.4 63.9C38.4 60.9 34.4333 59.4 29.5 59.4C25.3 59.4 21.6667 60.6 18.6 63V54C22.2667 52 26.2333 51 30.5 51C37.5667 51 43.4 53.3 48 57.9C52.6667 62.4333 55 68.4667 55 76C55 83.9333 52.5667 90.1 47.7 94.5C42.9 98.8333 36.8333 101 29.5 101C22.5 101 16.8333 98.7333 12.5 94.2C8.16667 89.6667 6 83.6 6 76V30ZM78.4727 100H69.6727V60.4H61.4727L65.4727 52H78.4727V100ZM69.2727 42C68.406 40.8667 67.9727 39.6333 67.9727 38.3C67.9727 36.9667 68.406 35.7667 69.2727 34.7C70.1393 33.5667 71.4727 33 73.2727 33C75.0727 33 76.406 33.5667 77.2727 34.7C78.1393 35.7667 78.5727 36.9667 78.5727 38.3C78.5727 39.6333 78.1393 40.8667 77.2727 42C76.406 43.0667 75.0727 43.6 73.2727 43.6C71.4727 43.6 70.1393 43.0667 69.2727 42ZM86.8398 60.4L104.74 42.5V52H118.24V60.4H104.74V81C104.74 83.3333 105.107 85.2667 105.84 86.8C106.64 88.3333 107.773 89.4333 109.24 90.1C110.707 90.7 112.073 91.1 113.34 91.3C114.673 91.5 116.307 91.6 118.24 91.6V100C110.573 100 104.907 98.5333 101.24 95.6C97.5732 92.6667 95.7398 87.8 95.7398 81V60.4H86.8398ZM154.477 71.8V80.8C151.944 78.8667 148.844 77.9 145.177 77.9C142.044 77.9 139.611 78.5333 137.877 79.8C136.144 81 135.277 82.7333 135.277 85C135.277 89.4 138.544 91.6 145.077 91.6H158.277V72.5C158.277 64.4333 154.344 60.4 146.477 60.4H130.477V52H146.977C153.444 52 158.411 53.6 161.877 56.8C165.344 60 167.077 64.6 167.077 70.6V100H144.777C139.111 100 134.611 98.7333 131.277 96.2C127.944 93.6667 126.277 89.9667 126.277 85.1C126.277 80.2333 128.044 76.5333 131.577 74C135.111 71.4667 139.544 70.2 144.877 70.2C147.877 70.2 151.077 70.7333 154.477 71.8Z" fill="#122F4D"/>
|
|
4
|
+
<path d="M205.67 52H215.37L203.27 72.9C211.47 75.1 215.57 81.7333 215.57 92.8V100H206.77V92.7C206.77 88.2333 205.437 84.8 202.77 82.4C200.17 79.9333 196.437 78.7 191.57 78.7C190.037 78.7 188.47 78.8 186.87 79V100H178.07V30H186.87V71.1C189.67 70.7 192.47 70.7 195.27 71.1L205.67 52ZM239.117 100H230.317V60.4H222.117L226.117 52H239.117V100ZM229.917 42C229.051 40.8667 228.617 39.6333 228.617 38.3C228.617 36.9667 229.051 35.7667 229.917 34.7C230.784 33.5667 232.117 33 233.917 33C235.717 33 237.051 33.5667 237.917 34.7C238.784 35.7667 239.217 36.9667 239.217 38.3C239.217 39.6333 238.784 40.8667 237.917 42C237.051 43.0667 235.717 43.6 233.917 43.6C232.117 43.6 230.784 43.0667 229.917 42ZM247.484 60.4L265.384 42.5V52H278.884V60.4H265.384V81C265.384 83.3333 265.751 85.2667 266.484 86.8C267.284 88.3333 268.418 89.4333 269.884 90.1C271.351 90.7 272.718 91.1 273.984 91.3C275.318 91.5 276.951 91.6 278.884 91.6V100C271.218 100 265.551 98.5333 261.884 95.6C258.218 92.6667 256.384 87.8 256.384 81V60.4H247.484Z" fill="#EBB759"/>
|
|
5
|
+
</g>
|
|
6
|
+
<defs>
|
|
7
|
+
<clipPath id="clip0_2269_3">
|
|
8
|
+
<rect width="300" height="130" fill="white"/>
|
|
9
|
+
</clipPath>
|
|
10
|
+
</defs>
|
|
11
|
+
</svg>
|
package/docs/reference.md
CHANGED
|
@@ -28,7 +28,7 @@ optional schemas retain their parse contract. Low-level scoped reads remain avai
|
|
|
28
28
|
Optional packages can project instance-local facades through `appExtensions` and augment
|
|
29
29
|
`AppExtensionMap`. Core owns no Settings implementation or duplicate state.
|
|
30
30
|
|
|
31
|
-
Service definitions use `exposeAs` to name their existing instance in `app.services`. Public names must be unique within the service namespace.
|
|
31
|
+
Service definitions use `exposeAs` to name their existing instance in `app.services`. Public names must be unique within the service namespace. Available since Core 0.1.1.
|
|
32
32
|
|
|
33
33
|
```ts
|
|
34
34
|
const documents = serviceKey<Documents>('editor.documents');
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bitakit/core",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"files": [
|
|
@@ -8,7 +8,8 @@
|
|
|
8
8
|
"README.md",
|
|
9
9
|
"discovery",
|
|
10
10
|
"docs",
|
|
11
|
-
"examples"
|
|
11
|
+
"examples",
|
|
12
|
+
"assets"
|
|
12
13
|
],
|
|
13
14
|
"exports": {
|
|
14
15
|
".": {
|
|
@@ -37,7 +38,7 @@
|
|
|
37
38
|
"zustand": "^5.0.0"
|
|
38
39
|
},
|
|
39
40
|
"devDependencies": {},
|
|
40
|
-
"description": "
|
|
41
|
+
"description": "AI-friendly, type-safe building blocks for modular apps: plugins, services, actions, and events.",
|
|
41
42
|
"license": "MIT",
|
|
42
43
|
"repository": {
|
|
43
44
|
"type": "git",
|