@jay-framework/jay-stack-cli 0.16.2 → 0.16.3

package/agent-kit-template/plugin/INSTRUCTIONS.md

@@ -13,7 +13,8 @@ A plugin provides headless components (data + interactions, no UI) that project
 3. **Define actions** with `.jay-action` metadata
 4. **Optionally add routes** — pages for admin tools and dashboards
 5. **Set up `plugin.yaml`** — list contracts, actions, services, contexts, routes
-6. **Validate** with `jay-stack validate-plugin`
+6. **Configure build** — dual entry points (server + client), vite.config.ts, package.json exports
+7. **Validate** with `jay-stack validate-plugin`
 
 ## Guides
 

package/agent-kit-template/plugin/plugin-structure.md

@@ -161,22 +161,101 @@ my-project/
 
 See `examples/jay-stack/fake-shop` for a working example.
 
+## Dual Entry Points
+
+Jay plugins are fullstack — they run on both server and client. The build produces two bundles:
+
+- **Server** (`dist/index.js`) — actions, services, SSR rendering, `init()`. Built with `vite build --ssr`.
+- **Client** (`dist/index.client.js`) — components for hydration, context tokens, `init()`. Built with `vite build`.
+
+Create two entry files:
+
+| File                  | Exports                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `lib/index.ts`        | Actions, services, components (SSR), init, service markers |
+| `lib/index.client.ts` | Components (hydration), context markers, init              |
+
+Actions and service providers are server-only. Components appear in **both** entries.
+
+## Build Scripts
+
+```json
+{
+  "scripts": {
+    "build": "npm run clean && npm run definitions && npm run build:client && npm run build:server && npm run build:copy-assets && npm run build:types && npm run validate",
+    "definitions": "jay-cli definitions lib",
+    "build:client": "vite build",
+    "build:server": "vite build --ssr",
+    "build:copy-assets": "cp lib/*.jay-contract* dist/",
+    "build:types": "tsup lib/index.ts lib/index.client.ts --dts-only --format esm",
+    "validate": "jay-stack-cli validate-plugin",
+    "clean": "rimraf dist"
+  }
+}
+```
+
+The `vite.config.ts` uses `isSsrBuild` to switch entry points:
+
+```typescript
+import { resolve } from 'path';
+import { defineConfig } from 'vite';
+import { jayStackCompiler } from '@jay-framework/compiler-jay-stack';
+
+const jayOptions = { tsConfigFilePath: resolve(__dirname, 'tsconfig.json'), outputDir: 'build' };
+
+export default defineConfig(({ isSsrBuild }) => ({
+  plugins: [...jayStackCompiler(jayOptions)],
+  build: {
+    minify: false,
+    ssr: isSsrBuild,
+    emptyOutDir: false,
+    lib: {
+      entry: isSsrBuild
+        ? { index: resolve(__dirname, 'lib/index.ts') }
+        : { 'index.client': resolve(__dirname, 'lib/index.client.ts') },
+      formats: ['es'],
+    },
+    rollupOptions: {
+      external: [
+        '@jay-framework/component',
+        '@jay-framework/fullstack-component',
+        '@jay-framework/stack-client-runtime',
+        '@jay-framework/stack-server-runtime',
+        '@jay-framework/reactive',
+        '@jay-framework/runtime',
+      ],
+    },
+  },
+}));
+```
+
 ## package.json Exports
 
-For NPM packages, declare exports so the framework can resolve the plugin:
+For NPM packages, declare exports for both server and client entry points:
 
 ```json
 {
   "name": "@my-org/my-plugin",
   "type": "module",
+  "main": "dist/index.js",
   "exports": {
-    ".": "./dist/index.js",
-    "./plugin.yaml": "./plugin.yaml"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/index.client.d.ts",
+      "default": "./dist/index.client.js"
+    },
+    "./plugin.yaml": "./plugin.yaml",
+    "./my-contract.jay-contract": "./dist/my-contract.jay-contract"
   },
-  "files": ["dist", "plugin.yaml", "lib/contracts", "lib/actions"]
+  "files": ["dist", "plugin.yaml"]
 }
 ```
 
+The `./client` export is required — the framework uses it for browser-side hydration code. The `.` export handles server-side rendering and action execution.
+
 ## Plugin-Contributed Agent-Kit Guides
 
 A plugin can include guides that are merged into the project's agent-kit during `jay-stack agent-kit`. Create an `agent-kit/` folder with subfolders for each role:

package/dist/index.js

@@ -3452,6 +3452,14 @@ async function validatePackageJson(context, result) {
           suggestion: 'Add "." export for the main module entry'
         });
       }
+      if (!packageJson.exports["./client"]) {
+        result.warnings.push({
+          type: "export-mismatch",
+          message: 'package.json exports missing "./client" entry point',
+          location: packageJsonPath,
+          suggestion: 'Add "./client": "./dist/index.client.js" to exports. The client bundle provides components for hydration and client-side contexts. Build with: vite build (client) + vite build --ssr (server)'
+        });
+      }
       if (context.manifest.contracts) {
         for (const contract of context.manifest.contracts) {
           const contractExport = "./" + contract.contract;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jay-framework/jay-stack-cli",
-  "version": "0.16.2",
+  "version": "0.16.3",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/index.js",
@@ -24,14 +24,14 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@jay-framework/compiler-jay-html": "^0.16.2",
-    "@jay-framework/compiler-shared": "^0.16.2",
-    "@jay-framework/dev-server": "^0.16.2",
-    "@jay-framework/editor-server": "^0.16.2",
-    "@jay-framework/fullstack-component": "^0.16.2",
-    "@jay-framework/logger": "^0.16.2",
-    "@jay-framework/plugin-validator": "^0.16.2",
-    "@jay-framework/stack-server-runtime": "^0.16.2",
+    "@jay-framework/compiler-jay-html": "^0.16.3",
+    "@jay-framework/compiler-shared": "^0.16.3",
+    "@jay-framework/dev-server": "^0.16.3",
+    "@jay-framework/editor-server": "^0.16.3",
+    "@jay-framework/fullstack-component": "^0.16.3",
+    "@jay-framework/logger": "^0.16.3",
+    "@jay-framework/plugin-validator": "^0.16.3",
+    "@jay-framework/stack-server-runtime": "^0.16.3",
     "chalk": "^4.1.2",
     "commander": "^14.0.0",
     "express": "^5.0.1",
@@ -42,7 +42,7 @@
     "yaml": "^2.3.4"
   },
   "devDependencies": {
-    "@jay-framework/dev-environment": "^0.16.2",
+    "@jay-framework/dev-environment": "^0.16.3",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.21",
     "nodemon": "^3.0.3",