Skip to content

docs(kernel): move plugin manifest dependency examples off ^2.0.0 and record what the kernel actually reads #18415

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
os-try-charles merged 1 commit into from
Sep 16, 2026
+23 −4
Merged

docs(kernel): move plugin manifest dependency examples off ^2.0.0 and record what the kernel actually reads #18415

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 23 additions & 4 deletions content/docs/protocol/kernel/plugin-spec.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ export default definePlugin({

// DEPENDENCIES
dependencies: {
'@objectstack/core': '^2.0.0',
'@objectstack/core': '^17.0.0',
'@mycompany/base': '1.0.0 - 2.0.0',
},

Expand Down Expand Up @@ -433,7 +433,7 @@ Plugin **cannot function** without these.

```typescript
dependencies: {
'@objectstack/core': '^2.0.0',
'@objectstack/core': '^17.0.0',
'@mycompany/base': '1.0.0 - 2.0.0',
}
```
Expand Down Expand Up @@ -467,6 +467,20 @@ Use for large dependencies (React, Vue) that should be shared across plugins.

### Version Constraints

<Callout type="warn">
**The kernel does not check these range strings at plugin load.** `manifest.dependencies`
has exactly two consumers today and both read `Object.keys(...)` only — the ids, never the
ranges: `resolveArtifactPackageOrder` (`packages/core/src/artifact-packages.ts`) hands the
ids to `resolvePluginOrder` as `optionalDependencies`, so an id naming a sibling package in
the same artifact orders ahead of it and an id naming anything else is skipped; and
`resolveWritePackageScope` (`packages/metadata-protocol/src/protocol.ts`) walks the ids
transitively for the write-scope gate. `SemanticVersionManager` and `DependencyResolver`
below are exported from `@objectstack/core` but have no call site outside their own unit
test. So a range here is a **declaration for the installer and for human readers** — a
stale or malformed one fails nothing at load. The forms below are the ones the parser in
`dependency-resolver.ts` accepts, not a set the kernel enforces on you.
</Callout>

ObjectStack uses **semantic versioning (semver)**. `SemanticVersionManager.satisfies()`
(`packages/core/src/dependency-resolver.ts`) accepts exactly these forms:

Expand Down Expand Up @@ -935,14 +949,19 @@ declares one (`PluginLifecycleSchema`) but nothing in the kernel calls it.
```

### 3. Pin Core Dependencies
Use exact version for `@objectstack/core` to avoid surprises:
Use an exact version for `@objectstack/core` rather than a caret range, so moving to a new
release is a deliberate edit and not whatever the installer happens to resolve:

```typescript
dependencies: {
'@objectstack/core': '2.0.0', // Not '^2.0.0'
'@objectstack/core': '17.4.0', // Not '^17.0.0'
}
```

Per the *Version Constraints* callout above, the kernel does not check this range at load,
so the advice is for whoever installs the plugin — and it applies with more force to the
same dependency in `package.json`, which npm really does resolve.

### 4. Validate Configuration Early
Parse config with your Zod schema in `init()` — the first phase that runs — so a bad
value fails the boot instead of the first request. There is no `onBoot` hook (the name
Expand Down
Loading