Reference¶
The declarations are the module am-ssr (the panel gives them to its editor ; a commit writes them as am-ssr.d.ts next to each website).
What a file exports¶
| File | Exports |
|---|---|
A page (pages/**/*.tsx) |
default (the component), loader, action, config, head |
A layout (_layout.tsx) |
default (gets children), loader, config, head |
A middleware (_middleware.ts) |
default (or middleware) : (ctx) => answer | undefined |
_404.tsx, _error.tsx |
default (gets error), config, head |
An endpoint (pages/**/*.ts) |
GET, POST, PUT, PATCH, DELETE, ALL, config |
site.config.ts |
default : defineSite({ ... }), values only. See settings. |
The module am-ssr¶
| Export | What it is |
|---|---|
raw(html) |
HTML written as it is. Never what a visitor wrote. |
url(path) |
An address of the website with its base path, for a value which is no attribute. |
asset(path) |
A file of public/ with the hash of its content : kept a year by browsers. |
withoutBase(path) |
An address of the server outside the website. |
serialize(value) |
JSON a <script> can hold. |
escape(text) |
A text as HTML writes it. |
classNames(...values) |
classNames('btn', active && 'active', { disabled }). |
Fragment |
<>…</>. |
formatDate(value, pattern?, { utc, offsetMinutes }) |
formatDate(date, 'D MMM YYYY [at] HH:mm') : YYYY YY MMMM MMM MM M DD D dddd ddd HH H hh h mm m ss s SSS A a. UTC by default. |
formatNumber(value, { decimals, thousands, decimal }) |
1,234.50 |
formatCurrency(value, currency?, options?) |
formatCurrency(1234.5, 'USD') is $1,234.50. |
timeAgo(value, now?) |
5 minutes ago, in 2 days. |
slugify(text), truncate(text, length, more?) |
|
paginate({ page, perPage, total, window }) |
{ page, pages, total, perPage, skip, limit, items, hasPrevious, hasNext, previous, next } : items are the numbers to show, '…' where some are left out. |
json(data, { status, headers }), text(body, init) |
An answer of an endpoint, an action or a middleware. |
Response |
new Response(body, { status, headers, type }). |
redirect(location, status?, { external }) |
Stops the render : the browser goes there. Another host needs { external: true }. |
notFound(message?), forbidden(message?), error(status, message?) |
Stop the render with the page of the error. |
HttpError |
What those throw, and what a refused call of ctx.db throws : status, message, errors. |
definePage(config), defineSite(config) |
Typed settings. |
site |
{ name, title } of the website. |
ctx¶
One per request : never keep it in a variable of a module.
| Member | What it is |
|---|---|
method, url, path |
The request : path without the base path (/products), url with the query. |
params |
The values of the parts of the path : [id] is params.id, [...rest] a list. |
query |
The query : texts, a list when a name is repeated. |
headers |
The headers, their names in small letters. |
body, form |
The body (a form, JSON) ; form its fields. |
files |
The files of a form of several parts : { fieldname, originalname, mimetype, size, path, filename }. |
ip, locale |
The address of the visitor ; the language it prefers. |
csrf |
Its CSRF token (forms get it by themselves). |
dev |
The page renders for the preview of the panel. |
site |
{ name, title, base, origin } : base is /ssr/<apiPath>/<name> or nothing behind a domain, origin https://host. |
user |
The visitor who signed in, or null. |
auth |
user, isLoggedIn, groups, hasGroup(...), login({ provider, username, password }), logout(), setToken(kind, token). |
cookies |
get(name), all(), set(name, value, { maxAge, expires, path, httpOnly, secure, sameSite }), delete(name). The cookies of API Maker are not seen. |
db |
The tables the website lists : getAll, getById, query, count, distinct, distinctQuery, aggregate, saveSingleOrMultiple, masterSave, arrayOperations, updateById, updateMany, replaceById, removeById, removeByQuery, and gen.*. |
api |
api.db (the same words, as the visitor), api.customApi(path, { method, body, query, headers }). |
sys |
g.sys, when data.allowSys turns it on. |
cache |
get, set(key, value, seconds), remove, getOrSet(key, seconds, make) : Redis, the keys of the website. |
fetch(address, { method, headers, body, timeout }) |
To the hosts data.fetch lists : { status, headers, body, json }. |
revalidate(...tags) |
Drops the kept pages of these tags. |
flashes, flash(type, text) |
The messages kept for this page ; a message for the next one. |
status(code), setHeader(name, value) |
The status and the headers of the answer. |
redirect, notFound, forbidden, unauthorized, error |
As the functions of am-ssr. |
json(data, status), text(body, status), html(body, status) |
Answers. html() takes a text or what a component gives. |
link(path), asset(path), withoutBase(path) |
Addresses. |
log(...values) |
Writes to the console of the account. |
PageConfig¶
| Field | What it is |
|---|---|
title, description, image, canonical |
The head. A value, or (data, ctx) => value. |
index |
false : not indexed. |
access |
'public', 'authenticated', { authenticated, groups, providers, check }. |
cache |
{ maxAge, staleWhileRevalidate, scope, tags, query }. |
libraries |
false for none, a list of names, every library of the list by default. |
csrf |
false : an endpoint which takes requests without the token. |
sitemap |
false, or { changefreq, priority }. |
SiteConfig¶
What defineSite of site.config.ts takes, typed setting by setting : every member says what it does, its default and the values the server takes, and the editor marks a setting of another name. See settings.
| Type | What it is |
|---|---|
SiteConfig |
{ title, titleTemplate, description, lang, domains, auth, defaultAccess, data, cache, security, seo, redirects, trailingSlash, maintenance, limits } |
SiteAuth |
auth : { providers, loginPath, sessionDays }. loginPath is a path of the website (`/${string}`). |
SiteAccess |
defaultAccess : 'public', 'authenticated', { authenticated, groups, providers }, without code. |
SiteData |
data : { read, write, apiUser, allowSys, fetch }. |
TableName |
`${string}/${string}/${string}` : 'instance/database/table'. |
TableRule |
{ table, where, set, requireUser, fields, allow }. |
TableWrite |
'create', 'update', 'delete'. |
SiteSecurity |
security : { csp, frameAncestors, headers }. |
SiteSeo |
seo : { sitemap, robots, noIndex }. |
SiteRedirect |
An item of redirects : { from, to, status }, from a path. |
SiteMaintenance |
maintenance as an object : { message, allowGroups }. |
SiteLimits |
limits : { memoryMb, cpuMs, timeoutMs }. |
Props¶
PageProps<typeof loader, ActionData> |
{ data, ctx, params, actionData } |
LayoutProps<typeof loader> |
{ children, data, ctx, error } |
ErrorProps |
{ error: { status, message, stack, errors }, ctx } |
Head |
{ title, description, image, canonical, index, meta: [...], links: [...] } |
Inside the engine¶
A page runs in QuickJS, not in Node.js : the language of today (ES2023), fetch-less (use ctx.fetch), no require of npm packages, no file system. There are URL, URLSearchParams, TextEncoder, TextDecoder, crypto.randomUUID(), crypto.getRandomValues(), structuredClone, queueMicrotask, atob, btoa, console. Code shared by the pages is a file of the website (lib/) ; libraries for the browser are UI libraries.