Custom GraphQL queries need more than an isolated file - they need a regular Magento 2 module with registration, a module.xml, and a dependency declaration. This chapter sets up the skeleton for a warm-up module Mironsoft\GraphqlDemo that accompanies blocks 2 and 3 - block 4 then kicks off a custom, continuous project (the events module Mironsoft\Event).

Module skeleton

app/code/Mironsoft/GraphqlDemo/
├── registration.php
└── etc/
    ├── module.xml
    └── schema.graphqls

<?php

declare(strict_types=1);

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Mironsoft_GraphqlDemo',
    __DIR__
);

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Mironsoft_GraphqlDemo">
        <sequence>
            <module name="Magento_GraphQl"/>
            <module name="Magento_CatalogGraphQl"/>
        </sequence>
    </module>
</config>

The <sequence> isn't an accident: Magento_GraphQl supplies the base types (Query, Mutation) as well as the @resolver directive itself - without this dependency, Magento might load the custom schema before the base types exist. Magento_CatalogGraphQl is listed here as well because block 3 extends the product type - if you only declare your own, independent types, you can do without that second dependency.

Creating an empty schema.graphqls

The file itself can stay empty at first, or contain just a comment - all that matters at this point is that Magento actually reads it in. A full reset of the schema cache is mandatory after every change to schema.graphqls, since the merged schema is cached:

bin/magento module:enable Mironsoft_GraphqlDemo
bin/magento setup:upgrade
bin/cache-clean config

Internalizing the cache-clean workflow

This workflow accompanies the rest of the entire series, so it's worth stating explicitly here: schema.graphqls changes don't need a setup:di:compile run (it's not generated PHP code), but they always need a cache clean. In the development environment with the Hyvä watcher enabled, bin/cache-clean config is enough; for stubborn cases, bin/magento cache:flush works as a sledgehammer.

With the module skeleton in place, chapter 5 fills schema.graphqls with real content for the first time: a first custom query with a matching resolver.