You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Two packaging improvements for embedding hosts. First, `yjs` and `y-protocols` are now required peer dependencies instead of being bundled, so your app and Apollon share a single Yjs instance — no duplicate payload and no cross-instance document errors. Second, a new `@tumaet/apollon/external` entry exposes the same imperative `ApollonEditor` API as the default entry but leaves **every** dependency external (React, MUI, emotion, xyflow, @dnd-kit, zustand, uuid, @chenglou/pretext, …) — so a bundler host of any framework resolves and de-duplicates each one from its own `node_modules` and gets full supply-chain / SBOM visibility, instead of a copy inlined invisibly into the bundle. The default `@tumaet/apollon` (self-contained) and `@tumaet/apollon/react` entries are unchanged. Action required only if you adopt the new entry or the Yjs peer: install the corresponding peers (most package managers do this automatically).
Same imperative `ApollonEditor` API as the default entry, but **every**
77
+
dependency is external — the React family above _and_ Apollon's own runtime
78
+
deps (`@dnd-kit`, `zustand`, `uuid`, `@chenglou/pretext`), which arrive
79
+
transitively with the package. Your bundler resolves and de-duplicates each one
80
+
against your app's `node_modules`, and your bundle analyzer / SBOM tooling sees
81
+
them as real packages instead of code inlined invisibly into one chunk. Use it
82
+
from any framework with a bundler, including non-React ones (the editor still
83
+
runs on the React you provide internally; your own code never touches it).
84
+
48
85
## Type definitions
49
86
50
-
Types ship with the package (`dist/index.d.ts`) and are identical for both subpaths. Requires TypeScript 5.0+ with `moduleResolution: "bundler" | "node16" | "nodenext"`.
87
+
Types ship with the package (`dist/index.d.ts`) and are identical for every subpath. Requires TypeScript 5.0+ with `moduleResolution: "bundler" | "node16" | "nodenext"`.
|`@tumaet/apollon`_(default)_| bundled |~2.4 MB | Any framework that doesn't already have React installed — Angular (the primary use case for [Artemis](https://artemis.tum.de/)), Vue, Svelte, vanilla JS. Zero peer deps to install. |
22
-
|`@tumaet/apollon/react`| externalized |~875 KB | React 18.3 hosts that want to share their React instance with the editor and dedupe the bundle. |
|`@tumaet/apollon`_(default)_| all bundled (except Yjs) |~2.4 MB | No bundler — vanilla JS, a `<script>` tag, or a CDN. Self-contained; only `yjs` + `y-protocols` to install. |
22
+
|`@tumaet/apollon/react`| React family external |~875 KB | A React host that shares its own React/MUI and wants the `<Apollon>` component. |
23
+
|`@tumaet/apollon/external`| everything external |~840 KB | A bundler host of any framework — Angular, Vue, Svelte, React — that wants one shared, fully auditable copy of every dependency. |
23
24
24
-
`peerDependenciesMeta.optional` covers all six peers —`npm install @tumaet/apollon` never warns about missing React.
25
+
`peerDependenciesMeta.optional` covers the six React-family peers, so`npm install @tumaet/apollon` never warns about missing React. `yjs` and `y-protocols` are required peers of all builds — they power Apollon's document model and undo/redo (and live collaboration when enabled), so the editor needs them either way, and keeping them external lets a host that already uses Yjs own a single instance. Most package managers add them automatically. The `/external` entry additionally externalizes Apollon's own runtime deps (`@dnd-kit`, `zustand`, `uuid`, `@chenglou/pretext`), which install transitively with the package.
|`@tumaet/apollon`_(default)_|**bundled**|~2.4 MB / ~540 KB | Your host is Angular, Vue, Svelte, or vanilla JS. No peer deps to install. |
37
-
|`@tumaet/apollon/react`|**peer deps** (shared) |~875 KB / ~170 KB | Your host is React 18.3 and should share its React and MUI with the editor instead of duplicating them. |
34
+
| Import | Dependencies | Size (min / gzip) | Use when |
|`@tumaet/apollon`_(default)_|**all bundled** (except Yjs) |~2.4 MB / ~540 KB | No bundler — vanilla JS, a `<script>` tag, or a CDN. Self-contained; only `yjs` + `y-protocols` to install. |
37
+
|`@tumaet/apollon/react`|**React family external**|~875 KB / ~170 KB | A React host that shares its own React and MUI with the editor. Also ships the `<Apollon>` component, hooks, provider. |
38
+
|`@tumaet/apollon/external`|**everything external**|~840 KB / ~175 KB | A bundler host (Angular, Vue, Svelte, React) that wants every dependency resolved from its own `node_modules` — one shared copy and full SBOM / audit visibility. |
38
39
39
-
Sizes are the published entry chunks. Gzip is the transfer size. The `/react`number excludes the peers your app already ships.
40
+
Sizes are the published entry chunks. Gzip is the transfer size. The `/react`and `/external` numbers exclude the peers your app already ships.
40
41
41
-
### Standalone build (any framework, no peer deps)
42
+
`yjs` and `y-protocols` are required peer dependencies of **all three** builds — they power Apollon's document model and undo/redo (and live collaboration when you enable it), so every editor needs them, collaboration or not. Keeping them external means a host that already uses Yjs (or a second Apollon on the page) shares a single Yjs instance instead of loading a private, possibly mismatched copy. Most package managers install missing peers automatically; the explicit commands below are listed for clarity.
43
+
44
+
### Standalone build (any framework)
42
45
43
46
```sh
44
-
npm install @tumaet/apollon
47
+
npm install @tumaet/apollon yjs y-protocols
45
48
```
46
49
47
50
```ts
48
51
import { ApollonEditor } from"@tumaet/apollon"
49
52
import"@tumaet/apollon/style.css"
50
53
```
51
54
52
-
React, MUI, emotion, and xyflow are bundled in. Nothing else to install.
55
+
React, MUI, emotion, and xyflow are bundled in; only `yjs` and `y-protocols` are peers you provide.
`yjs` and `y-protocols` are required for all builds; the React, MUI, emotion, and xyflow peers below are specific to the `/react` and `/external` builds.
Same imperative `ApollonEditor` API as the default entry, but **every** dependency is left external — the React family above _and_ Apollon's own runtime deps (`@dnd-kit`, `zustand`, `uuid`, `@chenglou/pretext`), which arrive transitively when you install the package. Your bundler then resolves and de-duplicates each one against your app's `node_modules`, and your bundle analyzer / SBOM tooling sees them as the real packages they are instead of code inlined invisibly into one chunk. Use this from any framework with a bundler — even a non-React one (the editor still runs on the React you provide internally; your own code never touches it).
74
95
75
-
It comes down to whether your host already runs React:
96
+
## Which build do I use?
76
97
77
-
-**Not a React app?** Use the default `@tumaet/apollon`. It bundles its own React, so there is nothing extra to install or configure.
78
-
-**A React app?** Use `@tumaet/apollon/react` and install the peers above. The default build bundles its own React, so in a React app you would load two copies. That causes "Invalid hook call" errors and a larger bundle. The `/react` subpath leaves React, MUI, emotion, and xyflow external so the editor shares the copies your app already has. It is also the only entry that exports the `<Apollon>` component, hooks, and provider.
98
+
-**No bundler** (vanilla JS, `<script>`, CDN)? Use the default `@tumaet/apollon`. It inlines its own React, so the only peers to install are `yjs` and `y-protocols`.
99
+
-**A React app?** Use `@tumaet/apollon/react` and install the peers above. The default build bundles its own React, so in a React app you would load two copies — that causes "Invalid hook call" errors and a larger bundle. The `/react` subpath leaves React, MUI, emotion, and xyflow external so the editor shares the copies your app already has. It is also the only entry that exports the `<Apollon>` component, hooks, and provider.
100
+
-**A bundler host that wants one shared, fully auditable copy of every dependency?** Use `@tumaet/apollon/external` and install the peers above. Works from any framework.
79
101
80
102
> **⚠️ Give the container an explicit, non-zero height** (`600px`, `80vh`, or a sized flex/grid child), whichever build you use. The canvas sizes itself to its parent, so with no resolvable height it collapses to zero pixels and renders blank. This is the most common embedding mistake. See [Troubleshooting](https://ls1intum.github.io/Apollon/library/troubleshooting).
81
103
@@ -178,6 +200,8 @@ export class DiagramEditorComponent {
178
200
179
201
### Vanilla JS / CDN
180
202
203
+
`yjs` and `y-protocols` are required peers, but on the CDN path esm.sh resolves and serves them from the import URL automatically — there is nothing extra to load. (With a bundler you install the peers yourself.)
0 commit comments