feat(module): introduce api.baseURL and deprecate base (#1695)

src/module.ts

@@ -19,7 +19,7 @@ import type { Lang as ShikiLang, Theme as ShikiTheme } from 'shiki-es'
 import { listen } from 'listhen'
 import type { WatchEvent } from 'unstorage'
 import { createStorage } from 'unstorage'
-import { withTrailingSlash } from 'ufo'
+import { joinURL, withLeadingSlash, withTrailingSlash } from 'ufo'
 import { name, version } from '../package.json'
 import {
   CACHE_VERSION,
@@ -45,8 +45,17 @@ export interface ModuleOptions {
    * Base route that will be used for content api
    *
    * @default '_content'
+   * @deprecated Use `api.base` instead
    */
   base: string
+  api: {
+    /**
+     * Base route that will be used for content api
+     *
+     * @default '/api/_content'
+     */
+    baseURL: string
+  }
   /**
    * Disable content watcher and hot content reload.
    * Note: Watcher is a development feature and will not includes in the production.
@@ -229,7 +238,11 @@ export default defineNuxtModule<ModuleOptions>({
     }
   },
   defaults: {
-    base: '_content',
+    // @deprecated
+    base: '',
+    api: {
+      baseURL: '/api/_content'
+    },
     watch: {
       ws: {
         port: 4000,
@@ -265,6 +278,12 @@ export default defineNuxtModule<ModuleOptions>({
   async setup (options, nuxt) {
     const { resolve } = createResolver(import.meta.url)
     const resolveRuntimeModule = (path: string) => resolveModule(path, { paths: resolve('./runtime') })
+
+    if (options.base) {
+      logger.warn('content.base is deprecated. Use content.api.baseURL instead.')
+      options.api.baseURL = withLeadingSlash(joinURL('api', options.base))
+    }
+
     const contentContext: ContentContext = {
       transformers: [],
       ...options
@@ -292,23 +311,23 @@ export default defineNuxtModule<ModuleOptions>({
       nitroConfig.handlers.push(
         {
           method: 'get',
-          route: `/api/${options.base}/query/:qid`,
+          route: `${options.api.baseURL}/query/:qid`,
           handler: resolveRuntimeModule('./server/api/query')
         },
         {
           method: 'get',
-          route: `/api/${options.base}/query`,
+          route: `${options.api.baseURL}/query`,
           handler: resolveRuntimeModule('./server/api/query')
         },
         {
           method: 'get',
-          route: `/api/${options.base}/cache.json`,
+          route: `${options.api.baseURL}/cache.json`,
           handler: resolveRuntimeModule('./server/api/cache')
         }
       )
 
       if (!nuxt.options.dev) {
-        nitroConfig.prerender.routes.unshift(`/api/${options.base}/cache.json`)
+        nitroConfig.prerender.routes.unshift(`${options.api.baseURL}/cache.json`)
       }
 
       // Register source storages
@@ -429,12 +448,12 @@ export default defineNuxtModule<ModuleOptions>({
         nitroConfig.handlers = nitroConfig.handlers || []
         nitroConfig.handlers.push({
           method: 'get',
-          route: `/api/${options.base}/navigation/:qid`,
+          route: `${options.api.baseURL}/navigation/:qid`,
           handler: resolveRuntimeModule('./server/api/navigation')
         })
         nitroConfig.handlers.push({
           method: 'get',
-          route: `/api/${options.base}/navigation`,
+          route: `${options.api.baseURL}/navigation`,
           handler: resolveRuntimeModule('./server/api/navigation')
         })
       })
@@ -446,13 +465,13 @@ export default defineNuxtModule<ModuleOptions>({
     if (options.highlight) {
       contentContext.transformers.push(resolveRuntimeModule('./transformers/shiki'))
       // @ts-ignore
-      contentContext.highlight.apiURL = `/api/${options.base}/highlight`
+      contentContext.highlight.apiURL = `${options.api.baseURL}/highlight`
 
       nuxt.hook('nitro:config', (nitroConfig) => {
         nitroConfig.handlers = nitroConfig.handlers || []
         nitroConfig.handlers.push({
           method: 'post',
-          route: `/api/${options.base}/highlight`,
+          route: `${options.api.baseURL}/highlight`,
           handler: resolveRuntimeModule('./server/api/highlight')
         })
       })
@@ -571,8 +590,10 @@ export default defineNuxtModule<ModuleOptions>({
         // Disable cache in dev mode
         integrity: nuxt.options.dev ? undefined : Date.now()
       },
+      api: {
+        baseURL: options.api.baseURL
+      },
       navigation: contentContext.navigation as any,
-      base: options.base,
       // Tags will use in markdown renderer for component replacement
       tags: contentContext.markdown.tags as any,
       highlight: options.highlight as any,

src/runtime/composables/client-db.ts

@@ -9,7 +9,7 @@ import { createQuery } from '../query/query'
 import type { NavItem, ParsedContent, ParsedContentMeta, QueryBuilderParams } from '../types'
 import { createNav } from '../server/navigation'
 
-const withContentBase = url => withBase(url, '/api/' + useRuntimeConfig().public.content.base)
+const withContentBase = url => withBase(url, useRuntimeConfig().public.content.api.baseURL)
 
 export const contentStorage = prefixStorage(createStorage({ driver: memoryDriver() }), '@content')
 

src/runtime/composables/utils.ts

@@ -2,7 +2,7 @@ import { withBase } from 'ufo'
 import { useRuntimeConfig, useRequestEvent, useCookie, useRoute } from '#app'
 import { unwrap, flatUnwrap } from '../markdown-parser/utils/node'
 
-export const withContentBase = (url: string) => withBase(url, '/api/' + useRuntimeConfig().public.content.base)
+export const withContentBase = (url: string) => withBase(url, useRuntimeConfig().public.content.api.baseURL)
 
 export const useUnwrap = () => ({
   unwrap,

src/runtime/server/api/cache.ts

@@ -1,17 +1,20 @@
 import { defineEventHandler } from 'h3'
 import { getContentIndex } from '../content-index'
 import { cacheStorage, serverQueryContent } from '../storage'
+import type { NavItem } from '../../types'
+import { useRuntimeConfig } from '#imports'
 
 // This route is used to cache all the parsed content
 export default defineEventHandler(async (event) => {
+  const { content } = useRuntimeConfig()
   const now = Date.now()
   // Fetch all content
   const contents = await serverQueryContent(event).find()
 
   // Generate Index
   await getContentIndex(event)
 
-  const navigation = await $fetch('/api/_content/navigation')
+  const navigation = await $fetch<NavItem[]>(`${content.api.baseURL}/navigation`)
   await cacheStorage.setItem('content-navigation.json', navigation)
 
   return {

test/__snapshots__/custom-api-base.test.ts.snap

@@ -0,0 +1,86 @@
+// Vitest Snapshot v1
+
+exports[`Custom api baaseURL > Get contents index > basic-index-body 1`] = `
+{
+  "children": [
+    {
+      "children": [
+        {
+          "type": "text",
+          "value": "Index",
+        },
+      ],
+      "props": {
+        "id": "index",
+      },
+      "tag": "h1",
+      "type": "element",
+    },
+    {
+      "children": [
+        {
+          "type": "text",
+          "value": "Hello World",
+        },
+      ],
+      "props": {},
+      "tag": "p",
+      "type": "element",
+    },
+  ],
+  "toc": {
+    "depth": 2,
+    "links": [],
+    "searchDepth": 2,
+    "title": "",
+  },
+  "type": "root",
+}
+`;
+
+exports[`Custom api baaseURL > Navigation > Get cats navigation > basic-navigation-cats 1`] = `
+[
+  {
+    "_path": "/cats",
+    "children": [
+      {
+        "_path": "/cats/bombay",
+        "title": "Bombay",
+      },
+      {
+        "_path": "/cats",
+        "title": "Cats",
+      },
+      {
+        "_path": "/cats/persian",
+        "title": "Persian",
+      },
+      {
+        "_path": "/cats/ragdoll",
+        "title": "Ragdoll",
+      },
+    ],
+    "title": "Cats list",
+  },
+]
+`;
+
+exports[`Custom api baaseURL > Navigation > Get dogs navigation > basic-navigation-dogs 1`] = `
+[
+  {
+    "_path": "/dogs",
+    "children": [
+      {
+        "_path": "/dogs/bulldog",
+        "title": "Bulldog",
+      },
+      {
+        "_path": "/dogs/german-shepherd",
+        "title": "German Shepherd",
+      },
+    ],
+    "icon": "🐶",
+    "title": "Dogs List",
+  },
+]
+`;