graphql-ssg

library0.4.8jsnpmunverified

graphql-ssg (version 0.4.8) is a static site generator (SSG) that specializes in bundling HTML from data feeds, particularly those powered by GraphQL. Unlike many Node.js-based SSGs, it uniquely performs bundling within a browser environment, leveraging native ESModules, URL imports, and import maps. This design choice aligns well with Web Components architectures, allowing for direct use of browser features for content generation. The project is currently in a pre-1.0 development phase, suggesting its API might evolve, but it provides a functional CLI for initializing, watching, and building projects. Key differentiators include its browser-centric bundling, automatic generation of typed GraphQL clients (via the `Chain` helper) based on configured schemas, and secure injection of configuration and environment variables into page-generating functions, preventing secret exposure. It supports both JavaScript and TypeScript page definitions for content creation.

web-framework data serialization

npm install graphql-ssg

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHQL-SSG

graphql-ssg

web-frameworkjavascriptv0.4.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Chain

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

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

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

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

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

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`.

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

✗ import { md } from 'markdown-it';

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.

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

graphql-ssg --version

Debug

Known issues

gotchaAll 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';`.

affects: >=0.1.0

gotchaConfiguration (`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.

affects: >=0.1.0

gotchaThe 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`).

affects: >=0.1.0

breakingAs `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.

affects: <1.0.0

Errors

Common errors & fixes

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

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

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

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.

Upgrade

Version history

0.4.8latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/graphql-editor/graphql-ssg ↗

packagehttps://www.npmjs.com/package/graphql-ssg ↗