Skip to main content
Version: v3.x beta



Hasura v3 introduces new configuration for projects on the Hasura Data Delivery Network (DDN). This config relies on four types of files:

File typeDescription
hasura.yamlThe main configuration file.
*.env.yamlA file that stores environment variables.
*.supergraph.yamlBuild manifest file(s) for a project.
*.hmlHasura metadata files for a project.
supergraphA directory, containing all the necessary configuration and metadata files, for the supergraph-level scope of a project.
<SUBGRAPH_DIRECTORY>A directory, containing all the necessary configuration and metadata files, for a corresponding subgraph within a project.


This is the entrypoint to a Hasura project.

version: v1
project: <PROJECT_NAME>
path: ./app
defaultSupergraphManifest: base

The version section is used to specify the version of the configuration file. The project field is used to specify the project name.

The hasura.yaml file also contains a subgraphs section. This section is used to specify the various subgraphs associated with the project.


This file is used to store environment variables. The CLI generates a base.env.yaml for you by default. You can add environment variables by adding key-value pairs under a particular subgraph:

supergraph: {}

And then referencing them in your metadata using valueFromEnv:

kind: ConnectorManifest
version: v1
- base
name: app_connector
type: cloud
type: hub
- context: .
Accessing environment variables

In the example above, our supergraphManifests array references our base.supergraph.hml file, which contains an envfile key that maps to our base.env.yaml. Thus, any environment variables present in this YAML file will then be accessible in our HML.

If these files contain sensitive information, you should add them to your gitignore so as to avoid accidentally committing them to version control.

Supergraph manifests

Supergraph manifests tell Hasura DDN how to construct your supergraph. A manifest will contain information such as which subgraphs to include and which resources to use for the build.

kind: SupergraphManifest
version: v1
name: base
envfile: base.env.yaml
- app


The supergraph directory contains the supergraph configuration files. The three included files are:

├── auth-config.hml
├── compatibility-config.hml
└── graphql-config.hml
Organizing files

The contents of these files include the necessary metadata objects to build your supergraph. We've separated them out into files organized by their purpose, but you can organize them anyway you like so long as the metadata objects within them are all included.

Each of these files' contents are used to configure the supergraph.

The auth-config.hml file contains the authentication configuration for the supergraph, allowing you to utilize either JWTs or webhooks.

The compatibility-config.hml file contains the compatibility configuration — using a version number — for the supergraph.

The graphql-config.hml file contains the GraphQL configuration for the supergraph, which allows you to customize the available query and mutation capabilities along with the schema.


Each subgraph is listed as a top-level directory in the root of the project. The CLI will init your project with an app subgraph.

Each subgraph directory will contain the following folder structure when a new connector manifest is added for the subgraph:

│   ├── <CONNECTOR_NAME>-types.hml
│   ├── <CONNECTOR_NAME>.hml
│   ├── connector
│   │   ├── <CONNECTOR_NAME>.build.hml
│   │   ├── configuration.json
│   │   └── schema.json
│   └── models
<CONNECTOR_NAME>The directory containing the build artifacts for the connector.
<CONNECTOR_NAME>-types.htmlThe metadata file for the connector's types.
<CONNECTOR_NAME>.hmlThe metadata file for the connector based on the introspection of the data source.
<CONNECTOR_NAME>/configuration.jsonThe configuration file for the connector.
<CONNECTOR_NAME>/schema.jsonThe schema file for the connector.
/connector/<CONNECTOR_NAME>.build.hmlThe build manifest for the connector.
customize the default subgraph

You can customize the default subgraph by:

  1. Deleting the app subgraph on DDN.
  2. Creating a new subgraph with the desired name.
  3. Renaming the app subgraph directory to the new subgraph name.
  4. Updating any app references for subgraphs in your metadata to the new subgraph name.