@chidchanun/bcp 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable framework changes are tracked here before release.
 
+## 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
+
+- Tailwind projects now install the official `@tailwindcss/cli` package and compile CSS before starting BCP.
+- Development runs Tailwind in watch mode alongside `bcp dev` using `concurrently`.
+- Production builds minify Tailwind CSS before `bcp build`.
+- Generated Tailwind CSS is served through a framework API stylesheet endpoint with cache disabled during development.
+- Root layout automatically links the generated stylesheet.
+- Tailwind source detection is explicitly rooted at the generated project so utility classes in `app/` and other project files are discovered.
+- Tailwind projects include starter utility classes so a fresh app visibly confirms that Tailwind is active.
+- Fixed source generator metadata so local generator runs target `@chidchanun/bcp` instead of the unrelated unscoped `bcp` package.
+
 ## 0.1.3 - Interactive project setup
 
 ### 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.5`. BCP is still pre-1.0 and validates each release candidate before the manual npm publish step.
 
 ## Quick start
 
@@ -40,12 +40,43 @@ 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.
+
 ## Commands
 
 ```bash
@@ -224,6 +255,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.3",
+  "version": "0.1.5",
   "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"