@chidchanun/bcp 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.9 - Server data loaders
+
+### Server rendering and data
+
+- Added route-level `loader.ts` / `loader.tsx` files next to `page.tsx` for server-only page data loading before SSR.
+- Added public `useLoaderData<T>()` through `bcp` so the page consumes the same loader value during SSR, browser hydration and later client navigations.
+- Loader context includes matched route `params` and a fresh `URLSearchParams` instance for the target request query string.
+- Loaders run inside the normal request context, so `cookies()`, `headers()`, `requestUrl()`, request/auth helpers and JWT session APIs can be used directly.
+- Loader modules may import application server-only/database modules without placing those dependencies in the browser bundle.
+- Loaders may return either JSON-safe data or a Web `Response`, including `redirect()` responses.
+- Response cookies created while a loader runs are merged into the final page, navigation or redirect response.
+- Loader results are serialized into framework data with the existing script-safe serialization rules and are provided to SSR through an internal loader-data provider.
+- Loader data rejects unsupported values such as functions, symbols, BigInt, non-finite numbers, class instances, Date/Map/Set objects and circular graphs.
+- Having both `loader.ts` and `loader.tsx` next to one page is rejected as an ambiguous route configuration.
+
+### SPA navigation and cache safety
+
+- Loader-backed routes now participate in BCP SPA navigation instead of requiring a full document reload.
+- `/_bcp/navigation` executes the target route loader on the server and returns fresh loader data together with route metadata and client asset information.
+- Navigation loaders receive a request context for the target page URL rather than the internal navigation transport URL, preserving target query parameters, cookies, sessions and request helpers.
+- Loader redirects are converted to a navigation redirect payload while preserving all response cookies; same-origin redirects continue through the SPA router and cross-origin redirects use normal browser navigation.
+- Non-navigation Web `Response` values continue to fall back to a document request so their original HTTP semantics remain authoritative.
+- Client navigation explicitly sends same-origin credentials, aborts superseded requests and uses a monotonically increasing navigation sequence so stale responses cannot update router state after a newer navigation has started.
+- Navigation redirect chains are capped at 10 redirects to prevent loops.
+- `useNavigation()` becomes active before the server request starts and route loading markup can be displayed while the target client runtime/assets finish after the payload arrives.
+- Standalone loader navigation is placed inside the existing middleware/security chain rather than bypassing application middleware or framework security gateways.
+- Production response-cache manifests continue to exclude loader-backed pages automatically because loader output may be user/request specific.
+- Navigation payload responses use `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`.
+
+### Production and reliability
+
+- Standalone production entries bundle each loader into the server artifact only and attach it to the corresponding page route definition.
+- Added a standalone loader-navigation gateway only when an application actually has loader-backed routes; applications without loaders keep the existing production runtime path.
+- Development loader imports use a server-side cache-busting version so edits are reflected without creating a client dependency edge.
+- Added a `/loader-demo/[id]` fixture covering route params, query params, cookies, request method, request URL, SSR serialization and redirect response cookies.
+- Added unit coverage for loader discovery, execution, response returns, serialization validation, duplicate-loader detection and SPA redirect/cookie transport.
+- Added development integration coverage for SSR loader data plus SPA navigation data, target request context, sessions and redirect cookies.
+- Added standalone production E2E coverage to verify the same SPA loader protocol after production bundling.
+- Expanded package artifact smoke checks to require the client router, dev navigation target runtime, navigation response transport and standalone loader navigation runtime.
+- Added dedicated server data loader documentation and updated the main README/application boundary guidance.
+
 ## 0.1.8 - JWT cookie sessions and auth preset
 
 ### Authentication

package/README.md

@@ -2,7 +2,7 @@
 
 BCP Framework is a React full-stack framework with file-based routing, SSR, client navigation, API routes, middleware, metadata, client islands, cache/revalidation, security defaults and standalone production builds.
 
-> Current development version: `0.1.8`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
+> Current development version: `0.1.9`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -35,6 +35,7 @@ app/
 ├─ not-found.tsx
 ├─ users/
 │  └─ [id]/
+│     ├─ loader.ts
 │     └─ page.tsx
 └─ api/
    └─ hello/
@@ -73,7 +74,7 @@ Server-only modules can declare:
 import "bcp/server-only";
 ```
 
-Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a page/client graph; put database work behind an API route instead.
+Database helpers generated by `create-bcp-app` include the server-only marker automatically. A server-only helper must not be imported from a hydrated page/client graph. Use an API route or, for page data in BCP 0.1.9+, a route-level `loader.ts` that runs only on the server.
 
 See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
 
@@ -123,7 +124,7 @@ Supported methods include GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS. HEAD
 
 ## Server request APIs
 
-BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. In the current 0.1.x client pipeline these helpers are intended for API routes and are rejected from page/client module graphs.
+BCP 0.1.7 adds request-scoped server helpers through `bcp/server`. These helpers are server-only and are available from API handlers and server data loaders.
 
 ```ts
 import {
@@ -196,6 +197,82 @@ export async function POST() {
 
 `redirect()` defaults to status `307`; supported statuses are `301`, `302`, `303`, `307` and `308`. Use `cookieStore.delete("session")` to expire a cookie. See [Server Request APIs](docs/server-request-apis.md) for proxy trust, URL handling, response helpers, request isolation, cookie options and boundary details.
 
+## Server data loaders
+
+BCP 0.1.9 adds a server-only `loader.ts` convention next to `page.tsx`. The loader runs before SSR, receives route `params` plus `searchParams`, and can use `bcp/server` APIs, sessions and server-only database modules.
+
+```text
+app/users/[id]/
+├─ loader.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/[id]/loader.ts
+import {
+    getSession,
+    redirect,
+} from "bcp/server";
+
+export async function loader({
+    params,
+    searchParams,
+}: {
+    params: {
+        id: string;
+    };
+    searchParams: URLSearchParams;
+}) {
+    const session =
+        await getSession();
+
+    if (!session) {
+        return redirect(
+            "/login",
+            303
+        );
+    }
+
+    return {
+        id:
+            params.id,
+        query:
+            searchParams.get("q"),
+        session,
+    };
+}
+```
+
+Pages consume the serializable result with `useLoaderData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+export default function UserPage() {
+    const data =
+        useLoaderData<{
+            id: string;
+            query: string | null;
+        }>();
+
+    return (
+        <main>
+            User {data.id}
+        </main>
+    );
+}
+```
+
+Loader data is validated as JSON-safe before SSR and is serialized into framework data so hydration reads the same value without importing `loader.ts` into the browser graph. A loader may also return a Web `Response`; response cookies are preserved on redirects.
+
+Loader-backed pages now use the same SPA navigation model as normal BCP routes. `<Link>`, `navigate()`, `router.push()`, `router.replace()`, history navigation and `router.refresh()` request `/_bcp/navigation`; the server executes the target loader inside a fresh target-page request context and returns current loader data with the route payload. Same-origin loader redirects continue through the router while preserving `Set-Cookie` headers. Superseded navigations are aborted and sequence-checked so stale responses cannot update the active route. Loader pages remain excluded from the production response-cache manifest by default because their output may depend on session, cookie, request identity or user-specific database state.
+
+See [Server Data Loaders](docs/server-data-loaders.md) for serialization rules, authentication patterns, redirect behavior, SPA navigation, cache safety and request-context semantics.
+
 ## JWT cookie sessions
 
 BCP 0.1.8 adds HS256 JWT cookie sessions directly to `bcp/server`. Configure a server-only secret of at least 32 bytes:
@@ -335,7 +412,7 @@ import {
 } from "bcp/cache";
 ```
 
-The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances.
+The current cache implementation is process-local and intentionally does not provide distributed invalidation across multiple Node.js instances. Loader-backed pages are excluded from the automatic production response-cache manifest in 0.1.9; cache loader data explicitly only when the application has a safe user-aware cache key and invalidation strategy.
 
 ## Middleware
 
@@ -445,6 +522,7 @@ No real npm publish command is run automatically by the repository.
 - [Getting Started](docs/getting-started.md)
 - [Application Modules](docs/application-modules.md)
 - [Server Request APIs](docs/server-request-apis.md)
+- [Server Data Loaders](docs/server-data-loaders.md)
 - [JWT Cookie Sessions](docs/session-auth.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)

package/docs/application-modules.md

@@ -8,7 +8,7 @@ import {
 } from "@/lib/database";
 ```
 
-The generated `tsconfig.json` maps `@/*` to the project root. BCP also installs a Node.js resolver during development so the same alias works in SSR and API route modules. Production builds resolve the alias through the application bundler.
+The generated `tsconfig.json` maps `@/*` to the project root. BCP also installs a Node.js resolver during development so the same alias works in SSR, loader and API route modules. Production builds resolve the alias through the application bundler.
 
 ## Client modules
 
@@ -79,7 +79,7 @@ import {
 } from "@/lib/database";
 ```
 
-Put the database operation behind an API route instead:
+For browser-driven data operations, put the database operation behind an API route:
 
 ```ts
 // app/api/users/route.ts
@@ -111,6 +111,66 @@ const result =
     await response.json();
 ```
 
+## Server data loaders
+
+BCP 0.1.9 adds a server-only page data path. A `loader.ts` next to `page.tsx` is not part of the hydrated page graph and may import server-only database helpers directly.
+
+```text
+app/users/
+├─ loader.ts
+└─ page.tsx
+```
+
+```ts
+// app/users/loader.ts
+import {
+    db,
+} from "@/lib/database";
+
+export async function loader() {
+    const [rows] =
+        await db.query(
+            "SELECT id, name FROM users"
+        );
+
+    return {
+        users: rows,
+    };
+}
+```
+
+The page consumes only the serializable result:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+export default function UsersPage() {
+    const data =
+        useLoaderData<{
+            users: Array<{
+                id: number;
+                name: string;
+            }>;
+        }>();
+
+    return (
+        <pre>
+            {JSON.stringify(
+                data.users,
+                null,
+                2
+            )}
+        </pre>
+    );
+}
+```
+
+The loader itself stays server-only; only its validated JSON-safe result is serialized for hydration. See [Server Data Loaders](server-data-loaders.md) for request context, authentication, redirects and cache behavior.
+
 ## Current boundary model
 
-BCP 0.1.x is not a React Server Components implementation. Pages and layouts can participate in browser hydration, so server-only dependencies must remain behind API routes or other server execution paths. The boundary checks are designed to make that rule explicit and prevent accidental database or secret-bearing code from entering client bundles.
+BCP 0.1.x is not a React Server Components implementation. Pages and layouts can participate in browser hydration, so server-only dependencies must remain behind explicit server execution paths: API routes, route-level server data loaders, middleware, or other framework server runtimes. The boundary checks are designed to prevent accidental database or secret-bearing code from entering client bundles.

package/docs/server-data-loaders.md

@@ -0,0 +1,240 @@
+# Server data loaders
+
+BCP 0.1.9 adds route-level server data loading for pages. A loader lives next to a page and runs on the server before that page is rendered. Loader-backed routes also participate in BCP client navigation: a navigation request executes the target loader on the server, returns fresh loader data, and renders the next route without requiring a full document reload.
+
+## File convention
+
+```text
+app/
+└─ users/
+   └─ [id]/
+      ├─ loader.ts
+      └─ page.tsx
+```
+
+`loader.ts` must export a named `loader()` function:
+
+```ts
+import {
+    getSession,
+    redirect,
+} from "bcp/server";
+
+export async function loader({
+    params,
+    searchParams,
+}: {
+    params: {
+        id: string;
+    };
+    searchParams: URLSearchParams;
+}) {
+    const session =
+        await getSession();
+
+    if (!session) {
+        return redirect(
+            "/login",
+            303
+        );
+    }
+
+    return {
+        id:
+            params.id,
+        filter:
+            searchParams.get(
+                "filter"
+            ),
+        user:
+            session,
+    };
+}
+```
+
+The matching page reads the loader result with `useLoaderData<T>()`:
+
+```tsx
+"use client";
+
+import {
+    useLoaderData,
+} from "bcp";
+
+interface UserLoaderData {
+    id: string;
+    filter: string | null;
+    user: {
+        sub: string;
+    };
+}
+
+export default function UserPage() {
+    const data =
+        useLoaderData<
+            UserLoaderData
+        >();
+
+    return (
+        <main>
+            <h1>
+                User {data.id}
+            </h1>
+        </main>
+    );
+}
+```
+
+## Loader context
+
+A loader receives:
+
+- `params` — the matched file-route parameters, including dynamic segments.
+- `searchParams` — a fresh `URLSearchParams` instance for the target request URL.
+
+Loaders run inside the normal BCP request context. Server-only helpers from `bcp/server`, including `headers()`, `cookies()`, `requestUrl()`, `requestMethod()`, `requestId()`, `clientIp()`, `bearerToken()`, `getSession()` and `redirect()`, are available while the loader is running.
+
+For both initial document requests and SPA navigations, the loader request context is created for the target page URL rather than the internal `/_bcp/navigation` transport URL. For example, navigating to `/users/42?filter=active` makes `requestUrl()` observe `/users/42?filter=active` and gives the loader the matching query string.
+
+This makes the recommended authenticated page flow:
+
+```text
+Initial document request
+    ↓
+loader.ts
+    ↓
+Session / database / authorization
+    ↓
+serializable loader data
+    ↓
+SSR page
+    ↓
+useLoaderData() during hydration
+
+Later <Link> / router navigation
+    ↓
+/_bcp/navigation
+    ↓
+loader.ts runs for the target URL
+    ↓
+fresh session / cookie / database state
+    ↓
+navigation payload with loader data
+    ↓
+client renders the target route
+```
+
+Database modules should remain server-only and can be imported directly by `loader.ts`.
+
+## Return values
+
+A loader can return either serializable data or a Web `Response`.
+
+### Data
+
+Loader data must contain only JSON-compatible values:
+
+- `null`
+- strings
+- booleans
+- finite numbers
+- arrays of supported values
+- plain objects containing supported values
+
+Values such as `Date`, `Map`, `Set`, functions, symbols, `BigInt`, class instances, `NaN`, `Infinity` and circular object graphs are rejected. Convert database-specific values to JSON-safe values before returning them.
+
+```ts
+export async function loader() {
+    const user =
+        await findUser();
+
+    return {
+        id:
+            user.id,
+        createdAt:
+            user.createdAt.toISOString(),
+    };
+}
+```
+
+The result is rendered through a server-side loader-data provider and serialized into BCP framework data. During SPA navigation the same data is carried in the navigation payload and written into the framework data before the target client bundle renders. `loader.ts` itself is never imported by the browser entry.
+
+### Redirects and other responses
+
+A loader can return a standard `Response`, including the BCP `redirect()` helper:
+
+```ts
+import {
+    cookies,
+    redirect,
+} from "bcp/server";
+
+export async function loader() {
+    const cookieStore =
+        await cookies();
+
+    cookieStore.set(
+        "last_guard",
+        "private-page",
+        {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+        }
+    );
+
+    return redirect(
+        "/login",
+        303
+    );
+}
+```
+
+Response cookies created during the loader are merged into the returned response, including redirects.
+
+For an SPA navigation, BCP converts an HTTP redirect into a navigation redirect payload while preserving all `Set-Cookie` values. Same-origin redirects continue through the BCP router without a full page reload. Cross-origin redirects are handed to normal browser navigation. The client router limits a single navigation chain to 10 redirects to prevent redirect loops.
+
+A loader may also return another Web `Response`. If that response is not a navigation payload or supported redirect response, the client router falls back to a normal document request so the original HTTP semantics are preserved.
+
+## Client navigation behavior in 0.1.9
+
+Routes with and without loaders both support BCP SPA navigation.
+
+When `<Link>`, `navigate()`, `router.push()`, `router.replace()`, browser history navigation, or `router.refresh()` targets a loader-backed page, BCP performs the following work:
+
+1. Starts navigation state immediately and aborts the previous in-flight navigation request.
+2. Requests `/_bcp/navigation` with the target pathname and query string.
+3. Runs the target route loader on the server inside a fresh request context.
+4. Returns route metadata, client asset information and the fresh loader data in one navigation payload.
+5. Writes the payload into `__BCP_DATA__` before importing/rendering the target client bundle.
+6. Reuses the existing React root so persistent layouts can keep client state where React reconciliation allows it.
+
+`AbortController` cancels superseded network requests. BCP also assigns each navigation a monotonically increasing sequence so a stale response that completes after a newer navigation is not allowed to update router state. The route bundle import receives the navigation identifier as its cache-busting query parameter as well.
+
+`loading.tsx` remains part of the navigation payload. `useNavigation()` is set to navigating before the server request starts; once the payload arrives, the matching loading markup can be shown while target assets/runtime work completes.
+
+## Middleware and security
+
+SPA loader navigation still travels through the normal BCP middleware and security gateway chain before reaching the loader navigation runtime. Applications should still enforce page authorization inside the loader itself because the loader owns the target page data and can make the authorization decision using `getSession()`, cookies, headers or database state.
+
+The internal `/_bcp/navigation` endpoint is transport infrastructure and is not a substitute for loader-level authorization checks.
+
+## Response cache behavior
+
+Loader-backed pages are excluded from the production response-cache manifest by default. A loader can depend on cookies, sessions, authorization headers, request identity or user-specific database state, so automatically placing the resulting HTML in a public route cache would be unsafe.
+
+Caching inside a loader can still be implemented explicitly with application-aware data caching where the cache key and invalidation model are known.
+
+Navigation payloads are sent with `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`.
+
+## Error and not-found behavior
+
+Errors thrown by a loader enter the same page error handling path as SSR errors. For navigation requests, server errors or unsupported response shapes cause the router to fall back to a normal document request so the page-level error/not-found rendering path remains authoritative.
+
+A loader can also call existing server/runtime primitives that throw the framework not-found signal; the matching `not-found.tsx` boundary remains responsible for rendering the 404 page.
+
+## Development reloads
+
+`loader.ts` and `loader.tsx` are watched as server files during development. Loader modules use a server-side cache-busting version during document rendering and navigation, so edits are reflected without putting loader code in the browser dependency graph.
+
+Only one loader file may exist next to a page. Having both `loader.ts` and `loader.tsx` is treated as a framework configuration error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/bundler/src/server-production.ts

@@ -22,6 +22,10 @@ import type {
     Route,
 } from "../../router/src/index.js";
 
+import {
+    findPageLoaderFile,
+} from "../../server/src/page-loader.js";
+
 import type {
     PartialHydrationBuildManifest,
 } from "./partial-hydration.js";
@@ -416,6 +420,26 @@ function createServerEntry(
                 `const ${pageName} = ${pageModuleName}.default;`
             );
 
+            const loaderFile =
+                findPageLoaderFile(
+                    route.filePath
+                );
+            let loaderName =
+                "null";
+
+            if (loaderFile) {
+                loaderName =
+                    `Loader${routeIndex}`;
+                imports.push(
+                    `import { loader as ${loaderName} } from ${JSON.stringify(
+                        toImportSpecifier(
+                            entryDirectory,
+                            loaderFile
+                        )
+                    )};`
+                );
+            }
+
             const layoutModules:
                 Array<{
                     name: string;
@@ -630,6 +654,7 @@ function createServerEntry(
   error: ${errorName},
   notFound: ${notFoundName},
   metadataSources: [${metadataSources.join(", ")}],
+  loader: ${loaderName},
   hydration: ${JSON.stringify(hydration)},
   client: ${JSON.stringify(client)}
 }`);

package/packages/client/src/index.tsx

@@ -17,6 +17,10 @@ export {
     type NavigationState,
 } from "./navigation-state.js";
 
+export {
+    useLoaderData,
+} from "./loader-data.js";
+
 export {
     createIsland,
     type BcpIslandMetadata,

package/packages/client/src/loader-data.tsx

@@ -0,0 +1,99 @@
+import {
+    createContext,
+    createElement,
+    useContext,
+    type ReactNode,
+} from "react";
+
+const LOADER_DATA_PARAM =
+    "__bcp_loader_data";
+const MISSING_LOADER_DATA =
+    Symbol(
+        "bcp-loader-data"
+    );
+
+const LoaderDataContext =
+    createContext<unknown>(
+        MISSING_LOADER_DATA
+    );
+
+export interface BcpLoaderDataProviderProps {
+    data: unknown;
+    children?: ReactNode;
+}
+
+export function BcpLoaderDataProvider({
+    data,
+    children,
+}: BcpLoaderDataProviderProps) {
+    return createElement(
+        LoaderDataContext.Provider,
+        {
+            value:
+                data,
+        },
+        children
+    );
+}
+
+export function useLoaderData<
+    T = unknown
+>(): T {
+    const contextValue =
+        useContext(
+            LoaderDataContext
+        );
+
+    if (
+        contextValue !==
+        MISSING_LOADER_DATA
+    ) {
+        return contextValue as T;
+    }
+
+    if (
+        typeof document !==
+        "undefined"
+    ) {
+        const element =
+            document.getElementById(
+                "__BCP_DATA__"
+            );
+
+        if (element) {
+            try {
+                const frameworkData =
+                    JSON.parse(
+                        element.textContent ||
+                        "{}"
+                    ) as {
+                        params?: Record<
+                            string,
+                            unknown
+                        >;
+                    };
+                const params =
+                    frameworkData.params;
+
+                if (
+                    params &&
+                    Object.prototype
+                        .hasOwnProperty.call(
+                            params,
+                            LOADER_DATA_PARAM
+                        )
+                ) {
+                    return params[
+                        LOADER_DATA_PARAM
+                    ] as T;
+                }
+            } catch {
+                // Fall through to the framework error below.
+            }
+        }
+    }
+
+    throw new Error(
+        "BCP Framework: useLoaderData() was used on a route without loader data. Add loader.ts next to page.tsx."
+    );
+}