chore: refactor, update docs

README.md

@@ -32,10 +32,10 @@ Most frameworks require you to learn a new strategy for rendering on the server,
 
 ```jsx
 // ReactServerComponent.jsx
-const ServerComponent = () => {
-    const res = await fetch("https://my-cms...");
-    const data = await res.json();
-    return <article>{data.html}</article>;
+const ServerComponent = async () => {
+	const res = await fetch("https://my-cms...");
+	const data = await res.json();
+	return <article>{data.html}</article>;
 };
 
 export default ServerComponent;

packages/create-domco/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "create-domco",
 	"description": "Create a new domco project",
-	"version": "0.0.44",
+	"version": "0.0.45",
 	"type": "module",
 	"types": "./index.d.ts",
 	"main": "./index.js",

packages/create-domco/template/index.ts

@@ -1,7 +1,7 @@
 const versions = {
 	typesNode: "20.12.10",
 	autoprefixer: "10.4.19",
-	domco: "0.5.10",
+	domco: "0.5.11",
 	prettier: "3.2.5",
 	prettierTailwind: "0.5.14",
 	tailwind: "3.4.3",

packages/domco/docs/README.md

@@ -33,10 +33,10 @@ Most frameworks require you to learn a new strategy for rendering on the server,
 
 ```jsx
 // ReactServerComponent.jsx
-const ServerComponent = () => {
-    const res = await fetch("https://my-cms...");
-    const data = await res.json();
-    return <article>{data.html}</article>;
+const ServerComponent = async () => {
+	const res = await fetch("https://my-cms...");
+	const data = await res.json();
+	return <article>{data.html}</article>;
 };
 
 export default ServerComponent;

packages/domco/docs/globals.md

@@ -50,7 +50,7 @@ export const config: Config = {
 
 #### Source
 
-[types/index.ts:55](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/types/index.ts#L55)
+[types/index.ts:55](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/types/index.ts#L55)
 
 ***
 
@@ -74,7 +74,7 @@ export const config: Config = {
 
 #### Source
 
-[types/index.ts:3](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/types/index.ts#L3)
+[types/index.ts:3](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/types/index.ts#L3)
 
 ***
 
@@ -110,7 +110,7 @@ The route as a string, for example: `/posts/[slug]/`
 
 #### Source
 
-[types/index.ts:16](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/types/index.ts#L16)
+[types/index.ts:16](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/types/index.ts#L16)
 
 ***
 
@@ -175,7 +175,7 @@ Provide the possible parameters for the current route.
 
 #### Source
 
-[types/index.ts:69](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/types/index.ts#L69)
+[types/index.ts:69](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/types/index.ts#L69)
 
 ***
 
@@ -185,7 +185,7 @@ Provide the possible parameters for the current route.
 
 #### Source
 
-[types/index.ts:67](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/types/index.ts#L67)
+[types/index.ts:67](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/types/index.ts#L67)
 
 ## Functions
 
@@ -229,4 +229,4 @@ export const config: Config = {
 
 #### Source
 
-[helpers/addBlocks/index.ts:26](https://github.com/rossrobino/domco/blob/84bbb923f7b5f1c7f53aef70597f89ed58dfa857/packages/domco/helpers/addBlocks/index.ts#L26)
+[helpers/addBlocks/index.ts:26](https://github.com/rossrobino/domco/blob/dafddc1d7f63cbf3011bbaaec6bed301367203ea/packages/domco/helpers/addBlocks/index.ts#L26)

packages/domco/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "domco",
 	"description": "Build-Time Rendering Without Templates",
-	"version": "0.5.10",
+	"version": "0.5.11",
 	"type": "module",
 	"keywords": [
 		"vite-plugin",

packages/domco/plugin/index.ts

@@ -1,11 +1,15 @@
-// types
-import { type ResolvedConfig, type Plugin } from "vite";
-import type { Config } from "../types/index.js";
+// Since the plugin uses node APIs it is exported from `/plugin` instead
+// of from the main export. The main export provides the more frequently
+// used APIs that can run in the browser.
 
 // node
 import path from "node:path";
 import fs from "node:fs/promises";
 
+// types
+import { type ResolvedConfig, type Plugin } from "vite";
+import type { Config } from "../types/index.js";
+
 // util
 import {
 	minifyHtml,
@@ -21,6 +25,21 @@ import {
 } from "../util/routeUtils/index.js";
 import { createDom, serializeDom } from "../util/createDom/index.js";
 
+/**
+ * Import the plugin and add to your `vite.config` file.
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { defineConfig } from "vite";
+ * import { domco } from "domco/plugin";
+ *
+ * export default defineConfig({
+ *   plugins: [domco()],
+ * });
+ * ```
+ * @param options domco options
+ * @returns the domco vite plugins
+ */
 export const domco = (options?: {
 	/**
 	 * Change the name of the page configuration file.
@@ -29,7 +48,11 @@ export const domco = (options?: {
 	 */
 	configFileName?: string;
 
-	/** `html-minifier-terser` options. */
+	/**
+	 * `html-minifier-terser` options.
+	 *
+	 * @default {}
+	 */
 	minifyHtmlOptions?: MinifyHtmlOptions;
 }): Plugin[] => {
 	const configFileName = options?.configFileName ?? "+config";
@@ -86,6 +109,7 @@ export const domco = (options?: {
 			},
 
 			configResolved(resolvedConfig) {
+				// to have access to the final values in other hooks
 				config = resolvedConfig;
 			},
 
@@ -100,6 +124,7 @@ export const domco = (options?: {
 					const fileEndings = [
 						`${configFileName}.js`,
 						`${configFileName}.ts`,
+						// nice to also have for these files by default:
 						"md",
 						"txt",
 						"json",
@@ -113,33 +138,39 @@ export const domco = (options?: {
 					}
 				});
 
-				server.middlewares.use((req, _, next) => {
-					if (!req.url) return next();
+				server.middlewares.use((request, _, next) => {
+					if (!request.url) return next();
 
-					// remove the empty strings since `dynPath` will not have those
-					const reqSegments = req.url.split("/").filter((v) => v !== "");
+					// remove the empty strings since `dynamicPath` will not have those
+					const reqSegments = request.url
+						.split("/")
+						.filter((segment) => segment !== "");
 
+					/** the possible paths based on the `index.html` files */
 					const actualPaths = Object.keys(entryPoints);
 
 					// ones that have "[" will be dynamic
-					const dynPaths = actualPaths.filter((v) => v.includes("["));
+					const dynamicPaths = actualPaths.filter((actualPath) =>
+						actualPath.includes("["),
+					);
 
-					for (const dynPath of dynPaths) {
-						const dynSegments = dynPath.split(path.sep);
+					for (const dynamicPath of dynamicPaths) {
+						// since using the file names, must use `sep` because of windows
+						const dynamicSegments = dynamicPath.split(path.sep);
 
-						if (dynSegments.length === reqSegments.length) {
+						if (dynamicSegments.length === reqSegments.length) {
 							// the paths are the same length, try to process
 							for (let i = 0; i < reqSegments.length; i++) {
 								const reqSegment = reqSegments[i];
-								const dynSegment = dynSegments[i];
+								const dynSegment = dynamicSegments[i];
 
 								if (reqSegment === dynSegment) {
 									// segments match, go to next
 									continue;
 								} else if (dynSegment?.startsWith("[")) {
 									// segment is dynamic, correct to the actual
 									reqSegments[i] = dynSegment;
-									req.url = `/${reqSegments.join("/")}/`;
+									request.url = `/${reqSegments.join("/")}/`;
 								} else {
 									// segments do not match and are not dynamic, stop checking
 									break;