@lastshotlabs/slingshot-ssg

npm install @lastshotlabs/slingshot-ssg

Functions

collectSsgRoutes

Scans the server routes directory for files that are candidates for static site generation, then returns the full list of URL paths to pre-render.

Detection strategy (in order):

1. If the route file source contains export async function staticPaths or export function staticPaths, the file is a dynamic SSG route. staticPaths() is called to enumerate all parameter combinations and each combination is expanded into a concrete URL path.
2. If the route file source contains a top-level export.*revalidate.*false pattern (static route, no dynamic segments required), the route URL itself is returned directly.

Source-level detection avoids executing untrusted modules at discovery time. The actual staticPaths() function is called via import() only for files that passed the source check, limiting the execution surface.

async function collectSsgRoutes(config: SsgConfig): Promise<string[]>

Source: packages/slingshot-ssg/src/crawler.ts

parseSsgConfig

Validate and parse a raw SSG config object.

Replaces an unchecked rawConfig as SsgConfig cast with schema-enforced validation. Throws a formatted error listing all issues on failure.

function parseSsgConfig(rawConfig: unknown): SsgConfig

Source: packages/slingshot-ssg/src/config.schema.ts

renderSsgPage

Render a single URL path to a static HTML file.

Preferred path: resolves the full file-based route chain via resolveRouteChain() and renders with renderer.renderChain(), faithfully reproducing the SSR pipeline (layouts, slots, interception, middleware).

Fallback path: when no file-based chain is found (e.g. custom renderer with manifest-driven routing), falls back to renderer.resolve() + render().

The rendered HTML is written to config.outDir/{path}/index.html. When the renderer returns a non-200 response (redirect, 404, etc.) the page is skipped and a warning is logged. SsgPageResult.error will be set.

Transient failures (timeout, renderer throws) are retried automatically according to config.retry.

async function renderSsgPage(urlPath: string, renderer: SlingshotSsrRenderer, config: SsgConfig, assetTagsHtml: string = '',): Promise<SsgPageResult>

Source: packages/slingshot-ssg/src/renderer.ts

renderSsgPages

Run renderSsgPage for a list of URL paths with a concurrency limit.

Pages are processed in parallel up to config.concurrency at a time. Individual page failures do not abort the batch — they are recorded in the returned SsgResult.

When config.circuitBreaker is set, a single circuit breaker is created for the entire run and shared across all pages. If the breaker trips (too many consecutive failures), subsequent pages fail fast without invoking the renderer, protecting upstream services from being hammered.

async function renderSsgPages(paths: readonly string[], renderer: SlingshotSsrRenderer, config: SsgConfig, assetTagsHtml: string = '',): Promise<SsgResult>

Source: packages/slingshot-ssg/src/renderer.ts

resolveExitCode

Resolve the exit code for a completed SSG run.

function resolveExitCode(succeeded: number, failed: number): SsgExitCode; export function resolveExitCode(result:

Source: packages/slingshot-ssg/src/cli.ts

Constants

ssgConfigSchema

Zod schema for SsgConfig.

Validates at the public API boundary before any filesystem operations begin. Unknown keys are stripped (Zod default) and a warning is emitted by validatePluginConfig for each unrecognised field.

Config Fields

Field	Description
circuitBreaker	Circuit breaker configuration for external HTTP fetches during rendering.
retry	Retry configuration for transient render failures.

Source: packages/slingshot-ssg/src/config.schema.ts

Classes

SsgCliArgError

Raised when an SSG CLI argument fails validation.

Source: packages/slingshot-ssg/src/errors.ts

SsgConfigError

Raised when SSG configuration is invalid or incomplete.

Source: packages/slingshot-ssg/src/errors.ts

SsgCrawlError

Raised when the SSG crawler cannot discover or normalize routes.

Source: packages/slingshot-ssg/src/errors.ts

SsgError

Errors thrown by the SSG package.

Source: packages/slingshot-ssg/src/errors.ts

SsgRenderError

Raised when static rendering fails for a specific URL.

Source: packages/slingshot-ssg/src/errors.ts

Interfaces

CircuitBreakerConfig

Circuit breaker configuration for external HTTP fetches during rendering.

When the circuit breaker trips (consecutive failures reach threshold), subsequent render attempts fail fast without invoking the renderer, allowing the build to avoid hammering a degraded upstream service. After cooldownMs, the breaker transitions to half-open and allows a single probe request.

Source: packages/slingshot-ssg/src/types.ts

RetryConfig

Retry configuration for transient render failures.

When a page render fails with a transient error (timeout, renderer throws), the SSG renderer retries up to maxAttempts times with exponential backoff and jitter before recording the page as failed.

Source: packages/slingshot-ssg/src/types.ts

SsgConfig

Configuration for the SSG crawler and renderer.

All paths must be absolute. Relative paths will produce incorrect output.

Source: packages/slingshot-ssg/src/types.ts

SsgPageError

P-SSG-5: serializable per-page error placeholder included in SsgPageResult so the build summary lists each failure with structured fields rather than just emitting them as console.error lines. Consumers (CI dashboards, automated PR comments) can iterate result.pages and route the failures without scraping stderr.

Source: packages/slingshot-ssg/src/types.ts

SsgPageResult

Result for a single pre-rendered page.

Source: packages/slingshot-ssg/src/types.ts

SsgResult

Aggregate result for a full SSG run.

Source: packages/slingshot-ssg/src/types.ts

Types

SsgConfigParsed

Parsed and validated SSG configuration produced by ssgConfigSchema.

Source: packages/slingshot-ssg/src/config.schema.ts

SsgExitCode

Tri-state exit codes for slingshot ssg (P-SSG-2).

Replaces the previous binary 0/1 model so CI can distinguish a run where one route blew up from a run where every route failed (or the build itself crashed). Concretely:

• 0 — every page rendered successfully (or there was nothing to do).
• 1 — total failure: the build crashed, every page failed, or the run never produced any successful output (succeeded === 0 && failed > 0).
• 2 — partial failure: at least one page failed and at least one page succeeded. The build proceeded; CI should treat this as a degraded state so consumers know which pages are stale.

Source: packages/slingshot-ssg/src/cli.ts

SsgStaticPathsFn

Exported from dynamic route files to enumerate all static paths. Required when load() returns revalidate: false on a dynamic route. Called during slingshot ssg — inject a DB context via globalThis.__ssgDb before calling this from the SSG crawler.

Source: packages/slingshot-ssr/src/types.ts