mininext
mininext Version 0.9.1Documentation |
For the ideas behind the API, see Architecture and Getting Started.
| Import | Contains | Use it in |
|---|---|---|
@spirobel/mininext | everything: html, build(), fill(), crawl() and the browser parts | server code |
@spirobel/mininext/browser | html, renderRoot, createRouter, types | frontend 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 literalFile: mininext/core.ts
function html(stringLiterals: TemplateStringsArray, ...values: MiniValue[]): MiniHtmlString;
Only the literal parts are html. Every ${value} is data:
| Value | Between tags | In an attribute |
|---|---|---|
string, number | text (escaped, never markup) | the attribute value (escaped, quoted) |
null, undefined, false | nothing | no attribute |
true | nothing | boolean attribute, like disabled |
html\...`` | a nested template | refused |
(mini) => value | a component, runs every render. it returns html or any value in this table | refused |
(event) => ... | refused | handler, only in on* attributes: onclick=${() => go(id)} |
| array | a list, one slot per item | refused |
| plain object | refused | refused |
The full rules (url checks, srcdoc, values in <style>) are in Architecture: Values.
const greeting = html`<h1 class="${cls}">Hello, ${name}!</h1>`;
renderRoot start renderingFile: 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>`,
});
component once per requestAnimationFrame. A hidden tab gets about one frame per second.Text.nodeValue, setAttribute, live properties (value, checked, selected) and handler properties. A frame with no change writes nothing to the DOM.renderRoot call on the same container (hot reload) swaps the component and keeps the state.createRouter hash routerFile: 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();
root is the folder that relative src and href start from. It defaults to the folder of the file that calls build().${null} becomes a numbered placeholder (__mini_null_0__, ...). The same skeleton gives the same html on every build.NODE_ENV=production: Bun.build() bundles and minifies the scripts and styles. static_routes serves the files. A page without scripts gets no empty script chunk.bun --hot): the page goes through Bun's own html bundler, so frontend edits hot swap and keep state. A server edit reloads the page.skeleton.fill() fill the placeholdersskeleton.fill(...values: MiniValue[]): Blob;
"/": () => new Response(skeleton.fill(html`<p>count ${count}</p>`)),
${null} placeholders in order.href="${null}", takes only a string or a number, with the same checks as a template value.Blob with type text/html;charset=utf-8.skeleton.mini() request stateskeleton.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() stateFile: mininext/minicache.ts
mini.state<T>(name: string, initial: T, global?: boolean): { value: T; name: string };
initial. Later calls return the same object. Change it with .value.global: true (always on the server) shares one scope for the whole page or request.mini.htmlThe 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();
paths (default ["/"]) and follows every same-origin href, src and css url()./docs is written as docs/index.html, so any static host can serve it.mini_artifact.json: the sha256 of each file, and one sha256 of the whole site. The combined hash uses sha256sum lines, so a shell can check it too.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 }[];
};