What is the Hygraph Management SDK and what can I do with it?

The Hygraph Management SDK is a JavaScript/TypeScript library that allows you to programmatically manage your Hygraph project schema and content models. With the SDK, you can create and update models, fields (simple, relational, union, component), and components, as well as automate schema migrations and batch operations. This enables developers to efficiently manage complex content structures and automate repetitive tasks in Hygraph projects. Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

What are the main steps to use the Management SDK in a Hygraph project?

To use the Management SDK, you need to: 1. Enable API access by obtaining an authentication token and endpoint from your Hygraph project's settings. 2. Initialize the SDK client with your authToken and endpoint. 3. Create models (e.g., Page, Author, Book) using createModel. 4. Add fields to models, including simple fields (string, integer, slug, rich text), relational fields (asset, m-1, m-n), union fields, and component fields. 5. Optionally, update or remove fields and components as needed. For detailed code examples, see the step-by-step example: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example.

How do I obtain the authentication token and endpoint required for the Management SDK?

To obtain the authentication token (authToken), go to your Hygraph project, navigate to Project Settings > Permanent Auth Tokens > Token, and create or copy a token with the necessary management permissions. For the endpoint (endpoint), go to Project Settings > Endpoints > High Performance Content API and copy the endpoint URL for the environment you wish to interact with. Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

What types of fields and relationships can I create with the Management SDK?

The Management SDK supports creating various field types, including: Simple fields: string, integer, slug, rich text, date/time, etc. Relational fields: asset fields, one-to-many (m-1), many-to-many (m-n) relationships. Union fields: fields that can reference multiple models. Component fields: reusable components with their own fields. Component union fields: fields that can reference multiple component types. It also supports field validations (e.g., regex for emails, range for integers), visibility settings, and embedding models in rich text fields. Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

What programming languages are supported by the Hygraph Management SDK?

The Hygraph Management SDK is designed for use with JavaScript and TypeScript, making it suitable for Node.js and modern web development environments. Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

How easy is it to get started with the Management SDK?

Getting started with the Management SDK is straightforward. You can install the SDK via npm, obtain your authentication token and endpoint from your Hygraph project settings, and follow the step-by-step example provided in the documentation. The SDK is designed to be intuitive for developers familiar with JavaScript/TypeScript. Source: https://hygraph.com/docs/api-reference/management-sdk/management-sdk-example

How long does it take to implement Hygraph and start using the Management SDK?

The implementation time for Hygraph can vary based on project complexity. For example, Top Villas launched a new project within 2 months from the initial touchpoint, and Si Vale met aggressive deadlines during their initial implementation. The Management SDK enables rapid schema setup and automation, further accelerating onboarding. Source: https://hygraph.com/case-studies/top-villas-case-study#why-hygraph, https://hygraph.com/case-studies/si-vale-case-study

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified for its hosting infrastructure, and GDPR compliant. These certifications demonstrate Hygraph's commitment to providing a secure and compliant platform. Source: https://hygraph.com/features/secure

What security features are available in Hygraph?

Hygraph offers granular permissions, SSO integrations, audit logs, encryption at rest and in transit, regular data backups, and enterprise-grade compliance features. Customers can also access a security and compliance report for certified infrastructure. Source: https://hygraph.com/features/secure

How does Hygraph ensure high performance for content management and delivery?

Hygraph delivers exceptional performance through features like Smart Edge Cache for faster content delivery, high-performance endpoints, and continuous improvements to its GraphQL API. These features are designed to support high-traffic, global audiences and provide practical advice for developers to optimize API usage. Source: https://hygraph.com/blog/improvements-to-high-performance-endpoint

What support options are available for developers using the Management SDK?

Hygraph provides 24/7 support via chat, email, and phone, as well as real-time troubleshooting through Intercom chat. Developers can also access extensive documentation, community Slack channels, webinars, live streams, and how-to videos. Enterprise customers receive a dedicated Customer Success Manager and structured onboarding. Source: https://hygraph.com/docs, https://hygraph.com/pricing, https://hygraph.com/enterprise-headless-cms

How does Hygraph handle maintenance, upgrades, and troubleshooting?

Hygraph is a cloud-based platform, so all deployment, updates, and infrastructure maintenance are managed by Hygraph. Upgrades, such as new features and SDK improvements, are seamlessly integrated. Troubleshooting is supported by 24/7 support, extensive documentation, and real-time chat. Source: manual

What does it cost to use Hygraph and the Management SDK?

Hygraph offers a Free Forever Developer Account for developers to explore and build projects at no cost. Self-service plans start at $299/month (or $199/month billed annually), and custom enterprise pricing starts at $900/month. Plans include 1,000 entries, with add-ons available for additional entries and locales. For more details, visit the Hygraph Pricing Page: https://hygraph.com/pricing.

Who can benefit from using Hygraph and the Management SDK?

Hygraph and its Management SDK are ideal for developers, product managers, and marketing teams in industries such as ecommerce, automotive, technology, food and beverage, manufacturing, transportation, staffing, and science. Organizations looking to modernize legacy tech stacks, streamline content operations, and scale globally will benefit most. Source: ICPVersion2_Hailey.pdf, https://hygraph.com/case-studies

What are some real-world examples of companies using Hygraph successfully?

Notable companies using Hygraph include: Komax: Achieved 3x faster time to market by managing 20,000+ product variations across 40+ markets. Samsung: Improved customer engagement by 15% with a scalable, composable member platform. Stobag: Increased online revenue share from 15% to 70% after digital transformation. AutoWeb: Saw a 20% increase in website monetization. For more, visit the Hygraph Case Studies Page: https://hygraph.com/case-studies.

How do customers rate the ease of use of Hygraph?

Customers frequently praise Hygraph's intuitive user interface, making it easy for both technical and non-technical users. Hygraph was recognized for 'Best Usability' in Summer 2023, and users highlight its flexibility and accessibility. Source: https://hygraph.com/try-headless-cms

What problems does Hygraph solve for its customers?

Hygraph addresses operational inefficiencies (reducing developer dependency, modernizing legacy tech stacks), financial challenges (lowering operational costs, accelerating speed-to-market), and technical issues (simplifying schema evolution, robust integrations, performance bottlenecks). Its user-friendly interface and GraphQL-native architecture make it a powerful tool for modern content management. Source: Hailey Feed .pdf

Why choose Hygraph over other headless CMS solutions?

Hygraph stands out with its GraphQL-native architecture, Smart Edge Cache, content federation, advanced localization, and developer-friendly APIs. It offers proven business outcomes (e.g., 3x faster time-to-market for Komax, 15% increase in engagement for Samsung), strong security/compliance, and dedicated support. Source: https://hygraph.com/case-studies

#Management SDK step by step example

This document is a step by step of the example presented here.

This whole example is run at once, but here we will show you how to write it step by step.

The first thing you need to do is enable API access.

import {
  Client,
  RelationalFieldType,
  SimpleFieldType,
  VisibilityTypes,
} from '@hygraph/management-sdk';

const client = new Client({
  authToken: '',
  endpoint: '',
});

You can find the authToken and endpoint from your project's settings.

Authentication Token authToken: In your Hygraph project, go to Project Settings > Permanent Auth Tokens > Token. Make sure the token has proper management permissions depending on what you plan to execute via the SDK.
Hygraph Content API Endpoint endpoint: Endpoint of the Content API that belongs to the environment that you plan to interact with. In your Hygraph project, go to Project Settings > Endpoints > High Performance Content API.

For more information, read this document.

Then, create the models:

client.createModel({
  apiId: 'Page',
  apiIdPlural: 'Pages',
  displayName: 'Page',
});

client.createModel({
  apiId: 'Author',
  apiIdPlural: 'Authors',
  displayName: 'Author',
});

client.createModel({
  apiId: 'Book',
  apiIdPlural: 'Books',
  displayName: 'Book',
});

Then, add simple fields. Here, we are adding a title, a simple field of type string, a slug field, a hidden integer field with custom field validation, a required & unique string field with custom regex validation for emails, a basic rich text field, a rich text with embeds and single allowed embeddable model, and a list of date/times:

// required title field of type string:
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.String,
  apiId: 'title',
  displayName: 'Title',
  isTitle: true,
  isRequired: true,
  visibility: VisibilityTypes.ReadWrite,
});

// simple field of type string:
client.createSimpleField({
  parentApiId: 'Author',
  type: SimpleFieldType.String,
  apiId: 'favouritePastime',
  displayName: 'Author Favourite Pastime',
  isRequired: true,
  visibility: VisibilityTypes.ReadWrite,
});

// slug field:
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.String,
  apiId: 'slug',
  displayName: 'Slug',
  description: 'Enter the slug for this page, such as about, blog, or contact',
  isRequired: true,
  isUnique: true,
  tableRenderer: 'GCMS_SLUG',
  formRenderer: 'GCMS_SLUG',
});

// hidden integer field with custom field validation:
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.Int,
  apiId: 'count',
  displayName: 'Count',
  visibility: VisibilityTypes.Hidden,
  validations: {
    Int: {
      range: {
        max: 1000,
        min: 0,
        errorMessage: 'Counter has to be between 0 and 1000',
      },
    },
  },
});

// required + unique string field with custom regex validation for emails:
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.String,
  apiId: 'email',
  displayName: 'Email',
  isRequired: true,
  isUnique: true,
  validations: {
    String: {
      matches: {
        regex: '^([a-z0-9_\\.\\+-]+)@([\\da-z\\.-]+)\\.([a-z\\.]{2,6})$',
      },
    },
  },
});

// basic richtext field
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.Richtext,
  apiId: 'content',
  displayName: 'Content',
  description:
    'Enter the content for this page. The content uses the rich-text editor, giving you a better visual representation.',
  isRequired: true,
});

// richtext with embeds and single allowed embeddable model:
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.Richtext,
  apiId: 'contentExtended',
  displayName: 'Content Extended',
  embedsEnabled: true,
  embeddableModels: ['Author'],
});

// list of date times
client.createSimpleField({
  parentApiId: 'Page',
  type: SimpleFieldType.Datetime,
  apiId: 'lastSeen',
  displayName: 'Last Seen',
  isRequired: true,
  isList: true,
});

Add relational fields. Here, we are adding a uni-directional asset field, regular bi-directional m-1 relation, and a m-n relation:

// required uni-directional asset field
client.createRelationalField({
  parentApiId: 'Page',
  apiId: 'preview',
  displayName: 'Preview',
  type: RelationalFieldType.Asset,
  isRequired: true,
  reverseField: {
    isUnidirectional: true,
    apiId: 'page',
    displayName: 'Page',
    modelApiId: 'Asset',
  },
});

// regular bi-directional m-1 relation
client.createRelationalField({
  parentApiId: 'Page',
  apiId: 'writtenBy',
  displayName: 'Written By',
  type: RelationalFieldType.Relation,
  reverseField: {
    modelApiId: 'Author',
    apiId: 'pages',
    displayName: 'pages',
    isList: true,
  },
});

// m-n relation
client.createRelationalField({
  parentApiId: 'Author',
  apiId: 'favouriteBooks',
  displayName: 'Favourite Books',
  type: RelationalFieldType.Relation,
  isList: true,
  reverseField: {
    modelApiId: 'Page',
    apiId: 'favouriteOf',
    displayName: 'Favourite of',
    isList: true,
  },
});

Add a union field:

client.createUnionField({
  parentApiId: 'Author',
  apiId: 'favourites',
  displayName: 'Author Favourite Books',
  reverseField: {
    apiId: 'authorFavouriteBook',
    displayName: 'author favourite book',
    modelApiIds: ['Book'],
  },
});

Then add a union member to the previous union field:

client.updateUnionField({
  parentApiId: 'Author',
  apiId: 'favourites',
  displayName: 'Favourite Pastime',
  reverseField: {
    modelApiIds: ['Book', 'Movie'],
  },
});

Add the components:

client.createComponent({
  apiId: 'Address',
  apiIdPlural: 'Adresses',
  displayName: 'Address',
});

client.createComponent({
  apiId: 'Contributor',
  apiIdPlural: 'Contributors',
  displayName: 'Contributor',
});

client.createComponent({
  apiId: 'VideoBlock',
  apiIdPlural: 'VideoBlocks',
  displayName: 'VideoBlock',
});

Add a field to the components:

client.createSimpleField({
  parentApiId: 'Address',
  type: SimpleFieldType.String,
  apiId: 'city',
  displayName: 'City',
});

Add a basic component field:

client.createComponentField({
  parentApiId: 'Author',
  apiId: 'address',
  displayName: 'Address',
  description: 'Address of the author',
  componentApiId: 'Address',
});

Add a component union field:

client.createComponentUnionField({
  parentApiId: 'Page',
  apiId: 'section',
  displayName: 'Section',
  componentApiIds: ['Contributor', 'VideoBlock'],
});

And finally, remove VideoBlock from the component union field:

client.updateComponentUnionField({
  parentApiId: 'Page',
  apiId: 'section',
  displayName: 'Section',
  componentApiIds: ['Contributor'],
});

Frequently Asked Questions

Management SDK: Features & Capabilities