Welcome to Nexus

Nexus is a Node.js TypeScript-focused code-first GraphQL framework. It has three complementary aspects that you interact with:

  1. An API for building your fully featured GraphQL API. All features include a focus on type-safety autocompletion and jsDoc.
  2. A CLI for supporting your daily workflows while working.
  3. A plugin system spaning API and CLI for rich end-to-end plugins that you can use (or write) to fill in your niche needs.

Nexus is young, but growing fast. Every two weeks a new release is cut and we have a roadmap.

The Nexus API enables you to:

  • Build your GraphQL Schema
  • Build your Database Schema
  • Map DB schema to GQL one
  • Generate CRUD
  • Generate clients
  • Query your database
  • Manage app configuration
  • Log structured data
  • Build your HTTP server
  • System test your GraphQL API

The Nexus CLI supports you with:

  • The nexus dev command which watches and recompiles your API on every change with rich interactivity such as database migration prompts and managed tsconfig settings.
  • The nexus build command which builds an optimized bundle for lean deployments.

The goals of Nexus

  1. Scale gracefully from simple to complex, prototype to production
  2. Be type-safe without excessive generics or incomprehensible type errors
  3. Have an API that is declarative
  4. Be largely learnable by just using it
  5. Be deeply extensible
  6. Be zero Config
  7. Approach zero boilerplate

Highlights of Nexus

  • Type-safety by default - Take advantage of TypeScript without the hassle of type annotations everywhere
  • GraphQL Server included - We manage the GraphQL server for you while letting you control it
  • Bundled CLI for development workflows - Develop, test and build your app using our CLI
  • Reusable modules - Leverage your programming language to reuse parts of your GraphQL schema
  • Scalable - Split your GraphQL schema by features to horizontally scale as your project grows
  • Testable - Nexus includes tooling to run integration tests against your API
  • Zero config - Thanks to conventions over configuration, get up and running quickly without the hassle of configuring anything
  • Batteries included (DB, rate limiting, relay connections, custom scalars, ...) - We've got you covered beyond the to-do app
  • Readable - Implement your schema with code, read it with the autogenerated GraphQL SDL file
  • Pluggable - Make use of the Nexus plugin ecosystem or create yours to enhance the default experience
  • No lock-in - Buying into a framework can be scary. We make sure you've got the right escape hatches

Why Nexus

Nexus, the framework, is built on top of a great library called Nexus Schema, built by Tim Griesser.

« Nexus Schema was born out of my experience building several production GraphQL APIs, in different languages and frameworks. The first with vanilla graphql-js, another schema-first with graph.ql and later graphql-tools. Following that with graphene-python and most recently with a bit of graphql-ruby.

After working with the toolkits in other scripting languages, it felt like there was a gap in the JavaScript approaches. Schema-first development starts out great, by simply expressing your schema in the GraphQL Schema Definition Language (SDL) and providing resolvers matching to the types as needed you are up and running fast! No need for tons of requires or "overhead" to get a GraphQL server running.

As your schema then grows to hundreds or thousands of types, manually curating these SDL fragments becomes tedious. Documentation changes can be tough. Modifying fields on interfaces can require manual changes to many implementing types, a process that can be quite error prone.

If only there were a way to combine the simplicity of schema-first development, with the long-term maintainability of a definition-first approach.

Nexus Schema aims to fill that void, making the process as simple as possible while also making good use of the runtime to introduce powerful ways of composing types, introducing type or schema wide changes, and much more.

The core idea of Nexus Schema draws from basing the schema off the SDL - keeping things declarative and simple to understand. For example it allows you to reference the type names as string literals rather than always need to import to reference types (but, you can do that too if you prefer).

By combining automatic type generation with some of the more powerful features of TypeScript - type merging, conditional types, and type inference, we can know exactly which type names we are referring to and able to use throughout our code. We can know both the parameters and the return type of resolvers without providing any type annotation. It takes a little getting used to, but it ends up leading to a great feedback loop of the types annotating themselves. » — Tim Griesser

The complex mechanisms on which Nexus Schema relies turned out to produce a lot of friction to the daily workflows that people have to deal with when working with it.

Nexus, the framework, is a natural continuation of that vision built by Tim Griesser which aims to make Nexus Schema more accessible to everyone by hiding some of the underlying complexity of the system and by trying to push users into the pit of success.

Learning pre-requisites

Having a decent understanding of GraphQL and a bit of familiarity with TypeScript may help you adopt Nexus. If you like to dive in and learn on the fly feel free to do so, but if you do want to build up some pre-requisite knowledge upfront then the following resources may be of interest.

GraphQL

TypeScript

Diving In

Edit this page on Github