Referencia de API

Referencia completa de API para @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

Renderiza un elemento JSX en un contenedor DOM. Pasa routes, notFoundRoute y errorRoute desde virtual:emberkit-routes para enrutamiento cliente y páginas 404/500 integradas.

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,
});

Consulta View Transitions.

hydrate

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

Hidrata HTML renderizado en el servidor con interactividad en el cliente.

createElement

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

Crea un elemento JSX. Lo usa la transformación JSX.

Señales

createSignal

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

Crea una señal reactiva.

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

createMemo

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

Crea un valor derivado que se actualiza cuando cambian las dependencias.

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

createEffect

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

Ejecuta un efecto secundario cuando cambian las dependencias. Devuelve una función de limpieza.

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

batch

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

Agrupa varias actualizaciones de señal en una sola notificación.

untrack

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

Lee señales sin registrarlas como dependencias.

Contexto

createContext

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

Crea un contexto con métodos Provider y use.

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

useContext

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

Lee el valor de contexto más cercano por encima del componente actual.

Viewport (lazy en vista)

Diferir renderizado e hidratación de secciones pesadas hasta que estén cerca del viewport. Consulta Hidratación — Carga diferida en viewport para conceptos y pruebas.

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>

Se invoca automáticamente tras render() en el cliente — rara vez llamarás los helpers siguientes salvo un flujo de montaje personalizado.

hydrateLazyInView

hydrateLazyInView(container: Element): void

Busca [data-ek-lazy-in-view]:not([data-ek-lazy-loaded]) bajo container, observa cada host, monta hijos registrados al ser visibles y ejecuta hidratación del subárbol (handlers + señales).

clearLazyRegistry

clearLazyRegistry(): void

Limpia cargadores de contenido en memoria. Útil en tests o desmontaje completo de la app.

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

Navegación programática.

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

Helpers de view transition

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>

Consulta View Transitions.

getCached / setCache

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

Caché en memoria para compartir datos en el cliente (p. ej. precarga antes de render()). Combínalo con la guía de hidratación para listas dinámicas al usar SSR + .map().

preload

preload(path: string): void

Precarga una página añadiendo un enlace prefetch al <head> del documento.

redirect

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

Redirección en el servidor. Lanza una Response.

Markdown

renderMarkdown

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

Renderiza Markdown a HTML.

extractFrontmatter

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

Extrae frontmatter YAML del Markdown.

getReadingTime

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

Estima el tiempo de lectura en minutos.

Formularios

handleFormSubmit

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

Gestiona el envío de formulario con validación.

createFormValidator

createFormValidator(schema: ValidationSchema): FormValidator

Crea un validador de formulario desde un esquema.

parseFormData

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

Extrae los datos del formulario como objeto plano.

Internacionalización

Consulta la guía completa: Internacionalización (i18n).

createI18n

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

Crea una instancia i18n desde catálogos en memoria (TypeScript u objetos JSON parseados).

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

Crea una instancia i18n desde objetos JSON (imports estáticos o datos parseados). El JSON anidado se aplana a claves con punto.

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

Carga cada locale desde resultados de import.meta.glob de Vite. El código de locale se deduce del nombre de archivo (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>

Obtiene catálogos JSON por red y crea una instancia i18n. Úsalo con archivos en public/locales/.

fetchLocaleMessages

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

Obtiene y parsea JSON de locale sin crear instancia.

createI18nContext

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

Proporciona t() consciente del locale vía contexto al estilo React.

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

Resuelve el locale activo desde una Request entrante (loaders SSR, handlers edge).

Helpers de ruta

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

Utilidades para prefijos de URL [locale].

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

Solo Node (@emberkit/core/i18n/node)

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

Cargadores de sistema de archivos para SSR Node y scripts. No disponibles en runtimes edge.

Meta

generateMeta

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

Genera meta tags HTML desde metadatos.

generateArticleSchema

generateArticleSchema(data: ArticleData): string

Genera esquema JSON-LD Article.

generateProductSchema

generateProductSchema(data: ProductData): string

Genera esquema JSON-LD Product.

generateBreadcrumbs

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

Genera esquema JSON-LD BreadcrumbList.

SSR y head

renderToHTMLString

renderToHTMLString(element: JSXNode | null): string

Convierte un árbol de elementos JSX en fragmento HTML. Texto y atributos string se escapan en HTML.

drainHeadContent

drainHeadContent(): string

Devuelve y limpia las etiquetas registradas por <Head> durante el pase de render actual. Úsalo en handlers entry-server personalizados.

RouteParams

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

Forma de props para componentes de ruta dinámica (SSR y cliente).

LoaderFunction

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

LoaderContext incluye params, query y request. Úsalo con createLoaderData() para resultados exitosos.

Config

defineConfig

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

Se usa en emberkit.config.ts para mode, server, build, opciones vite anidadas y devApi opcional. Consulta SSR y SSG y Dev API.

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

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

ExportDescripción
emberkitVitePlugin(options?)Rutas, middleware SSR, MDX, manifiesto
devApiPlugin(options)Solo dev /api → handler Node
sqlRawPlugin()Empaqueta *.sql?raw como literales string
registerDevApiMiddleware(server, options)Adjuntar middleware API personalizado
registerFileBasedDevApiMiddleware(server)Adjuntar enrutamiento src/routes/_api/*
isApiRequest(url)Verdadero para /api y /api/*

Siguientes pasos