Multi-Project Workspaces

For monorepos or applications with multiple GraphQL schemas, use the projects key to define independent GraphQL projects in a single config file.

Basic multi-project setup

.graphqlrc.yml

projects:
  api:
    schema: api/schema.graphql
    documents: api/**/*.graphql
  client:
    schema: client/schema.graphql
    documents: client/**/*.{graphql,tsx}

Each project is fully independent — it has its own schema, documents, and lint configuration.

Scoping files with include/exclude

Use include and exclude to precisely control which files belong to each project. This is especially useful when document patterns alone would be ambiguous:

projects:
  web:
    schema: packages/web/schema.graphql
    documents: packages/web/src/**/*.{graphql,tsx}
    include:
      - packages/web/**
    exclude:
      - packages/web/**/__tests__/**
  api:
    schema: packages/api/schema.graphql
    documents: packages/api/src/**/*.graphql
    include:
      - packages/api/**

include restricts the project to files under those paths. exclude removes files from the project even if they match other patterns. Both accept glob patterns.

Per-project client configuration

The client extension field (apollo | relay | none) controls which client-side directives are recognized for that project. For example, setting client: apollo makes @client, @connection, and other Apollo-specific directives valid in operations:

projects:
  web:
    schema: packages/web/schema.graphql
    documents: packages/web/src/**/*.{graphql,tsx}
    extensions:
      graphql-analyzer:
        client: apollo
  api:
    schema: packages/api/schema.graphql
    documents: packages/api/src/**/*.graphql
    extensions:
      graphql-analyzer:
        client: none

Per-project linting

projects:
  web:
    schema: packages/web/schema.graphql
    documents: packages/web/src/**/*.{graphql,tsx}
    extensions:
      graphql-analyzer:
        lint:
          extends: recommended
  api:
    schema: packages/api/schema/**/*.graphql
    documents: packages/api/src/**/*.graphql
    extensions:
      graphql-analyzer:
        lint:
          extends: recommended
          rules:
            noUnusedFields: error

Using with the CLI

Specify a project with --project:

# Validate a specific project
graphql --project api validate

# Lint a specific project
graphql --project client lint

# Without --project, all projects are checked
graphql check

Using with the LSP

The LSP automatically detects which project a file belongs to based on the documents patterns. Each file is validated against its project’s schema.

Real-world example: monorepo

projects:
  web:
    schema: packages/web/schema.graphql
    documents: packages/web/src/**/*.{graphql,tsx}
    extensions:
      graphql-analyzer:
        lint:
          extends: recommended
  mobile:
    schema: packages/mobile/schema.graphql
    documents: packages/mobile/src/**/*.{graphql,ts}
    extensions:
      graphql-analyzer:
        lint:
          extends: recommended
  api:
    schema: packages/api/schema/**/*.graphql
    documents: packages/api/src/**/*.graphql
    extensions:
      graphql-analyzer:
        lint:
          extends: recommended