How can I abstract types and interfaces when using TypeScript with Hygraph?

When integrating TypeScript with Hygraph, you can abstract types and interfaces by either declaring them directly in the file where they're used, or by creating a separate types.ts file at the root of your project. This approach allows you to import and reuse type definitions across multiple files, reducing redundancy and improving code maintainability. For example, in the Hygraphlix demo, all types are stored in a single file and imported as needed. See the abstract-types branch for a working example.

When should I avoid abstracting types in TypeScript projects with Hygraph?

If you're new to TypeScript or working on a small project, it's often best to keep your types close to where they're used. This makes your code easier to understand and avoids premature optimization. As your project grows, you can refactor and abstract types into separate files for better organization.

What are the benefits of abstracting types into a single file in a Hygraph + TypeScript project?

Abstracting types into a single file, such as types.ts, allows you to reuse type definitions across your application, reduces code duplication, and makes it easier to maintain and update your data models. This is especially useful in larger projects or when working with multiple components that share the same data structures.

How do I import shared types into my Next.js pages when using Hygraph?

After defining your shared types in a types.ts file, you can import them into your Next.js pages or components using standard ES6 import syntax. For example: import { Movie } from '@/types/types';. This ensures type safety and consistency across your application.

What is the structure of a typical Movie interface when using Hygraph with TypeScript?

A typical Movie interface might include properties such as id, federateMovie (with nested data like Title, Poster, Genre, Director), slug, and moviePoster (with height, width, url). This structure mirrors the data returned from Hygraph queries and ensures type safety in your application.

How does using TypeScript with Hygraph help catch errors earlier?

TypeScript's static type system enforces strict data structures, which helps catch errors at compile time rather than runtime. By defining interfaces that match your Hygraph schema, you ensure that your application only processes valid data, reducing bugs and improving reliability.

Can I autogenerate types for Hygraph schemas in TypeScript?

Yes, some developers choose to autogenerate TypeScript types from their Hygraph GraphQL schemas using code generation tools. This ensures that your types always match your backend schema, reducing manual maintenance and potential mismatches.

Where can I find a working example of Hygraph and TypeScript integration?

You can view a complete example of Hygraph and TypeScript integration in the Hygraphlix demo project. The code is available on GitHub in the abstract-types branch, which demonstrates best practices for type abstraction and usage.

How does Hygraph support composability in frontend projects?

Hygraph supports composability by allowing you to define reusable schema components and integrate with modern frontend frameworks like Next.js. This enables you to build modular, maintainable applications where content and presentation are decoupled. Learn more in the Composability blog series.

What community resources are available for developers working with Hygraph and TypeScript?

Developers can join the Hygraph Slack community to ask questions, share projects, and connect with other users. The community is a great place to get support and learn best practices for integrating Hygraph with TypeScript and other technologies.

How do I decide where to place my types and interfaces in a Hygraph + TypeScript project?

The placement of types and interfaces depends on your project size and team preferences. For small projects, keeping types close to their usage is fine. For larger projects, centralizing them in a shared file improves maintainability and reduces duplication. Ultimately, choose the approach that makes your codebase most readable and manageable for your team.

What is the advantage of using interfaces for API responses from Hygraph?

Using interfaces for API responses ensures that your application only processes data that matches the expected structure, reducing runtime errors and improving developer productivity. It also makes it easier to refactor and extend your application as your data models evolve.

How does Hygraph's federated content model work with TypeScript?

Hygraph's content federation allows you to integrate remote data sources, such as OMDB for movies, into your schema. By defining TypeScript interfaces that match the federated data structure, you can ensure type safety and seamless integration in your frontend code.

What is the role of the MovieCard component in the Hygraphlix demo?

In the Hygraphlix demo, the MovieCard component receives props defined by the Movie interface and renders movie details such as title, poster, genre, and director. This demonstrates how TypeScript interfaces help enforce consistent data structures across components.

How can I practice separating types in a Hygraph + TypeScript project?

You can clone the Hygraphlix project and experiment with moving type definitions between files. The abstract-types branch provides a reference implementation for best practices in type abstraction.

What is the recommended way to organize types for a large Hygraph + TypeScript application?

For large applications, it's recommended to centralize all type and interface definitions in a dedicated types.ts file or folder. This makes it easier to manage, update, and share types across your codebase, especially as your schema evolves.

How does Hygraph's API work with TypeScript?

Hygraph provides multiple APIs, including a Content API and a High Performance Content API, which you can query using TypeScript. By defining interfaces that match the API response structure, you can ensure type safety and reduce runtime errors. Learn more in the API Reference Documentation.

What is the purpose of the federateMovie field in the Movie interface?

The federateMovie field in the Movie interface represents a remote source integrated into Hygraph, such as OMDB. It contains a data object with properties like Title, Poster, Genre, and Director, allowing you to access federated content seamlessly in your application.

How does Hygraph help with code maintainability in TypeScript projects?

By encouraging the use of interfaces and type abstraction, Hygraph helps you write maintainable, scalable code. Centralizing type definitions reduces duplication, makes refactoring easier, and ensures consistency across your application.

Where can I get support or ask questions about using Hygraph with TypeScript?

You can join the Hygraph Slack community to connect with other developers, ask questions, and get support from the Hygraph team and community members.

What features does Hygraph offer for developers?

Hygraph offers a GraphQL-native architecture, content federation, user-friendly tools, robust security and compliance, Smart Edge Cache, localization, and extensive integration options. These features make it ideal for modern, scalable, and flexible content management. Learn more about Hygraph features.

Does Hygraph provide an API for content management?

Yes, Hygraph provides multiple APIs, including a Content API, High Performance Content API, MCP Server API, Asset Upload API, and Management API. These APIs support querying, mutating, and managing content, as well as integrating with AI assistants and external systems. See the API Reference.

What integrations are available with Hygraph?

Hygraph integrates with popular Digital Asset Management (DAM) systems like Aprimo, AWS S3, Bynder, Cloudinary, Imgix, Mux, and Scaleflex Filerobot. It also supports custom integrations via SDKs and APIs, and offers a marketplace for pre-built apps. Explore integrations.

How does Hygraph ensure high performance for content delivery?

Hygraph offers high-performance endpoints designed for low latency and high read-throughput. The platform actively measures GraphQL API performance and provides best practices for optimization. Read about performance improvements.

What technical documentation is available for Hygraph?

Hygraph provides comprehensive documentation covering API references, schema components, webhooks, AI integrations, and more. Access all resources at the Hygraph Documentation page.

What pricing plans does Hygraph offer?

Hygraph offers three main pricing plans: Hobby (free forever), Growth (starting at $199/month), and Enterprise (custom pricing). Each plan includes different features and support levels. See the pricing page for details.

What features are included in the Hygraph Hobby plan?

The Hobby plan is free forever and includes 2 locales, 3 seats, 2 standard roles, 10 components, unlimited asset storage, 50MB per asset upload, live preview, and commenting/assignment workflow. Sign up for free.

What does the Growth plan cost and include?

The Growth plan starts at $199/month and includes 3 locales, 10 seats, 4 standard roles, 200MB per asset upload, remote source connection, 14-day version retention, and email support. Get started with Growth.

What is included in the Hygraph Enterprise plan?

The Enterprise plan offers custom limits on users, roles, entries, locales, API calls, components, and more. It includes advanced features like scheduled publishing, dedicated infrastructure, SSO, multitenancy, instant backup recovery, custom workflows, and dedicated support. Try Enterprise for 30 days or request a demo.

What security certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant (since August 3, 2022), ISO 27001 certified, and GDPR compliant. These certifications ensure high standards for data protection and information security. Learn more about security.

How does Hygraph protect my data?

Hygraph uses encryption at rest and in transit, granular permissions, audit logs, SSO integrations, regular backups, and dedicated hosting options to protect your data. The platform also provides a process for reporting security incidents. See security features.

Who can benefit from using Hygraph?

Hygraph is designed for developers, product managers, content creators, marketing professionals, and solutions architects. It's suitable for enterprises, agencies, eCommerce, media, technology companies, and global brands. See case studies.

What industries use Hygraph?

Industries using Hygraph include SaaS, marketplace, education technology, media and publication, healthcare, consumer goods, automotive, technology, fintech, travel, food and beverage, eCommerce, agencies, online gaming, events, government, consumer electronics, engineering, and construction. Explore industry case studies.

What business impact can I expect from using Hygraph?

Customers report improved operational efficiency, accelerated speed-to-market, cost efficiency, enhanced scalability, and better customer engagement. For example, Komax achieved a 3x faster time-to-market, and Samsung improved customer engagement by 15%. See more success stories.

Can you share specific case studies of customers using Hygraph?

Yes, notable customers include Samsung (scalable API-first application), Dr. Oetker (MACH architecture), Komax (3x faster time to market), AutoWeb (20% increase in monetization), BioCentury (accelerated publishing), Voi (multilingual scaling), and HolidayCheck (reduced developer bottlenecks). Read all case studies.

How does Hygraph compare to other CMS platforms?

Hygraph is the first GraphQL-native Headless CMS, offering content federation, user-friendly tools, and enterprise-grade features. It stands out for its flexibility, scalability, and ease of implementation, ranking 2nd out of 102 Headless CMSs in the G2 Summer 2025 report. See G2 rankings.

Why choose Hygraph over alternatives like Contentful or Sanity?

Hygraph differentiates itself with its GraphQL-native architecture, content federation, cost efficiency, and ease of use for non-technical users. It is best for teams seeking modern workflows, rapid scaling, and seamless integration with multiple data sources. See why customers choose Hygraph.

How long does it take to implement Hygraph?

Implementation time varies by project. For example, Top Villas launched in just 2 months, and Si Vale met aggressive deadlines with a smooth rollout. Hygraph's onboarding process and resources support rapid adoption. Read the Top Villas case study.

How easy is it to get started with Hygraph?

Hygraph offers a free API playground, free developer accounts, structured onboarding, training resources, and a supportive community. Most users can start building immediately without lengthy onboarding. See documentation.

What support resources are available for Hygraph users?

Support resources include webinars, live streams, how-to videos, extensive documentation, and a community Slack channel. Enterprise customers receive dedicated support and custom SLAs. Contact support.

What do customers say about Hygraph's ease of use?

Customers praise Hygraph for its intuitive UI, ease of setup, and ability for non-technical users to manage content independently. For example, Anastasija S., Product Content Coordinator, highlighted the instant visibility of changes on the front-end. Read more feedback.

What pain points does Hygraph solve for its customers?

Hygraph addresses operational inefficiencies (developer dependency, legacy tech stacks), financial challenges (high costs, slow speed-to-market), and technical issues (schema evolution, integration difficulties, performance bottlenecks, localization, and asset management). See how Hygraph solves these pains.

Everything in its right place: How to abstract types in TypeScript

TypeScript (Ts) is a strongly typed programming language that compiles to JavaScript, so it can be used anywhere JavaScript (Js) is used, such as a browser. These qualities and the ability to work at any scale of application or tooling make it ideal for integrating a front-end with a CMS. You might be thinking, if it runs like Javascript and converts to it in the end, why not use JavaScript? The magic of TypeScript is that it adds strictly defined syntax called a type system that creates a tighter connection with your CMS and helps you catch errors faster and earlier.

When using TypeScript, you can organize your interfaces and types in various ways.

You can store interfaces on the main file that uses them directly.
You can explicitly export and import types from .ts files like any other class, function, or object. These files may be TypeScript files that only contain types. You can keep these files in the root folder or locally in the specific directory.

#When NOT to abstract your types in TypeScript

When you’re new to Typescript, keeping your types close at hand can give you a sense of security. It also keeps you from over-optimizing too early. When you have your first set of types, you can write them in place, and when you need to use them again, abstract them into a new file. When you’ve architected a few projects like this, you may already know when you’ll want to do this and abstract things from the beginning.

#When to Abstract your types in TypeScript

Looking at a TypeScript example: Hygraphlix

In the first iteration of Hygraphlix, a movie streaming platform demo built with Hygraph and NextJS 14, I placed my types and interfaces in the main file where they were used. I am still somewhat new to TypeScript, and having my types in the same place as the rest of my code helped me understand their connection to the Hygraph CMS and my NextJS code.

The code below creates the Hygraphlix Homepage that features the Top 8 movies on the platform by querying the first eight movies from Hygraph.

//Homepage with movies: app/page.js
import { Link } from "@nextui-org/link";
import { Snippet } from "@nextui-org/snippet";
import { Code } from "@nextui-org/code";
import { button as buttonStyles } from "@nextui-org/theme";
import { siteConfig } from "@/config/site";
import { title, subtitle } from "@/components/primitives";
import { GithubIcon } from "@/components/icons";
import MovieCard from "@/components/MovieCard";

//Get featured Movies
async function getFeaturedMovies() {
  const HYGRAPH_ENDPOINT = process.env.HYGRAPH_ENDPOINT;
  if (!HYGRAPH_ENDPOINT) {
    throw new Error("HYGRAPH_ENDPOINT is not defined");
  }
  const response = await fetch(HYGRAPH_ENDPOINT, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `
        query Movies {
          movies(first: 8) {
              federateMovie {
                data {
                  Title
                  Poster
                  Genre
                  Director
                    }
              }
              id
              slug
              moviePoster {
                height
                width
                url
              }
            }
        }`,
    }),
  });
  const json = await response.json();
  return json.data.movies;
}

The query returns our movie data in JSON format, and we map over it to place each movie in a MovieCard component:

export default async function Home() {
  const movies = await getFeaturedMovies();
  //console.log(movies);
  return (
    <>
      <section className="flex flex-col items-center justify-center gap-4 py-8 md:py-10">
       
          <!-- Homepage markup/HMTL here... -->
                    
          <div className="grid px-5 mt-4 lg:gap-xl-12 gap-x-6 md:grid-cols-2 lg:grid-cols-4">
            {movies.map(
                            // Declare movie interface and map over movies list to render in movie cards
              (movie: {
                id: string;
                federateMovie: {
                  data: {
                    Title: string;
                    Poster: string;
                    alt: string;
                    Genre: string;
                    Director: string;
                  };
                };
                slug: string;
                moviePoster: {
                  height: number;
                  width: number;
                  url: string;
                };
              }) => (
                <MovieCard
                  key={movie.id}
                  Title={movie.federateMovie.data.Title}
                  Poster={movie.federateMovie.data.Poster}
                  moviePoster={movie.moviePoster}
                  alt={movie.federateMovie.data.Title}
                  Genre={movie.federateMovie.data.Genre}
                  Director={movie.federateMovie.data.Director}
                  slug={movie.slug}
                />
              )
            )}
          </div>
        </section>
      </div>
    </>
  );
}

The async Home function retrieves all the featured movie data and maps them to a MovieCard component. The TypeScript Movie interface definition is located inside of the movies map function.

Zooming in on our Movie interface definition

// Movie TypeScript interface definition
interface Movie {
  id: string;
  federateMovie: {
    data: {
      Title: string;
      Poster: string;
      alt: string;
      Genre: string;
      Director: string;
    };
  };
  slug: string;
  moviePoster: {
    height: number;
    width: number;
    url: string;
  };
}

In the Movie Interface definition, we are defining the Movie object and properties like id, federateMovie, slug, and moviePoster. The federateMovie object is a remote source coming into Hygraph from OMDB, and open-source movie database that contains a data object with properties like Title, Poster, alt, Genre, and Director The moviePoster property is also an object that contains height, width, and url.

#Abstracting your types and interfaces into the same file

You can get started quickly with abstracting by declaring your types in the file where they will be used, but not directly in your function. Looking at the Homepage code again, you could declare the Movie interface above the async function Home() , like so:

// Movie TypeScript interface definition
interface Movie {
  id: string;
  federateMovie: {
    data: {
      Title: string;
      Poster: string;
      alt: string;
      Genre: string;
      Director: string;
    };
  };
  slug: string;
  moviePoster: {
    height: number;
    width: number;
    url: string;
  };
}

export default async function Home() {
  const movies: Movie[] = await getFeaturedMovies();
  //console.log(movies);
  return (
    <>
        <section className="flex flex-col items-center justify-center gap-4 py-8 md:py-10">
       
          <!-- Homepage markup/HMTL here... -->
       
          <div className="grid px-5 mt-4 lg:gap-xl-12 gap-x-6 md:grid-cols-2 lg:grid-cols-4">
          {movies.map((movie: Movie) => (
                        // Map over movie object list to render in movie cards
                <MovieCard
                  key={movie.id}
                  Title={movie.federateMovie.data.Title}
                  Poster={movie.federateMovie.data.Poster}
                  moviePoster={movie.moviePoster}
                  alt={movie.federateMovie.data.Title}
                  Genre={movie.federateMovie.data.Genre}
                  Director={movie.federateMovie.data.Director}
                  slug={movie.slug}
                />
              )
            )}
          </div>
        </section>
      </div>
    </>
  );
}

In this location and in line with the function, it is easier to understand how the Movie interface helps ensure that components receive the correct props and that objects have the correct structure as it strictly defines the shape of our query result or data object and the props that will be used in our Next app. This can help catch errors at compile time rather than runtime, making the code more robust and easier to debug.

While putting your types and interfaces directly into the file where they are used is okay, what happens when you want to use the Movie object again? You would have to define it in every new file that uses it. This can get complicated and messy very quickly when you have a large application. Another way to organize your types and interfaces when using TypeScript is to have a file that contains all of our definitions and import it into the files that require it. So, let’s do that!

#Abstracting your types and interfaces into a single file

To put all the types used in the Hygraphlix Next app together, go to the folder called types in the root of the project and rename the index.ts file to types.ts and copy and paste the types from the app routes and component directories. When complete, the file should match the below code:

//   @/types/types.ts

import { SVGProps } from "react";
import { ThemeProviderProps } from "next-themes/dist/types";

export interface Movie {
  id: string;
  federateMovie: {
    data: {
      Title: string;
      Poster: string;
      alt: string;
      Genre: string;
      Director: string;
    };
  };
  slug: string;
  moviePoster: {
    height: number;
    width: number;
    url: string;
  };
}
export interface MuxPlayerProps {
  playbackId: string;
}

export type MovieHeroProps = {
  Title: string;
  //Poster: string;
  Plot: string;
  Actors: string;
  Director: string;
  Genre: string;
  Rated: string;
  Runtime: string;
  Year: string;
};

export type MovieCardProps = {
  Poster: string;
  alt: string;
  Title: string;
  Genre: string;
  Director: string;
  slug: string;
  moviePoster: {
    height: number;
    width: number;
    url: string;
  };
};

export type IconSvgProps = SVGProps<SVGSVGElement> & {
  size?: number;
};
export interface ProvidersProps {
  children: React.ReactNode;
  themeProps?: ThemeProviderProps;
}

The addition of export allows our types and interfaces to be used throughout our Next app as needed.

Importing types into the homepage

Now that our types are in one file let’s take a quick look at the Homepage code from earlier to import our Movie interface:

import { Movie } from "@/types/types";

export default async function Home() {
  const movies: Movie[] = await getFeaturedMovies();
  //console.log(movies);
  return (
    <>
        <section className="flex flex-col items-center justify-center gap-4 py-8 md:py-10">
       
          <!-- Homepage markup/HMTL here... -->
       
          <div className="grid px-5 mt-4 lg:gap-xl-12 gap-x-6 md:grid-cols-2 lg:grid-cols-4">
          {movies.map((movie: Movie) => (
                        // Map over movie object list to render in movie cards
                <MovieCard
                  key={movie.id}
                  Title={movie.federateMovie.data.Title}
                  Poster={movie.federateMovie.data.Poster}
                  moviePoster={movie.moviePoster}
                  alt={movie.federateMovie.data.Title}
                  Genre={movie.federateMovie.data.Genre}
                  Director={movie.federateMovie.data.Director}
                  slug={movie.slug}
                />
              )
            )}
          </div>
        </section>
      </div>
    </>
  );
}

In the above code, we are now importing the Movie type from the types.ts file. Our Home function awaits the result of the getFeaturedMovies function and assigns it to the movies variable that contains the Movie object that we defined in our type definitions. We map over the movies array and pass the necessary props from our Movie object to render the list of movies. Not only is our homepage code a bit cleaner, but we have also removed the redundancy of having to define our types every time they are used in a new file. Let’s say, for example, we want to create a ‘related movie’ area on each individual movie page; by importing the types, we get the proper shape of Movie object without having to rewrite all the code.

#Conclusion

There are many approaches and opinions about where you should put your types when using Typescript. Some developers even autogenerate their types, while some prefer placing their types in the route folder where they will be used rather than one file at the root level. Ultimately, what matters is your own comfort level with your code and making sure your code is readable to the developer who comes along after you have moved on to another project. Clone the Hygraphlix project and frontend code and practice separating the types. To view Hygraphlix with all types stored in types.ts, go to the abstract-types branch of the repo. If you have any questions or feedback, find me in the community!

Join the community

Need help? Want to show off? Join the Slack community and meet other developers building with Hygraph

Meet us in Slack

Blog Author

Lo Etheridge

Senior Developer Relations

Lo is Hygraph's Senior Developer Relations Specialist. They focus on developer education around Headless CMS, JS-based frontends, and API technologies as well as the dynamic cross-functional relationship between developers and content professionals.

Share with others

Sign up for our newsletter!

Be the first to know about releases and industry news and insights.

Frequently Asked Questions

TypeScript & Hygraph Integration