graphql-tools Documentation

Wrench: Utility library for GraphQL to build, stitch and mock GraphQL schemas in the SDL-first approach

5,430 stars TypeScript TypeScript 1 file · ~3,107 tokens #graphql#graphql-api#graphql-js#graphql-schema#javascript#mock#schema-language#schema-stitching
RAW Doc

1. Project Overview & Quickstart (ardatan/graphql-tools)

File: README.md





renovate-app badge

This package provides a few useful ways to create a GraphQL schema:

  1. Use the GraphQL schema language to
    generate a schema with full support for
    resolvers, interfaces, unions, and custom scalars. The schema produced is completely compatible
    with GraphQL.js.
  2. Mock your GraphQL API with fine-grained per-type
    mocking
  3. Automatically
    stitch multiple schemas together
    into one larger API

Documentation

Read the docs.

Binding to HTTP

If you want to bind your JavaScript GraphQL schema to an HTTP server, you can use
GraphQL Yoga .

You can develop your JavaScript based GraphQL API with graphql-tools and GraphQL Yoga together:
One to write the schema and resolver code, and the other to connect it to a web server.

Example

When using graphql-tools, you describe the schema as a GraphQL type language string:

js
const typeDefs = /* GraphQL */ `
  type Author {
    id: ID! # the ! means that every author object _must_ have an id
    firstName: String
    lastName: String
    """
    the list of Posts by this author
    """
    posts: [Post]
  }

  type Post {
    id: ID!
    title: String
    author: Author
    votes: Int
  }

  # the schema allows the following query:
  type Query {
    posts: [Post]
  }

  # this schema allows the following mutation:
  type Mutation {
    upvotePost(postId: ID!): Post
  }

  # we need to tell the server which types represent the root query
  # and root mutation types. We call them RootQuery and RootMutation by convention.
  schema {
    query: Query
    mutation: Mutation
  }
`

export default typeDefs

Then you define resolvers as a nested object that maps type and field names to resolver functions:

js
const resolvers = {
  Query: {
    posts() {
      return posts
    }
  },
  Mutation: {
    upvotePost(_, { postId }) {
      const post = find(posts, { id: postId })
      if (!post) {
        throw new Error(`Couldn't find post with id ${postId}`)
      }
      post.votes += 1
      return post
    }
  },
  Author: {
    posts(author) {
      return filter(posts, { authorId: author.id })
    }
  },
  Post: {
    author(post) {
      return find(authors, { id: post.authorId })
    }
  }
}

export default resolvers

At the end, the schema and resolvers are combined using makeExecutableSchema:

js
import { makeExecutableSchema } from '@graphql-tools/schema'

const executableSchema = makeExecutableSchema({
  typeDefs,
  resolvers
})

GraphQL-Tools schema can be consumed by frameworks like GraphQL Yoga, Apollo GraphQL or
express-graphql For example in Node.js;

js
const { createYoga } = require('graphql-yoga')
const { createServer } = require('http')

const yoga = createYoga({
  schema: executableSchema
})

const server = createServer(yoga)

server.listen(4000, () => {
  console.log('Yoga is listening at http://localhost:4000/graphql')
})

You can check GraphQL Yoga for other JavaScript platforms and
frameworks besides vanilla Node.js HTTP.

This example has the entire type definition in one string and all resolvers in one file, but you can
combine types and resolvers from multiple files and objects, as documented in the
modularizing type definitions
and merging resolvers section of
the docs.

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed
a bug for yourself, please consider submitting a PR!

And if this is your first time contributing to this project, please do read our
Contributor Workflow Guide
before you get started off.

Code of Conduct

Help us keep GraphQL Tools open and inclusive. Please read and follow our
Code of Conduct as adopted
from Contributor Covenant

Maintainers

File: packages/webpack-loader/README.md

GraphQL Tools Webpack Loader

A webpack loader to preprocess GraphQL Documents (operations, fragments and SDL)

Slightly different fork of
graphql-tag/loader.

text
npm install @graphql-tools/webpack-loader

How is it different from graphql-tag? It removes locations entirely, doesn't include sources
(string content of imported files), no warnings about duplicated fragment names and supports more
custom scenarios.

Options

  • noDescription (default: false) - removes descriptions
  • esModule (default: false) - uses import and export statements instead of CommonJS

Importing GraphQL files

To add support for importing .graphql/.gql files, see
Webpack loading and preprocessing below.

Given a file MyQuery.graphql

graphql
query MyQuery {
  ...
}

If you have configured
the webpack @graphql-tools/webpack-loader, you can import
modules containing graphQL queries. The imported value will be the pre-built AST.

ts
import MyQuery from './query.graphql'

Preprocessing queries and fragments

Preprocessing GraphQL queries and fragments into ASTs at build time can greatly improve load times.

Webpack loading and preprocessing

Using the included @graphql-tools/webpack-loader it is possible to maintain query logic that is
separate from the rest of your application logic. With the loader configured, imported graphQL files
will be converted to AST during the webpack build process.

js
{
  loaders: [
    {
      test: /\.(graphql|gql)$/,
      exclude: /node_modules/,
      loader: '@graphql-tools/webpack-loader',
      options: {
        /* ... */
      }
    }
  ],
}

File: packages/schema/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/schema_src

You can also learn more about Generating Executable Schemas in this chapter;
https://www.graphql-tools.com/docs/generate-schema

File: packages/resolvers-composition/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/resolvers_composition_src

You can also learn more about Resolvers Composition in this chapter;
https://www.graphql-tools.com/docs/resolvers-composition

File: packages/relay-operation-optimizer/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/relay_operation_optimizer_src

You can also learn more about Relay Operation Optimizer in this chapter;
https://www.graphql-tools.com/docs/relay-operation-optimizer

File: packages/optimize/README.md

GraphQL Tools: `DocumentNode` Optimizer

This package is intended to allow developers to optimize DocumentNode objects created by graphql
library.

It's built as a set of small optimizers you can compose to get the most out of your GraphQL setup.

The goal of this package is mostly around making optimizations for the way the data is stored in
DocumentNode, and not to the essence of the DocumentNode.

Getting Started

text
npm install -D @graphql-tools/optimize

API

To get started with this tool, import it and run it over your DocumentNode.

ts
import { optimizeDocumentNode } from '@graphql-tools/optimize';

const myDocument: DocumentNode = { ... }
const optimizedDocument = optimizeDocumentNode(myDocument);

Customizing Optimizers

By default, we apply all optimizers available in this repo over your document. It shouldn't effect
any runtime since we just remove dead or unused areas.

You can modify the list of optimizers this way:

ts
import { optimizeDocumentNode, removeDescriptions } from '@graphql-tools/optimize';

const myDocument: DocumentNode = { ... }
const optimizedDocument = optimizeDocumentNode(myDocument, [removeDescriptions]);

Writing your own optimizer

You can create your own optimizer to manipulate DocumentNode, the API signature is pretty simple:

ts
export type DocumentOptimizer = (input: DocumentNode) => DocumentNode

Take a look at [./optimizers](this directory for inspiration and implementation reference).

File: packages/mock/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/mock_src

You can also learn more about Mocking in this chapter; https://www.graphql-tools.com/docs/mocking

File: packages/merge/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/merge_src

You can also learn more about Schema Merging in this chapter;
https://www.graphql-tools.com/docs/schema-merging

File: packages/load-files/README.md

Check API Reference for more information about this package;
https://www.graphql-tools.com/docs/api/modules/load_files_src

You can also learn more about File Loading in this chapter;
https://www.graphql-tools.com/docs/schema-merging#file-loading

2. Official Technical Reference & Guides (ardatan/website)

website

Public website for ITUGnu


INSTALL

  • Clone project from git
  • Create virtual environment: virtualenv venv -p python3.6
  • Switch to virtual environment: source venv/bin/activate
  • Install requirements: pip install -r requirements.txt
  • Create local_settings.py file in the project root directory
  • Initialize database: ./manage.py migrate
  • Run application: ./manage.py runserver

DEPLOYMENT

  • Ubuntu: apt install python3.6 python3.6-dev nginx libpq-dev postgresql postgresql-contrib
  • Set-up database and create settings file using cp local_settings.template.py local_settings.py (hint: use link (ln -s))
  • Install virtualenv: sudo pip3 install virtualenv
  • Create user: useradd -m itugnu
  • Check etc folder for deployment files (nginx & supervisor)
  • Application uses gunicorn and PostgreSQL (psycopg2-binary) database for deployment
  • Translations needs to be compiled to use them: ./manage.py compilemessages

LICENSE

text
Copyright 2018 ITUGnu 

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

AUTHORS

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#graphql Browse graphql catalog → #graphql-api Browse graphql-api catalog → #graphql-js Browse graphql-js catalog → #graphql-schema Browse graphql-schema catalog → #javascript Browse javascript catalog → #mock Browse mock catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →