GraphQL Shield Generator

Automatically generate GraphQL Shield permissions from your GraphQL schema

Installation • Quick Start • Features • API Reference • Examples

⭐ Star us on GitHub if this project helped you!

Why GraphQL Shield Generator?

Transform your GraphQL schema into a complete permission system in seconds. No more manually writing repetitive shield configurations—let the generator handle it while you focus on your business logic.

// ✨ From this schema...
type User {
  id: ID!
  email: String!
  posts: [Post!]!
}

type Query {
  users: [User!]!
  me: User
}

// 🚀 To this shield instantly
export const permissions = shield({
  Query: {
    users: hasAuth,
    me: hasAuth,
  },
  User: {
    posts: hasAuth,
  },
});

Installation

# npm
npm install graphql-shield-generator

# yarn
yarn add graphql-shield-generator

# pnpm
pnpm add graphql-shield-generator

# bun
bun add graphql-shield-generator

Quick Start

Basic Usage

import { generateGraphqlShield } from 'graphql-shield-generator';

await generateGraphqlShield({
  schema: mySchema, // or { typeDefs, resolvers }
  options: {
    outputDir: './permissions',
    fileName: 'shield',
    extension: 'ts',
    moduleSystem: 'ES modules',
  },
});

Advanced Configuration

await generateGraphqlShield({
  schema: { typeDefs, resolvers },
  options: {
    outputDir: './permissions',
    fileName: 'shield',
    extension: 'ts',
    moduleSystem: 'ES modules',
    
    // 🔐 Use custom authentication rules
    customrule: 'hasAuth',
    customrulepath: './auth/rules',
    
    // 🛡️ Security-first approach
    fallbackRule: 'deny', // Deny by default, allow explicitly
    
    // 📊 Organized output
    groupbyobjects: true, // Order by Query → Mutation → Subscription
    
    // ⚙️ Shield configuration
    shieldoptions: '{ allowExternalErrors: true }',
  },
});

Features

🔐 Custom Authentication Rules

Replace default allow with your custom rules:

customrule: 'hasAuth',
customrulepath: './auth/hasAuth'

🛡️ Security-First Fallbacks

Configure default permissions for unlisted fields:

fallbackRule: 'deny'    // '*': deny (secure by default)
fallbackRule: 'allow'   // '*': allow (permissive)
fallbackRule: false     // No fallback (clean output)

📊 Smart Type Ordering

Organize your shield with logical type priority:

groupbyobjects: true  // Query → Mutation → Subscription → Custom Types

⚙️ Shield Configuration

Pass options directly to the GraphQL Shield constructor:

shieldoptions: '{ allowExternalErrors: true, debug: true }'

🎯 Perfect TypeScript Support

Generate .ts files with proper imports and types.

📦 Multiple Module Systems

Support for both ES modules and CommonJS.

Generated Output Examples

With Custom Rules + Security Fallback

import { shield, deny } from 'graphql-shield';
import { hasAuth } from './auth/hasAuth';

export const permissions = shield({
  Query: {
    '*': deny,
    users: hasAuth,
    me: hasAuth,
  },
  Mutation: {
    '*': deny,
    createUser: hasAuth,
    updateUser: hasAuth,
  },
  User: {
    '*': deny,
    posts: hasAuth,
  },
}, { allowExternalErrors: true });

Clean Output (No Fallback)

import { shield } from 'graphql-shield';
import { hasAuth } from './auth/hasAuth';

export const permissions = shield({
  Query: {
    users: hasAuth,
    me: hasAuth,
  },
  User: {
    posts: hasAuth,
  },
});

API Reference

generateGraphqlShield(config)

Option	Type	Default	Description
schema	GraphQLSchema | { typeDefs, resolvers }	-	Your GraphQL schema
options.outputDir	string	'.'	Output directory
options.fileName	string	'shield'	Generated file name
options.extension	'js' | 'ts'	'js'	File extension
options.moduleSystem	'CommonJS' | 'ES modules'	'CommonJS'	Module system
options.customrule	string	'allow'	Custom rule function name
options.customrulepath	string	-	Import path for custom rule
options.fallbackRule	'allow' | 'deny' | false	false	Default rule for unspecified fields
options.groupbyobjects	boolean	false	Order types by priority
options.shieldoptions	string	-	Options passed to shield constructor

Examples

Check out the /example directory for comprehensive examples including:

• Basic shield generation
• Custom authentication rules
• Security-first configurations
• All feature combinations
• CommonJS and ES modules examples

Run the examples:

cd example
npm install
npm run test-fixes

Use Cases

🏢 Enterprise Applications

• Secure by default with fallbackRule: 'deny'
• Custom authentication rules
• Organized type structure

🚀 Rapid Prototyping

• Quick shield generation
• Permissive defaults for development
• Easy customization as you grow

🔄 Schema Evolution

• Automatic shield updates when schema changes
• Consistent permission structure
• No manual maintenance

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/omar-dulaimi/graphql-shield-generator.git
cd graphql-shield-generator
npm install
npm run build

License

MIT © Omar Dulaimi

---

Made with ❤️ by Omar Dulaimi