defuss-ssg

Static Site Generator (SSG) for defuss

Simply generate a static site from a content directory to an output directory with full defuss-MDX (GFM + Frontmatter) support:

npx defuss-ssg build ./folder

Or install globally or locally in a project:

npm install -g defuss-ssg

And then run (in an NPM script or globally):

defuss-ssg build ./folder

defuss-ssg serve ./folder

This starts a local server at http://localhost:3000 and watches for changes in:

• pages/ directory
• components/ directory
• assets/ directory

Changes trigger automatic rebuilds, with the last change always taking priority to prevent build queueing issues.

Advanced users may want to use the library programmatically:

import { setup, build, serve } from "defuss-ssg";

(async () => {

  // Setup project initially
  const setupStatus = await setup("./my-site");
  if (setupStatus.code !== "OK") { 
    console.error("Setup failed:", setupStatus.message);
    process.exit(1);
  }

  // One-time build
  await build({
    projectDir: "./my-site",
    debug: true,
  });

  // Or serve with auto-rebuild
  await serve({
    projectDir: "./my-site", 
    debug: true,
  });
})();

defuss-ssg is a CLI tool and library for building static websites using modern JavaScript/TypeScript and defuss. It reads content files (Markdown, MDX) from a specified directory, processes them with MDX plugins, compiles components with esbuild, and outputs fully static HTML sites ready for deployment.

It supports a plugin system for extending the build process at various phases (pre-build, post-build, page-level transformations), automatic file watching and rebuilding in serve mode, and seamless integration with defuss components for interactive features.

Features

• MDX Support: Full Markdown + JSX support with frontmatter parsing
• Component Integration: Use defuss components in your MDX files
• Plugin System: Extend the build process with custom plugins at multiple phases
• Fast Compilation: Powered by esbuild for quick builds and hot reloading
• Serve Mode: Built-in development server with file watching and auto-rebuild
• TypeScript Ready: Full TypeScript support for components and configuration
• Asset Handling: Automatic copying of static assets to output directory
• Flexible Configuration: Configurable via TypeScript config file with sensible defaults

Example site project structure

Create a project structure like this:

my-site/
├── pages/
│   ├── index.mdx
│   └── blog/
│       └── hello-world.mdx
├── components/
│   └── button.tsx
├── assets/
│   └── styles.css
└── config.ts

Then run defuss-ssg build ./my-site and a dist folder will be created with the complete static build.

Config file

You can customize the paths and behaviour of the build process, by creating a simple config.ts file in the project folder.

Example config.ts file

import { remarkPlugins, rehypePlugins } from "defuss-ssg";

export default {
  pages: "pages",
  output: "dist",
  components: "components",
  assets: "assets",
  remarkPlugins: [...remarkPlugins], // default remark plugins
  rehypePlugins: [...rehypePlugins], // default rehype plugins
  plugins: [],
};

You may add any remark and rehype plugin of your choice. See the MDX documentation for more informations on Remark and Rehype.

defuss-ssg plugins can be registered via the plugins array and are executed in order of registration, in each build phase.

Example MDX page (pages/index.mdx)

---
title: Home Page
---

import Button from "../components/button.js"

# Welcome to my site

This is a **markdown** page with JSX components.

<Button>Click me</Button>

Example Button component (components/button.tsx)

Components are imported as .js but saved as .tsx:

export const Button = ({ label }: { label: string }) => {
  return (
    <button type="button" onClick={() => alert("Button clicked!")}>
      {label}
    </button>
  );
};

Plugin System

Extend the build process with plugins that run at different phases:

import { rule, transval, access } from 'defuss-transval';

type UserData = {
  user: {
    profile: {
      name: string;
      email: string;
      settings: {
        theme: 'light' | 'dark';
        notifications: boolean;
      };
    };
    posts: Array<{
      title: string;
      published: boolean;
    import { SsgPlugin } from "defuss-ssg";

const myPlugin: SsgPlugin = {
  name: "my-plugin",
  phase: "page-html", // "pre" | "post" | "page-vdom" | "page-dom" | "page-html"
  fn: (html, relativePath, config) => {
    // Modify HTML before writing
    return html.replace("old-text", "new-text");
  },
};

export default {
  plugins: [myPlugin],
  // ... other config
};

Available plugin phases:

• pre: Before build starts
• page-vdom: After VDOM creation for each page
• page-dom: After DOM rendering for each page
• page-html: After HTML serialization for each page
• post: After build completes

MDX Features

defuss-ssg supports full MDX with defuss components and common GFM Markdown features:

• Frontmatter: YAML/TOML metadata extraction - the meta object holds frontmatter data - use e.g. { meta.title } for page title defined in frontmatter like this:

--- 
title: My Page 
---

• JSX Components: Use defuss components in your content
• Math Support: KaTeX rendering with $...$ and $$...$$
• Custom Plugins: Extend MDX processing with remark/rehype plugins

Build Process

The build process follows these steps:

1. Copy Project: Copy all files to temporary directory
2. Compile MDX: Process MDX files to ESM JavaScript
3. Compile Components: Bundle components with esbuild
4. Evaluate Pages: Run page functions to generate VDOM
5. Render HTML: Convert VDOM to HTML using defuss/server
6. Run Plugins: Execute plugins at various phases
7. Copy Assets: Copy static assets to output
8. Clean Up: Remove temporary files (unless debug mode)

CLI Reference

defuss-ssg <command> <folder>

Commands:
  build <folder>    Build the static site
  serve <folder>    Serve with auto-rebuild on changes