Skip to main content

A Django app that speeds up and simplifies implementing a GraphQL endpoint!

Project description

A red g with a grapple hook

Wagtail Grapple

A library to build GraphQL endpoints easily so you can grapple your Wagtail data from anywhere!

Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

About The Project

GraphQL Preview Demo

There is a range of GraphQL packages for Python and specifically Django. However, getting these packages to work out of the box with an existing infrastructure without errors isn't as easy to come by.

The purpose of Grapple is to be able to build GraphQL endpoints on a model by model basis as quickly as possible. The setup and configuration have been designed to be as simple but also provide the best features; No complex serializers need to be written - just add a graphql_fields list to your model and away you go (although if you want to go deeper you can!).


  • Easily create GraphQL types by adding a small annotation in your models.
  • Supports traditional Wagtail models:
    • Pages (including Streamfield & Orderables)
    • Snippets
    • Images
    • Documents
    • Media
    • Settings
    • Redirects
    • Search (on all models)
  • Custom Image & Document model support
  • Pagination support
  • Advanced headless preview functionality built using GraphQL Subscriptions to enable Page previews on any device!

Built With

This library is an abstraction upon and relies heavily on Graphene & Graphene Django. We also use Django Channels and the Potrace image library.

Getting Started

Getting Grapple installed is designed to be as simple as possible!


Django  >= 2.2, <3.1 (<2.3 if using channels)
wagtail >= 2.5, <2.12


pip install wagtail_grapple

Add the following to the installed_apps list in your Wagtail settings file:

installed_apps = [

For GraphQL Subscriptions with Django Channels, run pip install wagtail_grapple[channels] and add channels to installed apps:

installed_apps = [

Add the following to the bottom of the same settings file, where each key is the app you want to this library to scan and the value is the prefix you want to give to GraphQL types (you can usually leave this blank):

# Grapple Config:
GRAPHENE = {"SCHEMA": "grapple.schema.schema"}
    "home": ""

Add the GraphQL URLs to your

from grapple import urls as grapple_urls
urlpatterns = [
    url(r"", include(grapple_urls)),

Done! Now you can proceed onto configuring your models to generate GraphQL types that adopt their structure :tada: Your GraphQL endpoint is available at http://localhost:8000/graphql/


Here is a GraphQL model configuration for the default page from the Wagtail docs:

from grapple.models import (

class BlogPage(Page):
    author = models.CharField(max_length=255)
    date = models.DateField("Post date")
    body = StreamField(
            ("heading", blocks.CharBlock(classname="full title")),
            ("paragraph", blocks.RichTextBlock()),
            ("image", ImageChooserBlock()),

    content_panels = Page.content_panels + [

    # Note these fields below:
    graphql_fields = [

For more examples, please refer to the Documentation


Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature)
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Local development

  • In the python environment of your choice, navigate to /example
  • Run pip install -r requirements.txt
  • Delete the db.sqlite3 file and run ./ migrate
  • Run server ./ runserver


Wagtail Grapple supports:

  • Django 2.2.x, 3.0.x
  • Python 3.6, 3.7, 3.8 and 3.9
  • Wagtail >= 2.5, < 2.12


Distributed under the MIT License. See LICENSE for more information.


Nathan Horrigan

Project Link:

Inspired by

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Nathan Horrigan

💻 🐛 📖 🚇 🚧

Cameron Lamb

💻 🐛 📖 🚇 🚧

Dan Braghis

💻 🐛 📖 🚇 🚧

Rui Saraiva

💻 🐛 📖 🚇 🚧


💻 🐛 📖


💻 🐛

Tom Dyson

💻 📖


💻 🐛 📖

This project follows the all-contributors specification. Contributions of any kind welcome!

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for wagtail-grapple, version 0.10.2
Filename, size File type Python version Upload date Hashes
Filename, size wagtail_grapple-0.10.2-py2.py3-none-any.whl (38.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size wagtail-grapple-0.10.2.tar.gz (34.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page