Plugins

Plugins let you hook into ariadne-codegen to inspect or modify the GraphQL schema and the generated code before it is written to disk. A plugin is a Python class extending ariadne_codegen.plugins.base.Plugin that overrides one or more hooks - each hook fires at a specific point of a generation run and receives the value being produced (a schema, an ast node, or a source string), returning it modified or unchanged.

Why use a plugin

Plugins are the supported extension point when the built-in configuration is not enough. Common use cases:

• Add file headers or license banners to every generated module.
• Inject fields or metadata into generated Pydantic models (e.g. an __operation__ marker on result classes).
• Transform the final source - rename symbols, rewrite imports, reformat output.
• Inspect or rewrite the schema at startup before any code is generated.
• Read your own configuration from pyproject.toml to drive any of the above.

Real-world examples

The best worked examples are the standard plugins shipped in ariadne_codegen.contrib - each is a small, production plugin whose source is worth reading:

• ShorterResultsPlugin - rewrites generated client methods to return a single top-level field directly instead of the full result type.
• ExtractOperationsPlugin - moves query strings out into a separate module and rewrites the client's imports; also reads its own [tool.ariadne-codegen.extract-operations] config.
• ClientForwardRefsPlugin - moves Pydantic model imports under TYPE_CHECKING to speed up importing the client module.
• NoReimportsPlugin - empties the generated __init__.py to avoid eager initialization of large packages.

How they work

Plugins are instantiated once, at the start of the ariadne-codegen command, and run as a sequential pipeline - each plugin receives the output of the previous one. See Plugin execution model for the details.

Next steps

• Custom plugins - write and enable your own plugin.
• Hooks - the full reference of every hook, in the order it fires.
• Standard plugins - ready-to-use plugins shipped with ariadne-codegen.