From Zero to Hero: Getting Started with GraphQL, Strapi and Next.js 16 Part 2

Part 2 of a 4-part series on building with GraphQL, Strapi v5, and Next.js 16. Each part builds directly on the project from the previous post, so keep an eye out as we release them:

• Part 1, GraphQL basics with Strapi v5. Fresh install, a full Shadow CRUD tour, and your first custom resolvers.
• Part 2 (this post), Advanced backend customization. A Note + Tag model, middlewares and policies, Shadow CRUD restrictions, custom queries, and custom mutations.
• Part 3, Next.js 16 frontend. Apollo Client on the App Router: Server Component reads, Server Action writes.
• Part 4, Users and per-user content. Authentication, an ownership model, and two-layer authorization (read middlewares, write policies).

New to Strapi or GraphQL? Start with Part 1. Already comfortable with Shadow CRUD and basic custom resolvers? You are in the right place.

TL;DR

• This post picks up directly from Part 1. Same Strapi v5 project, same src/extensions/graphql/ folder, same aggregator. Nothing gets thrown out; everything new is added alongside.
• You will add a small note-taking model in the Content-Type Builder (a Note and a Tag, joined many-to-many), then use it to walk through the rest of the GraphQL plugin's customization APIs.
• What is covered: middlewares and a named policy via resolversConfig; turning parts of Shadow CRUD off (actions, output fields, filter inputs); adding new object types for aggregate responses with nexus.objectType; three custom queries that use the Document Service (and one raw-SQL example with strapi.db.connection.raw); three custom mutations.
• Every resolver added here is tested in the Apollo Sandbox before moving on. Part 3 picks up the same schema and consumes it from a Next.js 16 App Router frontend.
• Who this is for: developers who finished Part 1, or anyone with a Strapi v5 project that already has @strapi/plugin-graphql installed and a working aggregator under src/extensions/graphql/.

Picking up from Part 1

Part 1 left you with a Strapi v5 project named server. It has the example blog model (Article, Author, Category), @strapi/plugin-graphql installed and configured in config/plugins.ts, and a small customization folder under src/extensions/graphql/ containing an aggregator, a computed-fields factory (Article.wordCount), and a custom-queries factory (Query.searchArticles).

Here is the folder you ended Part 1 with:

1server/
2├── config/
3│   └── plugins.ts                        # depthLimit, maxLimit, defaultLimit, landingPage, introspection
4└── src/
5    ├── index.ts                          # calls registerGraphQLExtensions
6    └── extensions/
7        └── graphql/
8            ├── index.ts                  # aggregator
9            ├── computed-fields.ts        # Article.wordCount
10            └── queries.ts                # Query.searchArticles

In this post we will add:

• Two new content types (Note and Tag) through the admin UI.
• One new file under src/extensions/graphql/: middlewares-and-policies.ts.
• A policy file at src/policies/cap-page-size.ts.
• New entries in the existing computed-fields.ts and queries.ts (alongside what Part 1 wrote, not in place of it).
• A new mutations.ts under src/extensions/graphql/.
• Updated wiring in src/extensions/graphql/index.ts to register the three new factories.

If you skipped Part 1, run through it first. The setup, plugin configuration, and aggregator scaffolding are not repeated here.

What you will build

The note-taking model has two collection types:

• Tag: name (text), slug (UID), color (enumeration with a fixed palette). No relations to define by hand; the inverse relation back to Note is generated for you.
• Note: title (text), content (rich text, Markdown), pinned (boolean, default false), archived (boolean, default false), internalNotes (long text, marked private), plus a many-to-many relation to Tag.

Then, in order:

1. Hide internalNotes from the public schema and close off filter access to it.
2. Add a soft-delete contract to Query.notes and Query.note using middlewares, and cap the page size with a named policy.
3. Add three computed fields to Note: wordCount, readingTime, and excerpt(length: Int).
4. Add two new object types, NoteStats and TagCount, for aggregate responses.
5. Add three custom queries: searchNotes, noteStats, and notesByTag.
6. Add three custom mutations: togglePin, archiveNote, and duplicateNote.

By the end, every customization API the GraphQL plugin exposes has been used at least once against a realistic model.

Step 1: Create the Tag content type

Start the dev server if it is not already running:

npm run develop

Open the admin UI at http://localhost:1337/admin, then:

1. Click Content-Type Builder in the left sidebar (the blocks icon).
2. Under Collection Types, click Create new collection type.
3. Set Display name to Tag. Leave API ID (singular) as tag and API ID (plural) as tags. Click the Advanced Settings tab in the same dialog and uncheck Draft & Publish. Click Continue.
4. In the Select a field modal:
   • Click Text, name it name, leave the type as Short text. Open the Advanced settings tab and check Required field. Click Add another field.
   • Click UID, name it slug, and set Attached field to name. Click Add another field.
   • Click Enumeration, name it color, and add these values one per line: red, blue, green, yellow, purple, gray. Open the Advanced settings tab and set Default value to gray. Click Finish.
5. Click Save in the top right. The server restarts.

Tags are pure labels, so Draft & Publish adds nothing here. Turning it off means a tag is live the moment you save it, and you do not have to pass status: 'published' in any tag-related query later.

Here is the final look at our tag collection:

Open src/api/tag/content-types/tag/schema.json to confirm the attributes look right:

1{
2  "kind": "collectionType",
3  "collectionName": "tags",
4  "info": {
5    "singularName": "tag",
6    "pluralName": "tags",
7    "displayName": "Tag"
8  },
9  "options": {
10    "draftAndPublish": false
11  },
12  "pluginOptions": {},
13  "attributes": {
14    "name": {
15      "type": "string",
16      "required": true
17    },
18    "slug": {
19      "type": "uid",
20      "targetField": "name"
21    },
22    "color": {
23      "type": "enumeration",
24      "default": "gray",
25      "enum": ["red", "blue", "green", "yellow", "purple", "gray"]
26    }
27  }
28}

Step 2: Create the Note content type

Back in the Content-Type Builder:

1. Click Create new collection type under Collection Types.
2. Set Display name to Note and click the Advanced Settings tab in the same dialog. Uncheck Draft & Publish. Click Continue. (Turning Draft & Publish off on Note means our custom resolvers do not need to pass status: 'published'. Article in Part 1 had it on, which is why searchArticles had to pass it.)
3. Add the fields one at a time:
   • Text named title, Short text, Required.
   • Rich text (Markdown) named content. (Strapi has two rich-text variants: Blocks, an AST-style array, and Markdown, a plain string. Markdown is easier to render on the Next.js frontend in Part 3 and cheaper to handle on the backend, so we use it here.)
   • Boolean named pinned. Under Advanced settings, set Default value to false.
   • Boolean named archived. Under Advanced settings, set Default value to false.
   • Text named internalNotes, Long text. No required flag. Open the Advanced settings tab and check Private field. internalNotes is admin-only context (moderation notes, triage flags, anything the public API should never see). Marking it private keeps it out of every client-facing surface. On REST, Strapi strips private attributes from response bodies during sanitization. On GraphQL, the plugin goes further and removes private attributes from the output type, the filter input type, and the mutation input type. We verify this with an introspection query right after the schema snippet below.

4. Add the relation to Tag:
   • Click Relation in the field picker.
   • In the relation builder, the left card is Note (you are editing it) and the right card is the target. Click the right-hand dropdown and pick Tag.
   • Choose the many-to-many icon (the one where both sides show multiple arrows). The field on the Note side should be named tags, the inverse field on the Tag side should be named notes.
   • Click Finish.
5. Click Save. The server restarts again.

Open src/api/note/content-types/note/schema.json to confirm the attributes look right:

1{
2  "kind": "collectionType",
3  "collectionName": "notes",
4  "info": {
5    "singularName": "note",
6    "pluralName": "notes",
7    "displayName": "Note"
8  },
9  "options": {
10    "draftAndPublish": false
11  },
12  "pluginOptions": {},
13  "attributes": {
14    "title": {
15      "type": "string",
16      "required": true
17    },
18    "content": {
19      "type": "richtext"
20    },
21    "pinned": {
22      "type": "boolean",
23      "default": false
24    },
25    "archived": {
26      "type": "boolean",
27      "default": false
28    },
29    "internalNotes": {
30      "type": "text",
31      "private": true
32    },
33    "tags": {
34      "type": "relation",
35      "relation": "manyToMany",
36      "target": "api::tag.tag",
37      "inversedBy": "notes"
38    }
39  }
40}

Verify private: true hid internalNotes from GraphQL

Open the Apollo Sandbox at http://localhost:1337/graphql and run:

1query PrivateReference {
2  note: __type(name: "Note") {
3    fields {
4      name
5    }
6  }
7  filter: __type(name: "NoteFiltersInput") {
8    inputFields {
9      name
10    }
11  }
12  input: __type(name: "NoteInput") {
13    inputFields {
14      name
15    }
16  }
17}

Scan all three lists in the response. internalNotes is absent from every one. The GraphQL plugin reads the private: true flag out of schema.json and removes the attribute from the output type, the filter input type, and the mutation input type in one go. REST sanitization strips it from response bodies at the same time, so GET /api/notes never returns it either.

This is the Strapi-native way to hide sensitive fields from the public API. No extension code needed.

Step 3: Grant public permissions for Note and Tag

Same flow as Part 1, applied to the new content types.

1. In the admin UI, open Settings (gear icon, bottom of the left sidebar).
2. Under Users & Permissions Plugin, click Roles, then Public.

3. Expand Note and check find, findOne, create, and update. Leave delete unchecked. The frontend uses soft-delete via the archived flag, so the public API should never be able to hard-delete a note.

4. Expand Tag and check find, findOne, create, update, and delete.

5. Click Save.

Step 4: Seed a handful of entries

The queries, policies, and aggregations later in this post need data to return. Create a few entries by hand so the Sandbox has something to work with.

Create three Tag entries through Content Manager, Tag, Create new entry. Suggested starter values:

Strapi renders the color field as a dropdown with the six values from Step 1. The frontend in Part 3 maps each enum value to a Tailwind class, so you do not need to use every color in your seed data.

Click Save

Create three Note entries through Content Manager, Note, Create new entry. For each note:

• Pick a title like Weekly review, Gift ideas, or Side-project backlog.
• In content, add a paragraph or two of text. The wording does not matter, but make each note at least a sentence long so wordCount returns a real count in Step 7. (readingTime uses Math.max(1, ...) so it is always at least 1, even on an empty note.)
• Toggle pinned on for one of the three; leave the others off.
• Leave archived off for all of them. You can flip one to archived: true later when testing the archive rules.
• Fill internalNotes with anything, for example moderator flag: low priority. The private: true flag from Step 2 keeps it out of every public GraphQL and REST response, so whatever you write here only shows up in the admin UI.
• Under Tags, add one or two tags from the dropdown.
• Click Save.

Three notes are enough to test every resolver in the rest of the post. Add more if you like.

Step 5: Shadow CRUD, what it is and why you rarely customize it

Shadow CRUD is how Strapi auto-generates your GraphQL schema at boot. At startup, the GraphQL plugin reads every registered content type and emits matching queries, mutations, input types, and filter types. Everything you used in Part 1, the full notes / note / createNote / updateNote surface, came out of Shadow CRUD.

The plugin does expose an extension API for turning parts of the generated schema off:

1strapi
2  .plugin("graphql")
3  .service("extension")
4  .shadowCRUD("api::note.note")
5  .disable() // remove the whole content type
6  .disableQueries() // remove find/findOne
7  .disableMutations() // remove create/update/delete
8  .disableAction("delete");
9
10strapi
11  .plugin("graphql")
12  .service("extension")
13  .shadowCRUD("api::note.note")
14  .field("internalNotes")
15  .disable() // remove the field entirely
16  .disableOutput() // remove from the Note output type
17  .disableInput() // remove from create/update inputs
18  .disableFilters(); // remove from NoteFiltersInput

The full vocabulary, for reference:

Documented in full on the GraphQL plugin docs page.

Most projects skip this API

Two simpler tools cover almost everything you would use Shadow CRUD customization for:

1. Permissions already block calls at runtime. If you do not want the public role calling deleteNote, uncheck delete for the Public role in Step 3. The REST endpoint and the GraphQL resolver both return a Forbidden error. The mutation still appears in the schema, but no one can actually run it.
2. private: true already hides sensitive fields. Step 2 put private: true on internalNotes. The GraphQL plugin removes the field from the Note output type, from NoteFiltersInput, and from NoteInput. No extension file needed.

So when would you use Shadow CRUD customization? When you also want the field or action gone from the schema itself, so it does not show up in the Sandbox docs panel, in introspection responses, or in generated client types. Permissions block the call but leave the schema unchanged. Shadow CRUD customization changes the schema. For most projects the runtime block is enough, so this tutorial does not add a shadow-crud.ts file.

For real access control, use permissions (Step 3) and private: true (Step 2) first, then middlewares and policies (Step 6) for anything those two cannot express.

Step 6: resolversConfig, middlewares and policies

resolversConfig is how you attach middlewares, policies, and auth rules to a resolver. The resolver can be one Shadow CRUD generated for you (like Query.notes or Mutation.createNote) or one you wrote yourself (like the searchNotes query in Step 9). resolversConfig is a plain object: keys are the resolver's full name (Query.notes, Mutation.createNote, Note.wordCount), values are configuration objects.

Middleware vs. policy, and when to use each

Both are functions that run around a resolver. They answer different questions.

Policies answer "should this request even proceed?" Per the Strapi docs, policies are "functions that execute specific logic on each request before it reaches the controller. They are mostly used for securing business logic." A policy returns true to let the request through or false to reject it. If the policy returns false, the resolver never runs. Policies are the natural home for authorization checks like "is the user logged in", "does this user own this row", or "is this request coming from an allowed IP".

Policies for the GraphQL plugin live in either src/policies/ (the global folder) or src/api/<api>/policies/ (the per-content-type folder). You refer to them by name in resolversConfig: global::<filename> for the first folder, api::<api>.<filename> for the second. The word "global" here means "lives in the global folder", not "applies to everything". A policy in src/policies/ is available everywhere by name, but you still have to attach it to each resolver in resolversConfig (or to each REST route in the route's config.policies) where you want it. Nothing applies a policy automatically.

Middlewares answer "what should happen before and after?" Per the Strapi docs, middlewares "alter the request or response flow at application or API levels." A middleware wraps the resolver call. It can run code before the resolver, call next(...) to let the resolver run, and run code after the resolver with the result in hand. Use a middleware for things like:

• Timing or logging a call (the timing middleware in this step does this).
• Adding cache hints, CORS headers, or extra fields to the response.
• Changing the request before the resolver sees it (the soft-delete injection middleware does this; it adds archived: { eq: false } to args.filters).
• Changing or rejecting the response after the resolver has run (the Query.note middleware does this; it throws NotFoundError if the loaded note is archived).

Do not use a middleware to reject a request for authorization reasons. That is what policies are for.

The GraphQL plugin exposes both through the same resolversConfig key (see the plugin docs). middlewares is an array; each entry can be either a function (defined inline) or a string (the name of a middleware you registered elsewhere). policies accepts the same two shapes.

They run in a fixed order: middlewares first (in the order you list them), then policies, then the resolver. Each middleware has a "before" half (the code before next(...)) and an "after" half (the code after next(...) returns). At request time:

1. The "before" halves of each middleware run in array order.
2. Once they have all called next(...), the policies run in array order.
3. If any policy returns false, the request is rejected and nothing further runs.
4. Otherwise the resolver runs.
5. Then each middleware's "after" half runs, in reverse order.

What this step builds

The file below attaches four middlewares and one policy across two resolvers.

On Query.notes (the list query):

1. A soft-delete rejection middleware that throws ForbiddenError if the caller tried to filter on archived (whether they asked for true or false). Only the server changes archived, so callers do not get to ask about it.
2. A soft-delete injection middleware that runs after the rejection middleware and adds archived: { eq: false } to args.filters. By the time this runs, we already know the caller did not send archived, so adding it cannot overwrite anything they sent.
3. A timing middleware that logs how long every call takes and prints the filter the resolver ended up running against. Just for observability.
4. A named policy (global::cap-page-size) that rejects any Query.notes call asking for more than 100 rows in one page. A simple yes/no check based on what the caller sent, which is exactly what policies are for.

On Query.note (the single-fetch query):

5. A soft-delete coverage middleware that lets the resolver run, then looks at the loaded note and throws NotFoundError if the note is archived. The list query is already covered by rules 1 and 2, but fetching a single note by documentId goes through a different code path. Without this middleware, anyone holding an archived note's documentId could still pull it down. With it, an archived note no longer exists from the public API's point of view, whether you ask for the list or fetch one by ID.

Why use two middlewares for the soft-delete rule on Query.notes instead of one? Each one does a different job. The first looks at one field (args.filters.archived) and throws if it is present. The second sets that same field to { eq: false }, every time. You could put both checks in a single middleware, but splitting them keeps each one short, and it gives us three small middleware examples on the same resolver to compare against the timing middleware.

Why does Query.note check after the resolver runs instead of before? Because before the resolver runs, we do not yet know whether the requested note is archived. The Document Service has not loaded it. The simplest correct pattern is to call next(...) first, let the Document Service load the row, then check result.archived on the way back. This is the second basic middleware pattern: let the resolver run, then change or reject the response. The rejection middleware on Query.notes is the first pattern: look at args, reject before calling next(...). Both show up in the file below.

Create the file:

1// src/extensions/graphql/middlewares-and-policies.ts
2import type { GraphQLResolveInfo } from "graphql";
3import { errors } from "@strapi/utils";
4
5type NotesArgs = {
6  filters?: Record<string, unknown>;
7  pagination?: Record<string, unknown>;
8  sort?: string | string[];
9};
10
11type NoteArgs = {
12  documentId?: string;
13};
14
15type ResolverNext<A> = (
16  parent: unknown,
17  args: A,
18  context: unknown,
19  info: GraphQLResolveInfo,
20) => Promise<unknown>;
21
22export default function middlewaresAndPolicies() {
23  return {
24    resolversConfig: {
25      "Query.notes": {
26        middlewares: [
27          // Soft-delete invariant — rejection half.
28          // The `archived` field is server-controlled. Any caller-supplied
29          // filter on `archived` is rejected up front.
30          async (
31            next: ResolverNext<NotesArgs>,
32            parent: unknown,
33            args: NotesArgs,
34            context: unknown,
35            info: GraphQLResolveInfo,
36          ) => {
37            if (args?.filters?.archived !== undefined) {
38              throw new errors.ForbiddenError(
39                "Cannot filter on `archived` directly. Soft-deleted notes are not accessible via the public API.",
40              );
41            }
42            return next(parent, args, context, info);
43          },
44          // Soft-delete invariant — injection half.
45          // The first middleware guarantees `archived` was undefined here,
46          // so the injection is unconditional.
47          async (
48            next: ResolverNext<NotesArgs>,
49            parent: unknown,
50            args: NotesArgs,
51            context: unknown,
52            info: GraphQLResolveInfo,
53          ) => {
54            args.filters = {
55              ...(args?.filters ?? {}),
56              archived: { eq: false },
57            };
58            return next(parent, args, context, info);
59          },
60          // Timing logger.
61          // Wraps the rest of the chain to record how long Query.notes
62          // takes. Sees the final filter value because both soft-delete
63          // middlewares ran first.
64          async (
65            next: ResolverNext<NotesArgs>,
66            parent: unknown,
67            args: NotesArgs,
68            context: unknown,
69            info: GraphQLResolveInfo,
70          ) => {
71            const label = `[graphql] Query.notes (${JSON.stringify(args?.filters ?? {})})`;
72            console.time(label);
73            try {
74              return await next(parent, args, context, info);
75            } finally {
76              console.timeEnd(label);
77            }
78          },
79        ],
80        policies: ["global::cap-page-size"],
81      },
82      "Query.note": {
83        middlewares: [
84          // Soft-delete invariant — single-fetch coverage.
85          // Direct documentId lookup is a separate code path from
86          // Query.notes and needs its own enforcement. Let the resolver
87          // run so the entity is loaded, then inspect `archived` on the
88          // result and surface NotFoundError if it is true. From the
89          // public API's point of view, an archived note simply does not
90          // exist.
91          async (
92            next: ResolverNext<NoteArgs>,
93            parent: unknown,
94            args: NoteArgs,
95            context: unknown,
96            info: GraphQLResolveInfo,
97          ) => {
98            const result = (await next(parent, args, context, info)) as
99              | { archived?: boolean }
100              | null
101              | undefined;
102            if (result && result.archived === true) {
103              throw new errors.NotFoundError("Note not found.");
104            }
105            return result;
106          },
107        ],
108      },
109    },
110  };
111}

Order matters on Query.notes. Middlewares run in the order they appear in the array, the policy runs after them, and the resolver runs last. So at request time:

1. The rejection middleware runs first. If the caller passed archived in filters, it throws ForbiddenError and the chain stops here. The remaining middlewares, the policy, and the resolver are all skipped.
2. If the request gets past rejection, the injection middleware runs and sets args.filters.archived to { eq: false }. From this point on, every later step sees the same final filter.
3. The timing middleware runs and prints the filter. The log line reflects what the resolver actually ran against.
4. The policy reads policyContext.args.pagination.pageSize and rejects if it is over 100.
5. The resolver runs with archived: false and a capped page size.

Query.note works in reverse. Its single middleware lets the resolver run first, then checks the result on the way back. If the loaded entity has archived: true, the middleware throws NotFoundError. Otherwise it returns the entity untouched. This is the second basic middleware shape from earlier.

What these middlewares cover, and what they do not.

The middlewares above stop archived notes from coming back when someone calls the notes query (the list) or the note query (single fetch). Those are the two main ways the public API reads notes.

If you want archived notes hidden everywhere, three more places need attention:

• Custom queries. The custom queries we add in Step 9 (searchNotes, notesByTag) are separate resolvers. The middlewares above do not run on them. Both happen to be fine already: notesByTag filters out archived notes inside its own resolver, and searchNotes has an includeArchived argument that defaults to false. Any new custom query you add later has to do its own archived check.
• REST. Calls to GET /api/notes or GET /api/notes/:documentId do not go through the GraphQL plugin at all, so these middlewares never run. REST will return archived notes. The "GraphQL-only vs. both APIs" section right below shows how to make REST behave the same way.
• Write mutations. togglePin, updateNote, and duplicateNote will currently let you change an archived note. That arguably contradicts the point of soft-delete: a "deleted" note should not be editable. Adding a guard is short: load the note, check archived, throw if true. We leave it as an exercise. Part 4 adds per-user ownership on top of these mutations and is the natural place to revisit them.

The two function signatures to remember:

• A middleware is an async function written as async (next, parent, args, context, info) => .... The first argument, next, is a function: call it to let the next middleware run, or, if there are no more middlewares, to let the resolver run. Inside a middleware you can:

  • Change args before you call next(...). That changes what the resolver sees. The injection middleware does this; it adds archived: { eq: false } to args.filters before the resolver runs.
  • Run code after next(...) finishes, with the response in hand. The Query.note middleware does this; it looks at the loaded note, and if note.archived is true, it throws NotFoundError instead of returning the note.
  • Run code both before and after next(...). The timing middleware does this; it records the start time before, then logs the duration after.

  If you throw an error instead of calling next(...), no further middleware runs, no policy runs, and the resolver does not run. The error goes back to the caller in the GraphQL response. That is how the rejection middleware works: it throws ForbiddenError and the request stops there.

• A policy is a function written as (policyContext, config, { strapi }) => .... Return true or undefined to let the request through. Return false to reject it; Strapi turns that into a Policy Failed error. Policies run after every middleware, so by the time a policy runs, any middleware has already had a chance to change args.

When to pick which:

• Use a policy when the rule is "yes or no, based on what the caller sent", and the default Policy Failed error is good enough.
• Use a middleware when you need to change the request, change the response, add timing or logging, or reject with a specific error type. For example, the rejection middleware in this file throws ForbiddenError on purpose, so the GraphQL response carries extensions.code: "FORBIDDEN". That code matches the meaning ("you are not allowed to ask about archived") better than Policy Failed would.

Policies in resolversConfig can be either inline functions or strings that name a policy file (the plugin docs say both shapes work). The string form is global::<filename> for a file in src/policies/, or api::<api>.<filename> for one in src/api/<api>/policies/. We use the string form below so the same policy file can be referenced from both resolversConfig.policies (GraphQL) and a route's config.policies (REST). Part 4 takes advantage of that.

Before writing the policy, look at what its first argument is. Per the GraphQL plugin docs, when a policy runs from resolversConfig:

Policies directly implemented in resolversConfig are functions that take a context object and the strapi instance as arguments. The context object gives access to:

• the parent, args, context and info arguments of the GraphQL resolver,
• Koa's context with context.http and state with context.state.

So policyContext.args gives you the GraphQL resolver arguments (filters, pagination, sort, and whatever else the resolver accepts). policyContext.context.http gives you the underlying Koa request, in case you need to read headers. And policyContext.state.user gives you the signed-in user. (policyContext.context.state.user works too; both point at the same object.) The reason that matters: REST policies access the same user as policyContext.state.user. Using the short path lets the same policy file work in both REST and GraphQL, which Part 4 relies on. The PolicyContext type in the file below picks out only the fields this policy actually reads.

Create the policy file:

1// src/policies/cap-page-size.ts
2import type { Core } from "@strapi/strapi";
3
4const MAX_PAGE_SIZE = 100;
5
6type Pagination = {
7  pageSize?: number | string;
8  limit?: number | string;
9};
10
11type PolicyContext = {
12  args?: { pagination?: Pagination };
13};
14
15const capPageSize = (
16  policyContext: PolicyContext,
17  _config: unknown,
18  { strapi }: { strapi: Core.Strapi },
19): boolean => {
20  const pagination = policyContext?.args?.pagination ?? {};
21  const requested = Number(pagination.pageSize ?? pagination.limit ?? 0);
22
23  if (Number.isFinite(requested) && requested > MAX_PAGE_SIZE) {
24    strapi.log.warn(
25      `Query.notes blocked: pageSize ${requested} exceeds cap of ${MAX_PAGE_SIZE}.`,
26    );
27    return false;
28  }
29
30  return true;
31};
32
33export default capPageSize;

The policy reads policyContext.args.pagination.pageSize (the GraphQL plugin also accepts limit as an alias for offset-style pagination, so we check both), coerces it to a number, and rejects if it is over the cap. Anything inside the cap, or any query without a pagination argument at all, returns true and the request proceeds.

Register the factory in the aggregator:

1// src/extensions/graphql/index.ts
2import type { Core } from "@strapi/strapi";
3import computedFields from "./computed-fields";
4import queries from "./queries";
5import middlewaresAndPolicies from "./middlewares-and-policies";
6
7export default function registerGraphQLExtensions(strapi: Core.Strapi) {
8  const extensionService = strapi.plugin("graphql").service("extension");
9
10  extensionService.use(middlewaresAndPolicies);
11  extensionService.use(computedFields);
12  extensionService.use(function extendQueries({ nexus }: any) {
13    return queries({ nexus, strapi });
14  });
15}

Restart. From a terminal, check that all four rules are active.

First, the soft-delete middlewares. A bare query should succeed and exclude archived rows. A query that tries to filter on archived should be rejected with Forbidden, regardless of the value the caller passes:

# Bare query, no filter: succeeds, archived rows absent
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes { title archived } }"}'
# -> {"data":{"notes":[{"title":"...","archived":false}, ...]}}

# Sneaky query, archived: true: rejected
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes(filters:{ archived:{ eq: true } }){ title } }"}'
# -> {"errors":[{"message":"Cannot filter on `archived` directly. ... ", "extensions":{"code":"FORBIDDEN", ... }}],"data":null}

# Polite query, archived: false: also rejected. The server alone manages archived.
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes(filters:{ archived:{ eq: false } }){ title } }"}'
# -> {"errors":[{"message":"Cannot filter on `archived` directly. ... ", "extensions":{"code":"FORBIDDEN", ... }}],"data":null}

Next, the page-cap policy. Oversized requests should fail with Policy Failed. Requests inside the cap should succeed:

# pageSize over the cap: Policy Failed
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes(pagination:{ pageSize: 500 }){ documentId } }"}'
# -> {"errors":[{"message":"Policy Failed", ... }],"data":null}

# pageSize inside the cap: 200 OK
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes(pagination:{ pageSize: 10 }){ documentId } }"}'
# -> {"data":{"notes":[ ... ]}}

Notice the two error shapes. The middleware throws ForbiddenError and produces extensions.code: "FORBIDDEN". The policy returns false and produces the standard Policy Failed message. Callers can branch on the code.

Finally, the single-fetch coverage on Query.note. Archive a note in the admin UI (or via the archiveNote mutation), grab its documentId, and run:

# Direct fetch of an archived note: rejected with NotFound
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query F($id: ID!){ note(documentId: $id){ documentId title archived } }","variables":{"id":"<archived-documentId>"}}'
# -> {"errors":[{"message":"Note not found.", "extensions":{"code":"STRAPI_NOT_FOUND_ERROR", ... }}],"data":{"note":null}}

# Direct fetch of an active note: 200 OK
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"query F($id: ID!){ note(documentId: $id){ documentId title } }","variables":{"id":"<active-documentId>"}}'
# -> {"data":{"note":{"documentId":"...","title":"..."}}}

In the Strapi process output, every successful list call should also log a line like [graphql] Query.notes ({"archived":{"eq":false}}): 12ms. The filter in the log always includes archived: { eq: false }, even for bare queries, because the injection middleware runs before the timing middleware. Rejected calls do not produce a timing log; the chain stops before the timing middleware runs.

Query.note does not log timings. If you want timing on the single-fetch path too, copy the timing middleware and drop it in front of the soft-delete middleware in Query.note's middlewares array.

Heads up: resolversConfig only protects GraphQL

The middleware and the policy we just wrote sit in resolversConfig. That key is part of the GraphQL plugin's extension API, so the rules only run for /graphql requests. A caller hitting GET /api/notes skips both: the soft-delete middleware does not fire, and the page-size policy does not fire either.

You can see this from the terminal. GraphQL rejects the archived filter, REST returns archived rows without complaint:

# GraphQL: the middleware blocks the archived filter
curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ notes(filters:{ archived:{ eq: true } }){ title archived } }"}'
# -> {"errors":[{"message":"Cannot filter on `archived` directly. ... ",
#                "extensions":{"code":"FORBIDDEN", ... }}],"data":null}

# REST: nothing blocks it, archived rows come back
curl -s "http://localhost:1337/api/notes?filters\[archived\]\[\$eq\]=true"
# -> {"data":[ ... archived notes here ... ],"meta":{ ... }}

If your application only exposes a GraphQL endpoint, this is fine: the GraphQL rule is the only entry point, so the only door is locked. But if both surfaces are exposed (which is the default in Strapi v5), and the rule is genuinely "no caller of any API should ever see archived notes by default", you have to add the rule to REST as well.

Add the same rule to REST

The most direct way to mirror the rule onto REST is a route-level middleware on the Note router. Strapi's core router accepts a config block per action where you can attach Koa middlewares (see the Strapi route configuration docs). The middleware mirrors what the GraphQL pair does: reject if the caller asked for archived, then inject archived: false so the response only includes active notes.

1// src/api/note/routes/note.ts
2import { factories } from "@strapi/strapi";
3import { errors } from "@strapi/utils";
4
5const enforceSoftDelete = (ctx, next) => {
6  const filters = (ctx.query.filters ??= {}) as Record<string, unknown>;
7
8  // Rejection half: match the GraphQL behavior. If the caller tried to
9  // filter on `archived`, return a clear FORBIDDEN error instead of
10  // silently overwriting their filter.
11  if (filters.archived !== undefined) {
12    throw new errors.ForbiddenError(
13      "Cannot filter on `archived` directly. Soft-deleted notes are not accessible via the public API.",
14    );
15  }
16
17  // Injection half: every other request is forced to `archived: false`.
18  filters.archived = { $eq: false };
19  return next();
20};
21
22export default factories.createCoreRouter("api::note.note", {
23  config: {
24    find: { middlewares: [enforceSoftDelete] },
25    findOne: { middlewares: [enforceSoftDelete] },
26  },
27});

REST find and findOne now behave the same way GraphQL does. A caller who sends ?filters[archived][$eq]=true gets a 403 Forbidden response with a clear message. A caller who sends nothing gets back only active notes. Two notes on the syntax: the querystring operator is $eq rather than eq because Strapi's REST filters use $-prefixed operators, and errors.ForbiddenError from @strapi/utils translates to a 403 response on REST (the same error class translates to extensions.code: "FORBIDDEN" on GraphQL).

Restart the dev server, then verify from a terminal. The same REST request that returned a 200 OK with archived rows earlier in this section should now return a 403:

# REST: caller-supplied archived filter, now rejected by the route middleware
curl -s -i "http://localhost:1337/api/notes?filters\[archived\]\[\$eq\]=true"
# -> HTTP/1.1 403 Forbidden
# -> {"data":null,"error":{"status":403,"name":"ForbiddenError",
#      "message":"Cannot filter on `archived` directly. ...",
#      "details":{}}}

# REST: bare query, succeeds and excludes archived notes
curl -s "http://localhost:1337/api/notes" | jq '.data | map(.archived)'
# -> [false, false, false, ...]

The first request gets a 403 with the same message GraphQL produces. The second request comes back 200 OK with only active notes (the injection half added archived: { $eq: false } to the filter before the controller ran).

The cost of this approach: the soft-delete rule now lives in two files. The GraphQL version is in src/extensions/graphql/middlewares-and-policies.ts. The REST version is in src/api/note/routes/note.ts. If a future change updates one and not the other, the two surfaces drift apart.

Other options worth knowing

There are two more places you could put a rule like this, each with its own trade-offs.

Global application middleware (config/middlewares.ts). A middleware registered here runs for every HTTP request before any router dispatches. For soft-delete this works, because the rule is "always inject archived: false", regardless of who the caller is. The catch is timing: a global middleware runs before Strapi populates ctx.state.user, so it cannot read the signed-in user. Any rule that depends on the user (like Part 4's ownership check) cannot live here.

Document Service middleware (src/index.ts register()). The Document Service is the layer below both REST and GraphQL. Every Note read, whether it arrives via GET /api/notes or { notes } in GraphQL, eventually calls strapi.documents("api::note.note").findMany(...) or findOne(...). A middleware registered there with strapi.documents.use(...) fires once and covers both APIs from a single file. The shape of such a middleware looks like:

1// src/index.ts (inside register, sketch only)
2strapi.documents.use(async (context, next) => {
3  if (context.uid !== "api::note.note") return next();
4  if (context.action !== "findMany" && context.action !== "findOne") return next();
5  // ... inspect or change context.params.filters here ...
6  return next();
7});

The Strapi docs document this API on its own page (Document Service middlewares) but do not call it out as the cross-API solution; that framing is ours, derived from the architecture (Shadow CRUD GraphQL resolvers and REST controllers both go through the Document Service, source-confirmed in builders/resolvers/query.ts). We do not implement this version in Part 2; Part 4 uses the Document Service middleware approach for ownership scoping, where covering both APIs in one place becomes load-bearing instead of a nice-to-have.

Looking ahead to Part 4. Soft-delete is a simple rule that does not need the signed-in user, so the route-middleware approach above is enough for Part 2. Part 4's ownership rule is different: it must scope every read and write to ctx.state.user. Repeating that rule in resolversConfig for GraphQL and in src/api/note/routes/note.ts for REST means two files to keep in sync, plus extra code for any custom resolver. Part 4 instead implements the rule once as a Document Service middleware in src/index.ts register(), reads the user via strapi.requestContext.get()?.state?.user, and gets both API surfaces covered from one file. Part 4 also keeps an is-note-owner policy on the GraphQL write mutations as a worked policy example.

Step 7: Add computed fields to Note

Part 1 introduced computed fields on Article with a single-line description field. Note's body lives in content, a markdown string. Word counting and excerpting run directly on that string; a small helper strips common markdown syntax so the results reflect rendered text, not the raw source.

Extend the existing computed-fields.ts so Article's wordCount from Part 1 stays as it is, and three new fields appear on Note:

1// src/extensions/graphql/computed-fields.ts
2const WORDS_PER_MINUTE = 200;
3const DEFAULT_EXCERPT_LENGTH = 180;
4
5type ArticleSource = { description?: string | null };
6type NoteSource = { content?: string | null };
7
8/** Remove common markdown syntax so counts and excerpts reflect rendered text. */
9function stripMarkdown(md: string): string {
10  return (md ?? "")
11    .replace(/```[\s\S]*?```/g, " ") // code fences
12    .replace(/`[^`]*`/g, " ") // inline code
13    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") // images  -> alt
14    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") // links   -> text
15    .replace(/^#+\s+|^>\s+|^[-*+]\s+|^\d+\.\s+/gm, "") // headings, quotes, list markers
16    .replace(/\*\*([^*]*)\*\*|__([^_]*)__/g, (_, a, b) => a ?? b) // **bold** / __bold__
17    .replace(/\*([^*]*)\*|_([^_]*)_/g, (_, a, b) => a ?? b) // *italic* / _italic_
18    .replace(/\s+/g, " ")
19    .trim();
20}
21
22function countWords(text: string): number {
23  const trimmed = text.trim();
24  return trimmed ? trimmed.split(/\s+/).length : 0;
25}
26
27function truncateAt(text: string, maxLength: number): string {
28  return text.length <= maxLength
29    ? text
30    : text.slice(0, maxLength).trimEnd() + "...";
31}
32
33export default function computedFields({
34  nexus,
35}: {
36  nexus: typeof import("nexus");
37}) {
38  return {
39    types: [
40      nexus.extendType({
41        type: "Article",
42        definition(t) {
43          t.nonNull.int("wordCount", {
44            description: "Word count of the article description.",
45            resolve: (parent: ArticleSource) =>
46              countWords(parent?.description ?? ""),
47          });
48        },
49      }),
50
51      nexus.extendType({
52        type: "Note",
53        definition(t) {
54          t.nonNull.int("wordCount", {
55            description: "Word count of the note body (markdown stripped).",
56            resolve: (parent: NoteSource) =>
57              countWords(stripMarkdown(parent?.content ?? "")),
58          });
59
60          t.nonNull.int("readingTime", {
61            description: `Estimated reading time in minutes (${WORDS_PER_MINUTE} wpm).`,
62            resolve: (parent: NoteSource) => {
63              const words = countWords(stripMarkdown(parent?.content ?? ""));
64              return Math.max(1, Math.ceil(words / WORDS_PER_MINUTE));
65            },
66          });
67
68          t.nonNull.string("excerpt", {
69            description: "First N characters of the note, markdown stripped.",
70            args: { length: nexus.intArg({ default: DEFAULT_EXCERPT_LENGTH }) },
71            resolve: (parent: NoteSource, { length }: { length: number }) =>
72              truncateAt(stripMarkdown(parent?.content ?? ""), length),
73          });
74        },
75      }),
76    ],
77    resolversConfig: {
78      "Article.wordCount": { auth: false },
79      "Note.wordCount": { auth: false },
80      "Note.readingTime": { auth: false },
81      "Note.excerpt": { auth: false },
82    },
83  };
84}

Reading the factory

A computed-fields factory returns an object with two keys:

• types is an array of type definitions written with Nexus. At startup, the GraphQL plugin collects every entry from every factory and stitches them all into one schema. The call nexus.extendType({ type: "Note", definition(t) { ... } }) reads "find the existing Note type and add these fields to it." The same pattern works on any type Shadow CRUD generated, like Article or Tag.
• resolversConfig sets per-resolver options. For computed fields this is almost always just auth: false on each added field (more on that below).

Inside definition(t), each field is declared as t.nonNull.<scalar>("fieldName", { ... }). nonNull marks the field as required in the schema, so the value is never null and a client can read it without checking for null. Every field takes a description that shows up in the Sandbox schema panel and in generated client types.

The two nexus.extendType calls are independent. Article's wordCount runs off the description string. Note's three fields run off the markdown string in content. stripMarkdown removes code fences, inline code, images, links, headings, list bullets, blockquote markers, and bold/italic markers, so the counts and excerpts reflect readable text rather than raw markdown.

Why auth: false is needed here

Look at the bottom of the file: every computed field is marked auth: false. We did not need this on Query.notes in Step 6, because the Public role already has the find checkbox checked for Note in Settings → Users & Permissions Plugin → Roles → Public.

Here is what would happen without auth: false on a computed field. Before the resolver runs, the GraphQL plugin asks the Users & Permissions plugin: "does the current role have permission to call this?" For Query.notes it looks for api::note.note.find, which exists in the admin UI as a checkbox. Match found, request allowed.

For Note.wordCount it would look for api::note.note.wordCount. That permission does not exist. The admin UI only has checkboxes for the five built-in actions: find, findOne, create, update, delete. There is nowhere to grant wordCount. The lookup fails and the request comes back as Forbidden access.

auth: false tells the plugin to skip that lookup for the field. The field then runs whenever the parent object's own resolver runs. That is the behavior we want: if a caller is allowed to read a Note, they are allowed to read Note.wordCount on that same note. There is no separate "may they read the word count" question to answer.

Rule of thumb: any field you add with nexus.extendType on an existing content type needs auth: false in resolversConfig. The exception is when you want a custom rule to decide whether the field can be read, in which case you would attach a policy or middleware to that field instead. (None of the computed fields in this step do that, but Part 4's is-note-owner policy is an example of attaching a custom rule to a resolver.)

From the Sandbox, the new fields are selectable on any Note:

1query ComputedNoteFields {
2  notes(pagination: { pageSize: 3 }) {
3    title
4    wordCount
5    readingTime
6    excerpt(length: 60)
7  }
8}

Every note should return a wordCount that matches its content (zero only for an empty note) and a readingTime of at least 1 (the resolver clamps to 1 via Math.max). If wordCount is 0 across the board, the resolver is being called but content is empty or null. Open a note in the admin UI and check that there is actual text in the markdown editor, or query notes { content } and look at the raw string.

Step 8: Create new object types for aggregate responses

Step 7 used nexus.extendType to add fields to types Shadow CRUD had already generated. But not every response is a Note or a Tag. Sometimes a resolver returns something that does not match any row in the database:

• An aggregate, like { total: 42, published: 30, draft: 12 }.
• A per-group breakdown, like [{ tagName: "Work", count: 7 }, ...].
• A wrapper object around an operation, like { success: true, conflicts: [...] }.

For each of these you need a new GraphQL type. nexus.objectType is the API for declaring one.

So when do you use which?

• nexus.extendType: add a field to a type that already exists. Used in Step 7 for Note.wordCount, Note.readingTime, Note.excerpt.
• nexus.objectType: declare a brand-new type. Used here for TagCount and NoteStats.

The noteStats query in the next step returns three counts (total, pinned, archived) plus a per-tag breakdown. Neither return value matches a content type, so we declare two new types: NoteStats for the wrapper, and TagCount for each item in the per-tag list.

Open src/extensions/graphql/queries.ts. Part 1 created it with a single searchArticles query. You will add two nexus.objectType entries and three new Query fields alongside the existing one. The two object types come first; the query resolvers come in Step 9.

Nexus and SDL, briefly

Two terms worth defining first; they come up several times below.

SDL stands for Schema Definition Language. It is GraphQL's standard syntax for describing a schema, the same in any language and any framework. It looks like this:

1type TagCount {
2  slug: String!
3  name: String!
4  count: Int!
5}

SDL is what a GraphQL client sees when it asks the server "what does your schema look like" (an introspection query, like the one we ran in Step 2). It is also what tools like Apollo Sandbox, GraphQL Code Generator, and IDE plugins read to give you autocomplete and type information. Every GraphQL server, no matter how it builds its schema internally, eventually returns it as SDL.

Nexus is the TypeScript library that Strapi's GraphQL plugin uses to build that SDL from code, instead of asking you to write the SDL out as a string. Instead of typing the SDL above directly, you write:

1nexus.objectType({
2  name: "TagCount",
3  definition(t) {
4    t.nonNull.string("slug");
5    t.nonNull.string("name");
6    t.nonNull.int("count");
7  },
8});

At startup, Nexus collects every objectType and extendType call across all your factory files and produces one SDL schema from them. That SDL is what gets handed to Apollo Server and what clients see. The end result is identical SDL; the difference is just how you wrote it.

Why Strapi uses Nexus instead of SDL strings:

• TypeScript can check the resolvers. When you write resolve: (parent: NoteSource) => ..., TypeScript already knows the return value has to match the field type you declared with t.nonNull.int(...). If you wrote the schema as SDL strings, you would need an extra build step that reads the SDL and generates matching TypeScript types. Nexus skips that step.
• Many files can contribute to the same schema. computed-fields.ts, queries.ts, and mutations.ts each return their own Nexus types, and Nexus merges them at startup. With SDL strings, two files cannot both add fields to the same Note type without extra glue.
• Shadow CRUD already uses Nexus. The plugin walks over your content types and calls objectType and extendType to build the auto-generated schema. Your hand-written extensions use the same API, so there is one mental model instead of two.

The tradeoff: Nexus is a little more verbose than raw SDL, and you have to read several files to see what the final schema looks like. That is why every new type in this step is shown alongside its SDL equivalent. The SDL block is what clients will actually see.

Nexus recap

Part 1 covered the minimum Nexus you need for searchArticles. Two more pieces show up in this post.

Defining a new object type with nexus.objectType. Inside the call, the definition(t) callback declares each field on the type. The whole objectType call goes inside the types array your factory returns (the same array you saw in computed-fields.ts in Step 7). The pattern is always the same:

1export default function queries({ nexus, strapi }: { ... }) {
2  return {
3    types: [
4      // nexus.objectType({ ... })   <- new types go here
5      // nexus.extendType({ ... })   <- field extensions go here too
6    ],
7    resolversConfig: { /* ... */ },
8  };
9}

Step 9 shows the full queries.ts with both TagCount and NoteStats declared in the types array alongside the existing searchArticles extension. For now, look at one object type on its own:

1nexus.objectType({
2  name: "TagCount",
3  definition(t) {
4    t.nonNull.string("slug");
5    t.nonNull.string("name");
6    t.nonNull.int("count");
7  },
8});

The resulting SDL equivalent:

1type TagCount {
2  slug: String!
3  name: String!
4  count: Int!
5}

Modifiers stack left to right. You can chain .nonNull (the field is required, never null) and .list (the field is an array) in front of the field type. The order matches what the SDL would say, read left to right:

For object-typed fields, use t.field(name, { type }) or the chained forms (t.list.field, t.nonNull.field):

1t.nonNull.list.nonNull.field("byTag", { type: "TagCount" });
2// byTag: [TagCount!]!

Type references by name. When a field's type is given as a string (type: 'Note', type: 'NoteStats'), Nexus looks up that name at startup against every type that has been declared. This is what lets different files reference each other without imports. queries.ts can reference 'Note' without importing anything from the Note files; by the time Nexus puts everything together, Note is already known. If you misspell the name, Nexus either throws an error at startup (strict mode) or returns null for that field at query time (lax mode).

Add TagCount to queries.ts

Time to put this to work. Open src/extensions/graphql/queries.ts. Part 1 left it like this:

1// src/extensions/graphql/queries.ts (BEFORE)
2import type { Core } from "@strapi/strapi";
3
4export default function queries({
5  nexus,
6  strapi,
7}: {
8  nexus: typeof import("nexus");
9  strapi: Core.Strapi;
10}) {
11  return {
12    types: [
13      nexus.extendType({
14        type: "Query",
15        definition(t) {
16          t.list.field("searchArticles", {
17            type: nexus.nonNull("Article"),
18            args: { q: nexus.nonNull(nexus.stringArg()) },
19            async resolve(_parent: unknown, args: { q: string }) {
20              return strapi.documents("api::article.article").findMany({
21                filters: { title: { $containsi: args.q } },
22                sort: ["publishedAt:desc"],
23                status: "published",
24              });
25            },
26          });
27        },
28      }),
29    ],
30    resolversConfig: {
31      "Query.searchArticles": { auth: false },
32    },
33  };
34}

Add TagCount as a sibling entry at the top of the types array, in front of the existing nexus.extendType({ type: "Query", ... }). Nothing else changes yet: not resolversConfig, not the existing searchArticles block, not the factory signature.

1// src/extensions/graphql/queries.ts (AFTER adding TagCount)
2import type { Core } from "@strapi/strapi";
3
4export default function queries({
5  nexus,
6  strapi,
7}: {
8  nexus: typeof import("nexus");
9  strapi: Core.Strapi;
10}) {
11  return {
12    types: [
13      // NEW: standalone object type for the per-tag breakdown in noteStats (Step 9).
14      nexus.objectType({
15        name: "TagCount",
16        definition(t) {
17          t.nonNull.string("slug");
18          t.nonNull.string("name");
19          t.nonNull.int("count");
20        },
21      }),
22
23      // Existing from Part 1.
24      nexus.extendType({
25        type: "Query",
26        definition(t) {
27          t.list.field("searchArticles", {
28            type: nexus.nonNull("Article"),
29            args: { q: nexus.nonNull(nexus.stringArg()) },
30            async resolve(_parent: unknown, args: { q: string }) {
31              return strapi.documents("api::article.article").findMany({
32                filters: { title: { $containsi: args.q } },
33                sort: ["publishedAt:desc"],
34                status: "published",
35              });
36            },
37          });
38        },
39      }),
40    ],
41    resolversConfig: {
42      "Query.searchArticles": { auth: false },
43    },
44  };
45}

Three things to notice about the edit:

1. TagCount is a sibling entry in types, not nested inside the extendType block. Each entry in the types array is its own contribution to the schema. Nexus reads them as a flat list at startup.
2. Order does not matter. TagCount could come before or after the Query extension and the resulting schema would be identical. Nexus looks up type references by name once everything has been collected, so the order in the array does not affect correctness. Putting new object types first is a readability choice, not a requirement.
3. resolversConfig is unchanged. TagCount has no resolver of its own; it is just a type declaration. The fields on it get filled in by whatever resolver returns a TagCount value, which is noteStats in Step 9. Object types only need entries in resolversConfig when you want to attach an auth, middleware, or policy rule to one of their fields, and we do not for TagCount.

Save the file. Now a Nexus quirk worth knowing: if you introspect the schema for TagCount right now, you will get null.

curl -s -X POST http://localhost:1337/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ __type(name: \"TagCount\") { name } }"}'
# -> {"data":{"__type":null}}

That is not a bug in your edit. Before exposing the final schema, the GraphQL plugin runs pruneSchema from @graphql-tools/utils. That helper walks the schema starting from Query, Mutation, and Subscription, and removes any type that nothing else reaches. No field anywhere has type: "TagCount" yet, so TagCount is unreachable and gets pruned.

TagCount will appear the moment something references it. That happens in Step 9, when we add NoteStats.byTag: [TagCount!]! and the noteStats query that returns a NoteStats. Until then the declaration sits in the file with nothing to use it. That is fine: you can build a schema piece by piece, and the parts that nobody uses yet just stay invisible.

If you want to confirm the TagCount declaration is at least syntactically correct right now, the only evidence available is that the dev server restarted without a TypeScript error after the save. A typo in the name or a misspelled modifier would crash Strapi on reload. The full check happens at the end of Step 9.

Step 9: Custom queries

Step 9 adds three query resolvers to the same queries.ts file, plus one more object type (NoteStats). All three resolvers read data using the Document Service, which is Strapi's main API for working with content. One of them also has a side note showing the same query written as raw SQL.

Strapi gives you three ways to read or write data inside a resolver. Use the first one by default. The other two exist for the rare case when the Document Service cannot do what you need.

For almost everything, use the Document Service. The Query Engine is for specific cases, not the default. Raw SQL is the last resort. The four sub-steps below each make one small edit to queries.ts. By the end, the file matches the full version printed at the bottom of Step 9.

Step 9.1: Declare the NoteStats object type

NoteStats is the return type for the noteStats query. It has three integer counts (total, pinned, archived) and a list of TagCount items for the per-tag breakdown. Because it references TagCount (which you declared in Step 8), TagCount is finally reachable from a real query and Nexus stops pruning it from the schema.

Open src/extensions/graphql/queries.ts. Paste this nexus.objectType call as a sibling entry in the types array, right after the existing TagCount declaration:

1nexus.objectType({
2  name: "NoteStats",
3  definition(t) {
4    t.nonNull.int("total");
5    t.nonNull.int("pinned");
6    t.nonNull.int("archived");
7    t.nonNull.list.nonNull.field("byTag", { type: "TagCount" });
8  },
9}),

The one line worth pausing on is t.nonNull.list.nonNull.field("byTag", { type: "TagCount" }). Reading the chain left to right: "a non-null list of non-null TagCount". The SDL equivalent is byTag: [TagCount!]!. See the modifier table in Step 8 if you need a refresher.

NoteStats refers to TagCount by the string "TagCount". At startup, Nexus looks up every type by name across all the factories. TagCount was declared in the same types array, so the lookup succeeds. Both types now have at least one place that uses them: NoteStats uses TagCount, and the noteStats query (which we add in 9.3) will use NoteStats. Neither will be pruned from the final schema.

Step 9.2: Add searchNotes (Document Service API)

searchNotes filters notes by a substring of the title and lets the caller decide whether to include archived notes. It uses the Document Service, strapi.documents("api::note.note"). This is the same API the table at the top of Step 9 listed as the default; for any query that does not need to drop down to the Query Engine or raw SQL, this is the one to use.

Add one new field, searchNotes, to the Query extendType, just below the existing searchArticles field. After the edit, the whole Query extendType block in queries.ts should look like this:

1nexus.extendType({
2  type: "Query",
3  definition(t) {
4    t.list.field("searchArticles", {
5      type: nexus.nonNull("Article"),
6      args: { q: nexus.nonNull(nexus.stringArg()) },
7      async resolve(_parent: unknown, args: { q: string }) {
8        return strapi.documents("api::article.article").findMany({
9          filters: { title: { $containsi: args.q } },
10          sort: ["publishedAt:desc"],
11          status: "published",
12        });
13      },
14    });
15
16    // NEW below, everything above stays exactly as-is.
17    t.list.field("searchNotes", {
18      type: nexus.nonNull("Note"),
19      args: {
20        query: nexus.nonNull(nexus.stringArg()),
21        includeArchived: nexus.booleanArg({ default: false }),
22      },
23      async resolve(
24        _parent: unknown,
25        { query, includeArchived }: { query: string; includeArchived: boolean },
26      ) {
27        const where: any = { title: { $containsi: query } };
28        if (!includeArchived) where.archived = false;
29        return strapi.documents("api::note.note").findMany({
30          filters: where,
31          populate: ["tags"],
32          sort: ["pinned:desc", "updatedAt:desc"],
33        });
34      },
35    });
36  },
37}),

Three things to notice about the new field:

• includeArchived defaults to false. A caller who passes nothing for this argument gets back only active notes. They have to explicitly pass includeArchived: true to see archived rows. The default protects callers from accidentally getting deleted-looking notes mixed in with the live ones.
• populate: ["tags"]. This tells the Document Service to load the related tags for each note and include them in the response. Without it, every note in the result comes back with tags: undefined, and a client that selected tags { name } would see empty arrays even though the relations exist in the database.
• sort: ["pinned:desc", "updatedAt:desc"]. Pinned notes come first; within each group, the most recently edited note comes first. Same sort syntax as Strapi's REST API.

Then add the resolversConfig entry. Your resolversConfig object at the bottom of the file now has two keys instead of one:

1resolversConfig: {
2  "Query.searchArticles": { auth: false },
3  "Query.searchNotes": { auth: false }, // NEW
4},

Step 9.3: Add noteStats (Document Service, with a raw-SQL aside)

noteStats returns three counts plus a per-tag breakdown. Both halves use the Document Service:

• The three counts (total, pinned, archived) are three calls to strapi.documents("api::note.note").count({ filters: ... }).
• The per-tag breakdown is one call to strapi.documents("api::tag.tag").findMany({ populate: ["notes"] }). We then count tag.notes.length for each tag in plain JavaScript.

At the end of this sub-step there is also a side note showing the same per-tag count written as a single SQL query, for the case where the JavaScript version becomes slow on a very large dataset.

Add one more field, noteStats, to the Query extendType, just below searchNotes. The Query extendType now has three fields:

1nexus.extendType({
2  type: "Query",
3  definition(t) {
4    t.list.field("searchArticles", {
5      /* ... same as before ... */
6    });
7
8    t.list.field("searchNotes", {
9      /* ... same as Step 9.2 ... */
10    });
11
12    // NEW below, everything above stays exactly as-is.
13    t.nonNull.field("noteStats", {
14      type: "NoteStats",
15      async resolve() {
16        const [total, pinned, archived, tags] = await Promise.all([
17          strapi.documents("api::note.note").count({}),
18          strapi.documents("api::note.note").count({
19            filters: { pinned: true },
20          }),
21          strapi.documents("api::note.note").count({
22            filters: { archived: true },
23          }),
24          strapi.documents("api::tag.tag").findMany({
25            populate: ["notes"],
26            sort: ["name:asc"],
27          }),
28        ]);
29
30        const byTag = tags
31          .map((tag: any) => ({
32            slug: tag.slug,
33            name: tag.name,
34            count: Array.isArray(tag.notes) ? tag.notes.length : 0,
35          }))
36          .sort(
37            (a, b) => b.count - a.count || a.name.localeCompare(b.name),
38          );
39
40        return { total, pinned, archived, byTag };
41      },
42    });
43  },
44}),

A few notes on the implementation:

• strapi.documents(...).count({ filters: ... }): three counts, one per filter. The Document Service docs confirm count takes the same filters argument as findMany. Going through the Document Service also means these counts will respect Draft & Publish if you ever turn that setting back on for Note.
• strapi.documents("api::tag.tag").findMany({ populate: ["notes"] }): loads every Tag with its linked notes attached. The resolver then reads tag.notes.length to get the count for each tag. The .sort() call after the .map() orders the results by count descending, with name as a tie-breaker.
• Promise.all runs all four database calls at the same time instead of one after the other. The four results do not depend on each other, so there is no reason for them to wait their turn.

When would you use strapi.db.query(...) instead? The Query Engine is useful when you specifically need to skip something the Document Service does for you. Three examples: skipping lifecycle hooks in a bulk seed script, ignoring draft/publish and locale resolution, or filtering with a database-specific operator that the Document Service has not added yet. For a filtered count on a normal content type, the Document Service is the right tool.

Aside: the same per-tag count as raw SQL

The version above loads every Tag row, plus all of its linked Notes, and then counts in JavaScript. For a few dozen tags and a few hundred notes, that is fine. If you ever end up with thousands of tags and millions of notes, the database has to send all that note data over the wire just so the resolver can count it. At that point, doing the count in SQL avoids the round-trip cost. For reference, here is the per-tag count as a single SQL query:

1// Replace the `tags` fetch and the `byTag` mapping above with this, if the
2// populate-based approach becomes measurably slow on your dataset.
3const rows = await strapi.db.connection.raw(`
4  SELECT tags.slug AS slug, tags.name AS name, COUNT(link.note_id) AS count
5  FROM tags
6  LEFT JOIN notes_tags_lnk link ON link.tag_id = tags.id
7  GROUP BY tags.id
8  ORDER BY count DESC, tags.name ASC
9`);
10
11const byTag = (Array.isArray(rows) ? rows : []).map((r: any) => ({
12  slug: r.slug,
13  name: r.name,
14  count: Number(r.count ?? 0),
15}));

Don't copy this version into the resolver unless you have actually measured a slowness problem. Raw SQL skips validation, lifecycle hooks, Draft & Publish handling, and any future improvements to Strapi's higher-level APIs. The link-table name notes_tags_lnk is a Strapi internal, not a documented API, and a future Strapi version could rename it. Use raw SQL only when the Document Service truly cannot express what you need, not because typing SQL feels faster.

One more thing worth knowing: strapi.db.connection.raw(...) returns whatever the underlying Knex driver returns, and the return value is different from one database to another. SQLite (better-sqlite3, which Part 1 set up by default) returns a plain array of row objects, which is the Array.isArray(rows) branch in the code above. PostgreSQL returns an object like { rows: [...], ... }, so with that driver you would read rows.rows instead, and the Array.isArray(...) ? ... : [] fallback above would quietly drop all your data. If you switch databases, update the unwrapping code.

Your resolversConfig object now has three keys:

1resolversConfig: {
2  "Query.searchArticles": { auth: false },
3  "Query.searchNotes": { auth: false },
4  "Query.noteStats": { auth: false }, // NEW
5},

Step 9.4: Add notesByTag (nested relation filter)

notesByTag returns every active (non-archived) note that has a given tag, with pinned notes first. The resolver itself is a single Document Service call. The interesting part is how the filter walks across the relation.

Add the final field, notesByTag, to the Query extendType, below noteStats. All four Query fields are now in place:

1nexus.extendType({
2  type: "Query",
3  definition(t) {
4    t.list.field("searchArticles", {
5      /* ... same as before ... */
6    });
7
8    t.list.field("searchNotes", {
9      /* ... same as Step 9.2 ... */
10    });
11
12    t.nonNull.field("noteStats", {
13      /* ... same as Step 9.3 ... */
14    });
15
16    // NEW below, everything above stays exactly as-is.
17    t.list.field("notesByTag", {
18      type: nexus.nonNull("Note"),
19      args: { slug: nexus.nonNull(nexus.stringArg()) },
20      async resolve(_parent: unknown, { slug }: { slug: string }) {
21        return strapi.documents("api::note.note").findMany({
22          filters: { archived: false, tags: { slug: { $eq: slug } } },
23          populate: ["tags"],
24          sort: ["pinned:desc", "updatedAt:desc"],
25        });
26      },
27    });
28  },
29}),

The filter tags: { slug: { $eq: slug } } reads "match every note that has at least one related tag whose slug equals the argument I passed in." This is the same nested filter syntax Shadow CRUD already exposes on the auto-generated notes(filters: ...) query. The Document Service and Shadow CRUD use the same filter syntax everywhere, so once you know one you know the other.

The final state of resolversConfig:

1resolversConfig: {
2  "Query.searchArticles": { auth: false },
3  "Query.searchNotes": { auth: false },
4  "Query.noteStats": { auth: false },
5  "Query.notesByTag": { auth: false }, // NEW
6},

Complete file, for verification

After all four sub-steps, src/extensions/graphql/queries.ts should look like this end-to-end:

1// src/extensions/graphql/queries.ts
2import type { Core } from "@strapi/strapi";
3
4export default function queries({
5  nexus,
6  strapi,
7}: {
8  nexus: typeof import("nexus");
9  strapi: Core.Strapi;
10}) {
11  return {
12    types: [
13      nexus.objectType({
14        name: "TagCount",
15        definition(t) {
16          t.nonNull.string("slug");
17          t.nonNull.string("name");
18          t.nonNull.int("count");
19        },
20      }),
21      nexus.objectType({
22        name: "NoteStats",
23        definition(t) {
24          t.nonNull.int("total");
25          t.nonNull.int("pinned");
26          t.nonNull.int("archived");
27          t.nonNull.list.nonNull.field("byTag", { type: "TagCount" });
28        },
29      }),
30      nexus.extendType({
31        type: "Query",
32        definition(t) {
33          t.list.field("searchArticles", {
34            type: nexus.nonNull("Article"),
35            args: { q: nexus.nonNull(nexus.stringArg()) },
36            async resolve(_parent: unknown, args: { q: string }) {
37              return strapi.documents("api::article.article").findMany({
38                filters: { title: { $containsi: args.q } },
39                sort: ["publishedAt:desc"],
40                status: "published",
41              });
42            },
43          });
44
45          t.list.field("searchNotes", {
46            type: nexus.nonNull("Note"),
47            args: {
48              query: nexus.nonNull(nexus.stringArg()),
49              includeArchived: nexus.booleanArg({ default: false }),
50            },
51            async resolve(
52              _parent: unknown,
53              {
54                query,
55                includeArchived,
56              }: { query: string; includeArchived: boolean },
57            ) {
58              const where: any = { title: { $containsi: query } };
59              if (!includeArchived) where.archived = false;
60              return strapi.documents("api::note.note").findMany({
61                filters: where,
62                populate: ["tags"],
63                sort: ["pinned:desc", "updatedAt:desc"],
64              });
65            },
66          });
67
68          t.nonNull.field("noteStats", {
69            type: "NoteStats",
70            async resolve() {
71              const [total, pinned, archived, tags] = await Promise.all([
72                strapi.documents("api::note.note").count({}),
73                strapi.documents("api::note.note").count({
74                  filters: { pinned: true },
75                }),
76                strapi.documents("api::note.note").count({
77                  filters: { archived: true },
78                }),
79                strapi.documents("api::tag.tag").findMany({
80                  populate: ["notes"],
81                  sort: ["name:asc"],
82                }),
83              ]);
84
85              const byTag = tags
86                .map((tag: any) => ({
87                  slug: tag.slug,
88                  name: tag.name,
89                  count: Array.isArray(tag.notes) ? tag.notes.length : 0,
90                }))
91                .sort(
92                  (a, b) => b.count - a.count || a.name.localeCompare(b.name),
93                );
94
95              return { total, pinned, archived, byTag };
96            },
97          });
98
99          t.list.field("notesByTag", {
100            type: nexus.nonNull("Note"),
101            args: { slug: nexus.nonNull(nexus.stringArg()) },
102            async resolve(_parent: unknown, { slug }: { slug: string }) {
103              return strapi.documents("api::note.note").findMany({
104                filters: { archived: false, tags: { slug: { $eq: slug } } },
105                populate: ["tags"],
106                sort: ["pinned:desc", "updatedAt:desc"],
107              });
108            },
109          });
110        },
111      }),
112    ],
113    resolversConfig: {
114      "Query.searchArticles": { auth: false },
115      "Query.searchNotes": { auth: false },
116      "Query.noteStats": { auth: false },
117      "Query.notesByTag": { auth: false },
118    },
119  };
120}