Skip to content
Vincle
Esc

Loading…

    Deployment

    ssg generate writes a plain directory: dist/ by default. Any static host or CDN can serve it; there is no server runtime to deploy. This page covers what the host has to know about that directory.

    What the output looks like#

    Source Output
    src/pages/index.tsx dist/index.html
    src/pages/about.tsx dist/about/index.html
    src/pages/guide/intro.mdx dist/guide/intro/index.html, dist/guide/intro.md
    src/pages/feed.xml.ts dist/feed.xml
    src/pages/404.html.tsx dist/404.html
    public/robots.txt dist/robots.txt

    HTML pages use directory indexes, so /about is served by about/index.html. Most hosts resolve this on their own; the server configurations below make it explicit. A route whose name already carries its extension keeps it: this is how 404.html.tsx becomes a flat 404.html.

    Publish only the content of dist/. Every page is rendered and checked before dist/ is touched, and a failed build leaves the previous site in place. Replacing the files is not atomic, though: let the deployment step copy dist/ to the host rather than pointing a web server at it while a build runs.

    A custom 404 page#

    Generate the error page as a regular route, outside the sitemap. The host returns the 404 status; the page only supplies the markup:

    // src/pages/404.html.tsx
    export const meta = { title: "Page not found", sitemap: false };
    
    export default function NotFound() {
      return <h1>Page not found</h1>;
    }
    

    Mirror it in development so ssg dev behaves like the host:

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

    Content types#

    Hosts derive the Content-Type from the file extension. HTML, CSS, JavaScript, JSON and images are known everywhere. Markdown alternates (.md) are not: nginx and Caddy send them as a download unless configured. After a first deployment, check the type of one .md URL:

    curl -sI https://example.com/index.md | grep -i content-type
    

    dev.mimeTypes only affects the development server; production types belong to the host configuration.

    Server configuration#

    Caddy#

    example.com {
        root * /var/www/site
        encode zstd gzip
    
        @markdown path *.md
        header @markdown Content-Type "text/markdown; charset=utf-8"
    
        file_server
    
        handle_errors {
            rewrite * /404.html
            file_server
        }
    }
    

    nginx#

    server {
        server_name example.com;
        root /var/www/site;
    
        types {
            text/markdown md;
        }
        include mime.types;
    
        location / {
            try_files $uri $uri/ =404;
        }
    
        error_page 404 /404.html;
    }
    

    Apache#

    # .htaccess at the document root, e.g. public/.htaccess
    DirectoryIndex index.html
    ErrorDocument 404 /404.html
    AddType "text/markdown; charset=utf-8" .md
    

    Cloudflare Pages#

    Cloudflare Pages serves index.html for directories and 404.html for missing paths without configuration. Deploy the directory with npx wrangler pages deploy dist, or point a Git integration's output directory at dist. Place _headers and _redirects files in public/: they are copied to the output root and honoured.

    GitHub Pages#

    GitHub Pages resolves directory indexes and 404.html too. Deploy with a workflow: the uploaded artifact is served as is, without a Jekyll build.

    # .github/workflows/deploy.yml, in a job with pages: write and id-token: write
    - run: npm run build
    - uses: actions/upload-pages-artifact@v5
      with:
        path: dist
    - uses: actions/deploy-pages@v5
    

    Serving under a base path#

    To publish the site under /docs, keep site for the origin and set base:

    // ssg.config.ts
    import { defineConfig } from "@vincle/ssg";
    
    export default defineConfig({
      site: "https://example.com",
      base: "/docs/",
    });
    

    The sitemap and Vite asset URLs then carry the prefix, in ssg dev as in ssg generate, while the files stay at the root of dist/. Do not repeat the prefix in the Vite configuration: base sets it. Publish dist/ under /docs, and adapt the server configuration: for nginx, a location /docs/ with an alias to the directory; the error page becomes /docs/404.html.

    Caching#

    The output does not carry HTTP headers: set them on the host. Vite's hashed files never change and can be cached for a long time as immutable. HTML and Markdown should be revalidated, so a new deployment shows up immediately. With Cloudflare Pages:

    # public/_headers
    /assets/*
      Cache-Control: public, max-age=31536000, immutable