nuxt-edge-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+# nuxt-edge-ai
+
+`nuxt-edge-ai` is a Nuxt module for building local-first AI applications with a real server-side WASM inference runtime.
+
+It ships:
+
+- a Nuxt module install surface
+- Nitro API routes for health, model pull, and generation
+- a client composable for app-side usage
+- a vendored `transformers.js` + `onnxruntime-web` runtime inside the package
+- no Ollama, no `llama.cpp`, no Rust/C++/native runtime dependency for consumers
+
+The model weights are not bundled. Users either point the module at a local model directory or allow it to download and cache the model on first run.
+
+## Why this exists
+
+The goal is to make `nuxt-edge-ai` a credible, publishable Nuxt module:
+
+- installable in a regular Nuxt app
+- able to run a real local model
+- packaged as JS/TS + WASM only
+- suitable as a strong portfolio / resume project
+
+## Current runtime
+
+Current real runtime path:
+
+- `transformers.js` web build
+- `onnxruntime-web` WASM backend
+- server-side execution through Nitro
+
+Recommended first demo model:
+
+- `Xenova/distilgpt2` for quick validation
+
+Recommended next upgrade target:
+
+- `onnx-community/Qwen2.5-0.5B-Instruct-ONNX`
+
+## Install
+
+```bash
+pnpm add nuxt-edge-ai
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-edge-ai'],
+  edgeAI: {
+    runtime: 'transformers-wasm',
+    cacheDir: './.cache/nuxt-edge-ai',
+    model: {
+      id: 'Xenova/distilgpt2',
+      task: 'text-generation',
+      allowRemote: true,
+      dtype: 'q8',
+      generation: {
+        maxNewTokens: 96,
+        temperature: 0.7,
+        topP: 0.9,
+        doSample: true,
+        repetitionPenalty: 1.05,
+      },
+    },
+  },
+})
+```
+
+```vue
+<script setup lang="ts">
+const edgeAI = useEdgeAI()
+
+await edgeAI.pull()
+
+const result = await edgeAI.generate({
+  prompt: 'Write a pitch for a local-first Nuxt AI module.',
+})
+</script>
+```
+
+## Consumer runtime guarantees
+
+Consumers do not need to install:
+
+- Ollama
+- Rust
+- C++
+- Python
+- `llama.cpp`
+- extra runtime npm packages beyond this module
+
+What consumers do need:
+
+- a Node/Nitro server runtime
+- a model path or permission to download a compatible model
+
+## API surface
+
+- `GET /api/edge-ai/health`
+- `POST /api/edge-ai/pull`
+- `POST /api/edge-ai/generate`
+- `useEdgeAI().health()`
+- `useEdgeAI().pull()`
+- `useEdgeAI().generate()`
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Useful commands:
+
+```bash
+pnpm vendor:runtime
+pnpm lint
+pnpm test
+pnpm test:types
+pnpm prepack
+```
+
+## Docs
+
+See [`docs/index.md`](./docs/index.md) for the project docs tree.
+
+## Repository shape
+
+This repository follows a Nuxt modules-style layout:
+
+- `src/module.ts`: module entry and runtime config wiring
+- `src/runtime/`: composables, plugin, and Nitro runtime code
+- `playground/`: interactive demo app
+- `test/fixtures/`: module consumer fixtures
+- `docs/`: module documentation
+- `scripts/vendor-runtime.mjs`: vendored runtime generation
+
+## Status
+
+This is an MVP, but it now runs a real model instead of mock text when `runtime: 'transformers-wasm'` is enabled.

package/dist/module.d.mts

@@ -0,0 +1,23 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { EdgeAIGenerationOptions } from '../dist/runtime/types.js';
+export { EdgeAIGenerateRequest, EdgeAIGenerateResponse, EdgeAIHealthResponse, EdgeAIPullResponse } from '../dist/runtime/types.js';
+
+interface EdgeAIModelOptions {
+    id: string;
+    task: 'text-generation';
+    localPath?: string;
+    allowRemote: boolean;
+    dtype?: string;
+    generation: EdgeAIGenerationOptions;
+}
+interface ModuleOptions {
+    routeBase: string;
+    runtime: 'transformers-wasm' | 'mock';
+    cacheDir: string;
+    warmup: boolean;
+    model: EdgeAIModelOptions;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { EdgeAIModelOptions, ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-edge-ai",
+  "configKey": "edgeAI",
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,121 @@
+import { isAbsolute, resolve } from 'node:path';
+import { defineNuxtModule, createResolver, addImportsDir, addPlugin, addServerHandler, addTypeTemplate } from '@nuxt/kit';
+
+function resolveMaybeAbsolute(rootDir, value) {
+  if (!value) {
+    return void 0;
+  }
+  return isAbsolute(value) ? value : resolve(rootDir, value);
+}
+function normalizeRouteBase(routeBase) {
+  const normalized = routeBase.trim().replace(/\/+$/, "");
+  return normalized || "/api/edge-ai";
+}
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-edge-ai",
+    configKey: "edgeAI"
+  },
+  defaults: {
+    routeBase: "/api/edge-ai",
+    runtime: "transformers-wasm",
+    cacheDir: "./.cache/nuxt-edge-ai",
+    warmup: false,
+    model: {
+      id: "Xenova/distilgpt2",
+      task: "text-generation",
+      allowRemote: true,
+      dtype: "q8",
+      generation: {
+        maxNewTokens: 96,
+        temperature: 0.7,
+        topP: 0.9,
+        doSample: true,
+        repetitionPenalty: 1.05
+      }
+    }
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const routeBase = normalizeRouteBase(options.routeBase);
+    const cacheDir = resolveMaybeAbsolute(nuxt.options.rootDir, options.cacheDir) ?? options.cacheDir;
+    const modelLocalPath = resolveMaybeAbsolute(nuxt.options.rootDir, options.model.localPath);
+    const runtimeConfig = nuxt.options.runtimeConfig;
+    runtimeConfig.edgeAI = {
+      routeBase,
+      runtime: options.runtime,
+      cacheDir,
+      warmup: options.warmup,
+      model: {
+        id: options.model.id,
+        task: options.model.task,
+        localPath: modelLocalPath,
+        allowRemote: options.model.allowRemote,
+        dtype: options.model.dtype,
+        generation: {
+          maxNewTokens: options.model.generation.maxNewTokens,
+          temperature: options.model.generation.temperature,
+          topP: options.model.generation.topP,
+          doSample: options.model.generation.doSample,
+          repetitionPenalty: options.model.generation.repetitionPenalty
+        }
+      }
+    };
+    runtimeConfig.public.edgeAI = {
+      routeBase,
+      runtime: options.runtime,
+      defaultModel: options.model.id
+    };
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addPlugin(resolver.resolve("./runtime/plugin"));
+    addServerHandler({
+      route: `${routeBase}/health`,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/api/health.get")
+    });
+    addServerHandler({
+      route: `${routeBase}/pull`,
+      method: "post",
+      handler: resolver.resolve("./runtime/server/api/pull.post")
+    });
+    addServerHandler({
+      route: `${routeBase}/generate`,
+      method: "post",
+      handler: resolver.resolve("./runtime/server/api/generate.post")
+    });
+    addTypeTemplate({
+      filename: "types/nuxt-edge-ai.d.ts",
+      getContents: () => `import type { NuxtApp } from '#app'
+import type {
+  EdgeAIPullResponse,
+  EdgeAIGenerateRequest,
+  EdgeAIGenerateResponse,
+  EdgeAIHealthResponse
+} from 'nuxt-edge-ai'
+
+declare module '#app' {
+  interface NuxtApp {
+    $edgeAI: {
+      routeBase: string
+      runtime: 'transformers-wasm' | 'mock'
+      defaultModel: string
+      pull: () => Promise<EdgeAIPullResponse>
+      generate: (payload: EdgeAIGenerateRequest) => Promise<EdgeAIGenerateResponse>
+      health: () => Promise<EdgeAIHealthResponse>
+    }
+  }
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $edgeAI: NuxtApp['$edgeAI']
+  }
+}
+
+export {}
+`
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/composables/useEdgeAI.d.ts

@@ -0,0 +1,9 @@
+import type { EdgeAIGenerateRequest, EdgeAIGenerateResponse, EdgeAIHealthResponse, EdgeAIPullResponse } from '../types.js';
+export declare function useEdgeAI(): {
+    routeBase: string;
+    defaultModel: string;
+    runtime: "transformers-wasm" | "mock";
+    pull(): Promise<EdgeAIPullResponse>;
+    generate(payload: EdgeAIGenerateRequest): Promise<EdgeAIGenerateResponse>;
+    health(): Promise<EdgeAIHealthResponse>;
+};

package/dist/runtime/composables/useEdgeAI.js

@@ -0,0 +1,24 @@
+import { useNuxtApp, useRuntimeConfig } from "#app";
+export function useEdgeAI() {
+  const config = useRuntimeConfig();
+  const nuxtApp = useNuxtApp();
+  const edgeAIService = nuxtApp.$edgeAI;
+  const publicConfig = config.public.edgeAI;
+  const routeBase = publicConfig.routeBase;
+  const defaultModel = publicConfig.defaultModel;
+  const runtime = publicConfig.runtime;
+  return {
+    routeBase,
+    defaultModel,
+    runtime,
+    pull() {
+      return edgeAIService.pull();
+    },
+    generate(payload) {
+      return edgeAIService.generate(payload);
+    },
+    health() {
+      return edgeAIService.health();
+    }
+  };
+}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,21 @@
+import type { EdgeAIGenerateRequest, EdgeAIGenerateResponse, EdgeAIHealthResponse, EdgeAIPullResponse } from './types.js';
+declare const _default: import("nuxt/app").Plugin<{
+    edgeAI: {
+        routeBase: string;
+        runtime: "transformers-wasm" | "mock";
+        defaultModel: string;
+        pull(): Promise<EdgeAIPullResponse>;
+        generate(payload: EdgeAIGenerateRequest): Promise<EdgeAIGenerateResponse>;
+        health(): Promise<EdgeAIHealthResponse>;
+    };
+}> & import("nuxt/app").ObjectPlugin<{
+    edgeAI: {
+        routeBase: string;
+        runtime: "transformers-wasm" | "mock";
+        defaultModel: string;
+        pull(): Promise<EdgeAIPullResponse>;
+        generate(payload: EdgeAIGenerateRequest): Promise<EdgeAIGenerateResponse>;
+        health(): Promise<EdgeAIHealthResponse>;
+    };
+}>;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,31 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#app";
+export default defineNuxtPlugin(() => {
+  const config = useRuntimeConfig();
+  const publicConfig = config.public.edgeAI;
+  const routeBase = publicConfig.routeBase;
+  const runtime = publicConfig.runtime;
+  const defaultModel = publicConfig.defaultModel;
+  return {
+    provide: {
+      edgeAI: {
+        routeBase,
+        runtime,
+        defaultModel,
+        pull() {
+          return $fetch(`${routeBase}/pull`, {
+            method: "POST"
+          });
+        },
+        generate(payload) {
+          return $fetch(`${routeBase}/generate`, {
+            method: "POST",
+            body: payload
+          });
+        },
+        health() {
+          return $fetch(`${routeBase}/health`);
+        }
+      }
+    }
+  };
+});

package/dist/runtime/server/api/generate.post.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../types.js").EdgeAIGenerateResponse>>;
+export default _default;

package/dist/runtime/server/api/generate.post.js

@@ -0,0 +1,19 @@
+import { createError, defineEventHandler, readBody } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { generateEdgeAIText } from "../utils/edge-ai-engine.js";
+export default defineEventHandler(async (event) => {
+  const body = await readBody(event);
+  const prompt = body?.prompt?.trim();
+  if (!prompt) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Prompt is required."
+    });
+  }
+  const config = useRuntimeConfig().edgeAI;
+  return generateEdgeAIText(config, {
+    prompt,
+    model: body.model,
+    generation: body.generation
+  });
+});

package/dist/runtime/server/api/health.get.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../types.js").EdgeAIHealthResponse>>;
+export default _default;

package/dist/runtime/server/api/health.get.js

@@ -0,0 +1,6 @@
+import { defineEventHandler } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { getEdgeAIHealth } from "../utils/edge-ai-engine.js";
+export default defineEventHandler(async () => {
+  return getEdgeAIHealth(useRuntimeConfig().edgeAI);
+});

package/dist/runtime/server/api/pull.post.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<import("../../types.js").EdgeAIPullResponse>>;
+export default _default;

package/dist/runtime/server/api/pull.post.js

@@ -0,0 +1,6 @@
+import { defineEventHandler } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { pullEdgeAIModel } from "../utils/edge-ai-engine.js";
+export default defineEventHandler(async () => {
+  return pullEdgeAIModel(useRuntimeConfig().edgeAI);
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/server/utils/edge-ai-engine.d.ts

@@ -0,0 +1,4 @@
+import type { EdgeAIGenerateRequest, EdgeAIGenerateResponse, EdgeAIHealthResponse, EdgeAIServerRuntimeConfig, EdgeAIPullResponse } from '../../types.js';
+export declare function getEdgeAIHealth(config: EdgeAIServerRuntimeConfig): Promise<EdgeAIHealthResponse>;
+export declare function pullEdgeAIModel(config: EdgeAIServerRuntimeConfig): Promise<EdgeAIPullResponse>;
+export declare function generateEdgeAIText(config: EdgeAIServerRuntimeConfig, input: EdgeAIGenerateRequest): Promise<EdgeAIGenerateResponse>;