@laioutr/app-hygraph

Laioutr app that integrates Hygraph as a headless CMS. Provides a media library for the Laioutr Studio, blog content handlers, and reusable exports for other apps that connect to Hygraph.

Features

Assets

The module registers a Hygraph media library in the Laioutr Studio, giving editors a browsable asset picker backed by their Hygraph project.

The laioutr-integrated @nuxt/image provider is configured to use the Hygraph image CDN.

Exports

Other Laioutr apps that also talk to Hygraph can import the client, middleware, codegen config, and utilities from this package instead of duplicating code or configurationn. See Exports below.

Blog Demo

The module also includes a demo blog implementation with orchestr-handlers for blog content: query handlers and query template providers for blog collections and posts, link handlers for connecting posts to collections, and component resolvers for rendering both.

Configuration

Add the module to your nuxt.config.ts and provide your Hygraph credentials:

export default defineNuxtConfig({
  modules: ['@laioutr/app-hygraph'],
  '@laioutr/app-hygraph': {
    contentApiUrl: 'https://...',
    imageBaseUrl: 'https://...',
    token: '...',
  },
});

| Option | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | contentApiUrl | Hygraph Content API endpoint | | imageBaseUrl | Hygraph image CDN base URL (used by @nuxt/image). Region-specific; find yours by querying { assets(first: 1) { url } } against your Content API and taking the domain + first path-segment, e.g. https://eu-west-2.graphassets.com/cmh4jxx7w1fce07l80dils2d1 | | token | Permanent auth token for the Content API |

Exports

The package exposes three subpath exports for use outside the Nuxt module context.

@laioutr/app-hygraph/runtime

Everything needed to build Hygraph-backed orchestr handlers in another app.

import { defineHygraph, hygraphClientFactory, mapHygraphMedia } from '@laioutr/app-hygraph/runtime';
import type { HygraphAsset, HygraphClientConfig, HygraphResponse } from '@laioutr/app-hygraph/runtime';

| Export | Purpose | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | defineHygraph | Pre-configured orchestr builder with Hygraph metadata and a context.hygraph client. Chain .queryHandler(), .linkHandler(), etc. directly on it. | | hygraphClientFactory(config?) | Creates a Hygraph GraphQL client. Falls back to useRuntimeConfig() when called without arguments inside the Nuxt module. Pass a HygraphClientConfig to use it standalone. | | mapHygraphMedia(asset) | Converts a HygraphAsset to a Laioutr MediaImage, selecting the correct Nuxt Image provider (handles SVGs). |

@laioutr/app-hygraph/codegen

Generates TypeScript types from your Hygraph schema using GraphQL Code Generator. The factory produces a codegen config with Hygraph-specific scalar mappings (DateTime, RichTextAST, Json, Long, Hex, etc.) so you don't have to define them yourself.

Install the peer dependencies:

pnpm add -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations graphql

Create a codegen.ts at your project root:

import { defineHygraphCodegen } from '@laioutr/app-hygraph/codegen';

export default defineHygraphCodegen({
  documents: 'src/runtime/server/queries/**/*.ts',
  outputPath: 'src/runtime/server/generated/graphql.ts',
});

Set HYGRAPH_CONTENT_API_URL and HYGRAPH_TOKEN in your environment, then run:

npx graphql-codegen

This reads your .ts files containing tagged /* GraphQL */ template literals, introspects the Hygraph schema, and writes the generated types to outputPath.

| Option | Default | | ------------ | ------------------------------------------------------------------------------------- | | schemaUrl | process.env.HYGRAPH_CONTENT_API_URL | | token | process.env.HYGRAPH_TOKEN | | documents | src/runtime/server/queries/**/*.ts | | outputPath | src/runtime/server/generated/graphql.ts | | scalars | Hygraph defaults (DateTime, RichTextAST, Json, etc.) merged with your overrides |

@laioutr/app-hygraph/queries

Reusable GraphQL fragments.

import { AssetFragment } from '@laioutr/app-hygraph/queries';

const MY_QUERY = /* GraphQL */ `
  ${AssetFragment}
  query MyQuery {
    assets {
      ...Asset
    }
  }
`;

Development

# 1. Copy .npmrc.config to .npmrc and fill in NPM_LAIOUTR_TOKEN
# 2. Install dependencies
pnpm install

# 3. Fetch remote project config
npx @laioutr/cli rc fetch -p <org-slug>/<project-slug> -s <secret-key>

# 4. Prepare and start
export HYGRAPH_CONTENT_API_URL=<your-content-api-url>
export HYGRAPH_TOKEN=<your-token>
export HYGRAPH_IMAGE_BASE_URL=<your-image-base-url>
pnpm dev

Publishing

pnpm release

Runs lint, tests, builds, updates the changelog, publishes to npm, and pushes tags.

For private publishing to npm.laioutr.cloud, add "publishConfig": { "registry": "https://npm.laioutr.cloud/" } to package.json and ensure your package name follows the @laioutr-org/<org-slug>_<name> format.