Skip to content
Vincle
Esc

Loading…

    Pages & layouts

    A route is a file under src/pages/. Its extension decides how it renders; its path decides its URL. Everything else in the directory, helpers and components included, starts with _ or lives outside src/pages/.

    src/
      _layout.tsx        shared layout
      _client/main.ts    browser entry, optional
      components/        imported by pages, never routes
      pages/
        index.tsx        /
        blog/
          _layout.tsx    replaces the shared layout under /blog
          first-post.md  /blog/first-post
    public/              copied as is to dist/
    

    Formats#

    Components#

    A .tsx or .jsx page exports a default component, async or not. Its meta export describes the page: title, description, and any field of your own.

    src/pages/team.tsx
    import { TeamList } from "../components/TeamList";
    
    declare function loadPeople(): Promise<{ name: string }[]>;
    
    export const meta = { title: "Team", description: "Who builds the product" };
    
    export default async function Team() {
      const people = await loadPeople();
      return <TeamList people={people} />;
    }
    

    Markdown and MDX#

    .md and .mdx pages take their metadata from YAML frontmatter. MDX can import and render components; in a .md file, JSX and imports stay plain text.

    src/pages/blog/first-post.mdx
    ---
    title: First post
    description: Why we moved to a static site
    ---
    
    import { Note } from "../../components/Note";
    
    # First post
    
    <Note>Published on our new site.</Note>
    

    Text and binary files#

    A .ts or .js page that is not a component produces a file. Name it after the file it writes: feed.xml.ts becomes /feed.xml. The default export returns a string or bytes, directly or from a function, async or not.

    src/pages/feed.xml.ts
    import { renderFeed } from "../lib/feed";
    
    declare function loadPosts(): Promise<{ title: string; url: string }[]>;
    
    export const meta = { sitemap: false };
    
    export default async function () {
      return renderFeed(await loadPosts());
    }
    

    To write several files from one source, return { path, content } objects, or yield them from a generator. Paths are relative to dist/ and cannot leave it; two sources writing the same file fail the build. A component or MDX page can add files next to its HTML with an outputs export:

    import type { PageContext } from "@vincle/ssg";
    
    export const outputs = ({ outputPath, meta }: PageContext) => ({
      path: outputPath(".json"),
      content: JSON.stringify(meta),
    });
    

    Metadata#

    meta (or the frontmatter) reaches the page, its layout and the plugins. A few fields have a meaning for the build:

    Field Effect
    title Free for the layout to use
    sitemap false leaves the page out of sitemap.xml
    layout A layout path relative to the page, or false for none
    locale The page language, for the multilingual sitemap
    incremental false re-renders the page on every change during ssg dev

    Type your own fields by augmenting SsgMeta:

    declare module "@vincle/ssg" {
      interface SsgMeta {
        author?: string;
      }
    }
    

    Layouts#

    The nearest _layout.tsx, in the page's directory or above it, wraps components, Markdown and MDX. It receives the rendered page as children, along with meta. A layout lower in the tree replaces the one above it; to build on it, import it:

    src/pages/blog/_layout.tsx
    import type { JSX } from "@vincle/core";
    import type { SsgMeta } from "@vincle/ssg";
    
    import SiteLayout from "../../_layout";
    
    export default function BlogLayout({ children, meta }: { children: JSX.Element; meta: SsgMeta }) {
      return (
        <SiteLayout meta={meta}>
          <article>{children}</article>
        </SiteLayout>
      );
    }
    

    Text and binary files are never wrapped. The layout owns the whole document, <!DOCTYPE html> included: write it with raw("<!DOCTYPE html>\n") before <html>, as in the first site.

    Client assets#

    The site ships no JavaScript of its own. To add some, or a stylesheet, create src/_client/main.ts, and optionally src/_client/main.css: SSG builds them with Vite and publishes the hashed files with the pages. Reference them from the layout with Asset, which resolves the right URL in development and in production:

    import { Asset } from "@vincle/vite-plugin";
    
    <head>
      <Asset entry="src/_client/main.css" />
      <Asset entry="src/_client/main.ts" />
    </head>;
    

    Asset comes from @vincle/vite-plugin: install it next to @vincle/ssg. A vite.config.ts at the project root is picked up for both the pages and the assets. When @tailwindcss/vite is installed, SSG enables it: import tailwindcss from main.css.