@easy-cms/nuxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanawoot K.
+
+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,43 @@
+# @easy-cms/nuxt
+
+Nuxt 4 module for [Easy CMS](https://github.com/maritonx/easy-crm).
+
+```bash
+pnpm add @easy-cms/nuxt @easy-cms/core @easy-cms/db-sqlite
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@easy-cms/nuxt'],
+  easyCms: {
+    // configPath: 'easy-cms.config.ts',
+    // trustProxy: false, // use X-Forwarded-For for login rate limiting
+  },
+})
+```
+
+With `easy-cms.config.ts` in the project root you get:
+
+- **REST API** at `/api/cms` (collections, globals, uploads, login/logout/me); change it with `routes.api` in the Easy CMS config.
+- **Admin UI** at `/admin` (`admin.path` in the config).
+- **Local API** in server routes, typed from your config:
+
+  ```ts
+  // server/api/posts.get.ts
+  export default defineEventHandler(async (event) => {
+    const cms = await useEasyCMS()
+    const user = await useEasyCMSUser(event) // logged-in Easy CMS user or null
+    return cms.find('posts', { where: { status: { equals: 'published' } } })
+  })
+  ```
+
+## Development and production
+
+- `nuxi dev` pushes schema changes to the database automatically.
+- In production the schema must match the latest migration. Create migrations with
+  `npx easy-cms migrate:create <name>`, deploy the `easy-cms/migrations` folder, run
+  `npx easy-cms migrate`, then start the server **from the project root** (relative database
+  paths and the migrations folder resolve from the working directory).
+- The module tells Nitro to ship files the database adapter loads dynamically (libsql's native
+  binary), so `.output` runs on its own. Build on the same OS/architecture you deploy to.

package/dist/module.d.ts

@@ -0,0 +1,11 @@
+import { NuxtModule } from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Path to the Easy CMS config, relative to the project root. Default: `easy-cms.config.ts` (or .mts/.js/.mjs). */
+    configPath?: string;
+    /** Use `X-Forwarded-For` for the client IP (login rate limiting). Only enable behind a proxy you control. */
+    trustProxy?: boolean;
+}
+declare const module$1: NuxtModule<ModuleOptions>;
+
+export { type ModuleOptions, module$1 as default };

package/dist/module.js

@@ -0,0 +1,136 @@
+// src/module.ts
+import { existsSync, readFileSync } from "fs";
+import { createRequire } from "module";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { renderShell, SECURITY_HEADERS, SHELL_FILE } from "@easy-cms/admin";
+import {
+  CONFIG_FILE_NAMES,
+  DEFAULT_ADMIN_PATH,
+  DEFAULT_API_PATH,
+  importConfig
+} from "@easy-cms/core";
+import {
+  addServerHandler,
+  addServerImports,
+  addServerPlugin,
+  addTypeTemplate,
+  createResolver,
+  defineNuxtModule,
+  useLogger
+} from "@nuxt/kit";
+var SERVER = "#easy-cms-local-api";
+var HANDLER = "#easy-cms-rest-handler";
+var ADMIN_SHELL = "#easy-cms-admin-shell";
+var module = defineNuxtModule({
+  meta: {
+    name: "@easy-cms/nuxt",
+    configKey: "easyCms",
+    compatibility: { nuxt: ">=4.0.0" }
+  },
+  defaults: {
+    trustProxy: false
+  },
+  async setup(options, nuxt) {
+    const logger = useLogger("easy-cms");
+    const { resolve: resolveRuntime } = createResolver(import.meta.url);
+    const rootDir = nuxt.options.rootDir;
+    const configPath = options.configPath ? isAbsolute(options.configPath) ? options.configPath : resolve(rootDir, options.configPath) : CONFIG_FILE_NAMES.map((name) => join(rootDir, name)).find((path) => existsSync(path));
+    if (!configPath || !existsSync(configPath)) {
+      logger.warn(
+        `No Easy CMS config found in ${rootDir}. Create easy-cms.config.ts (or run \`npx create-easy-cms\`). The module is disabled.`
+      );
+      return;
+    }
+    let rawConfig;
+    try {
+      rawConfig = await importConfig(configPath);
+    } catch (error) {
+      logger.warn(`Could not read ${configPath} at build time: ${error.message}`);
+    }
+    const apiPath = `/${(rawConfig?.routes?.api ?? DEFAULT_API_PATH).replace(/^\/+|\/+$/g, "")}`;
+    const adminPath = `/${(rawConfig?.admin?.path ?? DEFAULT_ADMIN_PATH).replace(/^\/+|\/+$/g, "")}`;
+    const slash = (path) => path.replace(/\\/g, "/");
+    const runtime = (file) => JSON.stringify(slash(resolveRuntime(`./runtime/${file}`)));
+    const config = JSON.stringify(slash(configPath));
+    const nitro = nuxt.options.nitro;
+    nitro.virtual ??= {};
+    Object.assign(nitro.virtual, {
+      [SERVER]: `import config from ${config}
+import { getEasyCMS, getEasyCMSUser } from ${runtime("cms.js")}
+export function useEasyCMS() { return getEasyCMS(config) }
+export function useEasyCMSUser(event) { return getEasyCMSUser(config, event) }
+`,
+      [HANDLER]: `import config from ${config}
+import { createHandler } from ${runtime("handler.js")}
+export default createHandler(config, ${JSON.stringify({ basePath: apiPath, trustProxy: options.trustProxy ?? false })})
+`
+    });
+    addTypeTemplate(
+      {
+        filename: "types/easy-cms.d.ts",
+        getContents: ({ nuxt: n }) => {
+          const from = relative(join(n.options.buildDir, "types"), configPath).replace(/\\/g, "/").replace(/\.(m?ts|m?js)$/, "");
+          return `// Generated by @easy-cms/nuxt
+declare module '${SERVER}' {
+  import type { AuthUser, EasyCMS } from '@easy-cms/core'
+  import type { H3Event } from 'h3'
+  type Config = typeof import('${from.startsWith(".") ? from : `./${from}`}').default
+
+  /** The Easy CMS Local API for this server. */
+  export function useEasyCMS(): Promise<EasyCMS<Config>>
+  /** The logged-in Easy CMS user for this request (session cookie or Bearer token), or null. */
+  export function useEasyCMSUser(event: H3Event): Promise<AuthUser | null>
+}
+`;
+        }
+      },
+      { nitro: true, nuxt: false }
+    );
+    addServerImports([
+      { name: "useEasyCMS", from: SERVER },
+      { name: "useEasyCMSUser", from: SERVER }
+    ]);
+    addServerHandler({ route: apiPath, handler: HANDLER });
+    addServerHandler({ route: `${apiPath}/**`, handler: HANDLER });
+    addServerPlugin(resolveRuntime("./runtime/plugin.js"));
+    const runtimeDir = resolveRuntime("./runtime");
+    nitro.externals = {
+      ...nitro.externals,
+      inline: [...nitro.externals?.inline ?? [], runtimeDir]
+    };
+    const adminPackage = createRequire(import.meta.url).resolve("@easy-cms/admin/package.json");
+    const adminAppDir = join(dirname(adminPackage), "dist/app");
+    const shell = renderShell(readFileSync(join(adminAppDir, SHELL_FILE), "utf8"), {
+      basePath: adminPath,
+      apiPath,
+      locale: rawConfig?.admin?.locale ?? "en"
+    });
+    nitro.virtual[ADMIN_SHELL] = `export const basePath = ${JSON.stringify(adminPath)}
+export const html = ${JSON.stringify(shell)}
+export const headers = ${JSON.stringify(SECURITY_HEADERS)}
+`;
+    nitro.publicAssets = [
+      ...nitro.publicAssets ?? [],
+      // fallthrough: app routes (not files) continue to the shell handler below.
+      { dir: adminAppDir, baseURL: adminPath, maxAge: 60 * 60 * 24 * 365, fallthrough: true }
+    ];
+    const adminHandler = resolveRuntime("./runtime/admin.js");
+    addServerHandler({ route: adminPath, handler: adminHandler });
+    addServerHandler({ route: `${adminPath}/**`, handler: adminHandler });
+    const traceInclude = rawConfig?.db?.bundle?.traceInclude ?? [];
+    if (traceInclude.length > 0) {
+      const externals = nitro.externals ?? {};
+      nitro.externals = {
+        ...externals,
+        traceInclude: [...externals.traceInclude ?? [], ...traceInclude]
+      };
+    }
+    nuxt.options.ignore.push("**/*.db", "**/*.db-*", "easy-cms/migrations/**");
+    nuxt.options.watch.push(configPath);
+    logger.info(`Easy CMS admin at ${adminPath}, API at ${apiPath}`);
+  }
+});
+var module_default = module;
+export {
+  module_default as default
+};

package/dist/runtime/admin.d.ts

@@ -0,0 +1,10 @@
+import * as h3 from 'h3';
+
+/**
+ * Serves the admin SPA's HTML for every route under the admin path.
+ * Assets are served by Nitro as public assets; a request that reaches this
+ * handler for /assets/* means the file does not exist.
+ */
+declare const _default: h3.EventHandler<h3.EventHandlerRequest, string>;
+
+export { _default as default };

package/dist/runtime/admin.js

@@ -0,0 +1,28 @@
+import { defineEventHandler, getRequestURL, setResponseHeaders, setResponseStatus } from "h3";
+import { basePath, headers, html } from "#easy-cms-admin-shell";
+var admin_default = defineEventHandler((event) => {
+  const url = getRequestURL(event);
+  setResponseHeaders(event, headers);
+  if (event.method !== "GET" && event.method !== "HEAD") {
+    setResponseStatus(event, 405);
+    setResponseHeaders(event, { allow: "GET, HEAD" });
+    return "Method not allowed";
+  }
+  if (url.pathname === basePath) {
+    setResponseStatus(event, 308);
+    setResponseHeaders(event, { location: `${basePath}/${url.search}` });
+    return "";
+  }
+  if (url.pathname.startsWith(`${basePath}/assets/`)) {
+    setResponseStatus(event, 404);
+    return "Not found";
+  }
+  setResponseHeaders(event, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  return html;
+});
+export {
+  admin_default as default
+};

package/dist/runtime/cms.d.ts

@@ -0,0 +1,12 @@
+import { Config, EasyCMS, AuthUser } from '@easy-cms/core';
+import { H3Event } from 'h3';
+
+/**
+ * Returns the Easy CMS instance for this server, creating it on first use.
+ * When the config module is reloaded (dev HMR) the old instance is closed.
+ */
+declare function getEasyCMS(config: Config): Promise<EasyCMS>;
+/** The logged-in Easy CMS user for a request (session cookie or Bearer token), or `null`. */
+declare function getEasyCMSUser(config: Config, event: H3Event): Promise<AuthUser | null>;
+
+export { getEasyCMS, getEasyCMSUser };

package/dist/runtime/cms.js

@@ -0,0 +1,32 @@
+import {
+  createEasyCMS,
+  readCookie,
+  SESSION_COOKIE
+} from "@easy-cms/core";
+import { getRequestHeader } from "h3";
+const KEY = /* @__PURE__ */ Symbol.for("easy-cms.nuxt");
+const store = globalThis;
+function getEasyCMS(config) {
+  const cached = store[KEY];
+  if (cached?.config === config) return cached.promise;
+  if (cached) void cached.promise.then((cms) => cms.destroy()).catch(() => {
+  });
+  const promise = createEasyCMS(config);
+  store[KEY] = { config, promise };
+  promise.catch(() => {
+    if (store[KEY]?.promise === promise) delete store[KEY];
+  });
+  return promise;
+}
+async function getEasyCMSUser(config, event) {
+  const cms = await getEasyCMS(config);
+  const authorization = getRequestHeader(event, "authorization");
+  if (authorization?.startsWith("Bearer ")) return cms.auth.verify(authorization.slice(7).trim());
+  const cookie = getRequestHeader(event, "cookie");
+  const token = cookie ? readCookie(new Request("http://x", { headers: { cookie } }), SESSION_COOKIE) : void 0;
+  return cms.auth.verify(token);
+}
+export {
+  getEasyCMS,
+  getEasyCMSUser
+};

package/dist/runtime/handler.d.ts

@@ -0,0 +1,12 @@
+import * as h3 from 'h3';
+import { Config } from '@easy-cms/core';
+
+interface HandlerOptions {
+    readonly basePath: string;
+    /** Trust `X-Forwarded-For` for the client IP (only behind a proxy you control). */
+    readonly trustProxy: boolean;
+}
+/** Mounts the Easy CMS REST API as a Nitro event handler. */
+declare function createHandler(config: Config, options: HandlerOptions): h3.EventHandler<h3.EventHandlerRequest, Promise<void>>;
+
+export { type HandlerOptions, createHandler };

package/dist/runtime/handler.js

@@ -0,0 +1,24 @@
+import { createRestHandler } from "@easy-cms/core";
+import { defineEventHandler, getRequestIP, sendWebResponse, toWebRequest } from "h3";
+import { getEasyCMS } from "./cms.js";
+function createHandler(config, options) {
+  const handlers = /* @__PURE__ */ new WeakMap();
+  const clientIps = /* @__PURE__ */ new WeakMap();
+  return defineEventHandler(async (event) => {
+    const cms = await getEasyCMS(config);
+    let handler = handlers.get(cms);
+    if (!handler) {
+      handler = createRestHandler(cms, {
+        basePath: options.basePath,
+        getClientIp: (r) => clientIps.get(r)
+      });
+      handlers.set(cms, handler);
+    }
+    const request = toWebRequest(event);
+    clientIps.set(request, getRequestIP(event, { xForwardedFor: options.trustProxy }));
+    return sendWebResponse(event, await handler(request));
+  });
+}
+export {
+  createHandler
+};

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,4 @@
+/** Nitro plugin: connect (and push or verify the schema) at startup so problems show up immediately. */
+declare function easyCmsStartup(): void;
+
+export { easyCmsStartup as default };

package/dist/runtime/plugin.js

@@ -0,0 +1,9 @@
+import { useEasyCMS } from "#easy-cms-local-api";
+function easyCmsStartup() {
+  useEasyCMS().catch((error) => {
+    console.error(`[easy-cms] ${error instanceof Error ? error.message : String(error)}`);
+  });
+}
+export {
+  easyCmsStartup as default
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@easy-cms/nuxt",
+  "version": "0.1.0",
+  "description": "Nuxt module for Easy CMS",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/module.d.ts",
+      "default": "./dist/module.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.5.2",
+    "h3": "^1.15.11",
+    "@easy-cms/admin": "^0.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0",
+    "@easy-cms/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "@nuxt/schema": "^4.5.2",
+    "@nuxt/test-utils": "^4.3.2",
+    "nuxt": "^4.5.2",
+    "@easy-cms/core": "^0.1.0",
+    "@easy-cms/db-sqlite": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maritonx/easy-crm.git",
+    "directory": "packages/nuxt"
+  },
+  "keywords": [
+    "easy-cms",
+    "nuxt",
+    "nuxt-module",
+    "cms",
+    "headless-cms"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}