Extend
For ucks you want to version, publish, or depend on, wrap them in an npm
package. Extensions are packages that export a register(ctx) function —
the same contract as ucks.
Full Node.js runtime — no sandboxing. Extensions can import each other, call
child_process, hit the network, modify core behavior, whatever.
1. Create an extension
my-f-ext/
package.json
index.js
package.json:
{
"name": "@myorg/f-my-ext",
"version": "0.1.0",
"type": "module",
"main": "./index.js"
}
index.js:
export function register(ctx) {
// ctx.fVersion — f's version
// ctx.contractVersion — the contract this core speaks (2)
// ctx.self — this package's name
// (no ucks/registry here — peer access is run-time only)
return {
name: "myuck",
desc: "what it does (terse)",
run: (argv, args, runCtx) => {
// runCtx.ucks — [{name, desc}] of every loaded uck
// runCtx.registry — name -> everything that uck returned
console.log("hello", args._.join(" "));
},
};
// Can also return an array: [ {name: "a", ...}, {name: "b", ...} ]
}
export default { register };
2. Register it in f.config.json
Add it to the ucks array — an npm package is a source like any other:
{
"ucks": [
"@myorg/f-my-ext",
"./local-path/to/ext",
{ "source": "github:user/repo", "ref": "main" }
]
}
Source formats:
- npm —
"@scope/name"— fetched withnpm packinto a bucket under~/.f/ucks/onf up, and loaded from there. It does not need to be in your project'snode_modules. (A legacy path still resolves an npm source throughnode_modulesif one happens to be installed there; see Precedence.) - local —
"./my-ext"or"/abs/path"— a dir withpackage.jsonorindex.js. - git —
"github:user/repo"or"git+https://…". - object —
{ "source": "…", "ref": "branch", "name": "bucket" }.
3. Install and run
Add the package to ucks and run f up. f fetches the tarball into
~/.f/ucks/ — see Adding a uck.
// f.config.json
{ "ucks": ["@myorg/f-my-ext"] }
f up
f myuck hello
The package is a copy under the store, not a dependency of your project: nothing
is added to your package.json or node_modules, and f up is what refreshes
it. f uck itself has no install subcommand.
A legacy
extensionskey inf.config.jsonis still read as a source list whenucksis absent. Preferucks.
Extension interop
Extensions run in the full Node.js runtime, and they share the uck registry:
- Import each other:
import { helper } from "@other/f-ext" - Use
child_process,fs,http,net— everything. - Call other ucks through
ctx.registryinrun(e.g.ctx.registry.creds), and only there — the register-time ctx does not carryregistryat all, so a peer lookup beforerunfails loud rather than seeing a partial view. - Modify or override core
fbehavior.
No sandbox. No restrictions. Ucks are first-class.
Precedence
Later sources win, and load order is: store buckets first, then any npm source
that also resolves through node_modules. Since npm sources are installed as
store buckets, an npm package normally shadows a same-named uck from an earlier
bucket — the shadowing is bucket order, not npm-versus-store. The
node_modules step only fires for installs that predate store installs of npm
sources, and it is silent when the specifier does not resolve there. Within each
group, project config loads after global. See Ucks for shadowing.