Routes
Dynamic Parameters

Routing & Navigation

Routing in Carats is data, not a filesystem. Every route is declared in a single facets object that the client and the server share.

Routes

The routes map goes from a route pattern to a page component. The pattern is matched exactly, except for segments that start with a colon, which capture a parameter.

// src/client/facets.cara.ts
import { defineFacets } from '@carats/render';
import ErrorPage from './pages/_error';
import NotFound from './pages/_not_found';
import Home from './pages/home';
import Market from './pages/market';
import Profile from './pages/profile';
import Trade from './pages/trade';

export default defineFacets({
    routes: {
        '/': Home,
        '/profile': Profile,
        '/market': Market,
        '/trade/:symbol': Trade
    },
    suspense: {
        error: ErrorPage,
        notFound: NotFound
    },
    inAppRouting: true
});

A page folder name is a convention, not a requirement. The folder keeps related files together, but the route a folder serves is whatever string it is mapped to, so `/market` can live in a folder called `browse` if that reads better.

Dynamic Parameters

A :name segment becomes a prop on the page component, and it is also available as params.name inside a culet for the same route. The name must match on both sides.

// src/client/pages/trade/index.tsx
import { Burnish } from '@carats/render';
import Layout from '../_layout';
import './trade.sass';

export default Burnish<TradeData>(function (data) {
    this.head = <title>Trade {data.symbol}</title>;
    return (
        <Layout>
            <h1>{data.symbol}</h1>
        </Layout>
    );
});

`/trade/btc` renders this page with `data.symbol` resolved from the culet registered for the same route, and the page renders a different `` for every symbol. The framework does the matching in `getPageComponent`, which returns the component, the extracted `params` and the matched `route`.<blockquote>Route patterns are matched by @carats/url with matchRoute. There is no wildcard, no optional segment and no catch-all: an unmatched URL renders the notFound suspense component instead.</blockquote><h2>In-App Routing</h2>With inAppRouting enabled, the client intercepts clicks on internal anchors and swaps the page without a full page load. It also requires clientRender() in the client entrypoint. Turn it off when a page depends on a full document load, for example a page that must run a third-party script on every navigation.<pre><code class="hljs language-typescript">// src/client/entrypoint.tsimport { mount, clientRender } from '@carats/csr';import facets from './facets.cara';mount(facets);clientRender();</code></pre>Both lines are required when in-app routing is on. `mount` registers the facets in the browser, and `clientRender` starts intercepting navigation.Links need no framework component. A plain anchor is intercepted automatically, and a normal link is followed normally if the interception is disabled, which means pages stay crawlable and work without JavaScript.<h2>Programmatic Navigation</h2>goTo from @carats/csr navigates the same way an intercepted link click does. It is the right way to submit a search box or any other form that should not reload the document.<pre><code class="hljs language-tsx">import { goTo } from '@carats/csr';import { afterMount } from '@carats/hooks';import './search-bar.sass';export default function SearchInput() { afterMount(() => { const form=document.getElementById('search-bar'); const submit=(e: Event) => { e.preventDefault(); const input=document.getElementById('search-input') as HTMLInputElement; goTo(`/search?q=${input.value}`); }; form?.addEventListener('submit', submit); return () => form?.removeEventListener('submit', submit); }); return ( <form id="search-bar"> <input id="search-input" name="q" type="text" /> </form> );}</code></pre>Build the query string with the standard `URLSearchParams`, which handles the encoding for you. To read the parameters of the current route from a component, ask a culet for them: a culet receives the matched parameters in `req.params`, and the page receives whatever the culet returned.<h2>Suspense States</h2>The suspense map supplies the components used when a route cannot produce a page: notFound for an unmatched URL and error for a component or culet that threw. Both are optional, and error receives the thrown Error as its only argument.<pre><code class="hljs language-tsx">// src/client/pages/_not_found/index.tsximport Layout from '../_layout';import './notfound.sass';export default function NotFound() { return ( <Layout> <section class="notfound-page container"> <div class="notfound-code">404</div> <h1>Page not found</h1> <a href="/" class="btn btn-primary">Return to Dashboard</a> </section> </Layout> );}</code></pre><pre><code class="hljs language-tsx">// src/client/pages/_error/index.tsximport Layout from '../_layout';import './error.sass';export default function ErrorPage(error: Error) { return ( <Layout> <section class="error-page container"> <h1>Something went wrong</h1> <p class="error-message">{error.message}</p> <a href="/" class="btn btn-primary">Return to Dashboard</a> </section> </Layout> );}</code></pre>Wrap both in the shared layout. A failing page that renders without the site chrome is much harder to diagnose than one that keeps the header and navigation.</div> </article> </main> <footer> ◆ carats · documentation</footer> </div> <script src="/static/js/ui.js"></script> <script type="module" src="/static/js/search.js" defer></script> </body></html>

Contents

Routing & Navigation

Routes

Dynamic Parameters