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