GraphQL Shield Generator

Automatically generate GraphQL Shield permissions from your GraphQL schema

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