@laioutr/app-hygraph 1.2.0 → 1.4.0

package/README.md

@@ -1,13 +1,4 @@
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: Hygraph Laioutr
-- Package name: @laioutr/app-hygraph
-- Description: Laioutr Hygraph App
--->
-
-# Hygraph Laioutr
+# @laioutr/app-hygraph
 
 [![Laioutr][laioutr-src]][laioutr-href]
 [![npm version][npm-version-src]][npm-version-href]
@@ -15,61 +6,143 @@ Find and replace all on all files (CMD+SHIFT+F):
 [![License][license-src]][license-href]
 [![Nuxt][nuxt-src]][nuxt-href]
 
-My new [Laioutr](https://laioutr.com) App for doing amazing things using Nuxt.
+Laioutr app that integrates [Hygraph](https://hygraph.com) 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.
 
-See [laioutr.com](https://laioutr.com) for more information about Laioutr.
+## Features
 
-- [✨ &nbsp;Release Notes](/CHANGELOG.md)
-  <!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/@laioutr/app-hygraph?file=playground%2Fapp.vue) -->
-  <!-- - [📖 &nbsp;Documentation](https://example.com) -->
+### Assets
 
-## Features
+The module registers a Hygraph media library in the Laioutr Studio, giving editors a browsable asset picker backed by their Hygraph project.
 
-<!-- Highlight some of the features your module provide here -->
+The laioutr-integrated @nuxt/image provider is configured to use the Hygraph image CDN.
 
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
+### Exports
 
-## Quick Setup
+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](#exports) below.
 
-Before installing dependencies, you need to create a copy of the `.npmrc.config` file called `.npmrc` and fill in the `NPM_LAIOUTR_TOKEN` with your npm token. You can find this token in your [project settings](https://cockpit.laioutr.cloud/o/_/p/_/settings).
+### Blog Demo
 
-- `pnpm i`
-- `npx @laioutr/cli project fetch-rc -p <organization slug>/<project slug> -s <project secret key>` - This will load the `laioutrrc.json` file with the current remote project configuration.
-- `pnpm dev:prepare`
-- `pnpm orchestr-dev`
+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.
 
-That's it! You can now use Hygraph Laioutr in your [Laioutr Frontend](https://laioutr.com) ✨
+## Configuration
 
-You can find a thorough guide on getting started with Laioutr development in our [developer guide](https://docs.laioutr.io/developer-guide/setup).
+Add the module to your `nuxt.config.ts` and provide your Hygraph credentials:
 
-## Linting and Formatting
+```ts
+export default defineNuxtConfig({
+  modules: ['@laioutr/app-hygraph'],
+  '@laioutr/app-hygraph': {
+    contentApiUrl: 'https://...',
+    imageBaseUrl: 'https://...',
+    token: '...',
+  },
+});
+```
 
-We use ESLint and Prettier to lint and format the code. This repository contains opinionated configurations for both tools. You can - of course - replace them with your own configurations.
+| 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. |
+| `token`         | Permanent auth token for the Content API                                                                                                                                   |
 
-## Publishing
+## 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.
+
+```ts
+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:
 
-To publish a new version, run `pnpm release`. This will:
+```bash
+pnpm add -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations graphql
+```
 
-- Run the tests
-- Update the changelog
-- Publish the package to npmjs.org
-- Push the changes to the repository
+Create a `codegen.ts` at your project root:
 
-### Private publishing
+```ts
+import { defineHygraphCodegen } from '@laioutr/app-hygraph/codegen';
 
-If you want to publish a private package to npm.laioutr.cloud, you need to:
+export default defineHygraphCodegen({
+  documents: 'src/runtime/server/queries/**/*.ts',
+  outputPath: 'src/runtime/server/generated/graphql.ts',
+});
+```
 
-1. Make sure you have a `.npmrc` with your private npm registry token.
-2. Add this line to the root of the `package.json` file: `"publishConfig": { "registry": "https://npm.laioutr.cloud/" }`
-3. Make sure your package-name follows the `@laioutr-org/<organization-slug>_<package-name>` format.
+Set `HYGRAPH_CONTENT_API_URL` and `HYGRAPH_TOKEN` in your environment, then run:
+
+```bash
+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.
+
+```ts
+import { AssetFragment } from '@laioutr/app-hygraph/queries';
+
+const MY_QUERY = /* GraphQL */ `
+  ${AssetFragment}
+  query MyQuery {
+    assets {
+      ...Asset
+    }
+  }
+`;
+```
+
+## Development
+
+```bash
+# 1. Copy .npmrc.config to .npmrc and fill in NPM_LAIOUTR_TOKEN
+# 2. Install dependencies
+pnpm i
+
+# 3. Fetch remote project config
+npx @laioutr/cli rc fetch -p <org-slug>/<project-slug> -s <secret-key>
+
+# 4. Prepare and start
+pnpm dev:prepare
+pnpm dev              # playground
+pnpm orchestr-dev     # orchestr playground
+```
+
+## Publishing
 
-After that you can run `pnpm release` to publish the package to npm.laioutr.cloud.
+```bash
+pnpm release
+```
 
-## Contribution
+Runs lint, tests, builds, updates the changelog, publishes to npm, and pushes tags.
 
-Follow the [setup guide](https://docs.laioutr.io/developer-guide/setup) to get started.
+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.
 
 <!-- Badges -->
 

package/dist/codegen/index.d.mts

@@ -0,0 +1,18 @@
+import { CodegenConfig } from '@graphql-codegen/cli';
+
+interface HygraphCodegenOptions {
+    /** Hygraph Content API endpoint URL. Defaults to process.env.HYGRAPH_CONTENT_API_URL */
+    schemaUrl?: string;
+    /** Hygraph API token. Defaults to process.env.HYGRAPH_TOKEN */
+    token?: string;
+    /** Glob pattern for GraphQL document files. Defaults to 'src/runtime/server/queries/**\/*.ts' */
+    documents?: string;
+    /** Output file path for generated types. Defaults to 'src/runtime/server/generated/graphql.ts' */
+    outputPath?: string;
+    /** Additional custom scalar mappings (merged with Hygraph defaults) */
+    scalars?: Record<string, string>;
+}
+declare const defineHygraphCodegen: (options?: HygraphCodegenOptions) => CodegenConfig;
+
+export { defineHygraphCodegen };
+export type { HygraphCodegenOptions };

package/dist/codegen/index.mjs

@@ -0,0 +1,41 @@
+const DEFAULT_SCALARS = {
+  DateTime: "string",
+  Date: "string",
+  Json: "Record<string, unknown>",
+  Long: "number",
+  RichTextAST: "Record<string, unknown>",
+  Hex: "string",
+  RGBAHue: "string",
+  RGBATransparency: "number"
+};
+const defineHygraphCodegen = (options = {}) => {
+  const schemaUrl = options.schemaUrl ?? process.env.HYGRAPH_CONTENT_API_URL;
+  const token = options.token ?? process.env.HYGRAPH_TOKEN;
+  const documents = options.documents ?? "src/runtime/server/queries/**/*.ts";
+  const outputPath = options.outputPath ?? "src/runtime/server/generated/graphql.ts";
+  return {
+    overwrite: true,
+    schema: [
+      {
+        [schemaUrl]: {
+          headers: {
+            Authorization: `Bearer ${token}`
+          }
+        }
+      }
+    ],
+    documents,
+    generates: {
+      [outputPath]: {
+        plugins: ["typescript", "typescript-operations"],
+        config: {
+          skipTypename: true,
+          maybeValue: "T | null",
+          scalars: { ...DEFAULT_SCALARS, ...options.scalars }
+        }
+      }
+    }
+  };
+};
+
+export { defineHygraphCodegen };

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@laioutr/app-hygraph",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "configKey": "@laioutr/app-hygraph",
   "builder": {
     "@nuxt/module-builder": "1.0.1",

package/dist/module.mjs

@@ -3,7 +3,7 @@ import { defu } from 'defu';
 import { registerLaioutrApp } from '@laioutr-core/kit';
 
 const name = "@laioutr/app-hygraph";
-const version = "1.2.0";
+const version = "1.4.0";
 
 const module = defineNuxtModule({
   meta: {

package/dist/queries/index.d.mts

@@ -0,0 +1 @@
+export { AssetFragment } from '../../dist/runtime/server/queries/asset.js';

package/dist/queries/index.mjs

@@ -0,0 +1 @@
+export { AssetFragment } from '../../dist/runtime/server/queries/asset.js';

package/dist/runtime/index.d.ts

@@ -0,0 +1,4 @@
+export { hygraphClientFactory } from './server/client/hygraph.js';
+export { defineHygraph } from './server/middleware/defineHygraph.js';
+export { mapHygraphMedia, filenameToAlt, stripFileExtension } from './server/hygraph-utils/mediaMapper.js';
+export type { HygraphAsset, HygraphClientConfig, HygraphResponse } from './server/types/hygraph.js';

package/dist/runtime/index.js

@@ -0,0 +1,3 @@
+export { hygraphClientFactory } from "./server/client/hygraph.js";
+export { defineHygraph } from "./server/middleware/defineHygraph.js";
+export { mapHygraphMedia, filenameToAlt, stripFileExtension } from "./server/hygraph-utils/mediaMapper.js";

package/dist/runtime/server/client/hygraph.d.ts

@@ -1,9 +1,5 @@
-export interface HygraphResponse<TData> {
-    data: TData;
-    errors?: Array<{
-        message: string;
-    }>;
-}
-export declare const hygraphClientFactory: () => {
+import type { HygraphClientConfig, HygraphResponse } from '../types/hygraph.js';
+export type { HygraphResponse };
+export declare const hygraphClientFactory: (explicitConfig?: HygraphClientConfig) => {
     request: <TData = unknown>(query: string, variables?: unknown) => Promise<HygraphResponse<TData>>;
 };

package/dist/runtime/server/client/hygraph.js

@@ -1,6 +1,6 @@
 import { useRuntimeConfig } from "#imports";
-export const hygraphClientFactory = () => {
-  const config = useRuntimeConfig()["@laioutr/app-hygraph"];
+export const hygraphClientFactory = (explicitConfig) => {
+  const config = explicitConfig ?? useRuntimeConfig()["@laioutr/app-hygraph"];
   const request = async (query, variables = null) => {
     const res = await fetch(config.contentApiUrl, {
       method: "POST",

package/dist/runtime/server/hygraph-utils/mediaMapper.d.ts

@@ -1,6 +1,10 @@
 import { MediaImage } from '@laioutr-core/core-types/common';
-import type { AssetFragment } from '../generated/graphql.js';
+import type { HygraphAsset } from '../types/hygraph.js';
+/** Remove the file extension from a file name. */
+export declare const stripFileExtension: (fileName: string) => string;
+/** Convert a file name to a readable alt text. */
+export declare const filenameToAlt: (fileName: string) => string;
 /**
  * Map a Hygraph asset to a Media object.
  */
-export declare const mapHygraphMedia: (asset: AssetFragment) => MediaImage;
+export declare const mapHygraphMedia: (asset: HygraphAsset) => MediaImage;

package/dist/runtime/server/hygraph-utils/mediaMapper.js

@@ -1,5 +1,5 @@
-const stripFileExtension = (fileName) => fileName.replace(/\.[^.]+$/, "");
-const filenameToAlt = (fileName) => stripFileExtension(fileName).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").replace(/^\w/, (c) => c.toUpperCase()).trim();
+export const stripFileExtension = (fileName) => fileName.replace(/\.[^.]+$/, "");
+export const filenameToAlt = (fileName) => stripFileExtension(fileName).replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[-_]+/g, " ").replace(/^\w/, (c) => c.toUpperCase()).trim();
 export const mapHygraphMedia = (asset) => ({
   type: "image",
   sources: [

package/dist/runtime/server/middleware/defineHygraph.d.ts

@@ -1 +1,11 @@
-export declare const defineHygraph: any;
+export declare const defineHygraph: import("@laioutr-core/orchestr/types").OrchestrBuilder<import("@laioutr-core/orchestr/types").ArgsWithMiddleware<import("@laioutr-core/orchestr/types").ArgsWithMeta<import("@laioutr-core/orchestr/types").OrchestrArgsBase<Record<string, any> | undefined>, {
+    app: string;
+    logoUrl: string;
+    label: string;
+}>, {
+    context: {
+        hygraph: {
+            request: <TData = unknown>(query: string, variables?: unknown) => Promise<import("../../index.js").HygraphResponse<TData>>;
+        };
+    };
+}>>;

package/dist/runtime/server/middleware/defineHygraph.js

@@ -1,5 +1,7 @@
 import { defineOrchestr } from "#imports";
 import { hygraphClientFactory } from "../client/hygraph.js";
 export const defineHygraph = defineOrchestr.meta({
-  app: "@laioutr/app-hygraph"
-}).use(async (ctx, next) => next({ context: { hygraph: hygraphClientFactory() } }));
+  app: "@laioutr/app-hygraph",
+  logoUrl: "/app-hygraph/logo.svg",
+  label: "Hygraph"
+}).extendRequest(async () => ({ context: { hygraph: hygraphClientFactory() } }));

package/dist/runtime/server/orchestr/blog/blogCollection.resolver.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/orchestr/blog/blogCollectionBySlug.query.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/orchestr/blog/blogCollectionBySlug.template.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/orchestr/blog/blogCollectionPosts.link.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/orchestr/blog/blogPost.resolver.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/orchestr/blog/blogPostBySlug.query.d.ts

@@ -1,2 +1,2 @@
-declare const _default: any;
+declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/runtime/server/types/hygraph.d.ts

@@ -0,0 +1,18 @@
+export interface HygraphAsset {
+    url: string;
+    fileName: string;
+    mimeType?: string | null;
+    width?: number | null;
+    height?: number | null;
+    handle: string;
+}
+export interface HygraphClientConfig {
+    contentApiUrl: string;
+    token: string;
+}
+export interface HygraphResponse<TData> {
+    data: TData;
+    errors?: Array<{
+        message: string;
+    }>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laioutr/app-hygraph",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Laioutr Hygraph App",
   "repository": "your-org/@laioutr/app-hygraph",
   "license": "MIT",
@@ -9,6 +9,18 @@
     ".": {
       "types": "./dist/types.d.mts",
       "import": "./dist/module.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen/index.d.mts",
+      "import": "./dist/codegen/index.mjs"
+    },
+    "./queries": {
+      "types": "./dist/queries/index.d.mts",
+      "import": "./dist/queries/index.mjs"
     }
   },
   "main": "./dist/module.mjs",
@@ -16,35 +28,31 @@
     "*": {
       ".": [
         "./dist/types.d.mts"
+      ],
+      "runtime": [
+        "./dist/runtime/index.d.ts"
+      ],
+      "codegen": [
+        "./dist/codegen/index.d.mts"
+      ],
+      "queries": [
+        "./dist/queries/index.d.mts"
       ]
     }
   },
   "files": [
     "dist"
   ],
-  "scripts": {
-    "dev": "npm run dev:prepare && nuxi dev playground",
-    "dev:build": "nuxi build playground",
-    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
-    "lint": "eslint .",
-    "orchestr-dev": "npm run orchestr-dev:prepare && nuxi dev orchestr-playground",
-    "orchestr-dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare orchestr-playground",
-    "prepack": "nuxt-module-build build",
-    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish --access public && git push --follow-tags",
-    "test": "vitest run",
-    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
-    "test:watch": "vitest watch"
-  },
   "dependencies": {
     "@nuxt/kit": "3.16.2",
     "zod": "3.25.61"
   },
   "devDependencies": {
+    "@graphql-codegen/cli": "^6.2.1",
+    "@graphql-codegen/typescript": "^5.0.9",
+    "@graphql-codegen/typescript-operations": "^5.0.9",
+    "@laioutr-app/ui": "^1.32.2",
     "@laioutr-core/orchestr-devtools": "^1.6.21",
-    "@pinia/colada": "0.17.1",
-    "@pinia/colada-nuxt": "0.2.1",
-    "@vueuse/core": "13.1.0",
-    "pinia": "3.0.2",
     "@laioutr/eslint-config": "^1.8.8",
     "@laioutr/prettier-config": "^1.1.0",
     "@nuxt/devtools": "^2.6.3",
@@ -52,27 +60,49 @@
     "@nuxt/module-builder": "1.0.1",
     "@nuxt/schema": "3.16.2",
     "@nuxt/test-utils": "3.19.1",
+    "@pinia/colada": "0.17.1",
+    "@pinia/colada-nuxt": "0.2.1",
     "@types/node": "latest",
+    "@vueuse/core": "13.1.0",
     "changelogen": "^0.6.2",
     "eslint": "^9.35.0",
+    "graphql": "^16.13.1",
     "nuxt": "3.16.2",
+    "pinia": "3.0.2",
     "typescript": "5.9.2",
     "vitest": "3.1.1",
-    "vue-tsc": "2.2.10",
-    "@graphql-codegen/cli": "^6.2.1",
-    "@graphql-codegen/typescript": "^5.0.9",
-    "@graphql-codegen/typescript-operations": "^5.0.9",
-    "graphql": "^16.13.1",
-    "@laioutr-app/ui": "^1.32.2"
+    "vue-tsc": "2.2.10"
   },
   "peerDependencies": {
+    "@graphql-codegen/cli": "^6.0.0",
     "@laioutr-core/canonical-types": ">=0.22.13",
-    "@laioutr-core/core-types": ">=0.28.8",
-    "@laioutr-core/frontend-core": ">=0.28.8",
-    "@laioutr-core/kit": ">=0.28.8"
+    "@laioutr-core/core-types": ">=0.28.11",
+    "@laioutr-core/frontend-core": ">=0.28.11",
+    "@laioutr-core/kit": ">=0.28.11",
+    "graphql": "^16.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@graphql-codegen/cli": {
+      "optional": true
+    },
+    "graphql": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.12.0",
     "pnpm": ">=10.15.0"
+  },
+  "scripts": {
+    "dev": "npm run dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "lint": "eslint .",
+    "orchestr-dev": "npm run orchestr-dev:prepare && nuxi dev orchestr-playground",
+    "orchestr-dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare orchestr-playground",
+    "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish --access public && git push --follow-tags",
+    "test": "vitest run",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
+    "test:watch": "vitest watch"
   }
-}
+}