Shared GraphQL

GraphQL schema definitions, generated types, and utilities for the Substrate API.

For detailed usage documentation, see the Shared GraphQL documentation on the docs site.

Contributing

Prerequisites

• Node.js 20+ and Yarn
• Understanding of GraphQL schemas and resolvers
• Familiarity with GraphQL Code Generator

Commands

# Build the package
nx build shared-graphql

# Run tests
nx test shared-graphql

# Generate TypeScript types from GraphQL schemas
nx generate shared-graphql

# Lint the package
nx lint shared-graphql

# Clean build artifacts
nx clean shared-graphql

Project Structure

packages/shared-graphql/
├── src/
│   ├── schemas/         # GraphQL schema definitions (.graphql files)
│   │   ├── schema.graphql       # Base types (Query, Mutation, ApiError, etc.)
│   │   ├── user/
│   │   │   └── schema.graphql   # User and Profile types
│   │   └── org/
│   │       └── schema.graphql   # Organization and Membership types
│   ├── auth/            # Authentication utilities
│   │   ├── index.ts             # Auth utilities exports
│   │   └── mock-provider.ts     # Mock auth provider for development
│   ├── generated/       # Auto-generated TypeScript types
│   ├── types.ts         # GraphQL-specific TypeScript types
│   └── index.ts         # Package exports
├── docs/                # Documentation (built to docs site)
├── codegen.ts           # GraphQL Code Generator config
└── README.md            # This file

Working with GraphQL Schemas

Adding New Schema Types

1. Create or edit a .graphql file in src/schemas/
2. Run nx generate shared-graphql to generate TypeScript types
3. Use the generated types in your resolvers and client code

Code Generation

The package uses GraphQL Code Generator to automatically generate TypeScript types from GraphQL schemas. Configuration is in codegen.ts.

Generated types are placed in src/generated/ and should not be manually edited.

Environment Variables

Variable	Description	Default
AUTH_MOCK_ENABLED	Enable mock authentication in development	false
AUTH_MOCK_DOMAIN	Email domain for mock auth (e.g., "@dev.local")	@dev.local

OAuth Scopes

The package includes OAuth scope definitions and utilities for authorization. See the documentation for details on using scopes in your GraphQL resolvers.

Related Documentation

• Root README - Substrate overview
• Docs README - Documentation site
• GraphQL Documentation - GraphQL best practices