GraphQL Workflow

Goal

Use this workflow when you want to add GraphQL to a NestForge app without guessing how the schema, module container, and runtime fit together.

Step 1: enable the feature

nestforge = { version = "1", features = ["graphql"] }

Step 2: build the schema

NestForge uses async-graphql, so the first task is defining the schema root:

use nestforge::async_graphql::{EmptyMutation, EmptySubscription, Object, Schema};

struct QueryRoot;

#[Object]
impl QueryRoot {
    async fn health(&self) -> &str {
        "ok"
    }
}

let schema = Schema::build(QueryRoot, EmptyMutation, EmptySubscription).finish();

Step 3: bootstrap the app with GraphQL

Attach the schema to the NestForge HTTP runtime:

use nestforge::{GraphQlConfig, NestForgeFactory, NestForgeFactoryGraphQlExt};

let factory = NestForgeFactory::<AppModule>::create()?;
let config = factory.container().resolve::<AppConfig>()?;
let schema = build_schema(config.app_name.clone());

factory
    .with_graphql_config(schema, GraphQlConfig::new("/graphql").with_graphiql("/"))
    .listen(3001)
    .await?;

The maintained example mounts:

• /graphql
• /

Step 4: resolve providers from resolver context

When a resolver needs application state, resolve it from the NestForge container:

use nestforge::{async_graphql::Context, resolve_graphql};

async fn app_name(&self, ctx: &Context<'_>) -> String {
    let config = resolve_graphql::<AppConfig>(ctx).expect("app config should exist");
    config.app_name.clone()
}

This is the key integration point: GraphQL remains schema-driven, but still uses the same provider model as the rest of the app.

Step 5: test the schema through the testing module

Build the testing module, then mount the schema in test or by using the GraphQL router helpers:

let module = nestforge::TestFactory::<AppModule>::create().build()?;
let app = nestforge::graphql_router(schema).with_state(module.container().clone());

That is the shortest path for verifying resolvers against real container state.

What to verify

When GraphQL is first added, check these in order:

1. schema compiles
2. /graphql responds
3. resolvers can access required providers
4. provider overrides work in tests

What to read next

For the reference view of the GraphQL API, see GraphQL.