@xleddyl/nuxt-cms 0.1.41 → 0.1.43

package/README.md

@@ -57,8 +57,9 @@ Then declare your content types in a `cms.config.ts` at the project root with `d
 ### Disabling the CMS
 
 Keep the module in `modules[]` at all times and turn it off with the `enabled` option or the
-`NUXT_CMS_ENABLED` env var. When disabled the module registers no-op `useCms` / `$cmsQuery` stubs and
-nothing else, so components can call them unconditionally and simply render their empty states:
+`NUXT_CMS_ENABLED` env var. When disabled the module registers no-op query composables and keeps the
+generated types, and nothing else, so components can call them unconditionally and simply render
+their empty states:
 
 ```ts
 export default defineNuxtConfig({
@@ -96,8 +97,8 @@ Full documentation lives in [`docs/`](docs/README.md):
 - [Getting started](docs/getting-started.md) — install, configure, first content type, run.
 - [Configuration](docs/configuration.md) — every `cms.*` option and the `NUXT_CMS_*` env vars.
 - [Database](docs/database.md) — SQLite, Postgres, libSQL/Turso and D1 drivers, migrations, studio.
-- [Schema](docs/schema.md) — `defineCmsConfig`, entries, field types, relations, blocks, i18n.
-- [Querying content](docs/querying.md) — GraphQL API, `useCms` / `$cmsQuery`, filters, sorting, pagination.
+- [Schema](docs/schema.md) — `defineCmsConfig`, entries, pages, field types, relations, blocks, i18n.
+- [Querying content](docs/querying.md) — GraphQL API, `useCmsSingle` / `useCmsCollection` / `useCmsPage` / `useCms` / `$cmsQuery`, filters, sorting, pagination.
 - [Admin panel & security](docs/admin.md) — pages, authentication, sessions, admin REST API.
 - [Media](docs/media.md) — S3-compatible storage or local mode backed by your `public/` folder, upload flow, allowed file types.
 - [Deployment](docs/deployment.md) — host/driver matrix, migrations on serverless, horizontal scaling, Cloudflare Workers.

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@xleddyl/nuxt-cms",
   "configKey": "cms",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "unknown"

package/dist/module.mjs

@@ -1,16 +1,16 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { join, isAbsolute, resolve, relative, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { defineNuxtModule, createResolver, useLogger, addImports, resolvePath, addTemplate, addServerPlugin, addTypeTemplate, addVitePlugin, addComponentsDir, addRouteMiddleware, extendPages, addServerHandler } from '@nuxt/kit';
+import { defineNuxtModule, createResolver, useLogger, addImports, addTemplate, addServerPlugin, addTypeTemplate, addVitePlugin, addComponentsDir, addRouteMiddleware, extendPages, addServerHandler, resolvePath } from '@nuxt/kit';
 import tailwindcss from '@tailwindcss/vite';
 import svgLoader from 'vite-svg-loader';
 import { introspectionFromSchema, buildSchema } from 'graphql';
 import { minifyIntrospection, outputIntrospectionFile } from 'gql.tada/internal';
 import { createJiti } from 'jiti';
 import { typeName, blockTypeName, blocksFieldTypeName, renderGraphqlSdl } from '../dist/runtime/shared/graphql-sdl.js';
-import { isMultiSelect, fieldConditions, isTranslatableField, isTranslatableMediaField, isRequiredField, isPrivateField, mediaTypeFilter, DEFAULT_MEDIA_MAX_FILE_SIZE } from '../dist/runtime/shared/index.js';
+import { isTranslatableField, isTranslatableMediaField, isMultiSelect, pageAllFields, PAGE_PATH_FIELD, pageRoutes, fieldConditions, isRequiredField, pageFields, isPrivateField, entryFieldsFor, pageLabelFromPath, pageKeyFromPath, mediaTypeFilter, DEFAULT_MEDIA_MAX_FILE_SIZE } from '../dist/runtime/shared/index.js';
 import { scanMediaDirectory, readMediaFileMeta } from '../dist/runtime/server/utils/media-sync.js';
 import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
@@ -105,6 +105,7 @@ function validateConfig(config, i18n) {
       )}]`
     );
   }
+  let pageEntry;
   const entryIds = /* @__PURE__ */ new Map();
   const typeNames = /* @__PURE__ */ new Map();
   for (const [name, entry] of Object.entries(config)) {
@@ -130,8 +131,51 @@ function validateConfig(config, i18n) {
     } else {
       entryIds.set(entry.id, name);
     }
-    if (entry.kind !== "collection" && entry.kind !== "single")
-      errors.push(`${at}: kind must be 'collection' or 'single'`);
+    if (entry.kind !== "collection" && entry.kind !== "single" && entry.kind !== "page")
+      errors.push(`${at}: kind must be 'collection', 'single' or 'page'`);
+    if (entry.kind === "page") {
+      if (pageEntry) {
+        errors.push(
+          `${at}: only one page entry is allowed (already declared as '${pageEntry}')`
+        );
+      } else {
+        pageEntry = name;
+      }
+      if (entry.titleField) errors.push(`${at}: pages have no titleField`);
+      if (Object.hasOwn(entry.fields ?? {}, PAGE_PATH_FIELD))
+        errors.push(`${at}: '${PAGE_PATH_FIELD}' is a reserved field name on pages`);
+      const known = new Set(pageRoutes(entry).map((route) => route.path));
+      const keys = /* @__PURE__ */ new Map();
+      for (const route of pageRoutes(entry)) {
+        const clash = keys.get(route.key);
+        if (clash) errors.push(`${at}: paths '${clash}' and '${route.path}' give the same key`);
+        else keys.set(route.key, route.path);
+      }
+      for (const [path, override] of Object.entries(entry.overrides ?? {})) {
+        const oat = `${at}, override '${path}'`;
+        if (known.size && !known.has(path)) errors.push(`${oat}: '${path}' is not a page path`);
+        for (const key of Object.keys(override)) {
+          if (Object.hasOwn(entry.fields ?? {}, key))
+            errors.push(`${oat}: field '${key}' is already declared for every page`);
+          if (key === PAGE_PATH_FIELD)
+            errors.push(`${oat}: '${PAGE_PATH_FIELD}' is a reserved field name on pages`);
+        }
+      }
+      const declared = /* @__PURE__ */ new Map();
+      for (const [path, override] of Object.entries(entry.overrides ?? {})) {
+        for (const [key, field] of Object.entries(override)) {
+          const seen = declared.get(key);
+          if (seen && seen !== field.type) {
+            errors.push(
+              `${at}: field '${key}' is declared as '${seen}' and '${field.type}' by different pages`
+            );
+          }
+          declared.set(key, field.type);
+        }
+      }
+    } else if (entry.overrides || entry.routes || entry.include || entry.exclude) {
+      errors.push(`${at}: routes, include, exclude and overrides need kind 'page'`);
+    }
     if (entry.drafts && entry.kind !== "collection")
       errors.push(`${at}: drafts are only supported on collections`);
     if (!entry.fields || !Object.keys(entry.fields).length)
@@ -150,8 +194,9 @@ function validateConfig(config, i18n) {
         );
       }
     }
+    const allFields = entry.kind === "page" ? pageAllFields(entry) : entry.fields ?? {};
     const columnNames = /* @__PURE__ */ new Set();
-    for (const [key, field] of Object.entries(entry.fields ?? {})) {
+    for (const [key, field] of Object.entries(allFields)) {
       const fat = `${at}, field '${key}'`;
       if (!IDENTIFIER.test(key)) errors.push(`${fat}: key must be a valid identifier`);
       const column = snakeCase(key);
@@ -181,7 +226,7 @@ function validateConfig(config, i18n) {
           errors.push(`${fat}: the titleField cannot be conditional`);
         for (const condition of fieldConditions(field)) {
           const cat = `${fat}, showIf on '${condition.field}'`;
-          const target = entry.fields?.[condition.field];
+          const target = allFields[condition.field];
           if (!condition.field || !target) {
             errors.push(`${cat}: '${condition.field}' is not a declared field`);
             continue;
@@ -380,7 +425,10 @@ function tableExpr(name, entry, dialect) {
   const tableFn = pg ? "pgTable" : "sqliteTable";
   const lines = [];
   lines.push(`  id: text('id').primaryKey(),`);
-  for (const [key, field] of Object.entries(entry.fields)) {
+  if (entry.kind === "page") lines.push(`  path: text('path').notNull().unique(),`);
+  for (const [key, field] of Object.entries(
+    entry.kind === "page" ? pageAllFields(entry) : entry.fields
+  )) {
     if (isManyToMany(field)) continue;
     lines.push(columnExpr(key, field, dialect));
   }
@@ -440,7 +488,7 @@ function renderSchemaFile(config, dialect, resolveImport = (s) => s) {
   ];
   const tables = derived.map(([name, entry]) => tableExpr(name, entry, dialect));
   const joins = derived.flatMap(
-    ([name, entry]) => Object.entries(entry.fields).filter(([, field]) => isManyToMany(field)).map(([key, field]) => joinTableExpr(name, key, field, dialect))
+    ([name, entry]) => Object.entries(entry.kind === "page" ? pageAllFields(entry) : entry.fields).filter(([, field]) => isManyToMany(field)).map(([key, field]) => joinTableExpr(name, key, field, dialect))
   );
   return `${imports.join("\n")}
 
@@ -450,6 +498,139 @@ ${[mediaTableExpr(dialect), ...tables, ...joins].join(
 `;
 }
 
+const MEDIA_SELECTION = "key url type alt folder mime size width height";
+function blocksSelection(entryName, key, field) {
+  const parts = ["type"];
+  for (const [blockName, block] of Object.entries(field.blocks ?? {})) {
+    const fields = Object.entries(block.fields).map(
+      ([blockFieldKey, blockField]) => blockField.type === "media" ? `${blockFieldKey} { ${MEDIA_SELECTION} }` : blockFieldKey
+    );
+    if (!fields.length) continue;
+    parts.push(`... on ${blockTypeName(entryName, key, blockName)} { ${fields.join(" ")} }`);
+  }
+  return parts.join(" ");
+}
+function entrySelection(config, name, entry, withRelations, fields = entryFieldsFor(entry)) {
+  const parts = ["id"];
+  if (entry.kind === "page") parts.push("path");
+  for (const [key, field] of Object.entries(fields)) {
+    if (isPrivateField(field)) continue;
+    if (field.type === "relation") {
+      const target = config[field.to];
+      if (!withRelations || !target) continue;
+      parts.push(`${key} { ${entrySelection(config, field.to, target, false)} }`);
+      continue;
+    }
+    if (field.type === "media") {
+      parts.push(`${key} { ${MEDIA_SELECTION} }`);
+      continue;
+    }
+    if (field.type === "blocks") {
+      parts.push(`${key} { ${blocksSelection(name, key, field)} }`);
+      continue;
+    }
+    parts.push(key);
+  }
+  if (entry.kind === "collection") parts.push("createdAt");
+  parts.push("updatedAt");
+  return parts.join(" ");
+}
+function singleQuery(config, name, entry) {
+  const selection = entrySelection(config, name, entry, true);
+  return `query CmsSingle($locale: String) { ${name}(locale: $locale) { ${selection} } }`;
+}
+function collectionQuery(config, name, entry) {
+  const selection = entrySelection(config, name, entry, true);
+  const gqlType = typeName(name);
+  const args = [
+    "$locale: String",
+    `$filters: ${gqlType}Filters`,
+    `$sort: [${gqlType}Sort!]`,
+    "$limit: Int",
+    "$offset: Int"
+  ].join(", ");
+  return `query CmsCollection(${args}) { ${name}(locale: $locale, filters: $filters, sort: $sort, limit: $limit, offset: $offset) { ${selection} } }`;
+}
+function pageQuery(config, name, entry, path) {
+  const selection = entrySelection(config, name, entry, true, pageFields(entry, path));
+  return `query CmsPage($path: String!, $locale: String) { page: ${name}ByPath(path: $path, locale: $locale) { ${selection} } }`;
+}
+function renderQueriesFile(config) {
+  const singles = [];
+  const collections = [];
+  const pages = [];
+  for (const [name, entry] of Object.entries(config)) {
+    if (entry.kind === "page") {
+      for (const route of pageRoutes(entry)) {
+        pages.push(
+          `   ${JSON.stringify(route.path)}: ${JSON.stringify(
+            pageQuery(config, name, entry, route.path)
+          )},`
+        );
+      }
+      continue;
+    }
+    const line = `   ${JSON.stringify(name)}: ${JSON.stringify(
+      entry.kind === "single" ? singleQuery(config, name, entry) : collectionQuery(config, name, entry)
+    )},`;
+    if (entry.kind === "single") singles.push(line);
+    else collections.push(line);
+  }
+  return [
+    `export const cmsSingleQueries: Record<string, string> = {`,
+    ...singles,
+    `}`,
+    ``,
+    `export const cmsCollectionQueries: Record<string, string> = {`,
+    ...collections,
+    `}`,
+    ``,
+    `export const cmsPageQueries: Record<string, string> = {`,
+    ...pages,
+    `}`,
+    ``
+  ].join("\n");
+}
+
+const DYNAMIC = /[[\]]/;
+function vueFiles(dir, prefix = "") {
+  if (!existsSync(dir)) return [];
+  const files = [];
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const name = `${prefix}${item.name}`;
+    if (item.isDirectory()) files.push(...vueFiles(join(dir, item.name), `${name}/`));
+    else if (item.name.endsWith(".vue")) files.push(name);
+  }
+  return files;
+}
+function routePathFromFile(file) {
+  if (DYNAMIC.test(file)) return null;
+  const segments = file.replace(/\.vue$/, "").split("/").filter((segment) => !/^\(.+\)$/.test(segment));
+  if (segments.at(-1) === "index") segments.pop();
+  const path = `/${segments.join("/")}`.replace(/\/$/, "");
+  return path || "/";
+}
+function routePathsFromDir(pagesDir) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const file of vueFiles(pagesDir)) {
+    const path = routePathFromFile(file);
+    if (path) paths.add(path);
+  }
+  return [...paths];
+}
+function resolvePageRoutes(entry, discovered) {
+  const declared = Array.isArray(entry.routes) ? entry.routes : discovered;
+  const paths = /* @__PURE__ */ new Set([...declared, ...entry.include ?? []]);
+  for (const path of entry.exclude ?? []) paths.delete(path);
+  const rank = new Map((entry.order ?? []).map((path, index) => [path, index]));
+  const order = entry.order?.length ?? 0;
+  return [...paths].sort((a, b) => (rank.get(a) ?? order) - (rank.get(b) ?? order) || a.localeCompare(b)).map((path) => ({
+    path,
+    key: pageKeyFromPath(path),
+    label: entry.labels?.[path] ?? pageLabelFromPath(path)
+  }));
+}
+
 function mediaTsType(field) {
   const types = mediaTypeFilter(field.mediaType);
   return types ? `CmsMedia<${types.map((type) => `'${type}'`).join(" | ")}>` : "CmsMedia";
@@ -512,7 +693,8 @@ ${lines.join("\n")}
 }
 function entryTs(config, name, entry) {
   const lines = ["  id: string"];
-  for (const [key, field] of Object.entries(entry.fields)) {
+  if (entry.kind === "page") lines.push("  path: string");
+  for (const [key, field] of Object.entries(entryFieldsFor(entry))) {
     if (isPrivateField(field)) continue;
     lines.push(`  ${key}: ${fieldTsType(config, name, key, field)}`);
   }
@@ -522,6 +704,78 @@ function entryTs(config, name, entry) {
 ${lines.join("\n")}
 }`;
 }
+function relationKeys(entry) {
+  return Object.entries(entryFieldsFor(entry)).filter(([, field]) => field.type === "relation" && !isPrivateField(field)).map(([key]) => key);
+}
+function quotedKeys(keys) {
+  return keys.map((key) => `'${key}'`).join(" | ");
+}
+function shallowTypeTs(config, name) {
+  const target = typeName(name);
+  const entry = config[name];
+  const keys = entry ? relationKeys(entry) : [];
+  return keys.length ? `Omit<${target}, ${quotedKeys(keys)}>` : target;
+}
+function autoTypeTs(config, name, entry) {
+  const auto = `${typeName(name)}Auto`;
+  const keys = relationKeys(entry);
+  if (!keys.length) return `export type ${auto} = ${typeName(name)}`;
+  const lines = keys.map((key) => {
+    const field = entry.fields[key];
+    const shallow = shallowTypeTs(config, field.to);
+    if (field.cardinality === "many-to-many") return `  ${key}: ${shallow}[]`;
+    const nonNull = isRequiredField(field) && !config[field.to]?.drafts;
+    return `  ${key}: ${shallow}${nonNull ? "" : " | null"}`;
+  });
+  return `export type ${auto} = Omit<${typeName(name)}, ${quotedKeys(keys)}> & {
+${lines.join(
+    "\n"
+  )}
+}`;
+}
+function pageTypesTs(name, entry) {
+  const auto = `${typeName(name)}Auto`;
+  const lines = pageRoutes(entry).map((route) => {
+    const keys = ["id", "path", "updatedAt", ...Object.keys(pageFields(entry, route.path))];
+    return `  ${JSON.stringify(route.path)}: Pick<${auto}, ${quotedKeys(keys)}>`;
+  });
+  return [
+    `export interface CmsPageTypes {
+${lines.join("\n")}
+}`,
+    `export type CmsPagePath = keyof CmsPageTypes`
+  ];
+}
+function entryMapsTs(config) {
+  const singles = [];
+  const collections = [];
+  const pages = [];
+  for (const [name, entry] of Object.entries(config)) {
+    const line = `  ${JSON.stringify(name)}: ${typeName(name)}Auto`;
+    if (entry.kind === "single") singles.push(line);
+    else if (entry.kind === "page") pages.push(...pageTypesTs(name, entry));
+    else collections.push(line);
+  }
+  if (!pages.length) {
+    pages.push(
+      `export interface CmsPageTypes {
+  [path: string]: never
+}`,
+      `export type CmsPagePath = keyof CmsPageTypes`
+    );
+  }
+  return [
+    `export interface CmsSingleTypes {
+${singles.join("\n")}
+}`,
+    `export interface CmsCollectionTypes {
+${collections.join("\n")}
+}`,
+    `export type CmsSingleName = keyof CmsSingleTypes`,
+    `export type CmsCollectionName = keyof CmsCollectionTypes`,
+    ...pages
+  ];
+}
 function renderTypesFile(config) {
   const parts = [
     `export type CmsMediaType = 'image' | 'video' | 'file'`,
@@ -538,12 +792,14 @@ function renderTypesFile(config) {
 }`
   ];
   for (const [name, entry] of Object.entries(config)) {
-    for (const [key, field] of Object.entries(entry.fields)) {
+    for (const [key, field] of Object.entries(entryFieldsFor(entry))) {
       if (field.type === "blocks" && !isPrivateField(field))
         parts.push(...blockTypesTs(name, key, field));
     }
     parts.push(entryTs(config, name, entry));
   }
+  for (const [name, entry] of Object.entries(config)) parts.push(autoTypeTs(config, name, entry));
+  parts.push(...entryMapsTs(config));
   return `${parts.join("\n\n")}
 `;
 }
@@ -632,6 +888,136 @@ function resolveModuleOptions(options) {
     }
   };
 }
+const moduleRequire = createRequire(import.meta.url);
+function resolveImport(specifier) {
+  try {
+    return fileURLToPath(import.meta.resolve(specifier)).replace(/\\/g, "/");
+  } catch {
+    return moduleRequire.resolve(specifier).replace(/\\/g, "/");
+  }
+}
+async function loadCmsConfig(nuxt, resolver, configPathOption, i18n, logger) {
+  const configPath = await resolvePath(configPathOption, { cwd: nuxt.options.rootDir });
+  nuxt.options.alias["#nuxt-cms"] = resolver.resolve("./runtime/shared/index");
+  nuxt.options.watch.push(configPath);
+  let cmsConfig = {};
+  if (existsSync(configPath)) {
+    nuxt.options.alias["#cms-config"] = configPath;
+    const jiti = createJiti(import.meta.url, {
+      moduleCache: false,
+      alias: { "#nuxt-cms": resolver.resolve("./runtime/shared/index") }
+    });
+    cmsConfig = await jiti.import(configPath, { default: true });
+  } else {
+    logger.warn(
+      `[nuxt-cms] Config file not found: ${configPath}. Using an empty registry \u2014 create a ${configPathOption}.ts with defineCmsConfig().`
+    );
+    nuxt.options.alias["#cms-config"] = resolver.resolve("./runtime/shared/empty-config");
+  }
+  const pagesDir = join(
+    nuxt.options.srcDir ?? nuxt.options.rootDir,
+    nuxt.options.dir?.pages ?? "pages"
+  );
+  const discoveredRoutes = routePathsFromDir(pagesDir);
+  const routesByEntry = {};
+  for (const [name, entry] of Object.entries(cmsConfig)) {
+    if (entry.kind !== "page") continue;
+    entry.pages = resolvePageRoutes(entry, discoveredRoutes);
+    routesByEntry[name] = entry.pages;
+  }
+  if (Object.keys(routesByEntry).length) {
+    const source = (nuxt.options.alias["#cms-config"] ?? "").replace(/\\/g, "/").replace(/\.[cm]?[jt]s$/, "");
+    const wrapper = addTemplate({
+      filename: "cms/config.ts",
+      write: true,
+      getContents: () => [
+        `import config from '${source}'`,
+        ``,
+        `const pageRoutes = ${JSON.stringify(routesByEntry, null, 3)}`,
+        ``,
+        `for (const [name, routes] of Object.entries(pageRoutes)) {`,
+        `   const entry = (config as Record<string, { pages?: unknown }>)[name]`,
+        `   if (entry) entry.pages = routes`,
+        `}`,
+        ``,
+        `export default config`,
+        ``
+      ].join("\n")
+    });
+    nuxt.options.alias["#cms-config"] = wrapper.dst;
+  }
+  const configErrors = validateConfig(cmsConfig, i18n);
+  if (configErrors.length) {
+    for (const error of configErrors) logger.error(error);
+    throw new Error(
+      `[nuxt-cms] Invalid cms config (${configErrors.length} error${configErrors.length > 1 ? "s" : ""})`
+    );
+  }
+  return cmsConfig;
+}
+function addCmsTypeTemplates(nuxt, cmsConfig) {
+  addTemplate({
+    filename: "cms/schema.graphql",
+    write: true,
+    getContents: () => renderGraphqlSdl(cmsConfig)
+  });
+  const typesTemplate = addTemplate({
+    filename: "cms/types.ts",
+    write: true,
+    getContents: () => renderTypesFile(cmsConfig)
+  });
+  nuxt.options.alias["#cms-types"] = typesTemplate.dst;
+  const queriesTemplate = addTemplate({
+    filename: "cms/queries.ts",
+    write: true,
+    getContents: () => renderQueriesFile(cmsConfig)
+  });
+  nuxt.options.alias["#cms-queries"] = queriesTemplate.dst;
+  addTemplate({
+    filename: "cms/graphql-env.d.ts",
+    write: true,
+    getContents: () => {
+      const introspection = minifyIntrospection(
+        introspectionFromSchema(buildSchema(renderGraphqlSdl(cmsConfig)))
+      );
+      return outputIntrospectionFile(introspection, {
+        fileType: ".d.ts",
+        shouldPreprocess: true
+      }).split("import * as gqlTada from 'gql.tada';")[0];
+    }
+  });
+  const gqlTadaTypesPath = resolveImport("gql.tada").replace(/\.[mc]?js$/, "");
+  const graphqlTemplate = addTemplate({
+    filename: "cms/graphql.ts",
+    write: true,
+    getContents: () => [
+      `import type { initGraphQLTada, ResultOf, VariablesOf } from '${gqlTadaTypesPath}'`,
+      `import type { introspection } from './graphql-env'`,
+      ``,
+      `export type CmsGraphql = initGraphQLTada<{`,
+      `  introspection: introspection`,
+      `  scalars: {`,
+      `    JSON: unknown`,
+      `  }`,
+      `}>`,
+      ``,
+      `declare const graphql: CmsGraphql`,
+      ``,
+      `// @ts-ignore: gql.tada's cache overload rejects this instantiation, but the parse overload still resolves`,
+      `export type CmsDocument<Query extends string> = ReturnType<typeof graphql<Query, []>>`,
+      ``,
+      `export type CmsResult<Query extends string> = string extends Query`,
+      `  ? Record<string, unknown>`,
+      `  : ResultOf<CmsDocument<Query>>`,
+      ``,
+      `export type CmsVariables<Query extends string> = string extends Query`,
+      `  ? Record<string, unknown>`,
+      `  : VariablesOf<CmsDocument<Query>>`,
+      ``
+    ].join("\n")
+  });
+  nuxt.options.alias["#cms-graphql"] = graphqlTemplate.dst;
+}
 const module$1 = defineNuxtModule({
   meta: {
     name: "@xleddyl/nuxt-cms",
@@ -676,11 +1062,19 @@ const module$1 = defineNuxtModule({
     const logger = useLogger("nuxt-cms");
     const resolved = resolveModuleOptions(options);
     if (!resolveCmsEnabled(options.enabled, process.env[CMS_ENABLED_ENV])) {
-      const stub = resolver.resolve("./runtime/app/composables/cms-query-disabled");
+      const queryStub = resolver.resolve("./runtime/app/composables/cms-query-disabled");
+      const entryStub = resolver.resolve("./runtime/app/composables/cms-entry-disabled");
       addImports([
-        { name: "useCms", from: stub },
-        { name: "$cmsQuery", from: stub }
+        { name: "useCms", from: queryStub },
+        { name: "$cmsQuery", from: queryStub },
+        { name: "useCmsSingle", from: entryStub },
+        { name: "useCmsCollection", from: entryStub },
+        { name: "useCmsPage", from: entryStub }
       ]);
+      addCmsTypeTemplates(
+        nuxt,
+        await loadCmsConfig(nuxt, resolver, resolved.configPath, resolved.i18n, logger)
+      );
       nuxt.options.runtimeConfig.public.cms = {
         mediaBaseUrl: resolved.media.publicBaseUrl,
         mediaStorage: resolved.media.storage,
@@ -688,7 +1082,7 @@ const module$1 = defineNuxtModule({
         i18n: resolved.i18n
       };
       logger.info(
-        "[nuxt-cms] disabled: registering no-op useCms/$cmsQuery stubs, skipping admin, server and database setup"
+        "[nuxt-cms] disabled: registering no-op query composables and generated types, skipping admin, server and database setup"
       );
       return;
     }
@@ -713,38 +1107,13 @@ const module$1 = defineNuxtModule({
         "[nuxt-cms] media.storage is 's3' with credentials configured but no publicBaseUrl (media.publicBaseUrl or NUXT_PUBLIC_CMS_MEDIA_BASE_URL); uploaded media URLs will be null."
       );
     }
-    const configPath = await resolvePath(resolved.configPath, { cwd: nuxt.options.rootDir });
-    nuxt.options.alias["#nuxt-cms"] = resolver.resolve("./runtime/shared/index");
-    nuxt.options.watch.push(configPath);
-    let cmsConfig = {};
-    if (existsSync(configPath)) {
-      nuxt.options.alias["#cms-config"] = configPath;
-      const jiti = createJiti(import.meta.url, {
-        moduleCache: false,
-        alias: { "#nuxt-cms": resolver.resolve("./runtime/shared/index") }
-      });
-      cmsConfig = await jiti.import(configPath, { default: true });
-    } else {
-      logger.warn(
-        `[nuxt-cms] Config file not found: ${configPath}. Using an empty registry \u2014 create a ${resolved.configPath}.ts with defineCmsConfig().`
-      );
-      nuxt.options.alias["#cms-config"] = resolver.resolve("./runtime/shared/empty-config");
-    }
-    const configErrors = validateConfig(cmsConfig, resolved.i18n);
-    if (configErrors.length) {
-      for (const error of configErrors) logger.error(error);
-      throw new Error(
-        `[nuxt-cms] Invalid cms config (${configErrors.length} error${configErrors.length > 1 ? "s" : ""})`
-      );
-    }
-    const moduleRequire = createRequire(import.meta.url);
-    const resolveImport = (specifier) => {
-      try {
-        return fileURLToPath(import.meta.resolve(specifier)).replace(/\\/g, "/");
-      } catch {
-        return moduleRequire.resolve(specifier).replace(/\\/g, "/");
-      }
-    };
+    const cmsConfig = await loadCmsConfig(
+      nuxt,
+      resolver,
+      resolved.configPath,
+      resolved.i18n,
+      logger
+    );
     const schemaTemplate = addTemplate({
       filename: "cms/schema.ts",
       write: true,
@@ -755,64 +1124,15 @@ const module$1 = defineNuxtModule({
       )
     });
     nuxt.options.alias["#cms-tables"] = schemaTemplate.dst;
-    addTemplate({
-      filename: "cms/schema.graphql",
-      write: true,
-      getContents: () => renderGraphqlSdl(cmsConfig)
-    });
-    const typesTemplate = addTemplate({
-      filename: "cms/types.ts",
-      write: true,
-      getContents: () => renderTypesFile(cmsConfig)
-    });
-    nuxt.options.alias["#cms-types"] = typesTemplate.dst;
-    addTemplate({
-      filename: "cms/graphql-env.d.ts",
-      write: true,
-      getContents: () => {
-        const introspection = minifyIntrospection(
-          introspectionFromSchema(buildSchema(renderGraphqlSdl(cmsConfig)))
-        );
-        return outputIntrospectionFile(introspection, {
-          fileType: ".d.ts",
-          shouldPreprocess: true
-        }).split("import * as gqlTada from 'gql.tada';")[0];
-      }
-    });
-    const gqlTadaTypesPath = resolveImport("gql.tada").replace(/\.[mc]?js$/, "");
-    const graphqlTemplate = addTemplate({
-      filename: "cms/graphql.ts",
-      write: true,
-      getContents: () => [
-        `import type { initGraphQLTada, ResultOf, VariablesOf } from '${gqlTadaTypesPath}'`,
-        `import type { introspection } from './graphql-env'`,
-        ``,
-        `export type CmsGraphql = initGraphQLTada<{`,
-        `  introspection: introspection`,
-        `  scalars: {`,
-        `    JSON: unknown`,
-        `  }`,
-        `}>`,
-        ``,
-        `declare const graphql: CmsGraphql`,
-        ``,
-        `// @ts-ignore: gql.tada's cache overload rejects this instantiation, but the parse overload still resolves`,
-        `export type CmsDocument<Query extends string> = ReturnType<typeof graphql<Query, []>>`,
-        ``,
-        `export type CmsResult<Query extends string> = string extends Query`,
-        `  ? Record<string, unknown>`,
-        `  : ResultOf<CmsDocument<Query>>`,
-        ``,
-        `export type CmsVariables<Query extends string> = string extends Query`,
-        `  ? Record<string, unknown>`,
-        `  : VariablesOf<CmsDocument<Query>>`,
-        ``
-      ].join("\n")
-    });
-    nuxt.options.alias["#cms-graphql"] = graphqlTemplate.dst;
+    addCmsTypeTemplates(nuxt, cmsConfig);
+    const queryComposables = resolver.resolve("./runtime/app/composables/cms-query");
+    const entryComposables = resolver.resolve("./runtime/app/composables/cms-entry");
     addImports([
-      { name: "useCms", from: resolver.resolve("./runtime/app/composables/cms-query") },
-      { name: "$cmsQuery", from: resolver.resolve("./runtime/app/composables/cms-query") }
+      { name: "useCms", from: queryComposables },
+      { name: "$cmsQuery", from: queryComposables },
+      { name: "useCmsSingle", from: entryComposables },
+      { name: "useCmsCollection", from: entryComposables },
+      { name: "useCmsPage", from: entryComposables }
     ]);
     const {
       driver,