Skip to content
Get started

SDK: A project

An AllyHub project is a folder, laid out as its people like, and a TypeScript (Node) project. AllyHub finds what it holds by two things only: its list of work, allyhub.yaml, and imports. This file covers the folders, the items, how a piece imports the SDK and other files, the words it reads, allyhub.config.ts and fonts.

package.json depends on allyhub and @allyhub/sdk
tsconfig.json the compiler's settings: the SDK's types
allyhub.yaml the work a person sees: each piece's kind, file and title
allyhub.config.ts the project's settings, the look, fonts (optional)
AGENTS.md, CLAUDE.md the project's standing instructions (CLAUDE.md is @AGENTS.md)
.gitignore node_modules/ and .allyhub/
assets/ files used as they are: media/, data/, text/, fonts/
components/ code several items share
.allyhub/ this computer's own, never shared

Only the dot folders and Node’s own files are fixed places. assets/ and components/ are where AllyHub’s tools put what they fetch or add (allyhub add); the build follows imports, not folders.

  • A folder is a project when its package.json depends on allyhub or @allyhub/sdk, or it has an allyhub.config.*. A command works on the nearest one at or above where it runs. The smallest project is a folder with an allyhub.config.ts and no package.json: the CLI brings @allyhub/sdk (and its subpaths) to a project that does not install it.
  • The SDK and the CLI are one version. A project whose SDK is another version than the CLI that builds it is AK-B008; a package.json that declares AllyHub’s packages before npm install has installed them is AK-B009, and nothing is built.
  • A piece may import any package package.json declares and npm install installed. An import of an undeclared package, a file outside the project or a URL is AK-B005. three (with three/addons/…), @allyhub/model and @allyhub/scenery-host/layer are lent by the CLI unless the project declares its own.
  • npm create allyhub@latest <folder> starts a project with these files.
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Bundler",
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"types": ["@allyhub/sdk/client", "allyhub/client"],
"strict": true,
"noEmit": true,
"skipLibCheck": true,
"verbatimModuleSyntax": true,
"allowImportingTsExtensions": true
},
"include": ["**/*.ts", ".allyhub/cache/types"],
"exclude": ["node_modules"]
}
  • @allyhub/sdk/client types the imports the build understands (Media and data); allyhub/client, the packages the build lends by name (@allyhub/scenery-host/layer, @allyhub/model), from the project’s allyhub.
  • Every build (allyhub check, render, dev…) writes .allyhub/cache/types/messages.d.ts, the default language’s message keys as types: s() then autocompletes keys and a wrong key fails tsc. **/*.ts does not enter folders that start with a dot, so the folder is listed in include. Without it, any string is a key.
  • A vite.config.ts of the project’s own is read: its plugins, resolve, css, define, json, assetsInclude and oxc apply after AllyHub’s. Everything else is AllyHub’s.

This computer’s own: never shared, rebuilt as needed. Nothing a piece imports may live there.

Folder What is in it
.allyhub/work/ The agent’s working files, free to throw away: frame sheets, cut sheets, references (reference/)
.allyhub/out/ Renders and exports, by the item’s id
.allyhub/cache/ What the tools rebuild: builds, the media index (face tracks, mattes, levels), the part cache, types
.allyhub/trash/ What a person deleted in an editor, kept until they empty it

An item is a piece of work a person sees: a file of a kind, named by the project’s list, allyhub.yaml at its root. Files are yours to name and place; the list says what a person sees in Studio and allyhub dev, in its order, under its headings:

work:
- group: Launch
items:
- kind: video
file: launch/film.ts
title: Launch film, 30 s
- kind: video
file: launch/vertical/film.ts
- kind: slides
file: decks/seed.ts
- kind: doc
file: notes/brief.mdx
Kind Item Its file holds
video A video export default video({ … }) (video.md)
slides A deck export default presentation({ slides, script, size }, (prs) => { … }) from @allyhub/sdk/slides, naming its slides file and its script (slides.md)
image An image export default image({ script, boards }) from @allyhub/sdk/image, naming its script (image.md)
scenery A 3D scenery export default defineScenery({ … }) (scenery.md)
model A 3D model export default defineModel(build) (modeling.md)
doc A doc The doc itself, MDX (docs.md)
sheet A sheet The workbook, YAML: its sheets, cells, formulas, formats, names and checks; the CSV files it names hold its tables’ rows, and the module its code names makes sheets (sheets.md)
website A website JSON: how the web project in its folder is served, built and where the built site is (websites.md)
(none) A canvas A .canvas file, JSON Canvas: its editor opens it by its name, so its entry names no kind (- file: boards/launch.canvas)
  • Each piece has its kind, its file from the project’s root and, if you want, a title: its name where people see it; without one, the title its file says, else the file’s name. A group is a heading over its items, and groups nest. A new project’s list is work: []; an item a person makes in Studio or allyhub dev is added at its end.
  • A file the list does not name is yours alone: a scenery a video imports, a part, a helper, a draft. Nothing shows it to a person; the build still follows imports to it.
  • An item’s id is its file without its extension (launch/film), one in the project: it names the item in commands (allyhub check launch/film, --piece launch/film), in .allyhub/out/ and in a share. A piece’s id is its item’s unless it sets id (lowercase letters, digits, ., _ and -, with / between levels). Two pieces with one id are AK-B001. The id names its message keys (launch/film reads keys under launch.film.) and seeds its randomness.
  • An item names the other files it uses, each from its own file’s folder: a piece’s script (script: "./film.{locale}.yaml"), a deck’s slides file (slides: "./deck.yaml"), a sheet’s code (code: ./forecast.ts) and its tables’ CSV files. Nothing is found by a fixed name, so items share a folder freely, and two share a file only when both name it.
  • allyhub check reports what is wrong with the list: a list it cannot read, a kind not loaded, a file listed with no kind that no editor opens by its name, or a file not there (AK-M002), one id twice (a.ts and a.mdx, or one file listed twice, AK-M003). Moving or renaming a listed file in Studio writes the list again, with the imports.
  • The default export is video({ … }) or presentation(…) written in the file, or a constant holding one (const film = video({ … }); export default film). A re-export, a factory function or a conditional is not followed (AK-M001).
  • The module’s top level runs in Node when the build reads the piece: what needs window or document goes in parts (or pages) or in a layer’s mount and render. The top level may not use the network (AK-B003) and must finish (AK-B004).
  • Every field of the piece but its functions (parts, pages, covers) is plain data (AK-M001).

A project file imports @allyhub/sdk; the build gives it the SDK with video, part, take and footage made for that file (sdkFor({ file })), and @allyhub/sdk/slides with presentation made for it. So a path a module writes as a string is relative to that module’s own folder: take("./vo/en.mp3"), footage("./broll.mp4"), a part’s sounds, music, post.lut, .edits("./edits/host.json"). A field keeps the folder it was written in when another piece spreads it. Nothing is a global.

An item uses another by an ordinary relative import. A piece in another format is an item of its own:

import { part, say, video } from "@allyhub/sdk";
export default video({
format: "16x9",
music: "./music/bed.mp3",
parts: ({ s }) => [
part({ key: "hook", speech: say(s("launch.film.hook.say")) }),
],
});
import { video } from "@allyhub/sdk";
import film from "../film.ts";
// Its music is still launch/music/bed.mp3; its id is launch/vertical/film.
export default video({ ...film, format: "9x16" });
  • video() returns its fields as written, so a piece can spread another. A copy of a piece that sets id needs an id of its own.
  • A video item can be shown inside another: take(piece), footage(piece) and ctx.video(piece, el) (footage.md, speech.md). A chain of videos that reaches itself is AK-M010.

All the text people see or hear is read with s(key) (the parts function’s ctx.s). An item’s own words are its script; words several items share are in assets/text/<lang>.json.

An item’s script is one file per language, which the item names from its module’s folder, with {locale} once in the file’s name standing for each: video({ script: "./film.{locale}.yaml", … }) reads film.en.yaml, film.zh-cn.yaml; a deck names its own in presentation({ script }) (slides.md). A video without script has no words of its own.

title: Tidyform launch
text:
url: tidyform.app
parts:
- id: hook
say: Tidyform makes forms that fill themselves in, so you @{rest}only ask what you don't know.
screen:
line: Forms that fill themselves in.
- id: how
screen:
steps:
- Paste your form link
- We match the answers you have
- id: quote
say: Northwind cut their form from <12|twelve> fields to <3|three>.

The script becomes messages under the piece’s prefix (its id with / as .):

In the script Its key
title <prefix>.title, the piece’s title
text.<name> <prefix>.<name>
parts[].say <prefix>.<part>.say
parts[].screen.<name> <prefix>.<part>.<name>; names nest, a list is numbered (<prefix>.how.steps.0)
slides[].text.<name> <prefix>.<slide>.<name>, a deck’s shape’s words (slides.md)
boards[].text.<name> <prefix>.<board>.<name>, an image’s layer’s words (image.md)
  • A row’s id is a part’s key; a row has id, say and screen, nothing else. A row for a part the video does not have yet is allowed. A video’s words are under parts, a deck’s under slides, an image’s under boards (id and text), each by its kind’s own name for what it is made of.
  • A say is one line, or a plural: it may hold anchors (@{name}) and text shown one way and said another (<12|twelve>) (speech.md). A text on screen is a string, { display, speak }, a plural, a list, or texts by name.
  • A file that is not YAML or not a script, and a key made twice, are AK-M007. A script no item names is not read.

Flat keys, in inlang’s message format (allyhub.config.ts’s text names another folder):

{
"brand.tagline": "Forms that fill themselves in.",
"brand.legal": { "display": "© 2026 Tidyform", "speak": "Tidyform" },
"pricing.greeting": "Hello, {name}",
"pricing.count": [
{
"declarations": ["input count", "local n = count: plural"],
"selectors": ["n"],
"match": {
"n=0": "No plans yet",
"n=one": "{count} plan",
"n=other": "{count} plans"
}
}
]
}

A key is segments of letters, digits, _ and - joined by dots. A value is a string, { display, speak }, or a message with variants (one { declarations, selectors, match } in a list); {name} is a variable. A file that does not match is AK-M006.

Call Returns
s(key, hint?) The text in the combo’s language; display of a { display, speak } pair
s.list(prefix, hint?) prefix.0, prefix.1, … in order; deeper keys make objects (plans.0.name). s.list<Plan>(prefix) names the item type
s.with(key, inputs, hint?) The text with its {name} variables filled, and a plural’s or a selection’s variant picked
  • hint is { max?, note? }: a length budget and a note for whoever writes the text. It changes nothing.
  • A key missing in the combo’s language falls back to the default language (AK-S002, a warning); missing there too, it is "" (AK-S001).
  • A piece’s languages are its script’s and assets/text/’s, ordered with allyhub.config.ts’s locales first, else en; a piece’s matrix.dims.lang narrows them (batches.md). Each language is a combo of the piece.
  • A line may mark stretches: **strong**, *em*, ~~struck~~, `code`. s() returns the line as written; readMarks, markRuns and withoutMarks read it, and marked() from @allyhub/sdk/dom draws it (layers.md).
  • Text written in code is drawn as written, in every language.

A file is used by importing it, by a string path relative to the module that names it, or by ctx.asset(path) and ctx.data(path) for a path made at run time (relative to the piece’s file).

A share of one item serves only what the item reaches: the files its kind’s build lists for it (its file, its script, a deck’s slides file, a sheet’s code and tables, a doc’s pictures and sources), what its code imports, what its slides show, and what a path named at run time read when the check last loaded it, never its folder’s other files. A file named only at run time is in its share once the check has run since.

import { custom, part, video } from "@allyhub/sdk";
import logo from "../../assets/media/logo.svg";
import plans from "../../assets/data/plans.csv";
export default video({
parts: () =>
plans.map((plan, i) =>
part({
key: `plan-${String(i)}`,
layers: [
custom({
mount(el) {
const img = document.createElement("img");
img.src = String(logo); // a media value as a string is its url
el.append(img, String(plan.name));
},
render() {},
}),
],
}),
),
});
  • Media (pictures png jpg jpeg webp gif svg avif; sound mp3 wav m4a ogg aac flac; video mp4 webm mov m4v qt; fonts woff2 woff ttf otf; 3D glb gltf bin ktx2, environments hdr exr) imports as a MediaInfo: path from the project’s root, sha256, kind, width and height, duration, audio, and what the build measured (words, loudness, tempo, faces, matte…). url is where the stage loads it, valid only at run time; a media value turned into a string is its url (img.src = logo).
  • Beside a media file, files of the same name add to it: <name>.words.json (its word times: the file is a take, speech.md), <name>.elements.json (a screenshot’s named element boxes, elements), <file>.gen.json (how the file was made: gen; move it with its file).
  • Data: CSV imports as an array of objects keyed by the header row, a column whose every value is a number as numbers; YAML as its value; JSON as usual.
  • A file that is not there is AK-A001; one of the wrong kind AK-A003; a picture on the stage that does not load AK-A005.

Optional. Its default export is defineConfig(…):

import { defineConfig } from "@allyhub/sdk";
export default defineConfig({
locales: ["en", "zh-cn"],
fonts: ["@fontsource/space-grotesk/400.css", "./assets/fonts/brand.css"],
look: {
color: { accent: "#0f766e", bg: "#fbf8f3" },
font: {
display: '"Space Grotesk", "Inter Variable", "Noto Sans SC", sans-serif',
},
sfx: { ding: "assets/media/sfx/ding.wav" },
},
defaults: { format: "16x9", part: { lead: 0.15, tail: 0.4 } },
});
Field What it is
locales The project’s languages (BCP 47), the first its base; default the languages its words are in, en first
fonts Font stylesheets every stage loads, each named as an import from the project’s root (Fonts)
text The folder of the shared words; default assets/text
look { color?, font?, motion?, sfx? }, laid over the built-in clean look (video.md)
defaults { format?, part?: { dur?, lead?, tail? } }: what every video starts from; a video’s own defaults.part is over it

The stage draws offline, so it draws only fonts that are files: its own, and the stylesheets a project brings.

  • Built in: "Inter Variable" (Latin, Greek, Cyrillic, Vietnamese), "Noto Sans SC" (Chinese, 400 and 700) and "Noto Color Emoji" (the look’s font.emoji). The clean look’s mono is the computer’s own monospace font, which differs between computers: bring one for code.
  • Imported by code: install a font package and import its stylesheet in a piece or a module its pieces share (import "@fontsource/space-grotesk/400.css"), or import a stylesheet of @font-face rules beside the font files by a relative path. The package must be declared (AK-B005).
  • Listed in allyhub.config.ts: fonts loads stylesheets on every stage, so the look can name a family no piece imports. An entry that names no file is AK-A001.
  • A declared face costs nothing until text needs it: before the layers mount, the stage loads the faces of the families the look, the stylesheets and the layers’ props name that cover a character of the piece’s text; after mount, what the text on the stage asks for. A family that is not loaded falls to the next one, and a weight or style its faces lack is faked by the browser: both are AK-L006. A character no loaded font has is AK-L003.
Was this page helpful?