@janux/vite 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# @janux/vite
+
+Vite plugin for [Janux](https://github.com/aralroca/Janux): JSX runtime config, SSR dev bridge, and the SWC transform that swaps `*.api.ts` imports for ~100-byte fetch stubs so server code never reaches client bundles.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@janux/vite",
+  "version": "0.1.0",
+  "description": "Vite plugin for Janux: JSX config, SSR routes, api() client stubs (SWC) and the dev server bridge.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aralroca/Janux.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Aral Roca Gomez",
+    "email": "contact@aralroca.com"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@swc/core": "^1.9.0",
+    "janux": "0.1.0",
+    "@janux/server": "0.1.0",
+    "@janux/agent": "0.1.0"
+  },
+  "peerDependencies": {
+    "vite": ">=5"
+  },
+  "homepage": "https://github.com/aralroca/Janux#readme",
+  "bugs": "https://github.com/aralroca/Janux/issues",
+  "keywords": [
+    "janux",
+    "agentic-ui",
+    "mcp",
+    "webmcp",
+    "ai-agents",
+    "fullstack",
+    "framework",
+    "bun",
+    "vite",
+    "resumability",
+    "copilot"
+  ],
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api-stubs.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'bun:test';
+import { apiModuleName, apiStubModule, exportedApiNames } from './api-stubs';
+
+const serverCode = `
+import { api, schema } from '@janux/server';
+import { db } from './db';
+
+const PAGE_SIZE = 20;
+
+export const searchOrders = api({
+  input: schema({ q: str() }),
+  run: async ({ input }) => db.search(input.q, PAGE_SIZE),
+});
+
+export const refundOrder = api({ guard: 'confirm', run: () => db.refund() });
+
+function helper() {}
+`;
+
+describe('api client stubs (SWC)', () => {
+  it('extracts only exported const names', () => {
+    expect(exportedApiNames(serverCode)).toEqual(['searchOrders', 'refundOrder']);
+  });
+
+  it('derives the module namespace from the filename', () => {
+    expect(apiModuleName('/app/src/server/shop.api.ts')).toBe('shop');
+  });
+
+  it('rejects unsupported export shapes instead of silently dropping them', () => {
+    expect(() => exportedApiNames('export default api({ run: () => 1 });')).toThrow(/only support/);
+    expect(() => exportedApiNames('export function foo() {}')).toThrow(/only support/);
+    expect(() => exportedApiNames('const a = 1; export { a };')).toThrow(/only support/);
+    expect(() => exportedApiNames('export const { a } = obj;')).toThrow(/destructured/);
+    expect(exportedApiNames('export type X = string; export const ok = api({run(){}});')).toEqual(['ok']);
+  });
+
+  it('emits fetch stubs and never leaks server code to the client', () => {
+    const stub = apiStubModule('/app/src/server/shop.api.ts', serverCode);
+
+    expect(stub).toContain(`export const searchOrders = clientApi("shop.searchOrders");`);
+    expect(stub).toContain(`export const refundOrder = clientApi("shop.refundOrder");`);
+    expect(stub).not.toContain('db.search');
+    expect(stub).not.toContain('PAGE_SIZE');
+  });
+});

package/src/api-stubs.ts

@@ -0,0 +1,59 @@
+import { parseSync } from '@swc/core';
+import { basename } from 'node:path';
+
+const UNSUPPORTED_EXPORTS = new Set([
+  'ExportDefaultDeclaration',
+  'ExportDefaultExpression',
+  'ExportNamedDeclaration',
+  'ExportAllDeclaration',
+]);
+
+function assertSupportedExport(node: any): void {
+  if (UNSUPPORTED_EXPORTS.has(node.type)) {
+    throw new Error(
+      `Janux: *.api.ts modules only support \`export const name = api({...})\` — found ${node.type}`,
+    );
+  }
+  if (node.type !== 'ExportDeclaration') return;
+  if (node.declaration?.type?.startsWith('Ts')) return;
+  if (node.declaration?.type !== 'VariableDeclaration') {
+    throw new Error(
+      `Janux: *.api.ts modules only support \`export const name = api({...})\` — found exported ${node.declaration?.type}`,
+    );
+  }
+  node.declaration.declarations.forEach((declaration: any) => {
+    if (declaration.id?.type !== 'Identifier') {
+      throw new Error('Janux: destructured exports are not supported in *.api.ts modules');
+    }
+  });
+}
+
+/** Extracts exported const names from a `*.api.ts` module using SWC (no Babel). */
+export function exportedApiNames(code: string): string[] {
+  const module = parseSync(code, { syntax: 'typescript', tsx: false });
+
+  return module.body.flatMap((node: any) => {
+    assertSupportedExport(node);
+    if (node.type !== 'ExportDeclaration') return [];
+    if (node.declaration?.type !== 'VariableDeclaration') return [];
+
+    return node.declaration.declarations.map((declaration: any) => declaration.id.value);
+  });
+}
+
+export function apiModuleName(filePath: string): string {
+  return basename(filePath).replace(/\.api\.[tj]s$/, '');
+}
+
+/**
+ * Client projection of a server api module: every export becomes a typed
+ * fetch stub. Server code never reaches the browser bundle (RFC §7.1).
+ */
+export function apiStubModule(filePath: string, code: string): string {
+  const moduleName = apiModuleName(filePath);
+  const stubs = exportedApiNames(code)
+    .map((name) => `export const ${name} = clientApi(${JSON.stringify(`${moduleName}.${name}`)});`)
+    .join('\n');
+
+  return `import { clientApi } from 'janux/client';\n${stubs}\n`;
+}

package/src/app-config.ts

@@ -0,0 +1,48 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface JanuxAppConfig {
+  root: string;
+  routesDir: string;
+  serverDir: string;
+  clientEntry: string;
+  agentModule?: string;
+  storesModule?: string;
+  stylesheet?: string;
+  title?: string;
+}
+
+export interface JanuxPluginOptions {
+  routesDir?: string;
+  serverDir?: string;
+  clientEntry?: string;
+  agentModule?: string;
+  storesModule?: string;
+  title?: string;
+}
+
+function optional(path: string): string | undefined {
+  return existsSync(path) ? path : undefined;
+}
+
+/** Resolves the conventional app layout: src/routes, src/server, src/client.ts, src/agent.ts, src/stores.ts. */
+export function resolveAppConfig(root: string, options: JanuxPluginOptions = {}): JanuxAppConfig {
+  return {
+    root,
+    routesDir: resolve(root, options.routesDir ?? 'src/routes'),
+    serverDir: resolve(root, options.serverDir ?? 'src/server'),
+    clientEntry: options.clientEntry ?? optional(resolve(root, 'src/client.ts')) ?? '',
+    agentModule: options.agentModule ?? optional(resolve(root, 'src/agent.ts')),
+    storesModule: options.storesModule ?? optional(resolve(root, 'src/stores.ts')),
+    stylesheet: optional(resolve(root, 'src/styles.css')),
+    title: options.title,
+  };
+}
+
+export function apiFiles(serverDir: string): string[] {
+  if (!existsSync(serverDir)) return [];
+
+  return readdirSync(serverDir)
+    .filter((entry) => /\.api\.[tj]s$/.test(entry))
+    .map((entry) => join(serverDir, entry));
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { janux } from './plugin';
+export { resolveAppConfig, apiFiles, type JanuxPluginOptions, type JanuxAppConfig } from './app-config';
+export { apiStubModule, exportedApiNames, apiModuleName } from './api-stubs';
+export { toFetchRequest, sendFetchResponse } from './request-adapter';

package/src/plugin.ts

@@ -0,0 +1,89 @@
+import type { Plugin, ViteDevServer } from 'vite';
+import { createJanuxServer, type ServerOptions } from '@janux/server';
+import { defineAgent } from '@janux/agent';
+import { apiFiles, resolveAppConfig, type JanuxPluginOptions } from './app-config';
+import { apiModuleName, apiStubModule } from './api-stubs';
+import { sendFetchResponse, toFetchRequest } from './request-adapter';
+
+const SSR_PACKAGES = ['janux', '@janux/server', '@janux/agent'];
+
+async function loadServerOptions(vite: ViteDevServer, options: JanuxPluginOptions): Promise<ServerOptions> {
+  const app = resolveAppConfig(vite.config.root, options);
+  const apiModules = Object.fromEntries(
+    await Promise.all(
+      apiFiles(app.serverDir).map(async (file) => [
+        apiModuleName(file),
+        (await vite.ssrLoadModule(file)) as Record<string, unknown>,
+      ]),
+    ),
+  );
+  const agentModule = app.agentModule ? await vite.ssrLoadModule(app.agentModule) : undefined;
+  const storesModule = app.storesModule ? await vite.ssrLoadModule(app.storesModule) : undefined;
+
+  return {
+    routesDir: app.routesDir,
+    loadRoute: (filePath) => vite.ssrLoadModule(filePath),
+    apis: apiModules,
+    agent: (agentModule?.default as ServerOptions['agent']) ?? defineAgent(),
+    storeDefs: (storesModule ?? {}) as ServerOptions['storeDefs'],
+    runtimeUrl: app.clientEntry ? `/${relativeToRoot(vite.config.root, app.clientEntry)}` : undefined,
+    stylesheets: app.stylesheet ? [`/${relativeToRoot(vite.config.root, app.stylesheet)}`] : [],
+    title: app.title,
+  };
+}
+
+function relativeToRoot(root: string, absolute: string): string {
+  return absolute.startsWith(root) ? absolute.slice(root.length + 1) : absolute;
+}
+
+/** The Janux Vite plugin: JSX runtime config, api() client stubs (SWC) and the SSR dev bridge. */
+export function janux(options: JanuxPluginOptions = {}): Plugin {
+  return {
+    name: 'janux',
+
+    config() {
+      return {
+        appType: 'custom',
+        esbuild: { jsx: 'automatic', jsxImportSource: 'janux' },
+        resolve: { dedupe: ['janux'] },
+        ssr: { noExternal: SSR_PACKAGES },
+        optimizeDeps: { exclude: SSR_PACKAGES },
+      };
+    },
+
+    transform(code, id, transformOptions) {
+      if (!/\.api\.[tj]s($|\?)/.test(id)) return undefined;
+      if (transformOptions?.ssr) return undefined;
+
+      return { code: apiStubModule(id, code), map: null };
+    },
+
+    configureServer(vite) {
+      let cached: Promise<ReturnType<typeof createJanuxServer>> | undefined;
+
+      const januxServer = () => {
+        cached ??= loadServerOptions(vite, options).then(createJanuxServer);
+
+        return cached;
+      };
+
+      vite.watcher.on('change', () => {
+        cached = undefined;
+      });
+
+      return () => {
+        vite.middlewares.use((req, res, next) => {
+          const handle = async () => {
+            const server = await januxServer();
+            const response = await server.fetch(await toFetchRequest(req));
+
+            if (response.status === 404 && !req.url?.startsWith('/_janux/')) return next();
+            await sendFetchResponse(res, response);
+          };
+
+          handle().catch(next);
+        });
+      };
+    },
+  };
+}

package/src/request-adapter.ts

@@ -0,0 +1,26 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+async function readBody(req: IncomingMessage): Promise<Buffer | undefined> {
+  if (req.method === 'GET' || req.method === 'HEAD') return undefined;
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of req) chunks.push(chunk as Buffer);
+
+  return Buffer.concat(chunks);
+}
+
+export async function toFetchRequest(req: IncomingMessage): Promise<Request> {
+  const host = req.headers.host ?? 'localhost';
+  const body = await readBody(req);
+
+  return new Request(`http://${host}${req.url ?? '/'}`, {
+    method: req.method,
+    headers: Object.entries(req.headers).map(([name, value]) => [name, String(value)] as [string, string]),
+    body: body && body.length > 0 ? new Uint8Array(body) : undefined,
+  });
+}
+
+export async function sendFetchResponse(res: ServerResponse, response: Response): Promise<void> {
+  res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
+  res.end(Buffer.from(await response.arrayBuffer()));
+}