GraphQL SSG

Common errors

• Error: No default export found in file: {path-to-file}

  cause A page file (e.g., `pages/my-page.ts`) does not contain an `export default` statement.
  fix Add an `export default` statement to your page file, which should return the HTML content or a function that returns it, e.g., `export default () => html`.

• Cannot read properties of undefined (reading 'config')` or `ssg is not defined

  cause Attempting to access `ssg.config` or `ssg.env` outside of the `export default` or `export const head` functions within a page file.
  fix Move the code accessing `ssg.config` or `ssg.env` directly into the `export default` or `export const head` function to leverage the injected context.

• ReferenceError: Chain is not defined` or `Cannot find module '../ssg/{schema-name}/index.js

  cause Incorrect import path for the generated `Chain` client, `html` helper, or `md` helper, or a GraphQL schema name mismatch in `graphql-ssg.json`.
  fix Verify the relative import path (`../ssg/...`) matches the expected generated helper location based on your project structure and the schema name in your `graphql-ssg.json` file.

Warnings

• gotcha All page files (`.js`, `.ts`) *must* include an `export default` function or string to define the page content, otherwise they will not be processed correctly by the SSG. This is the primary mechanism for content generation.
  Fix: Ensure your page files (e.g., `./pages/index.ts`) contain `export default () => html` or `export default 'Hello world';`.
• gotcha Configuration (`ssg.config`) and environment variables (`ssg.env`) are strictly injected and accessible *only* within `export default` and `export const head` functions of your page files. Attempting to access them outside these contexts will result in `undefined` or runtime errors, designed to prevent secret leakage.
  Fix: Place any logic requiring `ssg.config` or `ssg.env` directly inside the `export default` function or an `export const head` function in your page files.
• gotcha The library is primarily designed for global installation (`npm i -g graphql-ssg`) as a CLI tool. While local installation is technically possible, typical usage and commands assume global availability.
  Fix: Install globally for convenient command-line access or ensure your `package.json` scripts correctly reference the local binary (e.g., `./node_modules/.bin/graphql-ssg`).
• breaking As `graphql-ssg` is in a pre-1.0 version (currently 0.4.8), its API and internal mechanics may undergo breaking changes in minor or patch releases without explicit major version increments. Users should pin exact versions for production and review changelogs for updates.
  Fix: Pin `graphql-ssg` to an exact version (e.g., `0.4.8`) in your `package.json` to prevent unexpected breaking changes during updates, and review release notes carefully before upgrading.

Install

• npm install graphql-ssg npm
• yarn add graphql-ssg yarn
• pnpm add graphql-ssg pnpm

Imports

• Chain
  wrong:

  const Chain = require('graphql-ssg/Chain');

  correct:

  import { Chain } from '../ssg/{schema-name}/index.js'

  Used to create a typed GraphQL client. The path is relative to your page file and depends on the name of your GraphQL schema defined in `graphql-ssg.json` (e.g., `../ssg/my-pokemon-schema/index.js`). This library is ESModules-only.
• html
  wrong:

  const html = require('lit-html').html;

  correct:

  import { html } from '../ssg/basic.js'

  A tagged template literal function that provides HTML syntax highlighting in IDEs, but does not transform the HTML. It's provided by `graphql-ssg` itself via a generated helper file, not `lit-html`.
• md
  wrong:

  import { md } from 'markdown-it';

  correct:

  import { md } from '../ssg/md.js'

  A tagged template literal function that processes Markdown using a `remarkable` renderer and converts it to HTML. Similar to `html`, it's provided by `graphql-ssg` via a generated helper file.

Quickstart

This quickstart demonstrates how to install `graphql-ssg` globally, initialize a project, configure a GraphQL schema, create a TypeScript page that fetches data using the generated `Chain` client, and then build the static HTML output.

// Install globally: npm i -g graphql-ssg
// Initialize project: graphql-ssg --init .
// Configure graphql-ssg.json with a 'pokemon' schema pointing to 'https://graphql-pokemon2.vercel.app/'

// ./pages/index.ts
import { html } from '../ssg/basic.js';
import { Chain } from '../ssg/pokemon/index.js'; // Path generated based on 'pokemon' schema name

export default async () => {
  // ssg.config is injected and only available within export default/head
  const graphQLClient = Chain(ssg.config.graphql.pokemon.url);
  const response = await graphQLClient.query({
    pokemon: [{ name: 'Pikachu' }, {
      id: true,
      name: true,
      number: true,
      types: true,
    }],
  });

  const pikachu = response.pokemon;

  return html`
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Pokemon SSG</title>
    </head>
    <body>
        <h1>Hello, ${pikachu?.name || 'World'}!</h1>
        <p>Number: ${pikachu?.number}</p>
        <p>Types: ${pikachu?.types?.join(', ') || 'N/A'}</p>
    </body>
    </html>
  `;
};

// To build your site: graphql-ssg --build
// To watch for changes: graphql-ssg