What is NecrassRs?

NecrassRs is an SDL-first GraphQL server framework for Rust. You define your public API in GraphQL Schema Definition Language (SDL), and NecrassRs turns that schema into Rust types, resolver contracts, and dispatch code during Cargo builds. You implement the resolver bodies with your application’s logic.

The schema describes what clients can request. Rust implements how those requests are fulfilled. Your application runs the web server, registers the GraphQL endpoint, and supplies the Context that resolvers need for each request.

Why NecrassRs?

GraphQL is most useful when frontend and backend developers can read the same public API contract: what data is available, how it is shaped, and which constraints apply. When that contract is inferred from Rust code, its source is tied to the host language instead of being expressed in GraphQL’s own schema language.

NecrassRs makes GraphQL SDL the source of truth. Cargo builds turn that language-independent contract into Rust types, resolver contracts, and dispatch code. This reduces repetitive declarations and catches mismatches between the schema and its Rust implementation at compile time, while leaving application developers to write the business logic in ordinary Rust resolver bodies.

Key features

• SDL-first API definition. Define fields, arguments, and types in GraphQL SDL. NecrassRs derives Rust contracts from that schema.
• Cargo-integrated generation. Your build script invokes necrassrs-build during ordinary Cargo builds. After project initialization, schema changes do not require a separate CLI generation command.
• Resolver source synchronization. Builds create new resolver stubs and preserve the bodies of retained fields. Deleted or renamed fields remove untouched generated stubs; an edited body, attribute, or comment stops synchronization until you remove or migrate it. Unrelated application code is preserved.
• Typed async resolvers. Generated argument types and resolver traits connect GraphQL inputs and results to Rust types. The compiler checks implementations against those contracts, and async methods can borrow request Context.
• Application-owned HTTP integration. Adapters handle GraphQL request extraction and response conversion. Your application chooses routes, middleware, shared state, and how to construct Context. The execution core is independent of the HTTP framework.

Under active development

The generated API supports built-in and application-owned custom scalars, enum results, ordinary and OneOf input objects, owned Object results, Interface and Union results, nullable and list forms, recursive input and Object relationships, and generated query, mutation, and subscription routing. Borrowed Object results and subscription transports remain unsupported. These pages describe the current source checkout. Consult the published package’s docs.rs API reference when using a released version.

Namesake

NecrassRs is named after Eblana Dublin (Necrass), an operator in the game Arknights.

Special Thanks

Special thanks to XiNiHa for his contributions to NecrassRs: sparking the initial idea by highlighting gaps in Rust’s GraphQL ecosystem, introducing tonic as a valuable reference point, creating solid-relay, and continually helping shape the API through thoughtful discussions.

Next steps

• Reed: learn about the GraphQL compiler toolkit used by NecrassRs.
• Tutorial: build a GraphQL web server and send queries and mutations with GraphiQL or HTTP.
• Personnel Management System: add Object, Interface, and Union results to a working server.
• Types: Rust type mappings, input presence, defaults, and generated input types.
• Custom Scalars: define scalar storage, input coercion, output serialization, and regeneration behavior.
• Subscriptions: create event sources, consume responses, and handle errors and cancellation.