Skip to content
Vincle
Esc

Loading…

    Configuration

    Without configuration, the conventions apply: routes in src/pages/ (or src/ when it has no pages/ directory), output in dist/, public/ copied as is. Add an ssg.config.ts at the project root when the site needs more:

    ssg.config.ts
    import { defineConfig } from "@vincle/ssg";
    
    export default defineConfig({
      site: "https://example.com",
      dev: {
        notFound: "/404.html",
        statuses: { "/404.html": 404 },
      },
    });
    

    defineConfig only adds types. It also accepts a function, async or not, receiving { command, mode }: command is "serve" under ssg dev and "build" under ssg generate. The configuration is read at startup; restart ssg dev after changing it.

    Options#

    Option Default Description
    root current directory Project directory; relative paths resolve from it
    src src/pages, otherwise src Directory of the routes
    out dist Output directory
    site none Public origin, such as https://example.com; enables sitemap.xml
    base / Path the site is served under, such as /docs/
    sitemap true when site is set false disables sitemap.xml
    i18n none { locales, defaultLocale }, for language alternates in the sitemap
    plugins [] Hooks into metadata, rendering and publication
    handlers built-in formats Add a source format, or false to disable an extension
    runtime Vincle Another JSX runtime and its renderer
    assets detected Asset integrations: one, an array, or false; omitted detects Vite
    copy public/ More directories to copy, as { from, to? }
    preserve none Top-level files of out that another tool owns

    dev holds the options of the development server alone:

    Option Description
    notFound Page served for a missing URL, or a function of the decoded path
    statuses HTTP status per generated path, such as { "/404.html": 404 }
    redirects Path-to-path redirects
    mimeTypes Content type per extension, such as { ".md": "text/markdown" }
    vite Vite settings for the server only

    These mirror what the host does in production: see Deployment for the same settings on the host side.

    Command line#

    ssg <dev|generate> [options]
    
      --config <file>  Use a specific configuration file
      --root <path>    Project directory (default: current directory)
      --mode <name>    Configuration mode (default: development or production)
      --port <number>  Development server port (default: 4321)
      --host <host>    Development server address (default: 127.0.0.1)
    

    The CLI looks for ssg.config with a .ts, .mts, .js, .mjs, .cts or .cjs extension. It runs on Node; pages that use Bun APIs need bun run --bun ssg generate. The same functions are exported for scripts:

    import { build, dev } from "@vincle/ssg";
    
    await build({ site: "https://example.com" });
    
    const server = await dev();
    server.vite.printUrls();
    

    Assets#

    assets accepts one AssetIntegration, an array, or false. Omitted, the conventional detection applies (vite.config.*, otherwise src/_client/main.*); assets: [] and assets: false both turn that detection off — the difference is the intent, not the effect.

    Every integration is prepared in its own directory tree, in declaration order, and each rendered directory is copied to the root of out in that same order; two outputs resolving to one path fail the build before publication. A relative directory resolves from the project root. render wrappers chain in declaration order, the first declared being the innermost (closest to the page), and dispose runs for all of them in reverse order after publication, best-effort. Only one integration may provide the module loader: two raise INVALID_CONFIG. An integration declaring dev() is prepared once per session; the others run prepare on every rebuild, and watch lists the files whose modification rebuilds the site, so ssg dev honours the declared integrations, not only Vite.

    ssg.config.ts
    import { defineConfig } from "@vincle/ssg";
    import { images } from "@vincle/ssg/image";
    import { viteAssets } from "@vincle/ssg/vite";
    
    export default defineConfig({
      assets: [viteAssets(), images({ converter, descriptors: [portrait] })],
    });
    

    See Images for the image module.

    Vite#

    A vite.config.ts at the project root applies to the pages and the client assets alike: aliases and plugins included. Set the base path with base in the SSG configuration, not in Vite's: SSG passes it to Vite, and reports a conflicting value. The Vite integration is one asset integration, the one detected by default: declaring assets makes it explicit. Page compilation always goes through Vite, even without a vite.config or client assets.

    Plugins#

    A plugin is an object with a name and up to four hooks, called in this order for every build:

    Hook Receives Typical use
    metadata each page's context Fill meta before layouts render
    render each output, not yet rendered Wrap or replace how an output is produced
    transform each output, rendered Rewrite the final text or bytes
    publish the whole site Emit derived files, such as a search index
    ssg.config.ts
    import { defineConfig } from "@vincle/ssg";
    
    export default defineConfig({
      plugins: [
        {
          name: "default-title",
          metadata(context) {
            context.meta.title ??= context.route;
          },
        },
      ],
    });
    

    A hook that throws stops the build before dist/ changes, and the error names the plugin and the hook.

    Errors#

    Every failure is an SsgError with a stable reason (such as SOURCE_MISSING or INVALID_CONFIG), a message stating the problem and its context, and a hint with the fix. JSON.stringify(error) gives the same diagnostic as structured data. Test reason, never the message text.