vite-plugin-server-actions 0.1.0

package/.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+indent_style = tab
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+
+[test/**/expected.css]
+insert_final_newline = false
+
+[package.json]
+indent_style = space
+
+[*.md]
+trim_trailing_whitespace = true
+indent_size = 2
+indent_style = space

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+	"printWidth": 120,
+	"quoteProps": "consistent",
+	"semi": true,
+	"singleQuote": false,
+	"bracketSameLine": false
+}

package/README.md

@@ -0,0 +1,192 @@
+# 🚀 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)
+[![Build Status](https://img.shields.io/github/workflow/status/HelgeSverre/vite-plugin-server-actions/CI)](https://github.com/HelgeSverre/vite-plugin-server-actions/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> 🚧 **Experimental:** This is currently a proof of concept. Use at your own risk.
+
+
+**Vite Server Actions** is a Vite plugin that makes it easy to create functions (actions) that runs on the server, while
+allowing you to call them from the client-side as if they were local functions.
+
+## ✨ Features
+
+- 🔄 Automatic API endpoint creation for server functions (e.g. `POST /api/todos/addTodo`)
+- 🔗 Seamless client-side proxies for easy usage (e.g. `import {addTodo} from './server/todos.server.js'`)
+- 🛠 Support for both development and production environments ( `vite build` )
+- 🚀 Zero-config setup for instant productivity
+
+## 🚀 Quick Start
+
+1. Install the plugin:
+
+```bash
+# Install using npm
+npm install vite-plugin-server-actions
+
+# Install using yarn
+yarn add vite-plugin-server-actions
+```
+
+2. Add to your `vite.config.js`:
+
+```javascript
+import {defineConfig} from "vite";
+import serverActions from "helgesverre/vite-plugin-server-actions";
+
+export default defineConfig({
+  plugins: [serverActions()],
+});
+```
+
+3. Create a `[whatever].server.js` file anywhere in your project:
+
+```javascript
+// ex: src/actions/todo.server.js
+import fs from "fs";
+import path from "path";
+
+const TODO_FILE_PATH = path.join(process.cwd(), "list-of-todos.json");
+
+export async function deleteTodoById(id) {
+  const data = fs.readFileSync(TODO_FILE_PATH, "utf-8");
+  const todos = JSON.parse(data);
+  const newTodos = todos.filter((todo) => todo.id !== id);
+  fs.writeFileSync(TODO_FILE_PATH, JSON.stringify(newTodos, null, 2));
+}
+
+export async function saveTodoToJsonFile(todo) {
+  const data = fs.readFileSync(TODO_FILE_PATH, "utf-8");
+  const todos = JSON.parse(data);
+  todos.push(todo);
+  fs.writeFileSync(TODO_FILE_PATH, JSON.stringify(todos, null, 2));
+}
+
+export async function listTodos() {
+  const data = fs.readFileSync(TODO_FILE_PATH, "utf-8");
+  return JSON.parse(data);
+}
+```
+
+4. Import and use your server actions in your client-side code:
+
+```svelte
+<!-- ex: src/App.svelte -->
+<script>
+  import { deleteTodoById, listTodos, saveTodoToJsonFile } from "./actions/todo.server.js";
+
+  let todos = [];
+  let newTodoText = "";
+
+  async function fetchTodos() {
+    todos = await listTodos();
+  }
+
+  async function addTodo() {
+    await saveTodoToJsonFile({ id: Math.random(), text: newTodoText });
+    newTodoText = "";
+    await fetchTodos();
+  }
+
+  async function removeTodo(id) {
+    await deleteTodoById(id);
+    await fetchTodos();
+  }
+
+  fetchTodos();
+</script>
+
+<div>
+  <h1>Todos</h1>
+  <ul>
+    {#each todos as todo}
+    <li>
+      {todo.text}
+      <button on:click="{() => removeTodo(todo.id)}">Remove</button>
+    </li>
+    {/each}
+  </ul>
+  <input type="text" bind:value="{newTodoText}" />
+  <button on:click="{addTodo}">Add Todo</button>
+</div>
+```
+
+## 🤯 How it works
+
+Vite Server Actions works by creating an API endpoint for each server function you define.
+
+When you import a server action in your client-side code, Vite Server Actions will intercept the import and return a
+proxy function that sends a request to the server endpoint instead of executing the function locally.
+
+In development mode, the server is run as a middleware in the Vite dev server, while in production mode, the server is
+bundled into a single file that can be run with Node.js.
+
+### Sequence Diagram
+
+```mermaid
+sequenceDiagram
+  participant Client
+  participant Vite Dev Server
+  participant Plugin Middleware
+  participant Server Function
+  participant File System
+  Client ->> Vite Dev Server: import { addTodo } from './server/todos.server.js'
+  Vite Dev Server ->> Client: Returns proxied function
+  Client ->> Client: Call addTodo({ text: 'New todo' })
+  Client ->> Vite Dev Server: POST /api/todos/addTodo
+  Vite Dev Server ->> Plugin Middleware: Handle POST request
+  Plugin Middleware ->> Server Function: Call addTodo function
+  Server Function ->> File System: Read todos.json
+  File System ->> Server Function: Return current todos
+  Server Function ->> Server Function: Add new todo
+  Server Function ->> File System: Write updated todos.json
+  File System ->> Server Function: Write confirmation
+  Server Function ->> Plugin Middleware: Return new todo
+  Plugin Middleware ->> Vite Dev Server: Send JSON response
+  Vite Dev Server ->> Client: Return new todo data
+```
+
+## 🔧 Configuration
+
+Vite Server Actions works out of the box, but you can customize it:
+
+```javascript
+serverActions({
+  // Options (coming soon)
+});
+```
+
+## 🛠️ Configuration Options
+
+TODO: Add configuration options and descriptions
+
+| Option           | Type                                   | Default     | Description                      |
+|------------------|----------------------------------------|-------------|----------------------------------|
+| logLevel         | 'error' \| 'warn' \| 'info' \| 'debug' | 'info'      | Server log level                 |
+| serverPath       | string                                 | '/api'      | Base path for server endpoints   |
+| serverPort       | number                                 | 3000        | Port for the server              |
+| serverHost       | string                                 | 'localhost' | Host for the server              |
+| serverMiddleware | (app: Express) => void                 | -           | Custom middleware for the server |
+
+## TODO
+
+This is a proof of concept, and things are still missing, such as:
+
+- [ ] Add configuration options
+- [ ] Add tests
+- [ ] Allow customizing the HTTP method for each action (e.g. `GET`, `POST`, `PUT`, `DELETE`)
+- [ ] Make sure name collisions are handled correctly
+- [ ] Make sure the actions are only available on the server when running in production mode.
+- [ ] Add more examples (Vue, React, etc.)
+- [ ] Publish to npm
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome! Feel free to
+check [issues page](https://github.com/helgesverre/vite-plugin-server-actions/issues).
+
+## 📝 License
+
+This project is [MIT](https://opensource.org/licenses/MIT) licensed.

package/examples/todo-app/.prettierrc

@@ -0,0 +1,17 @@
+{
+	"plugins": ["prettier-plugin-svelte", "prettier-plugin-tailwindcss"],
+	"overrides": [
+		{
+			"files": "*.svelte",
+			"options": {
+				"parser": "svelte",
+				"svelteAllowShorthand": false
+			}
+		}
+	],
+	"printWidth": 120,
+	"quoteProps": "consistent",
+	"semi": true,
+	"singleQuote": false,
+	"bracketSameLine": false
+}

package/examples/todo-app/README.md

@@ -0,0 +1,58 @@
+# Vite Server Actions - TODO App Example
+
+This is an example of a simple TODO application that
+uses [Vite Server Actions](https://github.com/HelgeSverre/vite-plugin-server-actions)
+and [Svelte](https://svelte.dev/) to demonstrate a real-world use case, where server actions are used to save, list, and
+delete TODOs, with data stored in a JSON file.
+
+## 🚀 Quick Start
+
+### Clone the repository and install dependencies
+
+```shell
+git clone
+cd examples/todo-app
+npm install
+```
+
+## Run in development mode
+
+```shell
+npm install
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) to view it in your browser. (Note: The port may vary, check the
+console output for the correct port)
+
+## Build and run in production mode
+
+Server Actions works in production mode by bundling the server into a single file that can be run with Node.js.
+
+Here's how you can build and run the example in production mode:
+
+```shell
+# Install dependencies and build the project
+npm install
+npm run build
+
+# Run the generated express.js server
+node dist/server.js
+```
+
+Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+
+## 📁 Project Structure
+
+The important files and directories in this example are:
+
+- `src/` - Contains the client-side Svelte application
+- `src/actions/` - Contains the server action files (functions that are run on the server, note the `.server.js` suffix)
+  - `src/actions/todo.server.js` - Contains server actions for managing TODOs
+  - `src/actions/auth.server.js` - Contains a dummy server action for demonstration purposes
+- `src/App.svelte` - The main Svelte component that imports and calls the server actions to manage TODOs.
+- `vite.config.js` - Vite configuration file that includes the Server Actions plugin `serverActions()`
+- `dist/` - The output directory for the production build.
+- `dist/server.js` - The express server that serves the client-side application and the server actions (automatically
+  created by the plugin)
+- `todos.json` - The JSON file where the TODOs are stored (serves the purpose of a simple database for this example)

package/examples/todo-app/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>TODO Example Svelte</title>
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="/src/main.js"></script>
+	</body>
+</html>

package/examples/todo-app/jsconfig.json

@@ -0,0 +1,32 @@
+{
+	"compilerOptions": {
+		"moduleResolution": "bundler",
+		"target": "ESNext",
+		"module": "ESNext",
+		/**
+		 * svelte-preprocess cannot figure out whether you have
+		 * a value or a type, so tell TypeScript to enforce using
+		 * `import type` instead of `import` for Types.
+		 */
+		"verbatimModuleSyntax": true,
+		"isolatedModules": true,
+		"resolveJsonModule": true,
+		/**
+		 * To have warnings / errors of the Svelte compiler at the
+		 * correct position, enable source maps by default.
+		 */
+		"sourceMap": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		/**
+		 * Typecheck JS in `.svelte` and `.js` files by default.
+		 * Disable this if you'd like to use dynamic types.
+		 */
+		"checkJs": true
+	},
+	/**
+	 * Use global.d.ts instead of compilerOptions.types
+	 * to avoid limiting type declarations.
+	 */
+	"include": ["src/**/*.d.ts", "src/**/*.js", "src/**/*.svelte"]
+}

package/examples/todo-app/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "todo-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "format": "npx prettier --write .",
+    "preview": "vite preview",
+    "sort": "npx sort-package-json"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^3.1.1",
+    "prettier": "^3.3.3",
+    "prettier-plugin-svelte": "^3.2.6",
+    "prettier-plugin-tailwindcss": "^0.6.5",
+    "svelte": "^4.2.18",
+    "vite": "^5.4.1",
+    "vite-plugin-inspect": "^0.8.7"
+  }
+}

package/examples/todo-app/src/App.svelte

@@ -0,0 +1,155 @@
+<script>
+	import { onMount } from "svelte";
+	import { addTodo, deleteTodo, getTodos, updateTodo } from "./actions/todo.server.js";
+	import { login } from "./actions/auth.server.js";
+
+	let todos = [];
+	let newTodoText = "";
+
+	onMount(() => {
+		login("admin", "admin");
+		loadTodos();
+	});
+
+	async function loadTodos() {
+		console.log("Loading todos...");
+		todos = await getTodos();
+	}
+
+	async function handleAddTodo() {
+		if (!newTodoText.trim()) return;
+
+		await addTodo({ text: newTodoText });
+		await loadTodos();
+		newTodoText = "";
+	}
+
+	async function handleToggleTodo(id) {
+		const todo = todos.find((t) => t.id === id);
+		if (todo) {
+			const updatedTodo = await updateTodo(id, { completed: !todo.completed });
+			todos = todos.map((t) => (t.id === id ? updatedTodo : t));
+		}
+	}
+
+	async function handleDeleteTodo(id) {
+		await deleteTodo(id);
+		await loadTodos();
+	}
+</script>
+
+<main>
+	<h1>Todo List</h1>
+
+	<form class="todo-form" on:submit|preventDefault={handleAddTodo}>
+		<input class="todo-input" bind:value={newTodoText} placeholder="Add a new todo" />
+		<button class="todo-button" type="submit">Add</button>
+	</form>
+
+	{#if todos.length > 0}
+		<ul class="todo-list">
+			{#each todos as todo}
+				<li class="todo-item">
+					<input type="checkbox" checked={todo.completed} on:change={() => handleToggleTodo(todo.id)} />
+					<span class:completed={todo.completed}>{todo.text}</span>
+					<button class="delete-button" on:click={() => handleDeleteTodo(todo.id)}>Delete</button>
+				</li>
+			{/each}
+		</ul>
+	{/if}
+</main>
+
+<style>
+	/* Basic global styling */
+	main {
+		font-family: sans-serif;
+		max-width: 600px;
+		margin: 2rem auto;
+		padding: 1rem;
+		background-color: #f8f8f8;
+		border-radius: 8px;
+		box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+	}
+
+	h1 {
+		text-align: center;
+		color: #333;
+		margin-bottom: 1rem;
+	}
+
+	.todo-form {
+		display: flex;
+		gap: 0.5rem;
+		margin-bottom: 1rem;
+	}
+
+	.todo-input {
+		flex: 1;
+		padding: 0.5rem;
+		border: 1px solid #ccc;
+		border-radius: 4px;
+		font-size: 1rem;
+	}
+
+	.todo-button {
+		padding: 0.5rem 1rem;
+		font-size: 1rem;
+		color: white;
+		background-color: #333;
+		border: none;
+		border-radius: 4px;
+		cursor: pointer;
+	}
+
+	.todo-button:hover {
+		background-color: #555;
+	}
+
+	.todo-list {
+		list-style: none;
+		padding: 0;
+		margin: 0;
+		border-top: 1px solid #e0e0e0;
+	}
+
+	.todo-item {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding: 0.5rem;
+		border-bottom: 1px solid #e0e0e0;
+	}
+
+	.todo-item:last-child {
+		border-bottom: none;
+	}
+
+	.todo-item input[type="checkbox"] {
+		margin-right: 1rem;
+	}
+
+	.todo-item span {
+		flex: 1;
+		font-size: 1rem;
+		color: #333;
+	}
+
+	.todo-item span.completed {
+		text-decoration: line-through;
+		color: #888;
+	}
+
+	.delete-button {
+		padding: 0.25rem 0.5rem;
+		font-size: 0.875rem;
+		color: #fff;
+		background-color: #cc0000;
+		border: none;
+		border-radius: 4px;
+		cursor: pointer;
+	}
+
+	.delete-button:hover {
+		background-color: #ff3333;
+	}
+</style>

package/examples/todo-app/src/actions/auth.server.js

@@ -0,0 +1,14 @@
+export function login(user, pass) {
+	if (user === "admin" && pass === "admin") {
+		return {
+			user: "admin",
+			role: "admin",
+		};
+	} else {
+		throw new Error("Invalid user or password");
+	}
+}
+
+export function logout() {
+	return true;
+}

package/examples/todo-app/src/actions/todo.server.js

@@ -0,0 +1,57 @@
+import fs from "fs/promises";
+import path from "path";
+
+const TODO_FILE = path.join(process.cwd(), "todos.json");
+
+async function readTodos() {
+	try {
+		const data = await fs.readFile(TODO_FILE, "utf8");
+		return JSON.parse(data);
+	} catch (error) {
+		console.log(error);
+		if (error.code === "ENOENT") {
+			// File doesn't exist, return an empty array
+			return [];
+		}
+		console.error("Error reading todos:", error);
+		throw error;
+	}
+}
+
+async function writeTodos(todos) {
+	try {
+		await fs.writeFile(TODO_FILE, JSON.stringify(todos, null, 2), "utf8");
+	} catch (error) {
+		console.error("Error writing todos:", error);
+		throw error;
+	}
+}
+
+export async function getTodos() {
+	return await readTodos();
+}
+
+export async function addTodo(todo) {
+	const todos = await readTodos();
+	const newTodo = { id: Date.now(), text: todo.text, completed: false };
+	todos.push(newTodo);
+	await writeTodos(todos);
+	return newTodo;
+}
+
+export async function updateTodo(id, updates) {
+	const todos = await readTodos();
+	const index = todos.findIndex((todo) => todo.id === id);
+	if (index !== -1) {
+		todos[index] = { ...todos[index], ...updates };
+		await writeTodos(todos);
+		return todos[index];
+	}
+	throw new Error("Todo not found");
+}
+
+export async function deleteTodo(id) {
+	const todos = await readTodos();
+	const newTodos = todos.filter((todo) => todo.id != id);
+	await writeTodos(newTodos);
+}

package/examples/todo-app/src/main.js

@@ -0,0 +1,8 @@
+import "./app.css";
+import App from "./App.svelte";
+
+const app = new App({
+	target: document.getElementById("app"),
+});
+
+export default app;

package/examples/todo-app/svelte.config.js

@@ -0,0 +1,7 @@
+import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+
+export default {
+	// Consult https://svelte.dev/docs#compile-time-svelte-preprocess
+	// for more information about preprocessors
+	preprocess: vitePreprocess(),
+};

package/examples/todo-app/todos.json

@@ -0,0 +1,27 @@
+[
+	{
+		"id": 1,
+		"text": "Finish writing documentation",
+		"completed": false
+	},
+	{
+		"id": 2,
+		"text": "Implement authentication logic",
+		"completed": true
+	},
+	{
+		"id": 3,
+		"text": "Design user interface",
+		"completed": false
+	},
+	{
+		"id": 4,
+		"text": "Test server actions",
+		"completed": true
+	},
+	{
+		"id": 5,
+		"text": "Deploy application",
+		"completed": false
+	}
+]

package/examples/todo-app/vite.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import serverActions from "../../src/index.js";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+	plugins: [
+		svelte(),
+		serverActions(),
+		// ...
+	],
+});