API Reference

Complete API reference for @emberkit/core.

Runtime

render

render(
  element: JSXElement | string | null | ((props: Record<string, unknown>) => JSXNode),
  container: Element | string,
  options?: {
    hydrate?: boolean;
    viewTransitions?: boolean | { rootId?: string };
    routes?: Array<{
      path: string;
      component: () => Promise<{ default: (props: Record<string, unknown>) => JSXNode }>;
    }>;
    notFoundRoute?: () => Promise<{ default: (props: Record<string, unknown>) => JSXNode }>;
    errorRoute?: () => Promise<{ default: (props: Record<string, unknown>) => JSXNode }>;
  }
): void

Renders a JSX element into a DOM container. Pass routes, notFoundRoute, and errorRoute from virtual:emberkit-routes for file-based client routing and default 404/500 handling.

import { render } from '@emberkit/core';
import { routes, notFoundRoute, errorRoute } from 'virtual:emberkit-routes';
import App from './routes/_layout.tsx';

render(App, document.getElementById('app')!, {
  routes,
  notFoundRoute,
  errorRoute,
  viewTransitions: true,
});

See View Transitions.

hydrate

hydrate(
  element: JSXElement | string | null,
  container: Element | string
): void

Hydrates server-rendered HTML with client-side interactivity.

createElement

createElement(
  type: string | ((props) => JSXNode),
  props?: Record<string, unknown> | null,
  ...children: unknown[]
): DOMElement

Creates a JSX element. Used by the JSX transform.

Signals

createSignal

createSignal<T>(
  initialValue: T,
  options?: { equals?: (prev: T, next: T) => boolean }
): [() => T, (newValue: T) => void] & Signal<T>

Creates a reactive signal.

const [count, setCount] = createSignal(0);
console.log(count()); // 0
setCount(1);

createMemo

createMemo<T>(
  computation: () => T,
  options?: SignalOptions<T>
): Signal<T>

Creates a derived value that updates when dependencies change.

const doubled = createMemo(() => count() * 2);
console.log(doubled.value); // reactive

createEffect

createEffect(
  callback: () => void | (() => void)
): () => void

Runs a side effect when dependencies change. Returns a cleanup function.

const dispose = createEffect(() => {
  document.title = `Count: ${count()}`;
  return () => { /* cleanup */ };
});

batch

batch<T>(fn: () => T): T

Groups multiple signal updates into a single notification.

untrack

untrack<T>(fn: () => T): T

Reads signals without tracking them as dependencies.

Context

createContext

createContext<T>(defaultValue?: T): ContextBridge<T>

Creates a context with Provider and use methods.

const ThemeContext = createContext<'light' | 'dark'>('light');

useContext

useContext<T>(context: Context<T>): T

Reads the nearest context value above the current component.

Viewport (lazy in view)

Defer rendering and hydrating heavy sections until they are near the viewport. See Hydration — Viewport lazy loading for concepts and testing.

LazyInView

function LazyInView(props: LazyInViewProps): JSXNode
interface LazyInViewProps {
  children: JSXNode | (() => JSXNode);
  fallback?: JSXNode;
  rootMargin?: string;      // default '200px'
  minHeight?: string | number;
  once?: boolean;             // default true
  ssr?: 'lazy' | 'eager';     // default 'lazy'
  as?: string;                // default 'div'
  className?: string;
  style?: Record<string, unknown>;
}
import { LazyInView } from '@emberkit/core';

<LazyInView minHeight="20rem" fallback={<div className="min-h-80 animate-pulse" />}>
  <ExpensiveSection />
</LazyInView>

Called automatically after client render() — you rarely call the helpers below unless you implement a custom mount flow.

hydrateLazyInView

hydrateLazyInView(container: Element): void

Finds [data-ek-lazy-in-view]:not([data-ek-lazy-loaded]) under container, observes each host, mounts registered children when visible, then runs subtree hydration (handlers + signals).

clearLazyRegistry

clearLazyRegistry(): void

Clears in-memory content loaders. Useful in tests or full app teardown.

navigate(
  to: string,
  options?: {
    replace?: boolean;
    state?: Record<string, unknown>;
    viewTransition?: boolean;
  }
): Promise<void>

Programmatic navigation.

navigate('/about');
navigate('/new', { replace: true });
await navigate('/docs', { viewTransition: true });

View transition helpers

supportsViewTransitions(): boolean
withViewTransition(callback: () => void | Promise<void>): Promise<void>
waitForAppUpdate(href: string, options?: { replace?: boolean; rootId?: string }): Promise<void>
initViewTransitions(options?: { rootId?: string }): void
navigateWithViewTransition(href: string, options?: { replace?: boolean; rootId?: string }): Promise<void>

See View Transitions.

getCached / setCache

getCached<T>(key: string): T | null
setCache<T>(key: string, data: T, ttl?: number): void

In-memory cache for client-side data sharing (e.g. preload before render()). Pair with hydration guidance for dynamic lists when using SSR + .map().

preload

preload(path: string): void

Prefetches a page by adding a prefetch link to the document head.

redirect

redirect(to: string, status?: number): never

Server-side redirect. Throws a Response.

Markdown

renderMarkdown

renderMarkdown(
  content: string,
  options?: MarkdownOptions
): string

Renders Markdown to HTML.

extractFrontmatter

extractFrontmatter(
  content: string
): { data: Record<string, unknown>; content: string } | null

Extracts YAML frontmatter from Markdown.

getReadingTime

getReadingTime(text: string, wpm?: number): number

Estimates reading time in minutes.

Forms

handleFormSubmit

handleFormSubmit(
  event: SubmitEvent,
  config: FormConfig
): Promise<boolean>

Handles form submission with validation.

createFormValidator

createFormValidator(schema: ValidationSchema): FormValidator

Creates a form validator from a schema.

parseFormData

parseFormData(form: HTMLFormElement): Record<string, unknown>

Extracts form data as a plain object.

Internationalization

See the full guide: Internationalization (i18n).

createI18n

createI18n(config, options?: { strict?: boolean }): I18nInstance

Creates an i18n instance from in-memory message catalogs (TypeScript or parsed JSON objects).

const i18n = createI18n({
  locales: ['en', 'es'] as const,
  defaultLocale: 'en',
  messages: { en, es },
});

createI18nFromJson

createI18nFromJson(
  config: { locales; defaultLocale; fallbackLocale?; messages: Record<Locale, unknown> },
  options?: { strict?: boolean }
): I18nInstance

Creates an i18n instance from JSON objects (static imports or parsed data). Nested JSON is flattened to dot keys.

import en from './locales/en.json';
import es from './locales/es.json';

const i18n = createI18nFromJson({
  locales: ['en', 'es'] as const,
  defaultLocale: 'en',
  messages: { en, es },
});

createI18nFromGlob

createI18nFromGlob(
  modules: Record<string, { default?: unknown } | unknown>,
  config: { locales; defaultLocale; fallbackLocale? },
  options?: { strict?: boolean }
): I18nInstance

Loads every locale from Vite import.meta.glob results. Locale code is derived from the file name (en.json → en).

const modules = import.meta.glob('./locales/*.json', { eager: true });
const i18n = createI18nFromGlob(modules, {
  locales: ['en', 'es'] as const,
  defaultLocale: 'en',
});

createI18nFromUrls

createI18nFromUrls(
  urls: Record<Locale, string>,
  config: { locales; defaultLocale; fallbackLocale? },
  options?: { strict?: boolean }
): Promise<I18nInstance>

Fetches JSON catalogs over the network and creates an i18n instance. Use with files in public/locales/.

fetchLocaleMessages

fetchLocaleMessages(urls: Record<Locale, string>): Promise<Record<Locale, MessageCatalog>>

Fetches and parses locale JSON without creating an instance.

createI18nContext

createI18nContext<TKeys extends string = string>(): {
  Provider: (props: { i18n; locale?; children? }) => JSXNode;
  useI18n: () => I18nInstance<TKeys>;
  context: ContextBridge;
}

Provides locale-aware t() via React-style context.

I18nInstance

interface I18nInstance {
  locale: string;
  t(key, values?): string;
  tp(key, count, values?): string;
  setLocale(locale): void;
  getLocale(): string;
  hasKey(key, locale?): boolean;
  formatDate(value, options?): string;
  formatNumber(value, options?): string;
  formatRelativeTime(value, unit, options?): string;
}

resolveLocaleFromRequest

resolveLocaleFromRequest(request: Request, options: {
  locales: readonly string[];
  defaultLocale: string;
  strategy?: 'path-prefix' | 'header' | 'cookie' | 'query' | Array<...>;
  cookieName?: string;
  queryParam?: string;
}): string

Resolves the active locale from an incoming Request (SSR loaders, edge handlers).

Path helpers

extractLocaleFromPath(pathname, supported): { locale; pathnameWithoutLocale }
stripLocalePrefix(pathname, supported): string
addLocalePrefix(pathname, locale): string
localizePath(pathname, locale, supported): string

Utilities for [locale] URL prefixes.

Catalog helpers

defineMessages(catalog): typeof catalog
parseMessageCatalog(input: unknown): MessageCatalog
parseMessageCatalogJson(json: string): MessageCatalog
mergeMessageCatalogs(...catalogs): MessageCatalog
localeFromJsonPath(path): string

Node-only (@emberkit/core/i18n/node)

readLocaleCatalog(filePath: string): MessageCatalog
loadLocalesFromDirectory(directory: string): Record<Locale, MessageCatalog>
createI18nFromDirectory(directory, config, options?): I18nInstance

Filesystem loaders for Node.js SSR and scripts. Not available on edge runtimes.

Meta

generateMeta

generateMeta(data: MetaData, baseUrl?: string): string

Generates HTML meta tags from metadata.

generateArticleSchema

generateArticleSchema(data: ArticleData): string

Generates JSON-LD Article schema.

generateProductSchema

generateProductSchema(data: ProductData): string

Generates JSON-LD Product schema.

generateBreadcrumbs

generateBreadcrumbs(items: Array<{ name: string; url: string }>): string

Generates JSON-LD BreadcrumbList schema.

SSR & head

renderToHTMLString

renderToHTMLString(element: JSXNode | null): string

Converts a JSX element tree to an HTML fragment. Text and string attributes are HTML-escaped.

drainHeadContent

drainHeadContent(): string

Returns and clears tags registered by <Head> during the current render pass. Use in custom entry-server handlers.

RouteParams

interface RouteParams<T extends Record<string, string> = Record<string, string>> {
  params: T;
  query: Record<string, string | string[]>;
  request: Request;
}

Props shape for dynamic route components (SSR and client).

LoaderFunction

type LoaderFunction<T = unknown> = (
  context: LoaderContext
) => Promise<LoaderResult<T>> | LoaderResult<T>;

LoaderContext includes params, query, and request. Use with createLoaderData() for success results.

Config

defineConfig

defineConfig(config: Record<string, unknown>): Record<string, unknown>

Used in emberkit.config.ts for mode, server, build, nested vite options, and optional devApi. See SSR & SSG and Dev API.

export default defineConfig({
  mode: 'ssr',
  devApi: {
    handler: './src/server/api.node.ts',
    export: 'handleRequest',
  },
});

Vite plugin (@emberkit/core/vite-plugin)

ExportDescription
emberkitVitePlugin(options?)Routes, SSR middleware, MDX, manifest
devApiPlugin(options)Dev-only /api → Node handler
sqlRawPlugin()Bundle *.sql?raw as string literals
registerDevApiMiddleware(server, options)Attach custom API middleware
registerFileBasedDevApiMiddleware(server)Attach src/routes/_api/* routing
isApiRequest(url)True for /api and /api/*

Next Steps