@easy-cms/next 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,52 @@
+# @easy-cms/next
+
+Next.js (App Router, 15+) adapter for [Easy CMS](https://github.com/maritonx/easy-crm).
+
+```bash
+pnpm add @easy-cms/next @easy-cms/core @easy-cms/db-postgres
+```
+
+**1. Wrap `next.config.ts`** so the server build keeps the admin UI and database drivers:
+
+```ts
+import { withEasyCMS } from '@easy-cms/next/config'
+export default withEasyCMS({ /* your Next config */ })
+```
+
+**2. Add two route handlers** (paths match `routes.api` and `admin.path` in your Easy CMS config):
+
+```ts
+// app/api/cms/[[...path]]/route.ts
+import { createRouteHandlers } from '@easy-cms/next'
+import config from '@/easy-cms.config'
+export const { GET, HEAD, POST, PATCH, PUT, DELETE, OPTIONS } = createRouteHandlers(config)
+```
+
+```ts
+// app/admin/[[...path]]/route.ts
+import { createAdminRouteHandlers } from '@easy-cms/next'
+import config from '@/easy-cms.config'
+export const { GET, HEAD } = createAdminRouteHandlers(config)
+```
+
+**3. Read content in Server Components** with the typed Local API:
+
+```tsx
+import { getEasyCMS, getEasyCMSUser } from '@easy-cms/next'
+import config from '@/easy-cms.config'
+
+export const dynamic = 'force-dynamic'
+
+export default async function Page() {
+  const cms = await getEasyCMS(config)
+  const { docs } = await cms.find('posts', { limit: 10 })
+  const user = await getEasyCMSUser(config) // logged-in Easy CMS user or null
+  // …
+}
+```
+
+Pages that read from the CMS should be dynamic (or use `revalidate`), otherwise `next build`
+tries to query the database while prerendering.
+
+`createRouteHandlers(config, { trustProxy: true })` uses `X-Forwarded-For` for login rate limiting;
+enable it behind a proxy you trust, such as Vercel.

package/dist/config.d.ts

@@ -0,0 +1,31 @@
+/** The subset of Next's config this helper reads and sets. */
+interface NextConfigLike {
+    serverExternalPackages?: string[];
+    outputFileTracingIncludes?: Record<string, string[]>;
+    [key: string]: unknown;
+}
+type NextConfigInput = NextConfigLike | ((phase: string, ctx: {
+    defaultConfig: NextConfigLike;
+}) => NextConfigLike | Promise<NextConfigLike>);
+interface WithEasyCMSOptions {
+    /** Path to the Easy CMS config, relative to the project root. Default: `easy-cms.config.ts` (or .mts/.js/.mjs). */
+    readonly configPath?: string;
+}
+/**
+ * Packages Next must load from node_modules instead of bundling: they read files next to
+ * themselves (the admin app, PGlite's WebAssembly) or load native binaries.
+ */
+declare const SERVER_EXTERNAL_PACKAGES: string[];
+/**
+ * Wraps `next.config.ts` so the server build includes what Easy CMS needs at runtime:
+ *
+ * ```ts
+ * import { withEasyCMS } from '@easy-cms/next/config'
+ * export default withEasyCMS({ ... })
+ * ```
+ */
+declare function withEasyCMS(nextConfig?: NextConfigInput, options?: WithEasyCMSOptions): (phase: string, ctx: {
+    defaultConfig: NextConfigLike;
+}) => Promise<NextConfigLike>;
+
+export { SERVER_EXTERNAL_PACKAGES, type WithEasyCMSOptions, withEasyCMS };

package/dist/config.js

@@ -0,0 +1,62 @@
+// src/config.ts
+import { existsSync } from "fs";
+import { createRequire } from "module";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+import { CONFIG_FILE_NAMES, importConfig } from "@easy-cms/core";
+var SERVER_EXTERNAL_PACKAGES = [
+  "@easy-cms/core",
+  "@easy-cms/admin",
+  "@easy-cms/drizzle",
+  "@easy-cms/db-sqlite",
+  "@easy-cms/db-postgres",
+  "@libsql/client",
+  "libsql",
+  "@electric-sql/pglite",
+  "drizzle-kit",
+  "drizzle-orm",
+  "postgres",
+  "sharp",
+  "jiti"
+];
+function withEasyCMS(nextConfig = {}, options = {}) {
+  return async (phase, ctx) => {
+    const base = typeof nextConfig === "function" ? await nextConfig(phase, ctx) : nextConfig;
+    const root = process.cwd();
+    const include = [...await tracedFiles(root, options.configPath)];
+    return {
+      ...base,
+      serverExternalPackages: [
+        .../* @__PURE__ */ new Set([...base.serverExternalPackages ?? [], ...SERVER_EXTERNAL_PACKAGES])
+      ],
+      outputFileTracingIncludes: {
+        ...base.outputFileTracingIncludes,
+        "/**": [...base.outputFileTracingIncludes?.["/**"] ?? [], ...include]
+      }
+    };
+  };
+}
+async function tracedFiles(root, configPath) {
+  const toGlob = (path) => relative(root, path).replace(/\\/g, "/");
+  const files = ["easy-cms/migrations/**"];
+  try {
+    const adminPackage = createRequire(join(root, "package.json")).resolve(
+      "@easy-cms/admin/package.json"
+    );
+    files.push(`${toGlob(join(dirname(adminPackage), "dist/app"))}/**`);
+  } catch {
+  }
+  const file = configPath ? isAbsolute(configPath) ? configPath : resolve(root, configPath) : CONFIG_FILE_NAMES.map((name) => join(root, name)).find((path) => existsSync(path));
+  if (file && existsSync(file)) {
+    try {
+      const config = await importConfig(file);
+      for (const path of config?.db?.bundle?.traceInclude ?? []) files.push(toGlob(path));
+    } catch (error) {
+      console.warn(`[easy-cms] Could not read ${file} at build time: ${error.message}`);
+    }
+  }
+  return files;
+}
+export {
+  SERVER_EXTERNAL_PACKAGES,
+  withEasyCMS
+};

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { Config, EasyCMS, AuthUser } from '@easy-cms/core';
+
+type Handler = (request: Request) => Promise<Response>;
+/**
+ * The Easy CMS Local API for this server, typed from your config. Use it in Server
+ * Components, Route Handlers and Server Actions. The instance survives hot reloads.
+ */
+declare function getEasyCMS<const C extends Config>(config: C): Promise<EasyCMS<C>>;
+interface RouteHandlerOptions {
+    /** Use `X-Forwarded-For` for the client IP (login rate limiting). Enable behind a proxy you trust, e.g. Vercel. */
+    readonly trustProxy?: boolean;
+}
+/**
+ * REST API route handlers. In `app/api/cms/[...path]/route.ts` (matching `routes.api`):
+ *
+ * ```ts
+ * import config from '@/easy-cms.config'
+ * import { createRouteHandlers } from '@easy-cms/next'
+ * export const { GET, HEAD, POST, PATCH, PUT, DELETE, OPTIONS } = createRouteHandlers(config)
+ * ```
+ */
+declare function createRouteHandlers(config: Config, options?: RouteHandlerOptions): {
+    GET: Handler;
+    HEAD: Handler;
+    POST: Handler;
+    PATCH: Handler;
+    PUT: Handler;
+    DELETE: Handler;
+    OPTIONS: Handler;
+};
+/**
+ * Admin UI route handlers. In `app/admin/[[...path]]/route.ts` (matching `admin.path`):
+ *
+ * ```ts
+ * import config from '@/easy-cms.config'
+ * import { createAdminRouteHandlers } from '@easy-cms/next'
+ * export const { GET, HEAD } = createAdminRouteHandlers(config)
+ * ```
+ */
+declare function createAdminRouteHandlers(config: Config, options?: {
+    appDir?: string;
+}): {
+    GET: Handler;
+    HEAD: Handler;
+};
+/** The logged-in Easy CMS user for the current request (session cookie or Bearer token), or `null`. */
+declare function getEasyCMSUser(config: Config): Promise<AuthUser | null>;
+
+export { type RouteHandlerOptions, createAdminRouteHandlers, createRouteHandlers, getEasyCMS, getEasyCMSUser };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import { createRequire } from "module";
+import { dirname, join } from "path";
+import { createAdminHandler } from "@easy-cms/admin";
+import {
+  createEasyCMS,
+  createRestHandler,
+  readCookie,
+  resolveConfig,
+  SESSION_COOKIE
+} from "@easy-cms/core";
+var KEY = /* @__PURE__ */ Symbol.for("easy-cms.next");
+var 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;
+}
+function createRouteHandlers(config, options = {}) {
+  const handlers = /* @__PURE__ */ new WeakMap();
+  const handle = async (request) => {
+    const cms = await getEasyCMS(config);
+    let handler = handlers.get(cms);
+    if (!handler) {
+      handler = createRestHandler(cms, {
+        getClientIp: (r) => options.trustProxy ? r.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || void 0 : void 0
+      });
+      handlers.set(cms, handler);
+    }
+    return handler(request);
+  };
+  return {
+    GET: handle,
+    HEAD: handle,
+    POST: handle,
+    PATCH: handle,
+    PUT: handle,
+    DELETE: handle,
+    OPTIONS: handle
+  };
+}
+function createAdminRouteHandlers(config, options = {}) {
+  let handler;
+  const handle = async (request) => {
+    handler ??= resolveConfig(config).then(
+      (resolved) => createAdminHandler({
+        basePath: resolved.admin.path,
+        apiPath: resolved.routes.api,
+        locale: resolved.admin.locale,
+        appDir: options.appDir ?? adminAppDir(),
+        // Next.js strips trailing slashes; redirecting back would loop.
+        trailingSlashRedirect: false
+      })
+    );
+    return (await handler)(request);
+  };
+  return { GET: handle, HEAD: handle };
+}
+async function getEasyCMSUser(config) {
+  const { headers } = await import("next/headers.js");
+  const all = await headers();
+  const cms = await getEasyCMS(config);
+  const authorization = all.get("authorization");
+  if (authorization?.startsWith("Bearer ")) return cms.auth.verify(authorization.slice(7).trim());
+  const cookie = all.get("cookie");
+  const token = cookie ? readCookie(new Request("http://x", { headers: { cookie } }), SESSION_COOKIE) : void 0;
+  return cms.auth.verify(token);
+}
+function adminAppDir() {
+  const fromProject = createRequire(join(process.cwd(), "package.json"));
+  const nextPackage = fromProject.resolve("@easy-cms/next/package.json");
+  const adminPackage = createRequire(nextPackage).resolve("@easy-cms/admin/package.json");
+  return join(dirname(adminPackage), "dist/app");
+}
+export {
+  createAdminRouteHandlers,
+  createRouteHandlers,
+  getEasyCMS,
+  getEasyCMSUser
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@easy-cms/next",
+  "version": "0.1.0",
+  "description": "Next.js adapter for Easy CMS",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "dependencies": {
+    "@easy-cms/admin": "^0.1.0"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0",
+    "@easy-cms/core": "^0.1.0"
+  },
+  "devDependencies": {
+    "next": "^16.3.6",
+    "@easy-cms/db-sqlite": "^0.1.0",
+    "@easy-cms/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maritonx/easy-crm.git",
+    "directory": "packages/next"
+  },
+  "keywords": [
+    "easy-cms",
+    "nextjs",
+    "next",
+    "cms",
+    "headless-cms"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}