Code-first approach in NestJS - Deep Dive

Overview - Code-first approach

What is it?

The code-first approach in NestJS is a way to build GraphQL APIs by writing your TypeScript classes and decorators first. These classes define your data models and operations, and NestJS automatically generates the GraphQL schema from them. This means you focus on writing code, and the schema is created for you behind the scenes.

Why it matters

Without the code-first approach, developers would have to write GraphQL schemas manually, which can be error-prone and hard to keep in sync with the code. The code-first method saves time, reduces mistakes, and keeps your API consistent with your code. It makes building and maintaining GraphQL APIs easier and faster.

Where it fits

Before learning code-first, you should understand basic TypeScript and NestJS fundamentals, including decorators and modules. After mastering code-first, you can explore advanced GraphQL features like schema stitching, federation, and performance optimization.

Mental Model

Core Idea

Write your API logic and data models in code first, and let NestJS create the GraphQL schema automatically.

Think of it like...

It's like writing a recipe (code) and having a cookbook (schema) automatically printed from it, instead of writing the cookbook first and then figuring out the recipe.

┌───────────────┐      ┌─────────────────────┐
│ TypeScript    │      │ GraphQL Schema      │
│ Classes &     │─────▶│ (auto-generated)    │
│ Decorators   │      │                     │
└───────────────┘      └─────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding GraphQL Basics

Concept: Learn what GraphQL is and how it uses schemas to define data and operations.

GraphQL is a way to ask for exactly the data you want from an API. It uses a schema to describe what data is available and how you can get or change it. The schema defines types, queries, and mutations.

Result

You know that a schema is a blueprint for the API's data and operations.

Understanding schemas is essential because the code-first approach revolves around generating these schemas from code.

2

Foundation

Basics of NestJS Decorators

Concept: Learn how decorators in NestJS add metadata to classes and methods.

Decorators are special functions that attach extra information to classes or methods. For example, @Resolver marks a class as a GraphQL resolver, and @Query marks a method as a GraphQL query.

Result

You can identify how NestJS uses decorators to connect code to GraphQL concepts.

Knowing decorators helps you understand how NestJS knows what parts of your code become parts of the GraphQL API.

3

Intermediate

Creating Object Types with Classes

🤔Before reading on: do you think GraphQL object types can be created by writing TypeScript classes directly? Commit to your answer.

Concept: Use TypeScript classes with @ObjectType and @Field decorators to define GraphQL object types.

In code-first, you write a class and decorate it with @ObjectType to say it represents a GraphQL type. Each property you want in the schema gets a @Field decorator. For example: @ObjectType() class User { @Field() name: string; @Field() age: number; } NestJS uses this to build the schema automatically.

Result

Your TypeScript class becomes a GraphQL type in the schema without writing schema language manually.

This step shows how code-first tightly couples your code structure with the API schema, reducing duplication.

4

Intermediate

Defining Queries and Mutations

🤔Before reading on: do you think methods in classes can represent GraphQL queries and mutations directly? Commit to your answer.

Concept: Use @Query and @Mutation decorators on methods inside resolver classes to define API operations.

You create a resolver class decorated with @Resolver. Inside, methods decorated with @Query return data, and methods with @Mutation change data. For example: @Resolver() class UserResolver { @Query(() => [User]) users() { return [...] } @Mutation(() => User) addUser(name: string) { return new User(name); } } NestJS uses these to build the API operations in the schema.

Result

Your methods become GraphQL queries and mutations automatically.

This shows how your code logic directly maps to API operations, making the API easy to maintain.

5

Advanced

Handling Input Types and Arguments

🤔Before reading on: do you think input types require separate classes or can be simple types? Commit to your answer.

Concept: Define input types as classes with @InputType and use @Args to accept arguments in queries and mutations.

For complex inputs, create classes decorated with @InputType. Use @Field for each input property. Then in resolver methods, use @Args to receive these inputs. Example: @InputType() class CreateUserInput { @Field() name: string; } @Mutation(() => User) addUser(@Args('input') input: CreateUserInput) { ... } This keeps input data structured and validated.

Result

Your API can accept complex, typed inputs cleanly.

Understanding input types improves API clarity and helps prevent errors from unstructured inputs.

6

Advanced

Schema Generation and Validation

🤔Before reading on: do you think the schema updates automatically when code changes, or do you need manual steps? Commit to your answer.

Concept: NestJS automatically generates and updates the GraphQL schema from your code at build or runtime, ensuring consistency.

When you run your NestJS app, it reads your decorated classes and methods, then creates the GraphQL schema file. This schema matches your code exactly. If you change code, the schema updates too. This avoids mismatches and manual syncing.

Result

Your GraphQL schema is always up-to-date with your code.

Automatic schema generation reduces bugs and saves time, making development smoother.

7

Expert

Advanced Decorator Internals and Performance

🤔Before reading on: do you think decorators add runtime overhead or are just compile-time helpers? Commit to your answer.

Concept: Decorators in NestJS add metadata at runtime, which the framework uses to build the schema and resolve requests efficiently.

Decorators store metadata using TypeScript's Reflect API. NestJS reads this metadata to build the schema and link resolvers. This happens once at startup, so runtime overhead is minimal. Understanding this helps optimize startup time and debug schema issues.

Result

You can write performant APIs and troubleshoot schema generation problems effectively.

Knowing how decorators work under the hood empowers you to write better, more efficient code and understand framework behavior deeply.

Under the Hood

NestJS uses TypeScript decorators to attach metadata to classes and methods. This metadata describes GraphQL types, fields, queries, and mutations. At runtime, NestJS reads this metadata using the Reflect API to build a GraphQL schema object. This schema is then used by the GraphQL server to validate and execute queries. The process happens automatically when the application starts, ensuring the schema matches the code exactly.

Why designed this way?

The code-first approach was designed to reduce duplication and errors between schema and code. Writing schemas manually is tedious and error-prone. Using decorators leverages TypeScript's features to keep schema and code in sync. Alternatives like schema-first require writing schema files separately, which can get out of sync. Code-first improves developer productivity and API reliability.

┌───────────────┐
│ TypeScript    │
│ Code +       │
│ Decorators   │
└──────┬────────┘
       │ Metadata via Reflect API
       ▼
┌───────────────┐
│ NestJS        │
│ Schema Builder│
└──────┬────────┘
       │ Generates
       ▼
┌───────────────┐
│ GraphQL       │
│ Schema Object │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does code-first mean you never see or use the GraphQL schema file? Commit yes or no.

Common Belief: Code-first means you don't have a GraphQL schema file at all.

Reality: NestJS still generates a schema file from your code, which you can view and use for tools or documentation.

Why it matters: Thinking there is no schema file can confuse debugging and integration with other tools that rely on the schema.

Quick: Do you think code-first is slower at runtime because of decorators? Commit yes or no.

Common Belief: Decorators add significant runtime overhead making code-first APIs slower.

Reality: Decorators add metadata at startup only; runtime query execution is efficient and not slowed by decorators.

Why it matters: Believing this may discourage using code-first, missing out on its productivity benefits.

Quick: Is code-first only for small projects? Commit yes or no.

Common Belief: Code-first is only suitable for small or simple APIs.

Reality: Code-first scales well for large projects with complex schemas and supports modular design.

Why it matters: Underestimating code-first's scalability can lead to unnecessary complexity or switching approaches mid-project.

Quick: Can you mix code-first and schema-first approaches freely? Commit yes or no.

Common Belief: You can easily mix code-first and schema-first approaches in the same NestJS project.

Reality: Mixing approaches is possible but complex and can cause conflicts; usually, one approach is chosen per project.

Why it matters: Trying to mix without understanding can cause schema conflicts and maintenance headaches.

Expert Zone

1

Decorators use TypeScript's Reflect Metadata API, which requires enabling experimental metadata in tsconfig, a detail often missed.

2

Input types and object types are separate classes, but they can share fields using inheritance or interfaces to reduce duplication.

3

Schema generation happens once at startup, so heavy computation in decorators can slow app boot but not query execution.

When NOT to use

Avoid code-first if you need to strictly control the GraphQL schema language or want to use existing schema files from other teams. In such cases, schema-first approach or schema stitching is better.

Production Patterns

In production, code-first is used with modular resolvers, input validation pipes, and custom scalars. Teams often generate schema files for documentation and use code generation tools to create TypeScript types for clients.

Connections

Schema-first approach

Alternative method to build GraphQL APIs where schema is written first, then code is generated or written to match.

Understanding code-first helps appreciate schema-first's tradeoffs and when to choose each approach.

TypeScript decorators

Code-first relies heavily on decorators to add metadata for schema generation.

Mastering decorators in TypeScript unlocks powerful patterns beyond GraphQL, like dependency injection and validation.

Database ORM models

Both code-first GraphQL types and ORM models define data structures in code, often sharing classes or interfaces.

Aligning GraphQL types with ORM models reduces duplication and keeps API and database in sync.

Common Pitfalls

#1 Forgetting to enable experimental metadata in tsconfig.json

Wrong approach:

{
"compilerOptions": {
"target": "ES2017",
"module": "commonjs"
// missing "emitDecoratorMetadata": true
}
}

Correct approach:

{
"compilerOptions": {
"target": "ES2017",
"module": "commonjs",
"emitDecoratorMetadata": true,
"experimentalDecorators": true
}
}

Root cause:

Decorators need metadata emitted to work properly; missing this causes schema generation to fail silently.

#2 Using simple types instead of @InputType classes for complex inputs

Wrong approach:

@Mutation(() => User)
addUser(@Args('name') name: string, @Args('age') age: number) { ... }

Correct approach:

@InputType()
class CreateUserInput {
@Field()
name: string;
@Field()
age: number;
}

@Mutation(() => User)
addUser(@Args('input') input: CreateUserInput) { ... }

Root cause:

Not using input types leads to messy argument lists and harder validation.

#3 Not decorating resolver classes with @Resolver

Wrong approach:

class UserResolver {
@Query(() => [User])
users() { return [...] }
}

Correct approach:

@Resolver()
class UserResolver {
@Query(() => [User])
users() { return [...] }
}

Root cause:

Without @Resolver, NestJS does not recognize the class as a GraphQL resolver, so queries won't be registered.

Key Takeaways

The code-first approach lets you write your API logic and data models in TypeScript code, and NestJS generates the GraphQL schema automatically.

Decorators like @ObjectType, @Field, @Resolver, @Query, and @Mutation connect your code to GraphQL concepts seamlessly.

Automatic schema generation keeps your API consistent and reduces errors compared to writing schemas manually.

Understanding how decorators work under the hood helps you write efficient and maintainable GraphQL APIs.

Code-first is scalable and powerful but requires enabling TypeScript metadata and following patterns for inputs and resolvers.