mininext Version 0.9.1

Documentation

Mininext API Reference

For the ideas behind the API, see Architecture and Getting Started.

Entry points

ImportContainsUse it in
@spirobel/mininexteverything: html, build(), fill(), crawl() and the browser partsserver code
@spirobel/mininext/browserhtml, renderRoot, createRouter, typesfrontend code

Bundlers that know the "browser" export condition (Bun does) pick browser automatically, so a frontend file can import from @spirobel/mininext too. No server code goes into a browser bundle.


html template literal

File: mininext/core.ts

function html(stringLiterals: TemplateStringsArray, ...values: MiniValue[]): MiniHtmlString;

Only the literal parts are html. Every ${value} is data:

ValueBetween tagsIn an attribute
string, numbertext (escaped, never markup)the attribute value (escaped, quoted)
null, undefined, falsenothingno attribute
truenothingboolean attribute, like disabled
html\...``a nested templaterefused
(mini) => valuea component, runs every render. it returns html or any value in this tablerefused
(event) => ...refusedhandler, only in on* attributes: onclick=${() => go(id)}
arraya list, one slot per itemrefused
plain objectrefusedrefused

The full rules (url checks, srcdoc, values in <style>) are in Architecture: Values.

const greeting = html`<h1 class="${cls}">Hello, ${name}!</h1>`;

renderRoot start rendering

File: mininext/frontend/minidom.ts

function renderRoot(options: {
  component: (mini: Mini) => MiniHtmlString;
  container: HTMLElement;
  cac?: CacheAndCursor; // your own cache, if you want to read it
}): void;
let count = 0;
renderRoot({
  container: document.getElementById("root")!,
  component: (mini) => mini.html`<button onclick=${() => count++}>${count}</button>`,
});

createRouter hash router

File: mininext/frontend/minirouter.ts

function createRouter(routes: Record<string, (params, mini: Mini) => MiniHtmlString>): {
  component: (mini: Mini) => MiniHtmlString;
  navigate(path: string, params?): void;
  link(path: string, params?): string; // "#/users/42"
  getCurrentPath(): string;
};
const router = createRouter({
  "/": () => html`<h1>Home</h1>`,
  "/users/:id": (params) => html`<h1>User ${params.id}</h1>`,
  "/files/*": (params) => html`<p>${params["*"]}</p>`,
});
renderRoot({ container, component: router.component });
html`<a href="${router.link("/users/:id", { id: "42" })}">user 42</a>`;

Static segments match before :params, and routes that end in /* match last, whatever the order of the keys. Params are typed from the route string, also in inline handlers. Params are percent decoded, and link() / navigate() encode them. A ?query after the path is ignored. An unknown hash renders nothing and warns one time.


.build() build a skeleton (server)

File: mininext/backend/html.ts

html`...`.build(mini?: Mini, root?: string, config?: Bun.BuildConfig): Promise<Skeleton>;
const skeleton = await html`<!doctype html>
  <html>
    <head><script type="module" src="./frontend.ts"></script></head>
    <body>${null}</body>
  </html>`.build();

skeleton.fill() fill the placeholders

skeleton.fill(...values: MiniValue[]): Blob;
"/": () => new Response(skeleton.fill(html`<p>count ${count}</p>`)),

skeleton.mini() request state

skeleton.mini(): Mini; // its fill() is bound to the skeleton
function handler(req: Request) {
  const mini = skeleton.mini();
  mini.state("req", req);
  return new Response(mini.fill(page));
}
function page(mini: Mini) {
  const req = mini.state<Request | null>("req", null).value;
  return mini.html`<p>you asked for ${new URL(req!.url).pathname}</p>`;
}

Every component in that fill() can read the state. You do not pass it down through props.


mini.state() state

File: mininext/minicache.ts

mini.state<T>(name: string, initial: T, global?: boolean): { value: T; name: string };

mini.html

The same function as html, on the Mini that a component gets.


.renderBackend() render to a string (server)

html`...`.renderBackend(mini?: Mini): string;

Renders a template to an html string with the server rules. It does not need a skeleton.


crawl() static site export (server)

File: mininext/backend/static.ts

crawl(start: string | URL, outdir: string, options?: { paths?: string[]; version?: string }): Promise<MiniArtifact>;
process.env.NODE_ENV = "production";
const server = Bun.serve({ port: 0, routes });
await crawl(server.url, "dist", { version: "1.0.0" });
server.stop();

Types

type MiniValue = string | number | null | boolean | undefined
  | MiniComponent | MiniHandler | MiniHtmlString | MiniValue[];
type MiniComponent = (mini: Mini) => MiniHtmlString;
type MiniHandler = (event: any) => unknown;

type MiniHtmlString = {
  stringLiterals: TemplateStringsArray;
  values: MiniValue[];
  resolve(mini?: Mini): ResolvedMiniHtmlString;
  build(mini?: Mini, root?: string, config?: Bun.BuildConfig): Promise<Skeleton>;
  renderBackend(mini?: Mini): string;
};

type Mini = {
  html: typeof html;
  state<T>(name: string, value: T, global?: boolean): StateObject<T>;
  cacheAndCursor: CacheAndCursor;
  fill(...args: MiniValue[]): Blob; // only on skeleton.mini()
};

type Skeleton = {
  static_routes: BunStaticRoutes; // put these in Bun.serve({ routes })
  fill(...args: MiniValue[]): Blob;
  mini(): Mini;
};

type MiniArtifact = {
  schema: "mini_artifact/1";
  version: string;
  sha256: string;
  files: { path: string; sha256: string }[];
};

See Also