arroact-umbraco-graphql-sdk

TypeScript SDK for Umbraco GraphQL headless CMS integration.

🚀 Features

• ✅ TypeScript First - Full type safety and IntelliSense support
• ✅ Environment Aware - Different behaviors for dev/staging/production
• ✅ Zero Configuration - Works out of the box with sensible defaults
• ✅ Extensible - Easy to extend with custom queries and models
• ✅ Production Ready - Built with enterprise patterns
• ✅ Tree Shakeable - ESM and CJS builds included

📦 Installation

npm install arroact-umbraco-graphql-sdk graphql

🔧 Usage

Basic Setup

import { HeadlessSDK } from 'arroact-umbraco-graphql-sdk';

const sdk = new HeadlessSDK({
  environment: 'development',
  graphqlUrl: 'https://your-umbraco-site.com/graphql',
  apiKey: 'your-api-key', // optional
  rootContentId: 'root-id', // optional
  enableLogging: true, // optional
  enableCache: false, // optional
});

Fetching Pages

// Get a page by slug
const page = await sdk.getPageBySlug('about-us');

if (page) {
  console.log(page.title);
  console.log(page.content);
  console.log(page.metaTitle);
  console.log(page.metaDescription);
}

Next.js Integration

// lib/sdk.ts
import { HeadlessSDK, Environment } from 'arroact-umbraco-graphql-sdk';

export const sdk = new HeadlessSDK({
  environment: process.env.NEXT_PUBLIC_ENV as Environment,
  graphqlUrl: process.env.GRAPHQL_URL!,
  apiKey: process.env.GRAPHQL_API_KEY,
  enableLogging: process.env.NEXT_PUBLIC_ENV === 'development',
});

// app/[slug]/page.tsx
import { sdk } from '@/lib/sdk';

export default async function Page({ params }: { params: { slug: string } }) {
  const page = await sdk.getPageBySlug(params.slug);
  
  return (
    <div>
      <h1>{page?.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: page?.content || '' }} />
    </div>
  );
}

📖 API Reference

HeadlessSDK

Main SDK class for interacting with Umbraco GraphQL.

Constructor Options

interface SdkConfig {
  environment: 'development' | 'staging' | 'production';
  graphqlUrl: string;
  apiKey?: string;
  rootContentId?: string;
  enableLogging?: boolean;
  enableCache?: boolean;
}

Methods

getPageBySlug(slug: string): Promise<PageModel | null>

Fetches a page by its URL slug.

Returns:

interface PageModel {
  id: string;
  slug: string;
  title: string;
  content: string;
  metaTitle?: string;
  metaDescription?: string;
  publishedDate?: string;
  updatedDate?: string;
}

🏗️ Architecture

The SDK is organized into clean, maintainable layers:

src/
├── client/          # GraphQL client factory
├── types/           # TypeScript type definitions
├── queries/         # GraphQL queries
├── models/          # Data models
├── mappers/         # Data transformation
├── services/        # Business logic
├── core/            # Main SDK class
└── index.ts         # Public exports

🔒 Environment Behavior

Development

• Full logging enabled
• Detailed error messages
• Debug information

Staging

• Partial logging
• Error tracking
• Performance monitoring

Production

• Minimal logging (unless enableLogging: true)
• Error suppression
• Optimized performance

🛠️ Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Watch mode
npm run dev

# Type checking
npm run lint

📦 Build Output

The SDK builds to multiple formats:

• dist/index.js - CommonJS
• dist/index.mjs - ES Modules
• dist/index.d.ts - TypeScript definitions

🧩 Extending the SDK

Adding Custom Queries

// queries/custom.query.ts
import { gql } from 'graphql-request';

export const GET_CUSTOM_DATA = gql`
  query GetCustomData($id: ID!) {
    content(id: $id) {
      # your fields
    }
  }
`;

Adding Custom Services

// services/custom.service.ts
import { GraphQLClient } from 'graphql-request';

export class CustomService {
  constructor(private client: GraphQLClient) {}
  
  async getCustomData(id: string) {
    // implementation
  }
}

📄 License

MIT

🤝 Contributing

Contributions are welcome! Please maintain the existing code structure and style.

📞 Support

For issues and questions, please open a GitHub issue.