feat: add fetchAlwaysLastModified content base option and other minor fixes

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.0.0-alpha.5
+
+### Minor Changes
+
+- feat: add new `fetchAlwaysLastModified` content base option
+
+### Patch Changes
+
+- fix: app navigation link types
+- chore: use `throwError` method from `@jadeja/ts` in components
+- chore: add comment for loading dynamic modules
+
 ## 1.0.0-alpha.4
 
 ### Patch Changes

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jadeja/docs",
   "description": "an opinionated documentation framework",
-  "version": "1.0.0-alpha.4",
+  "version": "1.0.0-alpha.5",
   "type": "module",
   "exports": {
     "./styles/*": {

src/components/layout/search.tsx

@@ -5,6 +5,7 @@
 /* ============================================================================================= */
 
 import debounce from "@jadeja/ts/lib/debounce";
+import { throwError } from "@jadeja/ts/lib/logger";
 import { useState, useEffect, startTransition, useRef, createContext, useContext } from "react";
 
 import { XIcon } from "@/components/assets/icons";
@@ -33,7 +34,7 @@ export const useSearchContext = () => {
   const context = useContext(SearchContext);
 
   if (!context) {
-    throw new Error("components must be used inside SearchRoot");
+    return throwError("components must be used inside SearchRoot");
   }
 
   return context;

src/components/link.tsx

@@ -2,6 +2,7 @@
 
 /* ============================================================================================= */
 
+import { throwError } from "@jadeja/ts/lib/logger";
 import { default as NextLink } from "next/link.js";
 import { usePathname } from "next/navigation.js";
 
@@ -25,7 +26,7 @@ export const Link = ({ href, navLink, ...rest }: LinkProps): ReactElement<HTMLAn
   const pathname = usePathname();
 
   if (!href) {
-    throw new Error("`href` prop is missing!");
+    return throwError("`href` prop is missing!");
   }
 
   // open external link in new tab

src/lib/content.ts

@@ -80,6 +80,11 @@ export class Content<U extends Record<string, unknown> = {}> {
 
     instance.options ??= options;
 
+    if (!("fetchAlwaysLastModified" in instance.options)) {
+      // oxlint-disable-next-line node/no-process-env
+      instance.options.fetchAlwaysLastModified = process.env.NODE_ENV === "production";
+    }
+
     instance.paths ??= paths;
 
     // register methods, so `this` would point to singleton instance and not this class
@@ -368,16 +373,23 @@ export class Content<U extends Record<string, unknown> = {}> {
 
         const fields = attributes;
 
-        if (!fields.title || !fields.description || !fields.keywords || !fields.authors) {
+        if (!fields.title || !fields.description || !fields.keywords || !fields.authors?.length) {
           return throwError(
             `Missing frontmatter [title, description, keywords, authors] field(s) in ${filePATH} with index ${index}`,
           );
         }
 
-        if (!fields.publishedAt || !fields.lastModifiedAt) {
+        if (!fields.publishedAt || !fields.lastModifiedAt || this.options.fetchAlwaysLastModified) {
+          //
+          let { lastModifiedAt } = fields;
+
+          if (!lastModifiedAt || this.options.fetchAlwaysLastModified) {
+            lastModifiedAt = getLastModified(filePATH);
+          }
+
           Object.assign(fields, {
             publishedAt: fields.publishedAt ?? new Date().toISOString(),
-            lastModifiedAt: fields.lastModifiedAt ?? getLastModified(filePATH),
+            lastModifiedAt,
           });
 
           // add modified frontmatter back to file (full rewrite)

src/lib/load-module.ts

@@ -31,6 +31,10 @@ export const loadModule = async ({ content, slugs }: LoadModuleOptions): LoadMod
 
   try {
     // dynamically import `.mdx` file as module
+    // NOTE: if bundler can't resolve the dynamic module, add alias with aboslute path
+    // NOTE: `"@/content": resolve(import.meta.dirname, "src/content")`
+    // TODO: find a more reliable way
+    //
     // oxlint-disable-next-line typescript/no-unsafe-assignment
     const dynamicModule: DocsModuleType = await import(
       `@/content/${content.paths.dir}/${filePath}`

src/types/config.ts

@@ -24,7 +24,7 @@ export interface DocsConfig {
   analytics?: Analytics;
   constants: Constants;
   links: {
-    navigations: Record<string, Link>;
+    navigations: Record<string, NavigationLink>;
     socials: Record<string, Link>;
   };
   mdxConfig: NextMDXOptions;
@@ -155,6 +155,10 @@ export interface Link {
   title?: string;
 }
 
+export type NavigationLink = Omit<Link, "url"> & {
+  url: Link["url"] | `/${string}`;
+};
+
 export type AuthorLink = Omit<Link, "icon"> & {
   img?: string;
 };

src/types/content.ts

@@ -8,6 +8,7 @@ import type { DocsConfig } from "@/types/config";
 ================================================================================================ */
 
 export interface ContentBaseOptions {
+  fetchAlwaysLastModified?: boolean;
   search: CreateSearchInstanceOptions;
   trailingSlash: DocsConfig["trailingSlash"];
 }