Ink Authoring API
Developmentink-authoring-apiInk Authoring API is an Agent Skill for development published in the inkline/inkline repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
The .ink.tsx authoring API — defineComponent, signals, control flow, slots, two-way binding, events — plus per-target rewrite behavior and the anti-patterns that reviewers reject on sight. Use whenever writing or reviewing .ink.tsx code.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/inkline/inkline/blob/HEAD/.claude/skills/ink-authoring-api/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ink-authoring-api, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
The .ink.tsx authoring API
The model
Components are authored once against @inkline/core and compiled to 7 frameworks. @inkline/core is authoring-time stubs — identity functions and no-ops that exist so code type-checks and produces predictable IR. The compiler removes every reference during emission; no core runtime ships. Never add real reactive/DOM behavior to the stubs — real behavior comes from the per-framework code the compiler emits.
import { defineComponent, createSignal, createMemo, Show, Slot } from "@inkline/core";
export interface ButtonBaseProps {
label?: string;
disabled?: boolean;
}
export default defineComponent(
{ meta: { headless: true }, slots: { default: {} } }, // options (slots, events, meta, name)
(props: ButtonBaseProps) => {
// setup — props via the TS parameter type
const [count, setCount] = createSignal(0);
const doubled = createMemo(() => count() * 2);
return (
<button disabled={props.disabled} onClick={() => setCount(count() + 1)}>
<Show when={doubled() > 4} fallback={<span>keep going</span>}>
…
</Show>
<Slot>{props.label}</Slot>
</button>
);
},
);
Primitives (all from @inkline/core)
createSignal(initial) → [get, set] · createMemo(fn) · createEffect(fn) (may return cleanup) · createRef() (.current, element refs only) · onMount / onCleanup · batch / untrack · defineModel(name = "value") (two-way prop + update:<name> event, returns a signal tuple) · defineEmits<E>() → emit (custom events) · defineSlot / hasSlot(name?) · createResource (deferred — no runtime yet).
Control flow is JSX, lowered in compiler pass P3: <Show when fallback> · <For each key> (key is required — INK0050 without it) · <Switch>/<Match> · <Slot name?> with fallback children (default slot: the lowercase <slot> intrinsic also works) · <Transition> (wraps one conditional element).
How reads rewrite per target (the compiler's job, but know it)
| Source | React | Solid | Vue | Svelte |
|---|---|---|---|---|
count() | count | count() | count | count |
setCount(x) | setCount(x) | setCount(x) | count.value = x | count = x |
Two-way: child declares defineModel("value"); parent binds $bind:value={text} (also on native elements). Emits per target: Vue v-model:value, Svelte $bindable, Angular model(), React/Solid value + onUpdateValue, Qwik QRL, Astro one-way only (static SSR — INK0045 notice). emit("change", x) becomes props.onChange?.(x) (React/Solid), defineEmits (Vue), callback prop (Svelte), @Output() (Angular), QRL (Qwik); inert on Astro.
hasSlot("prefix") lowers to a real runtime presence check on React/Solid/Svelte/Vue/Astro but is always true on Qwik and Angular (no runtime slot-presence API — INK0068 info notice). Pair every hasSlot-gated wrapper with a CSS :empty collapse rule in the component's .styleframe.ts.
Anti-patterns (reviewers reject on sight)
- Namespace import of core (
import * as ink from "@inkline/core") — hard error INK0001. Named imports only. <For>withoutkey(INK0050);<Show>withoutwhen(INK0060);<For>withouteach(INK0062).- A new primitive without its compiler binding. Adding an export to
core/corewithout wiring parse (P2) and lowering (P3) in the compiler leaves it verbatim in output and breaks every consumer. End-to-end or not at all. - Real logic in core stubs — the stubs are inert by contract.
- Component-ref forwarding — unsupported (INK0070); element refs only.
- Dynamic reactive reads (
obj[key()]) — defeats static dependency tracking (INK0020); React falls back to recompute-every-render. - Solid renders
undefinedas the string"undefined"for native string props — coalesce optional string→attribute bindings with?? "". !!,Boolean(),??sprinkled in JSX that must stay lint-clean across 7 emitted outputs — prefer explicit conditionals; check the compiled output when in doubt.- Interface-extension styling props that the compiler can't enumerate. The compiler only enumerates members of directly-named interfaces — when extending recipe prop types would collide (e.g. recipe
disabled: "true" | "false" | booleanvs a nativeboolean), declare the styling props explicitly (seeinput/styled/IInput.ink.tsx). - Effects for derivation —
createMemoderives,createEffectis for real side effects only; an effect with no reactive reads runs once (INK0010).
Where the truth lives
core/compiler/README.md (user-facing reference — mind its known drift), core/core/AGENTS.md (stub invariant + export table), diagnostics registry core/compiler/src/core/diagnostics/codes.ts (INK0001–INK0120). Component-building procedure: the research/implement/stories/test/document-component phase skills; live exemplars ui/components/src/components/{badge,button,input}.