Skip to content
τjs - Composing systems τjs - Composing systems

Getting Started with τjs

τjs registers application routes from taujs.config.ts as real Fastify routes. After Fastify dispatches one of those routes, τjs coordinates its policy, data and rendering before handing the response to the React, Vue or Solid renderer selected by the application.

Create a project

Section titled “Create a project”

@taujs/create-taujs scaffolds a working application and asks which framework and package manager to use:

Terminal window
npx @taujs/create-taujs my-app
cd my-app
npm run dev

If you selected another package manager, use the command printed by the scaffolder. You can also open the StackBlitz starter.

The generated project includes:

  • taujs.config.ts, containing one application with its renderer and routes
  • server and client entries for the selected framework
  • an SSR route and a streaming route
  • a small service registry and example service
  • development, build and production scripts

The application contract

Section titled “The application contract”

Each application declares one renderer and any routes whose responses the server should orchestrate. A declared route chooses ssr or streaming; hydration is a separate decision.

{
  appId: "main",
  entryPoint: "",
  renderer: reactRenderer({ project: "./tsconfig.json" }),
  routes: [
    {
      path: "/",
      attr: {
        render: "ssr",
        hydrate: true,
      },
    },
    {
      path: "/products/:id",
      attr: {
        render: "streaming",
        hydrate: true,
      },
    },
  ],
}

The same application shape works with vueRenderer() or solidRenderer(). See the configuration reference for the complete contract.

A route can also declare head metadata, critical data, deferred data, authentication and Content Security Policy. These declarations are optional: components can still perform UI-local work and client-side fetching when that work does not belong to the server response contract.

Undeclared routes stay client-rendered

Section titled “Undeclared routes stay client-rendered”

Client-side rendering is not a third value of attr.render. It happens by omission: a URL known to the client router but absent from taujs.config.ts stays client-rendered once the application has loaded in the browser.

For a direct request to such a URL, something must still serve the application document:

  • a Fastify instance created by τjs supplies the SPA fallback document
  • a Fastify instance supplied by the caller requires an explicit terminal /* τjs route when τjs should own unmatched document URLs

See Request Contracts & Data and Host Ownership for the full boundary.

Request flow

Section titled “Request flow”
  1. Fastify matches the request to a declared τjs route.
  2. τjs resolves route policy, head work and critical data.
  3. The selected renderer produces an SSR or streaming response.
  4. Deferred entries can continue behind native framework boundaries without delaying independent shell content.
  5. Hydration starts from the server snapshot when the route enables it.

The Architecture guide explains the ownership boundaries. Data Loading covers critical and deferred loaders.

Fastify ownership

Section titled “Fastify ownership”

The scaffold lets τjs create Fastify, then calls app.listen() from the server entry. You can instead pass an existing Fastify instance to createServer. In that form, the caller owns the host and τjs installs its declared routes and facilities inside an encapsulated scope.

That distinction affects the SPA fallback document, host-wide CSP, request identity and not-found handling. Read Host Ownership before embedding τjs into an existing server.

Development and production

Section titled “Development and production”

In development, Vite supplies framework transforms and HMR while the generated server process reloads as its TypeScript changes. τjs also exposes its development request graph and episode tooling.

In production, the application build contains its client assets and server-rendering modules. Fastify dispatches the registered routes and serves the configured static assets; the development recorder and Vite middleware are absent.

Where to go next

Section titled “Where to go next”