README

tcmts.react.README · #5ah2anx7 · md file

react

React's routes, links and data for a tcm app, as a library: tcm ships it, so tcm lib add tcm react adds the release your tcm has, with no network (and tcm lib upgrade react the one a newer tcm has). It's also announced by tcm.codes (tcm lib add @tcm.codes/react), and comes by hash from any tcm server that has it. It's a tcm library, not an npm package: it holds everything its code uses but React itself, so a codebase that adds it has every definition named.

import { Pages, Stylesheet, useAppLinks, useData, useLocation } from "#codebase/app/lib/react";
import { styles } from "#codebase/app";

export const App = () => {
  useAppLinks();
  return (
    <>
      <Stylesheet css={styles} />
      <Pages routes={{ "/": Home, "/n/:id": Note }} />
    </>
  );
};
const Note = ({ params }: { params: { id: string } }) => {
  const note = useData(`note:${params.id}`, () => readNote(params.id), { keep: true });
  return <h1>{note.value?.title}</h1>;
};

What it has

• The location: useLocation() (the path, query and fragment; re-renders when they change, and reads the page's URL in the server's first paint), navigate(to), useNavigating() while a navigation renders, match(pattern, path) for routes like /s/:owner/:key, and href(path), a path's address under the app's base.
• Links: useAppLinks() follows the page's links to the app without reloading it.
• Data: useData(key, read) reads something once per key while the page is open; refresh reads it again.
• Updates: useAppUpdate() says when a PWA's new version is ready.
• Pages: <Pages routes={…} /> renders the route the path matches, keeps the last few pages mounted but hidden (React's <Activity>), and renders a page a link to it is pointed at ahead.
• Stylesheets: <Stylesheet css={…} /> puts CSS in the page through React's stylesheets; one of the codebase is linked to as the file the app's build serves (its manifest gives it the stylesheet role).

A navigation is a transition (state is React state, never useSyncExternalStore): what's on screen stays until the next page is ready, and <ViewTransition> can animate it (navigate, navigate-forward, navigate-back).

tcm's runtime

It reaches tcm's runtime through the page's globals the runtime sets (__TCM_BASE__, __TCM_STYLESHEETS__, __TCM_TREES__, __tcmPrefetch, __tcmUpdate): version 1 of tcm's host protocol, as its manifest says. A tcm that doesn't serve that version won't build an app using it, rather than build one that breaks.

Its versions follow semver from its API, as any package's do (releases).