Core features vs. samples

In plain words

Kumiko ships bundled features and samples, but they make different promises. Bundled features are production dependencies: they are published, boot- validated, and maintained as part of the framework.

Samples demonstrate a pattern and include tests for that pattern. They are not published production dependencies. Read them or copy the relevant pattern into your own feature, but do not import code from samples/ into an app.

bundled feature (packages/bundled-features/) --> import it, run it in prod
sample (samples/recipes/, samples/apps/)      --> read it, copy the pattern, don't import it

Why the split exists

Both kinds of code are event-sourced Kumiko features and both are tested : so from the framework’s point of view, nothing structurally distinguishes them. The split is about what the code promises.

A bundled feature (packages/bundled-features/src/<name>/) promises: this is safe to run in production, its schema is stable across versions, its integrations (hooks, extension points, boot-validator checks) are correct, and when the framework finds a bug in it, you get a patched version for free. audit, secrets, user, tenant, jobs, these are the ready-made pieces covered in Bundled features vs. custom. That page is about a different axis: bundled vs. your own business code. This page is about samples, which are neither.

A sample (samples/recipes/<name>/, samples/apps/<name>/) promises something narrower: this pattern works, here is the shortest correct demonstration of it, and here is a test that fails the moment the framework regresses it. Samples exist so the framework’s own feature set has a worked example for every capability, relations, embedded fields, search, realtime, rate limiting, multi-currency money, and so on (see the full list in samples/README.md). They are not shipped as an npm package. They are not boot-validated as part of your app. Nobody patches them for you when a schema you copied out of one turns out to need a security fix six months from now, because it is your copy, in your app, and the framework has no idea it exists.

What tells them apart in practice

	Bundled feature	Sample
Lives in	packages/bundled-features/src/<name>/	samples/recipes/<name>/, samples/apps/<name>/
Published as	Part of @cosmicdrift/kumiko-bundled-features	Not published at all
You use it by	import { ... } from "@cosmicdrift/kumiko-bundled-features/<name>"	Reading the source, copying the pattern into your own feature
Framework patches it	Yes, version bumps carry fixes	No, once copied, it is your code
Test type	Integration + unit, gates every framework release	Integration/unit, gates that the pattern still works
Purpose	Solve a cross-cutting problem for you	Show you how to solve a specific problem yourself

Two of the two entries in the “recipes” table are worth calling out because they map directly to bundled features’ extension points rather than to a copyable pattern: recipes/cross-feature-events and recipes/designer-demo. Even those stay samples, they demonstrate the extension mechanism, they are not the mechanism itself.

The decision rule

Never import from samples/. If you find yourself doing that, what you actually want is either a bundled feature (check samples/README.md’s table and the bundled-features package first) or your own feature, written using the sample as a reference.

When you are about to build something and are not sure how, full-text search, a state machine, encrypted per-tenant config, rate limiting, check the recipes table first. Read the recipe, understand the two or three primitives it combines, then write your own feature using those primitives directly. The recipe’s job is done the moment you understand the pattern; it was never meant to become a dependency of your app.

See also

• Bundled features vs. custom, the other axis: ready-made cross-cutting features vs. your own business features. Samples are neither of those.
• Features and composition, what a feature definition is, the shape every bundled feature and every sample shares.