vite-plugin-server-actions 1.0.1 → 1.2.0

package/README.md

@@ -1,4 +1,4 @@
-# ⚡ Vite Server Actions
+# Vite Server Actions
 
 [![npm version](https://img.shields.io/npm/v/vite-plugin-server-actions.svg?style=flat)](https://www.npmjs.com/package/vite-plugin-server-actions)
 [![Downloads](https://img.shields.io/npm/dm/vite-plugin-server-actions.svg?style=flat)](https://www.npmjs.com/package/vite-plugin-server-actions)
@@ -20,26 +20,33 @@ import { getUsers } from "./server/db.server.js";
 const users = await getUsers(); // Just call it!
 ```
 
-## 🚀 Why Vite Server Actions?
+## Why Vite Server Actions?
 
 - **Zero API Boilerplate** - No need to define routes, handle HTTP methods, or parse request bodies
-- **Type Safety** - Full TypeScript support with proper type inference across client-server boundary
+- **TypeScript Support** - Full TypeScript support with automatic type generation
 - **Built-in Validation** - Automatic request validation using Zod schemas
-- **Auto Documentation** - OpenAPI spec and Swagger UI generated from your code
-- **Production Ready** - Builds to a standard Node.js Express server
-- **Developer Experience** - Hot reload, middleware support, and helpful error messages
+- **Auto Documentation** - OpenAPI 3.0 specs and Swagger UI generated automatically
+- **Production Ready** - Builds to optimized Node.js Express server
+- **Developer Experience** - Clear error messages, hot reload, and development-time validation
 
-## ✨ Core Features
+## Core Features
 
-- 🔗 **Seamless Imports** - Import server functions like any other module
-- 🛡️ **Secure by Default** - Server code never exposed to client
-- ✅ **Request Validation** - Attach Zod schemas for automatic validation
-- 📖 **API Documentation** - Auto-generated OpenAPI specs and Swagger UI
-- 🔌 **Middleware Support** - Add authentication, logging, CORS, etc.
-- 🎯 **Flexible Routing** - Customize how file paths map to API endpoints
-- 📦 **Production Optimized** - Builds to efficient Express server with all features
+- **Seamless Imports** - Import server functions like any other module
+- **Secure by Default** - Server code never exposed to client, path traversal protection
+- **TypeScript** - Full support with cross-file imports, automatic compilation via Vite's SSR module system
+- **Validation** - Zod schemas with type inference and OpenAPI generation
+- **Documentation** - OpenAPI 3.0 specs with Swagger UI
+- **Middleware Support** - Authentication, logging, CORS, and custom middleware
+- **Flexible Routing** - Multiple routing strategies with hierarchical paths
+- **Developer Experience** - Helpful error messages and development warnings
+- **Production Optimized** - Efficient Express server builds
 
-## 🚀 Quick Start
+## Requirements
+
+- Node.js 18+ (Node 16 reached EOL)
+- Vite 4, 5, 6, or 7
+
+## Quick Start
 
 ### 1. Install
 
@@ -63,7 +70,7 @@ export default defineConfig({
 
 ### 3. Create a Server Function
 
-Any file ending with `.server.js` becomes a server module:
+Any file ending with `.server.js` or `.server.ts` becomes a server module:
 
 ```javascript
 // actions/todos.server.js
@@ -108,12 +115,12 @@ function TodoApp({ userId }) {
 
 That's it! The plugin automatically:
 
-- ✅ Creates API endpoints for each function
-- ✅ Handles serialization/deserialization
-- ✅ Provides full TypeScript support
-- ✅ Works in development and production
+- Creates API endpoints for each function
+- Handles serialization/deserialization
+- Provides TypeScript support
+- Works in development and production
 
-## 📚 Real-World Examples
+## Real-World Examples
 
 ### Database Operations
 
@@ -199,7 +206,7 @@ login.schema = LoginSchema;
 - [Todo App with React](examples/react-todo-app) - Same todo app built with React
 - More examples coming soon for other frameworks
 
-## 🔍 How It Works
+## How It Works
 
 When you import a `.server.js` file in your client code, Vite Server Actions:
 
@@ -225,7 +232,7 @@ const user = await fetch("/api/user/getUser", {
 - **Development**: Server functions run as Express middleware in Vite's dev server
 - **Production**: Builds to a standalone Express server with all your functions
 
-## ⚙️ Configuration
+## Configuration
 
 ### Common Use Cases
 
@@ -280,29 +287,33 @@ serverActions({
 
 ### All Configuration Options
 
-| Option           | Type         | Default              | Description                    |
-| ---------------- | ------------ | -------------------- | ------------------------------ |
-| `apiPrefix`      | `string`     | `"/api"`             | URL prefix for all endpoints   |
-| `include`        | `string[]`   | `["**/*.server.js"]` | Files to process               |
-| `exclude`        | `string[]`   | `[]`                 | Files to ignore                |
-| `middleware`     | `Function[]` | `[]`                 | Express middleware stack       |
-| `routeTransform` | `Function`   | See below            | Customize URL generation       |
-| `validation`     | `Object`     | `{ enabled: false }` | Validation settings            |
-| `openAPI`        | `Object`     | `{ enabled: false }` | OpenAPI documentation settings |
+| Option           | Type         | Default                                | Description                    |
+| ---------------- | ------------ | -------------------------------------- | ------------------------------ |
+| `apiPrefix`      | `string`     | `"/api"`                               | URL prefix for all endpoints   |
+| `include`        | `string[]`   | `["**/*.server.js", "**/*.server.ts"]` | Files to process               |
+| `exclude`        | `string[]`   | `[]`                                   | Files to ignore                |
+| `middleware`     | `Function[]` | `[]`                                   | Express middleware stack       |
+| `routeTransform` | `Function`   | See below                              | Customize URL generation       |
+| `validation`     | `Object`     | `{ enabled: false }`                   | Validation settings            |
+| `openAPI`        | `Object`     | `{ enabled: false }`                   | OpenAPI documentation settings |
 
 #### Route Transform Options
 
+The plugin uses clean hierarchical paths by default (e.g., `actions/todo/create` instead of `src_actions_todo/create`).
+
 ```javascript
 import { pathUtils } from "vite-plugin-server-actions";
 
 // Available presets:
-pathUtils.createCleanRoute; // (default) auth.server.js → /api/auth/login
-pathUtils.createLegacyRoute; // auth.server.js → /api/auth_server/login
-pathUtils.createMinimalRoute; // auth.server.js → /api/auth.server/login
+pathUtils.createCleanRoute; // (default) src/actions/auth.server.js → /api/actions/auth/login
+pathUtils.createLegacyRoute; // src/actions/auth.server.js → /api/src_actions_auth/login
+pathUtils.createMinimalRoute; // actions/auth.server.js → /api/actions/auth.server/login
 ```
 
 #### Validation Options
 
+Validation is disabled by default. Enable it explicitly in your configuration.
+
 | Option    | Type      | Default | Description                           |
 | --------- | --------- | ------- | ------------------------------------- |
 | `enabled` | `boolean` | `false` | Enable request validation             |
@@ -532,7 +543,7 @@ export async function sendEmail(to, subject, body) {
 
 ### Server Code Isolation
 
-- Server files (`.server.js`) are never bundled into client code
+- Server files (`.server.js` and `.server.ts`) are never bundled into client code
 - Development builds include safety checks to prevent accidental imports
 - Production builds completely separate server and client code
 
@@ -564,39 +575,138 @@ export async function readAllowedFile(filename) {
 readAllowedFile.schema = FileSchema;
 ```
 
-## 💻 TypeScript Support
+## TypeScript Support
+
+Vite Server Actions provides TypeScript support with automatic type generation:
 
-Vite Server Actions has first-class TypeScript support with automatic type inference:
+### TypeScript Features
+
+- **Automatic Type Generation** - `.d.ts` files generated for all server actions
+- **Real-time Compilation** - TypeScript files compiled on-the-fly in development
+- **Helpful Error Messages** - Development-time suggestions for TypeScript usage
+- **Production Build Support** - Full TypeScript compilation in build process
 
 ```typescript
 // server/users.server.ts
-export async function getUser(id: number) {
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+/**
+ * Get user by ID with full type safety
+ * @param id - The user ID to fetch
+ * @returns Promise containing user data or null
+ */
+export async function getUser(id: number): Promise<User | null> {
   return await db.users.findUnique({ where: { id } });
 }
 
-// App.tsx - Full type inference!
-import { getUser } from "./server/users.server";
+// Client.tsx - Automatic type inference and IntelliSense!
+import { getUser, type User } from "./server/users.server";
 
 const user = await getUser(123); // Type: User | null
 ```
 
-### With Zod Validation
+### Validation with Type Safety
 
 ```typescript
 import { z } from "zod";
 
-const schema = z.object({
-  name: z.string(),
-  age: z.number(),
+// Define your schemas with TypeScript interfaces
+export interface CreateUserInput {
+  name: string;
+  email: string;
+  age?: number;
+}
+
+const CreateUserSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.string().email("Invalid email format"),
+  age: z.number().optional(),
 });
 
-export async function createUser(data: z.infer<typeof schema>) {
-  return await db.users.create({ data });
+export async function createUser(data: CreateUserInput): Promise<User> {
+  const validated = CreateUserSchema.parse(data);
+  return await db.users.create({ data: validated });
+}
+
+// Attach schema for automatic validation and OpenAPI generation
+createUser.schema = z.tuple([CreateUserSchema]);
+```
+
+### Documentation Generation
+
+TypeScript types and JSDoc comments automatically generate API documentation:
+
+```typescript
+/**
+ * Upload a file with validation and type safety
+ * @param fileData - File upload data with filename, content, and metadata
+ * @returns Promise containing upload result with file path and metadata
+ */
+export async function uploadFile(fileData: {
+  filename: string;
+  content: string;
+  mimetype: string;
+}): Promise<FileUploadResult> {
+  // Implementation...
 }
-createUser.schema = schema;
 ```
 
-## 🔧 Error Handling
+This automatically generates:
+
+- **OpenAPI 3.0 specs** with TypeScript types
+- **Swagger UI documentation** with interactive examples
+- **Type definitions** (`.d.ts`) for client-side imports
+
+## Developer Experience
+
+Vite Server Actions provides development feedback and suggestions to improve code quality:
+
+### Code Analysis
+
+The plugin uses AST-based parsing to analyze your server functions and provide helpful feedback:
+
+```typescript
+// The plugin analyzes your code and provides suggestions:
+
+// ⚠️ Warning: Function should be async
+export function syncFunction() {
+  return "data";
+}
+// 💡 Suggestion: Change to: export async function syncFunction()
+
+// ⚠️ Warning: Missing return type annotation
+export async function getUser(id) {
+  return await db.user.findUnique({ where: { id } });
+}
+// 💡 Suggestion: Add return type like: Promise<User | null>
+
+// ⚠️ Warning: Missing validation schema
+export async function updateUser(id, data) {
+  return await db.user.update({ where: { id }, data });
+}
+// Suggestion: Add schema: updateUser.schema = z.tuple([...])
+```
+
+### Development Warnings & Suggestions
+
+- **Type Safety Hints** - Suggestions for adding TypeScript types and return annotations
+- **Schema Validation** - Recommendations for adding Zod schemas to improve API reliability
+- **Function Structure** - Best practices for async functions and proper exports
+- **Security Warnings** - Path traversal detection and secure coding suggestions
+- **Performance Tips** - Optimization suggestions for production builds
+
+### Test Coverage
+
+- **Test Coverage** - Unit and e2e test suites
+- **Framework Support** - Tested with Svelte, Vue, React, and TypeScript React
+- **Production Testing** - Feature parity between development and production modes
+- **Cross-platform** - Works across different operating systems
+
+## Error Handling
 
 Server errors are automatically caught and returned with proper HTTP status codes:
 
@@ -624,7 +734,7 @@ export async function authenticate(token) {
 }
 ```
 
-## 🎯 Common Patterns
+## Common Patterns
 
 ### Authenticated Actions
 
@@ -668,13 +778,13 @@ export async function getExpensiveData(key) {
 }
 ```
 
-## 🤝 Contributing
+## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
 
-## 📄 License
+## License
 
 This project is [MIT](LICENSE) licensed.
 

package/index.d.ts

@@ -8,7 +8,7 @@ export interface ValidationOptions {
 	 * @default false
 	 */
 	enabled?: boolean;
-	
+
 	/**
 	 * Validation adapter to use
 	 * @default "zod"
@@ -22,7 +22,7 @@ export interface OpenAPIOptions {
 	 * @default false
 	 */
 	enabled?: boolean;
-	
+
 	/**
 	 * OpenAPI specification info
 	 */
@@ -31,19 +31,19 @@ export interface OpenAPIOptions {
 		version?: string;
 		description?: string;
 	};
-	
+
 	/**
 	 * Path to serve the Swagger UI documentation
 	 * @default "/api/docs"
 	 */
 	docsPath?: string;
-	
+
 	/**
 	 * Path to serve the OpenAPI JSON specification
 	 * @default "/api/openapi.json"
 	 */
 	specPath?: string;
-	
+
 	/**
 	 * Enable Swagger UI
 	 * @default true when OpenAPI is enabled
@@ -57,46 +57,46 @@ export interface ServerActionOptions {
 	 * @default "/api"
 	 */
 	apiPrefix?: string;
-	
+
 	/**
 	 * Include patterns for server action files
-	 * @default ["**\/*.server.js"]
+	 * @default ["**\/*.server.js", "**\/*.server.ts"]
 	 */
 	include?: string | string[];
-	
+
 	/**
 	 * Exclude patterns for server action files
 	 * @default []
 	 */
 	exclude?: string | string[];
-	
+
 	/**
 	 * Middleware to run before server action handlers
 	 * Can be a single middleware or array of middleware
 	 */
 	middleware?: RequestHandler | RequestHandler[];
-	
+
 	/**
 	 * Transform function for module names (internal use)
 	 * @param filePath - The file path relative to project root
 	 * @returns The module name to use internally
 	 */
 	moduleNameTransform?: (filePath: string) => string;
-	
+
 	/**
 	 * Transform function for API routes
 	 * @param filePath - The file path relative to project root
 	 * @param functionName - The exported function name
 	 * @returns The API route path (without prefix)
-	 * @default Clean hierarchical paths (removes src/ and .server.js)
+	 * @default Clean hierarchical paths (removes src/ and .server.js or .server.ts)
 	 */
 	routeTransform?: (filePath: string, functionName: string) => string;
-	
+
 	/**
 	 * Validation configuration
 	 */
 	validation?: ValidationOptions;
-	
+
 	/**
 	 * OpenAPI documentation configuration
 	 */
@@ -135,7 +135,7 @@ export declare const pathUtils: {
 	 * @returns Clean route path
 	 */
 	createCleanRoute: (filePath: string, functionName: string) => string;
-	
+
 	/**
 	 * Creates legacy underscore-separated routes: "src_actions_todo/create"
 	 * @param filePath - The file path relative to project root
@@ -143,7 +143,7 @@ export declare const pathUtils: {
 	 * @returns Legacy route path
 	 */
 	createLegacyRoute: (filePath: string, functionName: string) => string;
-	
+
 	/**
 	 * Creates minimal routes: "actions/todo.server/create"
 	 * @param filePath - The file path relative to project root
@@ -151,7 +151,7 @@ export declare const pathUtils: {
 	 * @returns Minimal route path
 	 */
 	createMinimalRoute: (filePath: string, functionName: string) => string;
-	
+
 	/**
 	 * Creates module names for internal use
 	 * @param filePath - The file path relative to project root
@@ -162,39 +162,83 @@ export declare const pathUtils: {
 
 // Validation exports
 export interface ValidationAdapter {
-	validate(schema: any, data: any): Promise<any>;
-	getSchemaType(schema: any): string;
+	validate(
+		schema: any,
+		data: any,
+	): Promise<{
+		success: boolean;
+		data?: any;
+		errors?: Array<{ path: string; message: string; code: string; value?: any }>;
+	}>;
+	toOpenAPISchema(schema: any): any;
+	getParameters(schema: any): any[];
 }
 
 export declare class ZodAdapter implements ValidationAdapter {
-	validate(schema: z.ZodSchema<any>, data: any): Promise<any>;
-	getSchemaType(schema: z.ZodSchema<any>): string;
+	validate(
+		schema: z.ZodSchema<any>,
+		data: any,
+	): Promise<{
+		success: boolean;
+		data?: any;
+		errors?: Array<{ path: string; message: string; code: string; value?: any }>;
+	}>;
+	toOpenAPISchema(schema: z.ZodSchema<any>): any;
+	getParameters(schema: z.ZodSchema<any>): any[];
 }
 
 export declare class SchemaDiscovery {
-	constructor();
+	constructor(adapter?: ValidationAdapter);
 	registerSchema(moduleName: string, functionName: string, schema: any): void;
 	getSchema(moduleName: string, functionName: string): any;
+	hasSchema(moduleName: string, functionName: string): boolean;
 	getAllSchemas(): Map<string, any>;
 	discoverFromModule(module: any, moduleName: string): void;
+	clear(): void;
 }
 
 export declare const adapters: {
-	zod: ZodAdapter;
+	zod: typeof ZodAdapter;
 };
 
-export declare function createValidationMiddleware(options: {
-	schemaDiscovery: SchemaDiscovery;
+export declare const defaultAdapter: ZodAdapter;
+export declare const defaultSchemaDiscovery: SchemaDiscovery;
+
+export declare function createValidationMiddleware(options?: {
+	adapter?: ValidationAdapter | "zod";
+	schemaDiscovery?: SchemaDiscovery;
 }): RequestHandler;
 
 // OpenAPI exports
 export declare class OpenAPIGenerator {
-	constructor(options?: { info?: any });
-	generateSpec(serverFunctions: Map<string, any>, schemaDiscovery: SchemaDiscovery, options?: any): any;
+	constructor(options?: {
+		info?: { title?: string; version?: string; description?: string };
+		adapter?: ValidationAdapter;
+		servers?: Array<{ url: string; description?: string }>;
+	});
+	generateSpec(
+		serverFunctions: Map<string, any>,
+		schemaDiscovery: SchemaDiscovery,
+		options?: {
+			apiPrefix?: string;
+			routeTransform?: (filePath: string, functionName: string) => string;
+			port?: number | string;
+		},
+	): any;
 }
 
-export declare function setupOpenAPIEndpoints(app: any, options: any): void;
-
-export declare function createSwaggerMiddleware(spec: any): RequestHandler;
-
-export default serverActions;
+export declare function setupOpenAPIEndpoints(
+	app: any,
+	openAPISpec: any,
+	options?: {
+		docsPath?: string;
+		specPath?: string;
+		enableSwaggerUI?: boolean;
+		port?: number;
+		swaggerOptions?: any;
+	},
+): void;
+
+export declare function createSwaggerMiddleware(spec: any, options?: { swaggerOptions?: any }): RequestHandler[];
+
+export default serverActions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vite-plugin-server-actions",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Server actions for Vite - call backend functions directly from your frontend with automatic API generation, TypeScript support, and zero configuration",
   "keywords": [
     "vite",
@@ -21,7 +21,7 @@
     "middleware",
     "express"
   ],
-  "homepage": "https://github.com/HelgeSverre/vite-plugin-server-actions",
+  "homepage": "https://serveractions.dev",
   "bugs": {
     "url": "https://github.com/HelgeSverre/vite-plugin-server-actions/issues"
   },
@@ -36,43 +36,48 @@
     "url": "https://helgesver.re"
   },
   "type": "module",
-  "main": "src/index.js",
-  "types": "index.d.ts",
   "exports": {
     ".": {
       "import": "./src/index.js",
       "types": "./index.d.ts"
     }
   },
+  "main": "src/index.js",
+  "types": "index.d.ts",
   "files": [
     "src",
     "index.d.ts",
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=16.0.0"
-  },
   "scripts": {
+    "check": "npm run test:run && npm run typecheck",
+    "deploy:docs": "cd docs && vc --prod",
+    "example:react-ts:build": "npm run build --prefix examples/react-todo-app-typescript",
+    "example:react-ts:dev": "npm run dev --prefix examples/react-todo-app-typescript",
+    "example:react:build": "npm run build --prefix examples/react-todo-app",
+    "example:react:dev": "npm run dev --prefix examples/react-todo-app",
     "example:svelte:build": "npm run build --prefix examples/svelte-todo-app",
     "example:svelte:dev": "npm run dev --prefix examples/svelte-todo-app",
     "example:vue:build": "npm run build --prefix examples/vue-todo-app",
     "example:vue:dev": "npm run dev --prefix examples/vue-todo-app",
-    "example:react:build": "npm run build --prefix examples/react-todo-app",
-    "example:react:dev": "npm run dev --prefix examples/react-todo-app",
     "format": "npx prettier --write .",
+    "prepublishOnly": "npm run check",
+    "reset:todos": "node scripts/reset-todos.js",
     "sort": "npx sort-package-json",
     "test": "vitest",
-    "test:run": "vitest run",
     "test:e2e": "playwright test",
+    "test:e2e:clean": "npm run reset:todos && npm run test:e2e",
+    "test:e2e:headed": "playwright test --headed",
     "test:e2e:ui": "playwright test --ui",
-    "typecheck": "tsc --noEmit",
-    "check": "npm run test:run && npm run typecheck",
-    "prepublishOnly": "npm run check",
-    "deploy:docs": "cd docs && vc --prod"
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^7.3.4",
+    "@babel/parser": "^7.27.7",
+    "@babel/traverse": "^7.27.7",
+    "esbuild": "^0.19.0",
     "express": "^4.21.0",
     "minimatch": "^10.0.3",
     "rollup": "^4.0.0",
@@ -88,6 +93,7 @@
     "@types/node": "^24.0.3",
     "@types/swagger-ui-express": "^4.1.6",
     "@vitest/runner": "^3.2.4",
+    "openapi-types": "^12.1.3",
     "playwright": "^1.53.1",
     "prettier": "^3.6.0",
     "typescript": "^5.8.3",
@@ -97,5 +103,8 @@
   "peerDependencies": {
     "vite": "^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0"
   },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "readme": "README.md"
 }