Building Type-Safe GraphQL Systems: Codegen, Tagging, Tools, and Optics

When architecting a GraphQL system in the TypeScript ecosystem, developers often encounter four distinct packages that solve very different problems. graphql-codegen, graphql-tag, graphql-tools, and optics-ts are frequently listed together, but they operate at different layers of the stack. Understanding when to use each—and when to avoid them—is critical for maintaining a clean, type-safe, and performant codebase.

🏗️ Core Purpose: Where Each Tool Fits

These packages do not compete; they complement each other or serve entirely different niches.

• graphql-codegen is a build-time tool. It reads your schema and queries to generate TypeScript code. It lives in your development workflow.
• graphql-tag is a runtime parser. It turns template strings into GraphQL ASTs so libraries like Apollo Client can read them. It lives in your bundled code.
• graphql-tools is a server-side utility belt. It helps create, mock, and stitch schemas. It lives on your backend.
• optics-ts is a general functional utility. It helps update immutable data. It lives in your state management logic, unrelated to GraphQL specifically.

⚡ Generating Types: The Power of graphql-codegen

The biggest challenge in GraphQL frontends is keeping TypeScript types in sync with your backend schema. Manual typing is error-prone and slow. graphql-codegen solves this by generating types automatically whenever your schema changes.

graphql-codegen generates full TypeScript interfaces and React hooks based on your actual queries.

// Generated by graphql-codegen
export type GetUserQuery = {
  __typename?: 'Query';
  user?: {
    __typename?: 'User';
    id: string;
    email: string;
  } | null;
};

// It also generates ready-to-use hooks
import { useGetUserQuery } from '@/generated/graphql';

function Profile() {
  const { data, loading } = useGetUserQuery({ variables: { id: '123' } });
  // 'data' is fully typed. No 'any' needed.
  return <div>{data?.user?.email}</div>;
}

Without this tool, you would have to manually define these interfaces, risking mismatches if the backend adds a field or changes a type.

🏷️ Parsing Queries: graphql-tag vs. Modern Alternatives

Historically, GraphQL clients needed a way to parse query strings inside JavaScript template literals. graphql-tag was the standard solution for this, wrapping strings in a tagged template function.

graphql-tag parses the string at runtime (or build time) into an AST object.

import gql from 'graphql-tag';

const query = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;
// 'query' is now an AST object, not a string

However, in modern workflows, graphql-codegen often makes graphql-tag redundant. When you configure codegen to import from .graphql files, your bundler handles the parsing, and you get better type safety without the runtime overhead of the gql tag.

// Modern approach with graphql-codegen and .graphql files
import { useGetUserQuery } from '@/generated/graphql';
import GetUserDocument from './GetUser.graphql'; // Loaded as a typed document

// No need for 'gql' tag; types are inferred directly from the file

If you are starting a new project today, prefer the file-based approach with graphql-codegen over inline gql tags unless you have a specific dynamic requirement.

🖥️ Server Utilities: The State of graphql-tools

On the server side, graphql-tools was once the go-to library for making executable schemas, mocking data, and stitching multiple schemas together. However, the landscape has shifted.

graphql-tools previously provided makeExecutableSchema to combine type definitions with resolvers.

// Legacy pattern using graphql-tools
import { makeExecutableSchema } from '@graphql-tools/schema';

const schema = makeExecutableSchema({
  typeDefs: `
    type Query {
      hello: String
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'Hello world'
    }
  }
});

Today, most of these utilities have moved into the core graphql package or are built directly into server frameworks like Apollo Server v4+ and GraphQL Yoga. The makeExecutableSchema function, for instance, is now available via @graphql-tools/schema, but many developers find they don't need it at all when using modern server constructors that accept typeDefs and resolvers directly.

// Modern pattern with GraphQL Yoga or Apollo Server v4
import { createYoga } from 'graphql-yoga';

const yoga = createYoga({
  schema: {
    typeDefs: `type Query { hello: String }`,
    resolvers: { Query: { hello: () => 'Hello' } }
  }
});
// No need for explicit 'makeExecutableSchema' in many cases

Use graphql-tools only if you need advanced features like schema stitching (combining multiple microservice schemas) or complex mocking that isn't supported by your server framework's defaults.

🔍 Immutable Updates: Where optics-ts Fits (and Doesn't)

optics-ts is the outlier here. It is not a GraphQL library. It is a functional programming tool for updating immutable data using "lenses." While GraphQL clients (like Apollo or Relay) manage immutable cache data, optics-ts is a general-purpose utility for any immutable structure.

optics-ts allows you to update deeply nested properties without writing nested spread operators.

import { optic, set } from 'optics-ts';

interface State {
  user: {
    profile: {
      settings: {
        theme: string;
      };
    };
  };
}

const oldState: State = { user: { profile: { settings: { theme: 'light' } } } };

// Using standard TypeScript (verbose)
const newState1 = {
  ...oldState,
  user: {
    ...oldState.user,
    profile: {
      ...oldState.user.profile,
      settings: {
        ...oldState.user.profile.settings,
        theme: 'dark'
      }
    }
  }
};

// Using optics-ts (concise and type-safe)
const themeOptic = optic<State>().prop('user').prop('profile').prop('settings').prop('theme');
const newState2 = set(themeOptic)('dark')(oldState);

You might use this in a GraphQL app if you are writing custom cache updates or managing complex local state outside of your GraphQL client's automatic normalization. However, do not install it expecting it to help with GraphQL queries or schemas; it solves a state management problem, not a GraphQL problem.

📊 Feature Comparison Matrix

💡 Strategic Recommendations

1. Start with graphql-codegen: If you are using TypeScript with GraphQL, this is non-negotiable. It provides the highest return on investment by automating types and hooks. Configure it to generate code from .graphql files to avoid relying on graphql-tag.

2. Avoid graphql-tag in New Projects: Unless you are dynamically constructing queries at runtime (a rare pattern), use static .graphql files processed by graphql-codegen. This reduces bundle size and improves type inference.

3. Audit graphql-tools Usage: If you are setting up a new server, check if your framework (Apollo, Yoga, Envelop) handles schema creation natively. Only add graphql-tools if you need specific advanced features like schema stitching or detailed mocking strategies that your framework lacks.

4. Use optics-ts Only for Complex State: Do not add this to your project just because you are using GraphQL. Only introduce it if you find yourself struggling with deeply nested immutable updates in your local state management and standard spread syntax becomes unreadable.

🏁 Final Verdict

For a modern, professional GraphQL stack:

• Frontend: Rely heavily on graphql-codegen for types and hooks. Use static .graphql files instead of graphql-tag.
• Backend: Use native schema definitions in your server framework. Reach for graphql-tools only for advanced stitching or mocking.
• State: Ignore optics-ts unless you have a specific, complex immutable data problem that standard patterns cannot solve cleanly.

By separating these concerns, you build a system that is type-safe, performant, and easy to maintain, without carrying unnecessary dependencies.