@chidchanun/bcp 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable framework changes are tracked here before release.
 
+## 0.1.6 - Critical CSS and release visibility
+
+### Performance
+
+- Small generated `/bcp.css` stylesheets are inlined into SSR HTML when they are 8 KiB or smaller, removing the stylesheet request from the initial render-critical path.
+- Critical CSS optimization is applied in development and standalone production.
+- Gzip, Brotli and deflate HTML responses are decoded, transformed and re-encoded so response compression remains intact.
+- Applications with CSP policies that do not allow inline styles automatically keep the external `/bcp.css` link instead of breaking page styling.
+- Critical CSS transformation is skipped entirely when the stylesheet is missing or larger than the inline threshold.
+
+### Reliability and release tooling
+
+- Added regression tests for critical CSS inlining, size fallback, closing-style escaping, compressed responses and CSP fallback.
+- Added `release:visibility-check` so an npm release is not considered ready until the exact framework and generator versions are readable from the registry.
+- `release:publish:yes` and `release:resume` now run the registry visibility check after npm accepts the publish.
+
+## 0.1.5 - Application module boundaries
+
+### Developer experience
+
+- Added the `@/` project-root alias for generated applications across TypeScript and BCP runtime resolution.
+- Generated applications use TypeScript Bundler module resolution so extensionless application imports match BCP runtime behavior.
+- React client hooks in hydrated application modules require an explicit `"use client"` directive.
+- Added `bcp/server-only` to prevent server dependencies from entering hydrated client bundles.
+- Database helpers generated by `create-bcp-app` are marked server-only automatically and are intended to be consumed from API routes.
+- Development HTTP request logs now focus on application API traffic and suppress `/_bcp/*`, page/static requests and the legacy internal Tailwind stylesheet endpoint.
+- Generated Tailwind projects now link `/bcp.css` directly from `public/` instead of routing CSS through `/api/bcp-styles`, shortening the initial request path and allowing normal static-asset caching/revalidation.
+
 ## 0.1.4 - Tailwind runtime fix
 
 ### create-bcp-app

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 status: pre-release `0.1.0`. The repository can produce npm-ready tarballs, validate Release Candidates and run npm publish dry-runs, but publishing to npm is intentionally a separate manual release action.
+> Current development version: `0.1.6`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -40,12 +40,47 @@ app/
    └─ hello/
       └─ route.ts
 
+lib/
 public/
 bcp.config.ts
 package.json
 tsconfig.json
 ```
 
+## Application imports and boundaries
+
+Generated applications include the project-root `@/` alias:
+
+```ts
+import {
+    db,
+} from "@/lib/database";
+```
+
+Modules that use React client hooks must declare `"use client"`:
+
+```tsx
+"use client";
+
+import {
+    useState,
+} from "react";
+```
+
+Server-only modules can declare:
+
+```ts
+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.
+
+See [Application Modules](docs/application-modules.md) for the complete boundary model and examples.
+
+## Tailwind and critical CSS
+
+Generated Tailwind projects compile to `public/bcp.css`. BCP 0.1.6 inlines that stylesheet into SSR HTML when it is 8 KiB or smaller, removing the stylesheet request from the initial render-critical path. Larger stylesheets remain external so the browser can cache them normally. If the application's Content Security Policy does not allow inline styles, BCP automatically keeps the external stylesheet link.
+
 ## Commands
 
 ```bash
@@ -217,6 +252,8 @@ npm run rc:check
 
 `rc:check` validates tests/release metadata, checks npm package-name availability or ownership, performs `npm publish --dry-run`, and clean-installs both generated tarballs into temporary projects.
 
+After a real publish, `npm run release:visibility-check` verifies that the exact framework and generator versions are readable from the npm registry before the release is treated as ready for installation.
+
 `package:prepare` stages the framework at `.package/bcp`. The default package name is `bcp`; set `BCP_PACKAGE_NAME` when preparing a scoped or alternate package name.
 
 No real npm publish command is run automatically by the repository.
@@ -224,6 +261,7 @@ No real npm publish command is run automatically by the repository.
 ## Documentation
 
 - [Getting Started](docs/getting-started.md)
+- [Application Modules](docs/application-modules.md)
 - [Routing](docs/routing.md)
 - [Configuration](docs/configuration.md)
 - [Caching](docs/caching.md)

package/docs/application-modules.md

@@ -0,0 +1,116 @@
+# Application Modules
+
+BCP applications can import project files through the project-root `@/` alias.
+
+```ts
+import {
+    db,
+} 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.
+
+## Client modules
+
+A page or shared module that uses React client hooks must begin with the `"use client"` directive.
+
+```tsx
+"use client";
+
+import {
+    useEffect,
+    useState,
+} from "react";
+
+export default function UsersPage() {
+    const [users, setUsers] =
+        useState([]);
+
+    useEffect(
+        () => {
+            void fetch("/api/users")
+                .then(
+                    (response) =>
+                        response.json()
+                )
+                .then(
+                    setUsers
+                );
+        },
+        []
+    );
+
+    return (
+        <pre>
+            {JSON.stringify(users, null, 2)}
+        </pre>
+    );
+}
+```
+
+BCP checks client-reachable page/layout module graphs at development startup and production build time. Using React client hooks without `"use client"` causes a boundary error.
+
+Client island files (`*.island.ts` and `*.island.tsx`) are already explicit client entry points and keep their existing island semantics.
+
+## Server-only modules
+
+Use `bcp/server-only` in modules that contain database clients, secrets, filesystem access, or other code that must never enter a browser bundle.
+
+```ts
+import "bcp/server-only";
+
+import mysql from "mysql2/promise";
+
+export const db =
+    mysql.createPool(
+        process.env.DATABASE_URL ??
+        ""
+    );
+```
+
+Database helpers generated by `create-bcp-app` include this marker automatically.
+
+Do not import a server-only module directly from a page or client component:
+
+```ts
+// Not allowed in a page/client graph
+import {
+    db,
+} from "@/lib/database";
+```
+
+Put the database operation behind an API route instead:
+
+```ts
+// app/api/users/route.ts
+import {
+    db,
+} from "@/lib/database";
+
+export async function GET() {
+    const [rows] =
+        await db.query(
+            "SELECT * FROM users"
+        );
+
+    return Response.json({
+        data: rows,
+    });
+}
+```
+
+Then call the API from the client:
+
+```ts
+const response =
+    await fetch(
+        "/api/users"
+    );
+
+const result =
+    await response.json();
+```
+
+## 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.

package/docs/development-logging.md

@@ -0,0 +1,13 @@
+# Development request logging
+
+BCP keeps development request output focused on application API traffic.
+
+By default, request-style console lines are shown for application API routes such as:
+
+```text
+GET /api/users 200 1.24ms
+```
+
+BCP suppresses framework and browser bootstrap traffic such as `/_bcp/*`, page/document requests, public static assets, and the generated Tailwind stylesheet endpoint `/api/bcp-styles`.
+
+Build, SSR, Fast Refresh, watcher and error diagnostics are not affected by this filter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
@@ -43,6 +43,11 @@
       "types": "./packages/client/src/config.ts",
       "default": "./packages/client/src/config.ts"
     },
+    "./server-only": {
+      "types": "./packages/client/src/server-only.d.ts",
+      "browser": "./packages/client/src/server-only.browser.mjs",
+      "default": "./packages/client/src/server-only.mjs"
+    },
     "./middleware": {
       "types": "./packages/server/src/middleware.ts",
       "default": "./packages/server/src/middleware.ts"