@flexacms/nuxt 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Mercedes
+
+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

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# @flexacms/nuxt
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Flexa](https://github.com/flexacms) for Nuxt 3 and 4. Composables are auto-imported and fetch through a **read-only server proxy**, so the API key never reaches the browser.
+
+```bash
+npm install @flexacms/nuxt
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+    modules: ['@flexacms/nuxt'],
+});
+```
+
+```env
+NUXT_FLEXA_URL=https://cms.example.com
+NUXT_FLEXA_API_KEY=flx_...
+```
+
+```vue
+<script setup lang="ts">
+const route = useRoute();
+const { data: posts } = await useFlexaEntries('posts', { status: 'published' });
+const { data: post, error } = await useFlexaEntry(
+    'posts',
+    () => route.params.slug as string,
+);
+</script>
+```
+
+Both are `useFetch` calls: they render during SSR, hydrate on the client and refetch when reactive arguments change. In server routes, `useFlexaClient()` gives the full client (writes included):
+
+```ts
+// server/api/subscribe.post.ts
+export default defineEventHandler(async (event) => {
+    const body = await readBody(event);
+
+    return useFlexaClient()
+        .entity('subscribers')
+        .create({ title: body.email, values: { email: body.email } });
+});
+```
+
+The proxy (`/api/_flexa/**` by default, `flexa.proxyPath` to change it) only allows GET requests for entities, entries and schemas, and drops parameters such as `trashed`, whatever abilities the key has.
+
+## Typed composables
+
+```ts
+// types/flexa-register.d.ts
+import type { FlexaSchema } from './flexa'; // npx @flexacms/cli generate
+
+declare module '@flexacms/nuxt' {
+    interface FlexaRegister {
+        schema: FlexaSchema;
+    }
+}
+```

package/dist/chunk-CPEHOITS.js

@@ -0,0 +1,25 @@
+// src/runtime/server/client.ts
+import { createClient } from "@flexacms/client";
+import { useRuntimeConfig } from "#imports";
+var client;
+function useFlexaClient() {
+  if (client) {
+    return client;
+  }
+  const config = useRuntimeConfig().flexa;
+  if (!config.url || !config.apiKey) {
+    throw new Error(
+      "Flexa: set NUXT_FLEXA_URL and NUXT_FLEXA_API_KEY (or flexa.url / flexa.apiKey in nuxt.config)."
+    );
+  }
+  client = createClient({
+    url: config.url,
+    apiKey: config.apiKey,
+    apiPath: config.apiPath
+  });
+  return client;
+}
+
+export {
+  useFlexaClient
+};

package/dist/chunk-DKK222XN.js

@@ -0,0 +1,33 @@
+// src/runtime/proxy-path.ts
+var ALLOWED_QUERY = [
+  "status",
+  "search",
+  "category",
+  "page",
+  "per_page"
+];
+function proxyRequestPath(path, query) {
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length === 0 || segments.length > 2 || segments.some((segment) => segment === ".." || segment === ".")) {
+    return null;
+  }
+  if (segments[0] === "entities" && segments.length > 1) {
+    return null;
+  }
+  const search = new URLSearchParams();
+  for (const key of ALLOWED_QUERY) {
+    const value = query[key];
+    if (typeof value === "string" || typeof value === "number") {
+      search.set(key, String(value));
+    }
+  }
+  if (query.include === "relations" && segments[0] !== "entities") {
+    search.set("include", "relations");
+  }
+  const queryString = search.toString();
+  return `/${segments.map(encodeURIComponent).join("/")}${queryString ? `?${queryString}` : ""}`;
+}
+
+export {
+  proxyRequestPath
+};

package/dist/module.d.ts

@@ -0,0 +1,31 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export * from '@flexacms/client';
+
+/**
+ * Register your generated schema to type the composables:
+ *
+ *     // types/flexa.d.ts
+ *     import type { FlexaSchema } from './flexa';
+ *
+ *     declare module '@flexacms/nuxt' {
+ *         interface FlexaRegister {
+ *             schema: FlexaSchema;
+ *         }
+ *     }
+ */
+interface FlexaRegister {
+}
+
+interface ModuleOptions {
+    /** Flexa URL. Prefer the NUXT_FLEXA_URL environment variable. */
+    url?: string;
+    /** API key, kept server-side. Prefer the NUXT_FLEXA_API_KEY environment variable. */
+    apiKey?: string;
+    /** Path of the content API. Defaults to `/api/v1`. */
+    apiPath?: string;
+    /** Route of the read-only proxy the composables call. Defaults to `/api/_flexa`. */
+    proxyPath?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { type FlexaRegister, type ModuleOptions, _default as default };

package/dist/module.js

@@ -0,0 +1,63 @@
+// src/module.ts
+import {
+  addImports,
+  addServerHandler,
+  addServerImports,
+  createResolver,
+  defineNuxtModule
+} from "@nuxt/kit";
+import { defu } from "defu";
+export * from "@flexacms/client";
+var module_default = defineNuxtModule({
+  meta: {
+    name: "@flexacms/nuxt",
+    configKey: "flexa",
+    compatibility: { nuxt: ">=3.12.0" }
+  },
+  defaults: {
+    apiPath: "/api/v1",
+    proxyPath: "/api/_flexa"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const proxyPath = `/${(options.proxyPath ?? "/api/_flexa").replace(/^\/+|\/+$/g, "")}`;
+    nuxt.options.runtimeConfig.flexa = defu(
+      nuxt.options.runtimeConfig.flexa,
+      {
+        url: options.url ?? "",
+        apiKey: options.apiKey ?? "",
+        apiPath: options.apiPath ?? "/api/v1"
+      }
+    );
+    nuxt.options.runtimeConfig.public.flexa = defu(
+      nuxt.options.runtimeConfig.public.flexa,
+      {
+        proxyPath
+      }
+    );
+    addServerHandler({
+      route: `${proxyPath}/**`,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/proxy")
+    });
+    addImports([
+      {
+        name: "useFlexaEntries",
+        from: resolver.resolve("./runtime/composables")
+      },
+      {
+        name: "useFlexaEntry",
+        from: resolver.resolve("./runtime/composables")
+      }
+    ]);
+    addServerImports([
+      {
+        name: "useFlexaClient",
+        from: resolver.resolve("./runtime/server/client")
+      }
+    ]);
+  }
+});
+export {
+  module_default as default
+};

package/dist/runtime/composables.js

@@ -0,0 +1,51 @@
+// src/runtime/composables.ts
+import { useFetch, useRuntimeConfig } from "#imports";
+import { computed, toValue } from "vue";
+function proxyBase() {
+  return useRuntimeConfig().public.flexa.proxyPath;
+}
+function listQuery(params) {
+  const query = {};
+  for (const [key, value] of Object.entries({
+    status: params.status,
+    search: params.search,
+    category: params.category,
+    page: params.page,
+    per_page: params.perPage,
+    include: params.includeRelations ? "relations" : void 0
+  })) {
+    if (value !== void 0 && value !== "") {
+      query[key] = value;
+    }
+  }
+  return query;
+}
+function useFlexaEntries(entity, params = {}) {
+  const base = proxyBase();
+  const query = computed(() => listQuery(toValue(params)));
+  return useFetch(
+    () => `${base}/${encodeURIComponent(toValue(entity))}`,
+    {
+      query,
+      // Library composables need an explicit key: Nuxt's automatic keys are
+      // per call site, which would be shared by every use of this function.
+      key: `flexa:${toValue(entity)}:${JSON.stringify(query.value)}`,
+      watch: [query]
+    }
+  );
+}
+function useFlexaEntry(entity, idOrSlug, params = {}) {
+  const base = proxyBase();
+  return useFetch(
+    () => `${base}/${encodeURIComponent(toValue(entity))}/${encodeURIComponent(String(toValue(idOrSlug)))}`,
+    {
+      query: params.includeRelations ? { include: "relations" } : {},
+      key: `flexa:${toValue(entity)}:${String(toValue(idOrSlug))}`,
+      transform: (response) => response.data
+    }
+  );
+}
+export {
+  useFlexaEntries,
+  useFlexaEntry
+};

package/dist/runtime/proxy-path.js

@@ -0,0 +1,6 @@
+import {
+  proxyRequestPath
+} from "../chunk-DKK222XN.js";
+export {
+  proxyRequestPath
+};

package/dist/runtime/server/client.js

@@ -0,0 +1,6 @@
+import {
+  useFlexaClient
+} from "../../chunk-CPEHOITS.js";
+export {
+  useFlexaClient
+};

package/dist/runtime/server/proxy.js

@@ -0,0 +1,33 @@
+import {
+  useFlexaClient
+} from "../../chunk-CPEHOITS.js";
+import {
+  proxyRequestPath
+} from "../../chunk-DKK222XN.js";
+
+// src/runtime/server/proxy.ts
+import { isFlexaError } from "@flexacms/client";
+import { createError, defineEventHandler, getQuery } from "h3";
+var proxy_default = defineEventHandler(async (event) => {
+  const path = proxyRequestPath(
+    String(event.context.params?._ ?? ""),
+    getQuery(event)
+  );
+  if (path === null) {
+    throw createError({ statusCode: 404, statusMessage: "Not Found" });
+  }
+  try {
+    return await useFlexaClient().request("GET", path);
+  } catch (error) {
+    if (isFlexaError(error)) {
+      throw createError({
+        statusCode: error.status || 502,
+        statusMessage: error.message
+      });
+    }
+    throw error;
+  }
+});
+export {
+  proxy_default as default
+};

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@flexacms/nuxt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@flexacms/nuxt",
+    "version": "0.2.0",
+    "description": "Nuxt module for the Flexa headless CMS: auto-imported composables and a read-only server proxy that keeps your API key private.",
+    "keywords": [
+        "cms",
+        "flexa",
+        "headless",
+        "nuxt",
+        "nuxt-module",
+        "vue"
+    ],
+    "homepage": "https://github.com/flexacms/sdk/tree/main/packages/nuxt#readme",
+    "bugs": {
+        "url": "https://github.com/flexacms/sdk/issues"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/flexacms/sdk.git",
+        "directory": "packages/nuxt"
+    },
+    "files": [
+        "dist",
+        "README.md",
+        "LICENSE"
+    ],
+    "type": "module",
+    "main": "./dist/module.js",
+    "types": "./dist/module.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/module.d.ts",
+            "default": "./dist/module.js"
+        }
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "tsup",
+        "typecheck": "tsc -p tsconfig.json"
+    },
+    "dependencies": {
+        "@flexacms/client": "^0.2.0",
+        "@nuxt/kit": "^3.12.0 || ^4.0.0",
+        "defu": "^6.1.4"
+    },
+    "devDependencies": {
+        "@nuxt/kit": "^4.6.1",
+        "@nuxt/schema": "^4.6.1",
+        "h3": "^1.15.11",
+        "vue": "^3.5.0"
+    }
+}