graphql-shield: a permission layer for GraphQL resolvers

The problem graphql-shield targets: authorization spread across resolvers

In a plain GraphQL server, access checks usually end up inside resolvers. Each resolver repeats a variant of the same question: does this caller get to see this field? The README frames the project as a way to "create a permission layer for your application" using an "intuitive rule-API", so that permissions sit outside the resolver body. That is the whole pitch, and it is a narrow one.

The audience is GraphQL server authors who already have a schema and want a declarative place to say who can reach what. The README states the tool is "Compatible: Works with all GraphQL Servers", which is a claim about the middleware layer it builds on rather than about the tool itself. The repository layout backs this up: examples/ contains directories for basic, advanced, with-apollo-server-lambda, with-graphql-middleware-forward-binding and with-graphql-nexus. That is a set of integration shapes, not a framework lock-in.

If your authorization logic is already centralized in a gateway or a data layer, this project adds a second place to look. Its value is highest when permissions are naturally expressed against the schema, per type or per field.

How the shield engine sits between the request and the resolver

graphql-shield is built on GraphQL Middleware, and the README lists that as the first feature: "Flexible: Based on GraphQL Middleware". The practical consequence is that the shield does not parse or execute your query itself. It registers as a middleware layer over the schema, and the middleware layer is what the server calls before the resolver runs.

Rules are attached per type or per field. The README describes this as "Per-Type or Per-Field: Write permissions for your schema, types or specific fields". A rule is a function that receives the resolver arguments and returns a decision; the engine then either lets the resolver proceed or replaces the result with an error. Because the decision is made before the resolver body executes, a denied field never reaches your data access code.

The README also claims an "Intelligent V8 Shield engine" that "caches all your requests to prevent any unnecessary load". This is the part of the design worth scrutinizing. Caching rule results per request means a rule that depends on mutable state within a single query can behave differently from one that depends only on the caller. The README does not describe the cache key, the cache lifetime, or how to invalidate it. Anyone relying on per-request caching should read the documentation site at https://the-guild.dev/graphql/shield rather than the README, because the README stops at the claim.

Installing graphql-shield and applying a first rule

The package is published on npm as graphql-shield. The README's badge links to the npm page, and the repository is a pnpm workspace with packages/* as the workspace globs. A consumer installs the published package, not the workspace.

npm install graphql-shield

After installation, the documented pattern is to build a permissions object and apply it to the schema through the middleware layer. The README does not reproduce a full code sample, so the exact rule API is defined on the documentation site at https://the-guild.dev/graphql/shield. What the README does confirm is the shape of the integration: a rule-API, a shield engine applied on every request, and permissions written per type or per field.

The repository ships runnable integrations under examples/. The directories are basic, advanced, with-apollo-server-lambda, with-graphql-middleware-forward-binding and with-graphql-nexus. If you want a working reference before writing your own permissions, those directories are the place the project itself points to. The README does not state which example to start with.

One practical note: the repository's root package.json is marked "private": true and its build script is bob build, with a prerelease step of yarn build and a release step of changeset publish. That is the maintainers' release machinery, not something an application author needs to run.

Where graphql-shield is the wrong tool

The README's feature list is short, and the gaps matter. There is no mention of query cost analysis, depth limiting, or rate limiting. A permission layer answers whether a caller may reach a field; it does not answer whether the query is expensive. A client that is allowed to read a field can still ask for it in a shape that is costly to resolve, and graphql-shield has nothing to say about that.

The caching claim is also a limitation in disguise. "Caches all your requests" is stated without a described invalidation model. If a rule reads context that changes during request processing, the documented behaviour does not tell you what happens. The README is silent on this, which is a reason to treat the cache as something to verify against the documentation site before depending on it.

Finally, the README is a landing page, not a reference. It links to https://the-guild.dev/graphql/shield for "extensive documentation" and stops there. For a project whose entire value is an API surface, that is a thin repository README. An engineer who evaluates tools by reading the repository will not find the rule API here.

On maintenance, the repository is not archived, and the last push was on 2026-09-19. The most recent releases listed are from 2022: release-1669144116521 on 2022-11-22, release-1666970453565 on 2022-10-28, and release-1665995493587 on 2022-10-17. Commits and published releases are not the same thing, and the release history is the more relevant signal for a library you install.

graphql-shield alternatives and how they differ

The search data around this project is full of people looking for a replacement, which is itself informative. The most direct alternative in that list is GraphQL Armor. The difference in approach is the layer being defended. graphql-shield decides access per type and per field, at resolver level, and returns an error when a rule denies. GraphQL Armor addresses query-level protections rather than per-field permissions.

That distinction decides the choice. If your question is "may this user read this field", graphql-shield is the shape you want. If your question is "should this query be allowed to run at all", a query-level protection layer is the shape you want, and a permission layer is not a substitute.

A second alternative is to write the checks yourself in resolver wrappers or a schema directive. That keeps the dependency count at zero and keeps everything in your repository, at the cost of reimplementing the rule composition and the per-request caching that graphql-shield already provides. The trade is maintenance burden against an external dependency whose behaviour is documented outside the repository.

The repository's own examples hint at how much integration surface the project expects. with-graphql-middleware-forward-binding and with-apollo-server-lambda are not trivial setups. If your server build does not already route through GraphQL Middleware, adopting graphql-shield means adopting that layer too.

Licence and upgrade cost

graphql-shield is MIT licensed, as stated in the README ("MIT @ Matic Zavadlal") and in the repository's LICENSE file and root package.json license field. MIT permits commercial use and modification with the licence and copyright notice retained. That is a permissive baseline; it is not legal advice, and if your organization has specific obligations around attribution, check with counsel.

Upgrade cost is the more interesting question. The repository uses changesets: the root package.json defines a release script of changeset publish and depends on @changesets/cli and @changesets/changelog-github. That means version bumps and changelogs are generated from changeset files rather than hand-written release notes. The .changeset/ directory is present at the top level. For a consumer, that is a reasonable release discipline, but it also means the changelog is generated from commit-level entries.

The listed releases stop in 2022 while the last push is on 2026-09-19. If you pin to the latest published version, you are pinning to something from 2022. Before upgrading, read the generated changelog for the version you are moving to; the README does not document a rollback path, and neither does the repository layout suggest a compatibility shim.

Editorial conclusion

Adopt graphql-shield if your GraphQL server already runs through GraphQL Middleware and you want permissions expressed as rules on types and fields rather than scattered checks inside resolvers. Do not adopt it if you need every rule documented in the repository README, or if you want an engine that inspects query cost and depth rather than resolver access. Before committing, verify three things: that your server build can apply a middleware layer, that the rule API you need is documented on the project's documentation site rather than in the README, and that your team accepts a dependency whose README defers to an external docs page.

Frequently asked questions

Official sources

1. License: MIT
2. maticzav/graphql-shield on GitHub
3. Project website
4. README
5. Releases