@harperfast/template-vue-ts-studio 1.7.4 → 1.8.1

package/.agents/skills/harper-best-practices/AGENTS.md

@@ -1617,59 +1617,78 @@ Instructions for the agent to follow when serving web content from Harper.
 
 #### When to Use
 
-Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance.
+Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.
 
 #### How It Works
 
-1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin.
-2. **Option A: Static Plugin (Simple)**:
-   - Add to `config.yaml`:
-     ```yaml
-     static:
-       files: 'web/*'
-     ```
-   - Place files in a `web/` folder in the project root.
-   - Files are served at the root URL (e.g., `http://localhost:9926/index.html`).
-3. **Option B: Vite Plugin (Advanced/Development)**:
-   - Add to `config.yaml`:
-     ```yaml
-     '@harperfast/vite-plugin':
-       package: '@harperfast/vite-plugin'
-     ```
-   - Ensure `vite.config.ts` and `index.html` are in the project root.
+There are two building blocks. Harper's built-in `static` plugin **serves** files; the `@harperfast/vite` plugin **builds** (and, for SSR, **renders**) a Vite app. For a Vite app they work **together** — the plugin builds into a directory and `static` serves that same directory.
 
-   ```javascript
-   import vue from '@vitejs/plugin-vue';
-   import path from 'node:path';
-   import { defineConfig } from 'vite';
-
-   // https://vite.dev/config/
-   export default defineConfig({
-   	plugins: [vue()],
-   	resolve: {
-   		alias: {
-   			'@': path.resolve(import.meta.dirname, './src'),
-   		},
-   	},
-   	build: {
-   		outDir: 'web',
-   		emptyOutDir: true,
-   		rolldownOptions: {
-   			external: ['**/*.test.*', '**/*.spec.*'],
-   		},
-   	},
-   });
-   ```
+##### Option A: Static plugin only (simple, pre-built assets)
 
-   - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`.
-   - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately.
+For a plain static site or already-built assets, use `static` on its own:
 
-4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. For example, these scripts in a package.json can perform the necessary steps:
-   ```json
-   "build": "vite build",
-   "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && (cd deploy && harper deploy_component . project=web restart=rolling replicated=true) && rm -Rf deploy",
-   ```
-   Then in production, the "Static Plugin" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you.
+```yaml
+static:
+  files: 'web/*'
+```
+
+- Place files in a `web/` folder in the project root; they are served from the root URL (e.g. `http://localhost:9926/index.html`).
+- Static files are matched first; if none matches, Harper falls through to your resource and table APIs.
+
+##### Option B: Vite plugin + static plugin (integrated Vite app)
+
+> **Renamed in v1:** the plugin was previously `@harperfast/vite-plugin`. From `1.0.0` on it is **`@harperfast/vite`** (same key and `package`). It now pairs with the `static` plugin instead of building into `web/` itself.
+
+`@harperfast/vite` **builds** your app — in `harper dev` it runs Vite in middleware mode with HMR; in `harper run` it runs `vite build` and rebuilds when watched files change (and renders HTML for SSR). The `static` plugin **serves** the built output. Point both at the same directory (`output`, default `dist`) — that shared directory is the only contract between them.
+
+**SPA `config.yaml`** — list the plugin first so its dev server wins in `harper dev`; `notFound` + `fallthrough: false` makes client-side routing work:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+static:
+  files: 'dist/**'
+  notFound:
+    file: 'index.html'
+    statusCode: 200
+  fallthrough: false
+```
+
+**SSR `config.yaml`** — add an `ssr` entry so the plugin renders `index.html`, and set `index: false` on `static` so it serves assets only:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+  ssr: 'src/entry-server.tsx'
+
+static:
+  files: 'dist/**'
+  index: false
+```
+
+- Install dependencies: `npm install --save-dev vite @harperfast/vite @vitejs/plugin-react` (swap in your framework's Vite plugin, e.g. `@vitejs/plugin-vue`).
+- Then `harper dev .` runs the app with HMR and `harper run .` runs the production build. Vite does _not_ need to be executed separately.
+
+#### Deploying to Production
+
+Because `@harperfast/vite` builds on the node and `static` serves the output, deploy the component as-is — no manual build-and-move step is needed:
+
+```json
+{
+	"scripts": {
+		"dev": "harper dev .",
+		"start": "harper run .",
+		"deploy": "harper deploy_component . restart=true replicated=true"
+	}
+}
+```
+
+On deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup for you.
 
 ### 4.5 Harper Logging
 

package/.agents/skills/harper-best-practices/rules/serving-web-content.md

@@ -11,56 +11,75 @@ Instructions for the agent to follow when serving web content from Harper.
 
 ## When to Use
 
-Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React app) directly from your Harper instance.
+Use this skill when you need to serve a frontend (HTML, CSS, JS, or a React/Vue app) directly from your Harper instance — either plain static files or an integrated Vite app with hot module replacement (HMR) in development and a real production build when deployed.
 
 ## How It Works
 
-1. **Choose a Method**: Decide between the simple Static Plugin or the integrated Vite Plugin.
-2. **Option A: Static Plugin (Simple)**:
-   - Add to `config.yaml`:
-     ```yaml
-     static:
-       files: 'web/*'
-     ```
-   - Place files in a `web/` folder in the project root.
-   - Files are served at the root URL (e.g., `http://localhost:9926/index.html`).
-3. **Option B: Vite Plugin (Advanced/Development)**:
-   - Add to `config.yaml`:
-     ```yaml
-     '@harperfast/vite-plugin':
-       package: '@harperfast/vite-plugin'
-     ```
-   - Ensure `vite.config.ts` and `index.html` are in the project root.
-
-   ```javascript
-   import vue from '@vitejs/plugin-vue';
-   import path from 'node:path';
-   import { defineConfig } from 'vite';
-
-   // https://vite.dev/config/
-   export default defineConfig({
-   	plugins: [vue()],
-   	resolve: {
-   		alias: {
-   			'@': path.resolve(import.meta.dirname, './src'),
-   		},
-   	},
-   	build: {
-   		outDir: 'web',
-   		emptyOutDir: true,
-   		rolldownOptions: {
-   			external: ['**/*.test.*', '**/*.spec.*'],
-   		},
-   	},
-   });
-   ```
-
-   - Install dependencies: `npm install --save-dev vite @harperfast/vite-plugin`.
-   - Then `harper run .` will start up Harper and Vite with HMR. Vite does _not_ need to be executed separately.
-
-4. **Deploy for Production**: For Vite apps, use a build script to generate static files into a `web/` folder and deploy them using the static handler pattern. For example, these scripts in a package.json can perform the necessary steps:
-   ```json
-   "build": "vite build",
-   "deploy": "rm -Rf deploy && npm run build && mkdir deploy && mv web deploy/ && cp -R deploy-template/* deploy/ && cp -R schemas resources deploy/ && (cd deploy && harper deploy_component . project=web restart=rolling replicated=true) && rm -Rf deploy",
-   ```
-   Then in production, the "Static Plugin" option will performantly and securely serve your assets. `npm create harper@latest` scaffolds all of this for you.
+There are two building blocks. Harper's built-in `static` plugin **serves** files; the `@harperfast/vite` plugin **builds** (and, for SSR, **renders**) a Vite app. For a Vite app they work **together** — the plugin builds into a directory and `static` serves that same directory.
+
+### Option A: Static plugin only (simple, pre-built assets)
+
+For a plain static site or already-built assets, use `static` on its own:
+
+```yaml
+static:
+  files: 'web/*'
+```
+
+- Place files in a `web/` folder in the project root; they are served from the root URL (e.g. `http://localhost:9926/index.html`).
+- Static files are matched first; if none matches, Harper falls through to your resource and table APIs.
+
+### Option B: Vite plugin + static plugin (integrated Vite app)
+
+> **Renamed in v1:** the plugin was previously `@harperfast/vite-plugin`. From `1.0.0` on it is **`@harperfast/vite`** (same key and `package`). It now pairs with the `static` plugin instead of building into `web/` itself.
+
+`@harperfast/vite` **builds** your app — in `harper dev` it runs Vite in middleware mode with HMR; in `harper run` it runs `vite build` and rebuilds when watched files change (and renders HTML for SSR). The `static` plugin **serves** the built output. Point both at the same directory (`output`, default `dist`) — that shared directory is the only contract between them.
+
+**SPA `config.yaml`** — list the plugin first so its dev server wins in `harper dev`; `notFound` + `fallthrough: false` makes client-side routing work:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+static:
+  files: 'dist/**'
+  notFound:
+    file: 'index.html'
+    statusCode: 200
+  fallthrough: false
+```
+
+**SSR `config.yaml`** — add an `ssr` entry so the plugin renders `index.html`, and set `index: false` on `static` so it serves assets only:
+
+```yaml
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+  ssr: 'src/entry-server.tsx'
+
+static:
+  files: 'dist/**'
+  index: false
+```
+
+- Install dependencies: `npm install --save-dev vite @harperfast/vite @vitejs/plugin-react` (swap in your framework's Vite plugin, e.g. `@vitejs/plugin-vue`).
+- Then `harper dev .` runs the app with HMR and `harper run .` runs the production build. Vite does _not_ need to be executed separately.
+
+## Deploying to Production
+
+Because `@harperfast/vite` builds on the node and `static` serves the output, deploy the component as-is — no manual build-and-move step is needed:
+
+```json
+{
+	"scripts": {
+		"dev": "harper dev .",
+		"start": "harper run .",
+		"deploy": "harper deploy_component . restart=true replicated=true"
+	}
+}
+```
+
+On deploy the plugin runs `vite build` at startup (and rebuilds when `files` change) while `static` serves the result. If you prefer to build in CI, commit the build output, point `static` at it, and omit `files` so the plugin stays idle while `static` serves the prebuilt assets. Either way, `npm create harper@latest` scaffolds a working setup for you.

package/.gitignore

@@ -1,6 +1,5 @@
 .DS_Store
-web
-deploy
+dist
 
 #
 # https://raw.githubusercontent.com/github/gitignore/refs/heads/main/Node.gitignore

package/README.md

@@ -73,7 +73,7 @@ These schemas are the heart of a great Harper app, specifying which tables you w
 
 ### View Your Website
 
-Pop open [http://localhost:9926](http://localhost:9926) to view [web/index.html](./web/index.html) in your browser.
+Pop open [http://localhost:9926](http://localhost:9926) to view [index.html](./index.html) in your browser.
 
 ### Use Your API
 

package/config.yaml

@@ -20,6 +20,19 @@ jsResource:
   files: 'resources/*.ts'
 
 # Generates types for the schema so your code is schema-aware
-# Bootstraps Vite to build your frontend to HTML/JS/CSS
-'@harperfast/vite-plugin':
-  package: '@harperfast/vite-plugin'
+# Bootstraps Vite to build your frontend to HTML/JS/CSS.
+# In production it builds your app (and recompiles when files in `files` change); the `static`
+# component below serves the built output. Listed before `static` so its dev server wins in `harper dev`.
+'@harperfast/vite':
+  package: '@harperfast/vite'
+  files: 'src/**/*'
+  output: 'dist'
+
+# Serves the built frontend from Vite's output directory. `notFound` + `fallthrough: false` makes
+# client-side routing work (unmatched routes return index.html); the REST routes above take precedence.
+static:
+  files: 'dist/**'
+  notFound:
+    file: 'index.html'
+    statusCode: 200
+  fallthrough: false

package/package.json

@@ -1,8 +1,15 @@
 {
 	"name": "@harperfast/template-vue-ts-studio",
-	"version": "1.7.4",
+	"version": "1.8.1",
 	"type": "module",
 	"repository": "github:HarperFast/create-harper",
 	"scripts": {},
+	"dependencies": {
+		"@harperfast/schema-codegen": "^1.0.10",
+		"@harperfast/vite": "^1.1.0",
+		"@vitejs/plugin-vue": "^6.0.5",
+		"vite": "^8.0.0",
+		"vue": "^3.5.29"
+	},
 	"devDependencies": {}
 }

package/skills-lock.json

@@ -5,7 +5,7 @@
       "source": "harperfast/skills",
       "sourceType": "github",
       "skillPath": "harper-best-practices/SKILL.md",
-      "computedHash": "921b0848ec9f7ee375fec2d4191c99325e1d7160c0ab463832b3e0443e80576a"
+      "computedHash": "8aa6811090a5ef3721428b048f3c1208fc50d93b5fe03acad27d89a416a081a1"
     }
   }
 }

package/vite.config.ts

@@ -13,7 +13,7 @@ export default defineConfig({
 		},
 	},
 	build: {
-		outDir: 'web',
+		outDir: 'dist',
 		emptyOutDir: true,
 		rolldownOptions: {
 			external: ['**/*.test.*', '**/*.spec.*'],

package/deploy-template/config.yaml

@@ -1,10 +0,0 @@
-fastifyRoutes:
-  files: fastify/*.js
-
-rest: true
-
-graphqlSchema:
-  files: 'schemas/*.graphql'
-
-jsResource:
-  files: 'resources/*.ts'

package/deploy-template/fastify/static.js

@@ -1,14 +0,0 @@
-import fastifyStatic from '@fastify/static';
-import { join } from 'path';
-
-export default async (fastify) => {
-	fastify.register(fastifyStatic, {
-		root: join(import.meta.dirname, '../web'),
-		maxAge: '30d',
-		immutable: true,
-	});
-
-	fastify.get('/', function(req, reply) {
-		reply.sendFile('index.html', { maxAge: '1m', immutable: false });
-	});
-};

package/deploy-template/package.json

@@ -1,5 +0,0 @@
-{
-	"dependencies": {
-		"@fastify/static": "^9.0.0"
-	}
-}