Routes and documents

API references extracted from the Gracile code base.
Examples, functions, classes, constants, type declarations…

Function: defineRoute()

function defineRoute<
  GetHandlerData,
  PostHandlerData,
  CatchAllHandlerData,
  StaticPathOptions,
  RouteContext,
>(options): (RouteModule) => R.RouteModule;

Defines a file-based route for Gracile to consume.

Type parameters

Type Parameter	Default type
`GetHandlerData` extends `HandlerDataHtml`	`undefined`
`PostHandlerData` extends `HandlerDataHtml`	`undefined`
`CatchAllHandlerData` extends `HandlerDataHtml`	`undefined`
`StaticPathOptions` extends `undefined` \| `StaticPathOptionsGeneric`	`undefined`
`RouteContext` extends `RouteContextGeneric`	`object`

Parameters

Parameter	Type	Description
`options`	`object`	Options to populate the current route module.
`options.document`?	`DocumentTemplate`<`RouteContext`>	A function that returns a server only template. Route context is provided at runtime during the build. See documentation
`options.handler`?	`StaticPathOptions` extends `object` ? `never` : `undefined` \| `Handler`<`CatchAllHandlerData`> \| `object`	A function or an object containing functions named after HTTP methods. A handler can return either a standard `Response` that will terminate the request pipeline, or any object to populate the current route template and document contexts. See documentation
`options.prerender`?	`boolean`	A switch to produce an HTML file as it was built with the `static` mode, in the `dist/client` build directory. Only available in `static` output mode. See documentation
`options.staticPaths`?	() => `undefined` \| `MaybePromise`<`StaticPathOptions`[]>	A function that returns an array of route definition object. Only available in `static` output mode. See documentation
`options.template`?	`BodyTemplate`<`RouteContext`>	A function that returns a server only or a Lit client hydratable template. Route context is provided at runtime during the build. See documentation

Returns

Function

Parameters

Parameter	Type
`RouteModule`	typeof `R.RouteModule`

Returns

R.RouteModule

See full guide in the documentation.

Defined in

packages/server/dist/route.d.ts:7

Function: html()

function html(strings, ...values): ServerRenderedTemplate;

A lit-html template that can only be rendered on the server, and cannot be hydrated.

These templates can be used for rendering full documents, including the doctype, and rendering into elements that Lit normally cannot, like <title>, <textarea>, <template>, and non-executing <script> tags like <script type="text/json">. They are also slightly more efficient than normal Lit templates, because the generated HTML doesn’t need to include markers for updating.

Server-only html templates can be composed, and combined, and they support almost all features that normal Lit templates do, with the exception of features that don’t have a pure HTML representation, like event handlers or property bindings.

Server-only html templates can only be rendered on the server, they will throw an Error if created in the browser. However if you render a normal Lit template inside a server-only template, then it can be hydrated and updated. Likewise, if you place a custom element inside a server-only template, it can be hydrated and update like normal.

A server-only template can’t be rendered inside a normal Lit template.

Parameters

Parameter	Type
`strings`	`TemplateStringsArray`
…`values`	`unknown`[]

Returns

ServerRenderedTemplate

Defined in

node_modules/.pnpm/@lit-labs+ssr@3.2.2/node_modules/@lit-labs/ssr/lib/server-template.d.ts:35

Function: pageAssetsCustomLocation()

function pageAssetsCustomLocation(): ServerRenderedTemplate;

Overrides the default location for routes sibling assets, which is normally right before the closing </head> tag.

Returns

ServerRenderedTemplate

Example

import { pageAssetsCustomLocation } from '@gracile/gracile/document';
import { html } from '@gracile/gracile/server-html';

export const document = (_props) => html`
  <!doctype html>
  <html lang="en">
    <head>
      <!-- ... -->

       Route sibling assets injection marker.  
      ${pageAssetsCustomLocation()}

      <!-- ... -->
    </head>

    <body>
      <route-template-outlet></route-template-outlet>
    </body>
  </html>
`;

Defined in

packages/server/dist/assets.d.ts:32