@aerobuilt/content 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @aerobuilt/content
+
+Content collections for Aero: load Markdown (and other files) with frontmatter, validate with Zod, and render to HTML. Powers the `aero:content` virtual module and optional content plugin.
+
+## Exports
+
+| Export                        | Description                                                                                                                       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `@aerobuilt/content`          | `defineCollection`, `defineConfig`, `render`; types `ContentDocument`, `ContentMeta`, `ContentCollectionConfig`, `ContentConfig`. |
+| `@aerobuilt/content/vite`     | `aeroContent(options?)` Vite plugin.                                                                                              |
+| `@aerobuilt/content/markdown` | Markdown/remark utilities (used internally).                                                                                      |
+| `@aerobuilt/content/render`   | `render(doc)` for markdown-to-HTML.                                                                                               |
+| `@aerobuilt/content/types`    | TypeScript types.                                                                                                                 |
+
+## Usage in apps
+
+Enable content in `aero.config.ts` (`content: true` or `content: { config: 'content.config.ts' }`), then define collections in **content.config.ts** and import from `aero:content` in templates.
+
+**content.config.ts**
+
+```ts
+import { defineConfig, defineCollection } from 'aerobuilt/content'
+import { z } from 'zod'
+
+const docs = defineCollection({
+	name: 'docs',
+	directory: 'content/docs',
+	include: '**/*.md',
+	schema: z.object({ title: z.string(), published: z.boolean().optional() }),
+	transform: async doc => ({ ...doc, data: { ...doc.data, slug: doc._meta.slug } }),
+})
+
+export default defineConfig({ collections: [docs] })
+```
+
+**In a page (e.g. getStaticPaths + render)**
+
+```html
+<script is:build>
+	import { getCollection, render } from 'aero:content'
+
+	export async function getStaticPaths() {
+		const docs = await getCollection('docs')
+		return docs.map((doc) => ({ params: { slug: doc._meta.slug }, props: doc }))
+	}
+
+	const doc = aero.props
+	const { html } = await render(doc)
+</script>
+<article each="{ doc in [doc] }">
+	<h1>{ doc.data.title }</h1>
+	<div>{ html }</div>
+</article>
+```
+
+## API (from `aero:content`)
+
+- **getCollection(name, filterFn?)** — Returns a promise of documents for the named collection. In production, only documents with `data.published === true` are returned unless overridden. Optional `filterFn(doc)` can filter further.
+- **render(doc)** — Renders a content document’s markdown body to HTML. Returns `{ html: string }`. Use with a document from `getCollection` or props.
+
+## Content document shape
+
+Each document has:
+
+- **id** — Collection-relative path without extension.
+- **data** — Validated frontmatter (from schema).
+- **body** — Raw markdown (after frontmatter).
+- **\_meta** — `{ path, slug, filename, extension }`.
+
+## Vite plugin
+
+`aeroContent(options?)` resolves the virtual module `aero:content` (and `aero:content/...`) with serialized collections, `getCollection`, and `render`. It loads `content.config.ts` at config resolve/build start and watches collection directories for HMR. Options: `config` (path to config file, default `content.config.ts`).
+
+## File structure
+
+- `src/loader.ts` — Load collections, serialize to virtual module source.
+- `src/markdown.ts` — Parse Markdown and frontmatter (gray-matter, remark).
+- `src/render.ts` — Lazy markdown-to-HTML (remark).
+- `src/types.ts` — `defineCollection`, `defineConfig`, types.
+- `src/vite.ts` — Vite plugin.
+
+## Tests
+
+Vitest in `packages/content`: loader, markdown, render, Vite plugin. Run from repo root: `pnpm test`.

package/dist/chunk-3IPQCQIC.js

@@ -0,0 +1,16 @@
+// src/render.ts
+import { remark } from "remark";
+import remarkHtml from "remark-html";
+var processor = remark().use(remarkHtml);
+async function render(doc) {
+  if (!doc) {
+    console.warn("[aero] render() received null or undefined document. Returning empty HTML.");
+    return { html: "" };
+  }
+  const result = await processor.process(doc.body);
+  return { html: String(result) };
+}
+
+export {
+  render
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { a as ContentCollectionConfig, b as ContentConfig, C as ContentDocument, c as ContentMeta, d as defineCollection, e as defineConfig } from './types-VPBJNne0.js';
+export { render } from './render.js';
+import 'zod';

package/dist/index.js

@@ -0,0 +1,16 @@
+import {
+  render
+} from "./chunk-3IPQCQIC.js";
+
+// src/types.ts
+function defineCollection(config) {
+  return config;
+}
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineCollection,
+  defineConfig,
+  render
+};

package/dist/markdown.d.ts

@@ -0,0 +1,19 @@
+import { C as ContentDocument } from './types-VPBJNne0.js';
+import 'zod';
+
+/**
+ * Eager markdown-to-HTML compilation for use in collection transforms.
+ *
+ * @remarks
+ * Uses remark + remark-html. For lazy rendering in pages, use `render()` from `aero:content` instead.
+ */
+
+/**
+ * Compile a document's markdown body to HTML. Use in `transform` to attach `html` to each document.
+ *
+ * @param document - Content document (body is compiled).
+ * @returns HTML string.
+ */
+declare function compileMarkdown(document: ContentDocument): Promise<string>;
+
+export { compileMarkdown };

package/dist/markdown.js

@@ -0,0 +1,11 @@
+// src/markdown.ts
+import { remark } from "remark";
+import remarkHtml from "remark-html";
+var processor = remark().use(remarkHtml);
+async function compileMarkdown(document) {
+  const result = await processor.process(document.body);
+  return String(result);
+}
+export {
+  compileMarkdown
+};

package/dist/render.d.ts

@@ -0,0 +1,21 @@
+import { C as ContentDocument } from './types-VPBJNne0.js';
+import 'zod';
+
+/**
+ * Lazy markdown-to-HTML for use in pages (import from `aero:content`).
+ *
+ * @remarks
+ * Uses the same remark pipeline as compileMarkdown. Call from on:build with a document (e.g. from getCollection); returns `{ html }`.
+ */
+
+/**
+ * Render a content document's markdown body to HTML. Use in pages with documents from getCollection.
+ *
+ * @param doc - Content document (or null/undefined; returns empty HTML and logs a warning).
+ * @returns `{ html: string }`.
+ */
+declare function render(doc: ContentDocument | null | undefined): Promise<{
+    html: string;
+}>;
+
+export { render };

package/dist/render.js

@@ -0,0 +1,6 @@
+import {
+  render
+} from "./chunk-3IPQCQIC.js";
+export {
+  render
+};

package/dist/types-VPBJNne0.d.ts

@@ -0,0 +1,64 @@
+import { ZodType } from 'zod';
+
+/**
+ * Content package types: document metadata, collection config, and define helpers.
+ *
+ * @remarks
+ * Used by the loader (frontmatter + body → ContentDocument), by content.config.ts (defineCollection, defineConfig), and by the Vite plugin.
+ */
+
+/** Metadata attached to every content document (path, slug, filename, extension). */
+interface ContentMeta {
+    /** Path relative to the collection directory (no extension). */
+    path: string;
+    /** Slug derived from the filename (no extension). */
+    slug: string;
+    /** The raw filename including extension. */
+    filename: string;
+    /** The file extension (e.g. `'.md'`). */
+    extension: string;
+}
+/** A content document: id, validated frontmatter (`data`), raw body, and `_meta`. */
+interface ContentDocument<TSchema extends Record<string, any> = Record<string, any>> {
+    /** Unique identifier: collection-relative path without extension. */
+    id: string;
+    /** Validated frontmatter fields. */
+    data: TSchema;
+    /** Raw body content (everything after frontmatter). */
+    body: string;
+    /** Auto-generated metadata. */
+    _meta: ContentMeta;
+}
+/** Single collection definition: name, directory, glob, optional schema and transform. */
+interface ContentCollectionConfig<TSchema extends Record<string, any> = Record<string, any>, TOutput = ContentDocument<TSchema>> {
+    /** Unique collection name (used as the export key, e.g. `allDocs`). */
+    name: string;
+    /** Directory to scan, relative to project root. */
+    directory: string;
+    /** Glob pattern for files to include (default: `**\/*.md`). */
+    include?: string;
+    /** Zod schema for frontmatter validation; `body` is always present. */
+    schema?: ZodType<TSchema>;
+    /** Optional async transform after validation; receives document, returns final shape. */
+    transform?: (document: ContentDocument<TSchema>) => TOutput | Promise<TOutput>;
+}
+/** Top-level content config: array of collection definitions. */
+interface ContentConfig {
+    collections: ContentCollectionConfig<any, any>[];
+}
+/**
+ * Define a content collection (typed helper for content.config.ts).
+ *
+ * @param config - Collection config (name, directory, include, schema, transform).
+ * @returns The same config (unchanged).
+ */
+declare function defineCollection<TSchema extends Record<string, any> = Record<string, any>, TOutput = ContentDocument<TSchema>>(config: ContentCollectionConfig<TSchema, TOutput>): ContentCollectionConfig<TSchema, TOutput>;
+/**
+ * Define the content config (typed helper for content.config.ts).
+ *
+ * @param config - Config with `collections` array.
+ * @returns The same config (unchanged).
+ */
+declare function defineConfig(config: ContentConfig): ContentConfig;
+
+export { type ContentDocument as C, type ContentCollectionConfig as a, type ContentConfig as b, type ContentMeta as c, defineCollection as d, defineConfig as e };

package/dist/vite.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from 'vite';
+
+/** Options for the content plugin (config file path). */
+interface AeroContentOptions {
+    /** Path to content config file relative to project root (default: `content.config.ts`). */
+    config?: string;
+}
+/**
+ * Vite plugin that provides the `aero:content` virtual module (getCollection, render, serialized data).
+ *
+ * @param options - Optional config file path.
+ * @returns Vite plugin.
+ */
+declare function aeroContent(options?: AeroContentOptions): Plugin;
+
+export { type AeroContentOptions, aeroContent };

package/dist/vite.js

@@ -0,0 +1,172 @@
+// src/loader.ts
+import fg from "fast-glob";
+import matter from "gray-matter";
+import fs from "fs";
+import path from "path";
+async function loadCollection(config, root) {
+  const dir = path.resolve(root, config.directory);
+  const pattern = config.include || "**/*.md";
+  const files = await fg(pattern, { cwd: dir, absolute: true });
+  const documents = [];
+  for (const file of files) {
+    const raw = fs.readFileSync(file, "utf-8");
+    const { data: frontmatter, content: body } = matter(raw);
+    const relPath = path.relative(dir, file);
+    const parsed = path.parse(relPath);
+    const id = parsed.dir ? `${parsed.dir}/${parsed.name}` : parsed.name;
+    const meta = {
+      path: id,
+      slug: parsed.name,
+      filename: parsed.base,
+      extension: parsed.ext
+    };
+    let validated = frontmatter;
+    if (config.schema) {
+      const result = config.schema.safeParse(frontmatter);
+      if (!result.success) {
+        const errors = "error" in result ? result.error?.issues?.map((i) => i.message).join(", ") : "Validation failed";
+        console.warn(
+          `[aero:content] \u26A0 Skipping "${relPath}" in collection "${config.name}": ${errors}`
+        );
+        continue;
+      }
+      validated = result.data;
+    }
+    const doc = {
+      id,
+      data: validated,
+      body,
+      _meta: meta
+    };
+    if (config.transform) {
+      documents.push(await config.transform(doc));
+    } else {
+      documents.push(doc);
+    }
+  }
+  return documents;
+}
+async function loadAllCollections(config, root) {
+  const result = /* @__PURE__ */ new Map();
+  for (const collection of config.collections) {
+    const docs = await loadCollection(collection, root);
+    result.set(collection.name, docs);
+  }
+  return result;
+}
+function getWatchedDirs(config, root) {
+  return config.collections.map((c) => path.resolve(root, c.directory));
+}
+function serializeContentModule(loaded) {
+  const collectionsContent = Array.from(loaded.entries()).map(([name, docs]) => `  ${JSON.stringify(name)}: ${JSON.stringify(docs, null, 2)}`).join(",\n");
+  return `
+const __collections = {
+${collectionsContent}
+};
+
+export function getCollection(name, filterFn) {
+  let data = __collections[name];
+  if (!data) throw new Error(\`[aero:content] Collection "\${name}" not found. Available: \${Object.keys(__collections).join(", ")}\`);
+
+  if (import.meta.env.PROD) {
+    data = data.filter(item => item.data.published === true);
+  }
+
+  if (typeof filterFn === "function") {
+    return data.filter(filterFn);
+  }
+
+  return data;
+}
+
+export { render } from '@aerobuilt/content/render';
+`;
+}
+
+// src/vite.ts
+import path2 from "path";
+import { pathToFileURL } from "url";
+var CONTENT_MODULE_ID = "aero:content";
+var RESOLVED_CONTENT_MODULE_ID = "\0aero:content";
+var CONFIG_FILE = "content.config.ts";
+function aeroContent(options = {}) {
+  let resolvedConfig;
+  let contentConfig = null;
+  let serialized = null;
+  let watchedDirs = [];
+  return {
+    name: "vite-plugin-aero-content",
+    /** Load content.config.ts, set contentConfig and watchedDirs; warn if config missing. */
+    async configResolved(config) {
+      resolvedConfig = config;
+      const root = config.root;
+      const configPath = path2.resolve(root, options.config || CONFIG_FILE);
+      try {
+        const configUrl = pathToFileURL(configPath).href;
+        const mod = await import(
+          /* @vite-ignore */
+          configUrl
+        );
+        contentConfig = mod.default;
+        watchedDirs = getWatchedDirs(contentConfig, root);
+      } catch (err) {
+        if (err.code === "ERR_MODULE_NOT_FOUND" || err.code === "ENOENT") {
+          config.logger.warn(
+            `[aero:content] No config found at "${configPath}". Content collections disabled.`
+          );
+          return;
+        }
+        throw err;
+      }
+    },
+    /** Resolve aero:content and aero:content/… to the resolved virtual ID. */
+    resolveId(id) {
+      if (id === CONTENT_MODULE_ID) {
+        return RESOLVED_CONTENT_MODULE_ID;
+      }
+      if (id.startsWith(CONTENT_MODULE_ID + "/")) {
+        return RESOLVED_CONTENT_MODULE_ID;
+      }
+      return null;
+    },
+    /** Load virtual module: loadAllCollections, serializeContentModule, return ESM source. */
+    async load(id) {
+      if (id !== RESOLVED_CONTENT_MODULE_ID) return null;
+      if (!contentConfig) {
+        return "// aero:content \u2014 no collections configured\n";
+      }
+      const loaded = await loadAllCollections(contentConfig, resolvedConfig.root);
+      serialized = serializeContentModule(loaded);
+      return serialized;
+    },
+    /** Invalidate virtual module and full-reload when a file in a watched content dir changes. */
+    handleHotUpdate({ file, server }) {
+      const isContent = watchedDirs.some((dir) => file.startsWith(dir));
+      if (!isContent) return;
+      const mod = server.moduleGraph.getModuleById(RESOLVED_CONTENT_MODULE_ID);
+      if (mod) {
+        server.moduleGraph.invalidateModule(mod);
+        server.hot.send({ type: "full-reload" });
+      }
+    },
+    /** Fallback: load config in build if not already loaded in configResolved. */
+    async buildStart() {
+      if (contentConfig) return;
+      const root = resolvedConfig.root;
+      const configPath = path2.resolve(root, options.config || CONFIG_FILE);
+      try {
+        const configUrl = pathToFileURL(configPath).href;
+        const mod = await import(
+          /* @vite-ignore */
+          configUrl
+        );
+        contentConfig = mod.default;
+        watchedDirs = getWatchedDirs(contentConfig, root);
+      } catch {
+      }
+    }
+  };
+}
+export {
+  aeroContent
+};

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@aerobuilt/content",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jamie Wilson",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aerobuilt/aero.git",
+    "directory": "packages/content"
+  },
+  "homepage": "https://github.com/aerobuilt/aero",
+  "private": false,
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown.d.ts",
+      "default": "./dist/markdown.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "default": "./dist/render.js"
+    },
+    "./types": "./dist/types.d.ts"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "gray-matter": "^4.0.3",
+    "remark": "^15.0.1",
+    "remark-html": "^16.0.1"
+  },
+  "peerDependencies": {
+    "vite": "8.0.0-beta.15",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vite": "8.0.0-beta.15",
+    "vitest": "^4.0.18",
+    "zod": "^4.3.6"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/vite.ts src/markdown.ts src/render.ts --format esm --dts --clean --out-dir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}