@thexjs/core 1.2.3 → 1.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/adapter.d.ts +52 -52
- package/dist/adapter.js +151 -152
- package/dist/data.d.ts +7 -7
- package/dist/data.js +78 -78
- package/dist/index.d.ts +154 -112
- package/dist/index.js +1360 -1234
- package/package.json +6 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,44 +1,5 @@
|
|
|
1
1
|
import * as react from 'react';
|
|
2
|
-
import { ComponentType, ReactNode, AnchorHTMLAttributes } from 'react';
|
|
3
|
-
|
|
4
|
-
interface RouteEntry {
|
|
5
|
-
filePath: string;
|
|
6
|
-
routePath: string;
|
|
7
|
-
paramNames: string[];
|
|
8
|
-
isApi: boolean;
|
|
9
|
-
}
|
|
10
|
-
interface MiddlewareEntry {
|
|
11
|
-
filePath: string;
|
|
12
|
-
dirPath: string;
|
|
13
|
-
}
|
|
14
|
-
/** Scan page routes — same as scanRoutes but never marks anything as api. */
|
|
15
|
-
declare function scanPages(rootDir: string): RouteEntry[];
|
|
16
|
-
/** Scan API routes from a separate directory (not nested under pages/routes).
|
|
17
|
-
* Route paths are prefixed with /api so they match requests to /api/…. */
|
|
18
|
-
declare function scanApiDir(rootDir: string): RouteEntry[];
|
|
19
|
-
declare function scanRoutes(rootDir: string): RouteEntry[];
|
|
20
|
-
interface LayoutEntry {
|
|
21
|
-
filePath: string;
|
|
22
|
-
dirPath: string;
|
|
23
|
-
}
|
|
24
|
-
declare function scanLayouts(rootDir: string): LayoutEntry[];
|
|
25
|
-
/**
|
|
26
|
-
* Scan a dedicated layouts directory. Every layout file found is registered
|
|
27
|
-
* as a root-level layout. The file name becomes the layout key (e.g.
|
|
28
|
-
* main.tsx -> "main"), and it covers the root path "/" so it wraps every page.
|
|
29
|
-
* Nested _layout.tsx files inside pages/ still work for directory-level
|
|
30
|
-
* nesting — this is additive, not exclusive.
|
|
31
|
-
*/
|
|
32
|
-
declare function scanLayoutsDir(layoutsDir: string): LayoutEntry[];
|
|
33
|
-
declare function findLayoutChain(routeFilePath: string, layouts: LayoutEntry[], routesDir: string): LayoutEntry[];
|
|
34
|
-
interface NotFoundEntry {
|
|
35
|
-
filePath: string;
|
|
36
|
-
}
|
|
37
|
-
declare function scanNotFound(rootDir: string): NotFoundEntry | null;
|
|
38
|
-
declare function scanMiddleware(rootDir: string): MiddlewareEntry[];
|
|
39
|
-
declare function findMiddlewareChain(routeFilePath: string, middleware: MiddlewareEntry[], routesDir: string): MiddlewareEntry[];
|
|
40
|
-
declare function generateManifestSource(routes: RouteEntry[]): string;
|
|
41
|
-
declare function writeManifest(routes: RouteEntry[], routesDir: string): string;
|
|
2
|
+
import { ComponentType, ReactNode, CSSProperties, AnchorHTMLAttributes } from 'react';
|
|
42
3
|
|
|
43
4
|
type RouteMode = "static" | "server";
|
|
44
5
|
interface BuildOptions {
|
|
@@ -60,6 +21,35 @@ interface BuildOptions {
|
|
|
60
21
|
}
|
|
61
22
|
declare function build(options: BuildOptions): Promise<void>;
|
|
62
23
|
|
|
24
|
+
/**
|
|
25
|
+
* Inline client-side navigation script.
|
|
26
|
+
*
|
|
27
|
+
* Embedded directly into every rendered page as a <script> tag (see render.ts).
|
|
28
|
+
* Intercepts same-origin <a> clicks, fetches the destination page, and swaps
|
|
29
|
+
* the #root element's content in place. Includes hover-prefetch and popstate
|
|
30
|
+
* (back/forward) support.
|
|
31
|
+
*
|
|
32
|
+
* Opt-out attributes on <a> / <Link />:
|
|
33
|
+
* - data-no-nav — skip client navigation (full page load)
|
|
34
|
+
* - data-no-prefetch — skip hover prefetch (navigation still works)
|
|
35
|
+
*/
|
|
36
|
+
declare const CLIENT_NAV_SCRIPT: string;
|
|
37
|
+
|
|
38
|
+
interface Frontmatter {
|
|
39
|
+
title?: string;
|
|
40
|
+
[key: string]: unknown;
|
|
41
|
+
}
|
|
42
|
+
interface ContentEntry {
|
|
43
|
+
filePath: string;
|
|
44
|
+
routePath: string;
|
|
45
|
+
slug: string;
|
|
46
|
+
frontmatter: Frontmatter;
|
|
47
|
+
body: string;
|
|
48
|
+
}
|
|
49
|
+
declare function scanContent(rootDir: string): ContentEntry[];
|
|
50
|
+
declare function escapeHtml(s: string): string;
|
|
51
|
+
declare function renderMarkdown(md: string): string;
|
|
52
|
+
|
|
63
53
|
/**
|
|
64
54
|
* Minimal remote-image proxy. Fetches an allow-listed remote image
|
|
65
55
|
* server-side and streams it back from your own origin at /_x/image, so the
|
|
@@ -254,6 +244,45 @@ declare function createOtelReporter(tracer: OtelTracerLike): ErrorReporter;
|
|
|
254
244
|
/** Combines multiple reporters — useful for sending to Sentry and OTel at once. */
|
|
255
245
|
declare function combineReporters(...reporters: ErrorReporter[]): ErrorReporter;
|
|
256
246
|
|
|
247
|
+
interface RouteEntry {
|
|
248
|
+
filePath: string;
|
|
249
|
+
routePath: string;
|
|
250
|
+
paramNames: string[];
|
|
251
|
+
isApi: boolean;
|
|
252
|
+
}
|
|
253
|
+
interface MiddlewareEntry {
|
|
254
|
+
filePath: string;
|
|
255
|
+
dirPath: string;
|
|
256
|
+
}
|
|
257
|
+
/** Scan page routes — same as scanRoutes but never marks anything as api. */
|
|
258
|
+
declare function scanPages(rootDir: string): RouteEntry[];
|
|
259
|
+
/** Scan API routes from a separate directory (not nested under pages/routes).
|
|
260
|
+
* Route paths are prefixed with /api so they match requests to /api/…. */
|
|
261
|
+
declare function scanApiDir(rootDir: string): RouteEntry[];
|
|
262
|
+
declare function scanRoutes(rootDir: string): RouteEntry[];
|
|
263
|
+
interface LayoutEntry {
|
|
264
|
+
filePath: string;
|
|
265
|
+
dirPath: string;
|
|
266
|
+
}
|
|
267
|
+
declare function scanLayouts(rootDir: string): LayoutEntry[];
|
|
268
|
+
/**
|
|
269
|
+
* Scan a dedicated layouts directory. Every layout file found is registered
|
|
270
|
+
* as a root-level layout. The file name becomes the layout key (e.g.
|
|
271
|
+
* main.tsx -> "main"), and it covers the root path "/" so it wraps every page.
|
|
272
|
+
* Nested _layout.tsx files inside pages/ still work for directory-level
|
|
273
|
+
* nesting — this is additive, not exclusive.
|
|
274
|
+
*/
|
|
275
|
+
declare function scanLayoutsDir(layoutsDir: string): LayoutEntry[];
|
|
276
|
+
declare function findLayoutChain(routeFilePath: string, layouts: LayoutEntry[], routesDir: string): LayoutEntry[];
|
|
277
|
+
interface NotFoundEntry {
|
|
278
|
+
filePath: string;
|
|
279
|
+
}
|
|
280
|
+
declare function scanNotFound(rootDir: string): NotFoundEntry | null;
|
|
281
|
+
declare function scanMiddleware(rootDir: string): MiddlewareEntry[];
|
|
282
|
+
declare function findMiddlewareChain(routeFilePath: string, middleware: MiddlewareEntry[], routesDir: string): MiddlewareEntry[];
|
|
283
|
+
declare function generateManifestSource(routes: RouteEntry[]): string;
|
|
284
|
+
declare function writeManifest(routes: RouteEntry[], routesDir: string): string;
|
|
285
|
+
|
|
257
286
|
/**
|
|
258
287
|
* CSRF protection for server actions (`/__x/actions/*`) and other mutating
|
|
259
288
|
* endpoints. Two independent checks are provided and both run by default:
|
|
@@ -492,56 +521,49 @@ interface RevalidateOptions {
|
|
|
492
521
|
declare function defineConfig(config: CreateAppOptions): CreateAppOptions;
|
|
493
522
|
declare function createApp(options: CreateAppOptions): Promise<AppServeOptions>;
|
|
494
523
|
|
|
495
|
-
declare function
|
|
524
|
+
declare function renderErrorOverlay(error: unknown): string;
|
|
496
525
|
|
|
497
|
-
interface
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
526
|
+
interface ImageProps {
|
|
527
|
+
src: string;
|
|
528
|
+
alt: string;
|
|
529
|
+
/** Intrinsic width in px. Omitted when using `fill`. */
|
|
530
|
+
width?: number;
|
|
531
|
+
/** Intrinsic height in px. Omitted when using `fill`. */
|
|
532
|
+
height?: number;
|
|
533
|
+
/** `sizes` attribute for responsive srcset. */
|
|
534
|
+
sizes?: string;
|
|
535
|
+
/** LCP image — skips lazy-loading, adds fetchpriority="high". */
|
|
536
|
+
priority?: boolean;
|
|
537
|
+
/** Absolutely-fill the parent (hero/card layouts). Mutually exclusive with width/height. */
|
|
538
|
+
fill?: boolean;
|
|
539
|
+
/** Blur placeholder mode. Requires blurDataURL for a visible effect. */
|
|
540
|
+
placeholder?: "blur" | "empty";
|
|
541
|
+
/** Tiny base64 image used as the blur placeholder until the real image loads. */
|
|
542
|
+
blurDataURL?: string;
|
|
543
|
+
/** 1-100, forwarded to the proxy as `&q=` (validated-and-ignored until a resizer exists). */
|
|
544
|
+
quality?: number;
|
|
545
|
+
className?: string;
|
|
546
|
+
style?: CSSProperties;
|
|
547
|
+
children?: ReactNode;
|
|
511
548
|
}
|
|
512
|
-
|
|
513
|
-
declare
|
|
514
|
-
declare function renderStaticPage(node: ReactNode, options?: RenderOptions): string;
|
|
515
|
-
declare function renderStreamingPage(node: ReactNode, options?: RenderOptions): Promise<ReadableStream<Uint8Array>>;
|
|
516
|
-
|
|
549
|
+
/** Candidate widths for srcset generation (px), spread across common breakpoints/DPR. */
|
|
550
|
+
declare const SRCSET_WIDTHS: number[];
|
|
517
551
|
/**
|
|
518
|
-
*
|
|
519
|
-
*
|
|
520
|
-
*
|
|
521
|
-
*
|
|
522
|
-
* the #root element's content in place. Includes hover-prefetch and popstate
|
|
523
|
-
* (back/forward) support.
|
|
524
|
-
*
|
|
525
|
-
* Opt-out attributes on <a> / <Link />:
|
|
526
|
-
* - data-no-nav — skip client navigation (full page load)
|
|
527
|
-
* - data-no-prefetch — skip hover prefetch (navigation still works)
|
|
552
|
+
* Generates a responsive srcset for a remote image by appending width params
|
|
553
|
+
* to the proxy URL (`/_x/image?url=...&w=640`, ...) — only when the src is
|
|
554
|
+
* remote and its host is in the allow-list. Local images have no resize
|
|
555
|
+
* pipeline, so they return undefined and use the intrinsic src.
|
|
528
556
|
*/
|
|
529
|
-
declare
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
frontmatter: Frontmatter;
|
|
540
|
-
body: string;
|
|
541
|
-
}
|
|
542
|
-
declare function scanContent(rootDir: string): ContentEntry[];
|
|
543
|
-
declare function escapeHtml(s: string): string;
|
|
544
|
-
declare function renderMarkdown(md: string): string;
|
|
557
|
+
declare function buildSrcSet(src: string, opts?: {
|
|
558
|
+
quality?: number;
|
|
559
|
+
remoteHosts?: string[];
|
|
560
|
+
}): string | undefined;
|
|
561
|
+
/**
|
|
562
|
+
* Set an explicit remote-host allow-list so dev-mode warnings can fail fast
|
|
563
|
+
* on a remote src whose host isn't configured. Mirrors x.config images.remoteHosts.
|
|
564
|
+
*/
|
|
565
|
+
declare function setImageRemoteHosts(hosts: string[]): void;
|
|
566
|
+
declare function Image(props: ImageProps): ReactNode;
|
|
545
567
|
|
|
546
568
|
type IslandMode = "idle" | "visible" | "load";
|
|
547
569
|
interface IslandEntry {
|
|
@@ -574,12 +596,48 @@ interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"
|
|
|
574
596
|
*/
|
|
575
597
|
declare function Link({ href, children, clientNav, prefetch, ...rest }: LinkProps): react.JSX.Element;
|
|
576
598
|
|
|
577
|
-
declare function
|
|
578
|
-
declare function resetServerFunctions(): void;
|
|
579
|
-
declare function registerServerFunctions(routePath: string, paramNames: string[], fns: Record<string, (...args: unknown[]) => Promise<unknown>>): void;
|
|
580
|
-
declare function getServerFunctionHandler(csrfOptions?: CsrfOptions): (req: Request) => Promise<Response | null>;
|
|
599
|
+
declare function DefaultNotFound(_props: RouteProps): react.JSX.Element;
|
|
581
600
|
|
|
582
|
-
|
|
601
|
+
/**
|
|
602
|
+
* Structured JSON logging. Replaces ad-hoc `console.log` with one JSON
|
|
603
|
+
* object per line — easy to ingest into Datadog, Grafana Loki, Kibana, etc.
|
|
604
|
+
*/
|
|
605
|
+
interface LogFields {
|
|
606
|
+
[key: string]: unknown;
|
|
607
|
+
}
|
|
608
|
+
interface Logger {
|
|
609
|
+
info(message: string, fields?: LogFields): void;
|
|
610
|
+
warn(message: string, fields?: LogFields): void;
|
|
611
|
+
error(message: string, fields?: LogFields): void;
|
|
612
|
+
}
|
|
613
|
+
declare const logger: Logger;
|
|
614
|
+
/**
|
|
615
|
+
* Wraps a fetch handler so every request is logged as one structured JSON
|
|
616
|
+
* line with `timestamp`, `requestId`, `route`, `status`, and `durationMs`.
|
|
617
|
+
* A second argument (Bun.serve's `server` handle) is forwarded untouched so
|
|
618
|
+
* downstream middleware like the rate limiter can resolve the client IP.
|
|
619
|
+
*/
|
|
620
|
+
declare function withRequestLogging<Server = unknown>(handler: (req: Request, server?: Server) => Response | Promise<Response>): (req: Request, server?: Server) => Promise<Response>;
|
|
621
|
+
|
|
622
|
+
interface RenderOptions {
|
|
623
|
+
title?: string;
|
|
624
|
+
islandScripts?: string[];
|
|
625
|
+
islandProps?: Record<string, string>;
|
|
626
|
+
/** Path to a stylesheet to <link> in <head>, e.g. "/styles.css". */
|
|
627
|
+
stylesheet?: string | undefined;
|
|
628
|
+
/** Set to false to omit the client-side navigation script. Defaults to true. */
|
|
629
|
+
clientNav?: boolean;
|
|
630
|
+
/** Inject live-reload script (development mode). */
|
|
631
|
+
liveReload?: boolean;
|
|
632
|
+
}
|
|
633
|
+
interface LoaderArgs {
|
|
634
|
+
params: Record<string, string>;
|
|
635
|
+
request: Request;
|
|
636
|
+
}
|
|
637
|
+
type LoaderReturn = Record<string, unknown> | Response;
|
|
638
|
+
declare function renderPage(node: ReactNode, options?: RenderOptions): string;
|
|
639
|
+
declare function renderStaticPage(node: ReactNode, options?: RenderOptions): string;
|
|
640
|
+
declare function renderStreamingPage(node: ReactNode, options?: RenderOptions): Promise<ReadableStream<Uint8Array>>;
|
|
583
641
|
|
|
584
642
|
/**
|
|
585
643
|
* Compiler boundary between server-only environment variables and the
|
|
@@ -605,25 +663,9 @@ declare class EnvLeakageError extends Error {
|
|
|
605
663
|
/** Throws EnvLeakageError if the given bundle source references non-public env vars. */
|
|
606
664
|
declare function assertNoEnvLeakage(code: string, file: string): void;
|
|
607
665
|
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
interface LogFields {
|
|
613
|
-
[key: string]: unknown;
|
|
614
|
-
}
|
|
615
|
-
interface Logger {
|
|
616
|
-
info(message: string, fields?: LogFields): void;
|
|
617
|
-
warn(message: string, fields?: LogFields): void;
|
|
618
|
-
error(message: string, fields?: LogFields): void;
|
|
619
|
-
}
|
|
620
|
-
declare const logger: Logger;
|
|
621
|
-
/**
|
|
622
|
-
* Wraps a fetch handler so every request is logged as one structured JSON
|
|
623
|
-
* line with `timestamp`, `requestId`, `route`, `status`, and `durationMs`.
|
|
624
|
-
* A second argument (Bun.serve's `server` handle) is forwarded untouched so
|
|
625
|
-
* downstream middleware like the rate limiter can resolve the client IP.
|
|
626
|
-
*/
|
|
627
|
-
declare function withRequestLogging<Server = unknown>(handler: (req: Request, server?: Server) => Response | Promise<Response>): (req: Request, server?: Server) => Promise<Response>;
|
|
666
|
+
declare function generateServerFunctionClient(routeFilePath: string, fnNames: string[], endpointBase: string): string;
|
|
667
|
+
declare function resetServerFunctions(): void;
|
|
668
|
+
declare function registerServerFunctions(routePath: string, paramNames: string[], fns: Record<string, (...args: unknown[]) => Promise<unknown>>): void;
|
|
669
|
+
declare function getServerFunctionHandler(csrfOptions?: CsrfOptions): (req: Request) => Promise<Response | null>;
|
|
628
670
|
|
|
629
|
-
export { type BuildOptions, CLIENT_NAV_SCRIPT, type ContentEntry, type CounterSeries, type CreateAppOptions, type CsrfOptions, type CsrfResult, DEFAULT_HISTOGRAM_BUCKETS_MS, DefaultNotFound, EnvLeakageError, type ErrorContext, type ErrorReporter, type Frontmatter, type HealthCheck, type HealthCheckOptions, type HistogramSeries, type ImageProxyOptions, type InMemoryMetricsOptions, type InMemoryMetricsReporter, Island, type IslandEntry, type IslandMode, IslandProvider, type LayoutEntry, Link, type LinkProps, type LoaderArgs, type LoaderReturn, type LogFields, type Logger, type MetricLabels, type MetricsReporter, type MetricsSnapshot, type MiddlewareContext, type MiddlewareEntry, type MiddlewareFn, type MiddlewareNext, type NotFoundEntry, type OtelMeterLike, type OtelTracerLike, PUBLIC_ENV_PREFIX, type RateLimitOptions, type RateLimitResult, type RateLimitStore, type ReadinessResult, type RevalidateOptions, type RouteEntry, type RouteMode, type RouteProps, type SecurityHeadersOptions, type SentryLike, applySecurityHeaders, assertNoEnvLeakage, build, buildSecurityHeaders, checkCsrf, combineReporters, composeMiddleware, createApp, createHealthCheckHandler, createImageProxyHandler, createInMemoryMetrics, createOtelReporter, createOtlpMetricsReporter, createRateLimiter, createRedisRateLimitStore, createSentryReporter, defineConfig, escapeHtml, findLayoutChain, findLeakedEnvKeys, findMiddlewareChain, generateCsrfToken, generateManifestSource, generateServerFunctionClient, getErrorReporter, getServerFunctionHandler, logger, noopMetrics, noopReporter, rateLimitMiddleware, registerServerFunctions, renderErrorOverlay, renderMarkdown, renderPage, renderStaticPage, renderStreamingPage, reportException, resetServerFunctions, scanApiDir, scanContent, scanLayouts, scanLayoutsDir, scanMiddleware, scanNotFound, scanPages, scanRoutes, setErrorReporter, verifyCsrfToken, verifyOrigin, withCsrfCookie, withRequestLogging, withRequestMetrics, writeManifest };
|
|
671
|
+
export { type BuildOptions, CLIENT_NAV_SCRIPT, type ContentEntry, type CounterSeries, type CreateAppOptions, type CsrfOptions, type CsrfResult, DEFAULT_HISTOGRAM_BUCKETS_MS, DefaultNotFound, EnvLeakageError, type ErrorContext, type ErrorReporter, type Frontmatter, type HealthCheck, type HealthCheckOptions, type HistogramSeries, Image, type ImageProps, type ImageProxyOptions, type InMemoryMetricsOptions, type InMemoryMetricsReporter, Island, type IslandEntry, type IslandMode, IslandProvider, type LayoutEntry, Link, type LinkProps, type LoaderArgs, type LoaderReturn, type LogFields, type Logger, type MetricLabels, type MetricsReporter, type MetricsSnapshot, type MiddlewareContext, type MiddlewareEntry, type MiddlewareFn, type MiddlewareNext, type NotFoundEntry, type OtelMeterLike, type OtelTracerLike, PUBLIC_ENV_PREFIX, type RateLimitOptions, type RateLimitResult, type RateLimitStore, type ReadinessResult, type RevalidateOptions, type RouteEntry, type RouteMode, type RouteProps, SRCSET_WIDTHS, type SecurityHeadersOptions, type SentryLike, applySecurityHeaders, assertNoEnvLeakage, build, buildSecurityHeaders, buildSrcSet, checkCsrf, combineReporters, composeMiddleware, createApp, createHealthCheckHandler, createImageProxyHandler, createInMemoryMetrics, createOtelReporter, createOtlpMetricsReporter, createRateLimiter, createRedisRateLimitStore, createSentryReporter, defineConfig, escapeHtml, findLayoutChain, findLeakedEnvKeys, findMiddlewareChain, generateCsrfToken, generateManifestSource, generateServerFunctionClient, getErrorReporter, getServerFunctionHandler, logger, noopMetrics, noopReporter, rateLimitMiddleware, registerServerFunctions, renderErrorOverlay, renderMarkdown, renderPage, renderStaticPage, renderStreamingPage, reportException, resetServerFunctions, scanApiDir, scanContent, scanLayouts, scanLayoutsDir, scanMiddleware, scanNotFound, scanPages, scanRoutes, setErrorReporter, setImageRemoteHosts, verifyCsrfToken, verifyOrigin, withCsrfCookie, withRequestLogging, withRequestMetrics, writeManifest };
|