Skip to main content
Version: v3.x beta

Create a Supergraph

What's about to happen?

We're going to create a supergraph.

Your supergraph is the composite of all your subgraphs and their various data sources and business logic.


Step 1. Initialize your supergraph

To initialize your supergraph, from an empty directory, run:
ddn supergraph init --dir .
Specifying a directory

Instead of passing a . (this directory specifier) you can pass a directory name to the --dir flag to create a supergraph in a specific directory. If it doesn't exist it will be created.

Step 2. Set the supergraph config

Next, as a feature of convenience, we'll set the context which replaces the need to set frequently used default values (such as the flag --supergraph) when utilizing CLI commands by saving the path of your supergraph.yaml to a context file in your .hasura directory. You can learn more about using context here.

In the project's root directory, run:
ddn context set supergraph ./supergraph.yaml

Step 3. Build your supergraph

You now have all the scaffolding necessary to start developing your Hasura supergraph. In fact, we can create a build by running the following command.

From the project's root, run:
ddn supergraph build local --output-dir ./engine

The above command is generating all of the JSON necessary to configure and serve your supergraph. As we passed the local subcommand, this will output the files to our ./engine directory so that we can then use this when starting our services in the next step.

Step 4. Start the services

Then, we can start the docker-compose.hasura.yaml in the root of the directory to start the GraphQL engine and the accompanying services.

From the project's root, run:
HASURA_DDN_PAT=$(ddn auth print-pat) docker compose -f docker-compose.hasura.yaml watch

This command sets the HASURA_DDN_PAT environment variable using a value retrieved from the command ddn auth print-pat and then uses Docker Compose to start and monitor the Hasura services defined in the docker-compose.hasura.yaml file. Your PAT is your personal access token generated by Hasura DDN and used by the CLI.

You should see your various services returned as Running or Started in the terminal. This provides a watch mode, which will allow us to iteratively modify and test our API locally with blazing-fast feedback loops.

You can now navigate to and interact with your API using the Hasura Console!

However, you'll see a very empty GraphQL schema. We're showing you this so you can see that your API starts off as a blank slate, allowing you to iteratively and collaboratively build it out. Hasura utilizes a system of immutable builds which provide a stable snapshot of your API at any point in the development process.

What did this do?

The CLI created all the files needed for local development and iteration in your local directory, including a docker-compose for local development and helper files for VS Code.

Click here to see an expanded directory structure.
├── .devcontainer
│ └── devcontainer.json
├── .env.engine
├── .gitattributes
├── .hasura
│ └── context.yaml
├── .vscode
├── docker-compose.hasura.yaml
├── engine
│ ├── auth_config.json
│ ├── metadata.json
│ └── open_dd.json
├── hasura.yaml
├── otel-collector-config.yaml
├── supergraph.yaml
└── supergraph_globals
├── .env.supergraph_globals
├── auth-config.hml
├── compatibility-config.hml
└── graphql-config.hml

ddn supergraph init will always be the first command you run when starting a new project. However, you may have arrived here after being invited to join an existing project. In that case, your supergraph will already exist; you can simply clone the repository containing your supergraph and pick up with the next section.

Regardless of how you've arrived at your supergraph, you'll have needed to create a build and then run it using Docker. This is the typical workflow when starting a new project or picking up with an existing one.

Next steps

The most common next step from here is to add a new subgraph.