How to Manage Project Contexts

Introduction

Contexts simplify your development workflow by making CLI commands more concise and ensuring easy transitions between environments. They act as predefined configurations that the CLI uses to interact with specific sets of values, making processes like deploying, testing, or managing your project in CI/CD pipelines easier.

You can manage your project's contexts using the .hasura/context.yaml file, which is generated in the root of your project when the CLI initializes it.

Contexts

By default, the CLI sets up your project with a default context. To add new contexts, use the create-context CLI command.

For a full list of context-related commands, refer to this category of commands. Although you can modify these values directly in the file, we recommend using the CLI for consistency and ease. Examples are provided below.

Project

The project key-value pair can be mapped to a Hasura DDN cloud project. This is used to dictate which cloud-hosted project should be referenced by the CLI when cloud-based and project-related commands are executed.

When the default context is set, the great-ddn-1234 project will be used by the CLI:

contexts:
  default:
    project: great-ddn-1234
    supergraph: ../supergraph.yaml
    subgraph: ../app/subgraph.yaml
    localEnvFile: ../.env
    cloudEnvFile: ../.env.cloud

When you initialize a new Hasura Cloud project, the project key-value will automatically be set by the CLI. You can also override this manually using the ddn context set command.

This key-value pair simplifies switching contexts across development stages. For instance, the default context could be used for production builds, while a separate staging context could map to a dedicated project for API collaboration and testing before moving to production.

Supergraph

The supergraph key-value pair maps to a Supergraph metadata object, which contains a list of the subgraphs to include in any supergraph build.

When the default context is set, the root supergraph.yaml will be used by the CLI:

contexts:
  default:
    project: great-ddn-1234
    supergraph: ../supergraph.yaml
    subgraph: ../app/subgraph.yaml
    localEnvFile: ../.env
    cloudEnvFile: ../.env.cloud

By default, this is set to the root supergraph.yaml when you initialize a local project. However, you can customize this to use any valid Supergraph metadata object.

As with subgraphs below, setting this value makes any supergraph-related CLI commands more concise by eliminating the need for extra flags.

Subgraph

The subgraph key-value pair maps to a Subgraph metadata object which contains information about which connectors are included in the subgraph and mappings for environment variables.

With the configuration below, if the current context is default, the app/subgraph.yaml configuration file will be used:

contexts:
  default:
    project: great-ddn-1234
    supergraph: ../supergraph.yaml
    subgraph: ../app/subgraph.yaml
    localEnvFile: ../.env
    cloudEnvFile: ../.env.cloud

For projects with multiple subgraphs, it's handy to use this command to switch between subgraphs:

ddn context set subgraph <path-to-subgraph-configuration-file>

This ensures common actions — like adding data connectors and generating metadata after introspection — are executed by the CLI in the correct subgraph, keeping your supergraph organized and resources with their appropriate owners.

localEnvFile

Your project is initialized with a root-level .env file and this is automatically set in the default context. Whenever a new environment variable is added — such as when initializing a new connector — the CLI will add the appropriate key-value pairs to this file. It is used in local development such as when running your local services (i.e., the engine and connectors).

When the default context is set, the root .env file will be used by the CLI for any local development commands:

contexts:
  default:
    project: great-ddn-1234
    supergraph: ../supergraph.yaml
    subgraph: ../app/subgraph.yaml
    localEnvFile: ../.env
    cloudEnvFile: ../.env.cloud

Ideally, the values here will — such as connection strings to data sources — will be mapped to development instances, whether that be locally or hosted elsewhere. This makes it easy to work with what will eventually become a production build, but using local resources for quicker iteration and shorter feedback loops.

Any time you need to add additional environment variables to a connector, you can use the CLI.

cloudEnvFile

Your project includes a root-level .env.cloud file, which is automatically set in the current context whenever a new cloud project is initialized. This file is specifically used for cloud-related operations, such as deploying or managing your services in a cloud environment.

When the default context is set, the root .env.cloud file will be used by the CLI for any cloud-related commands:

contexts:
  default:
    project: great-ddn-1234
    supergraph: ../supergraph.yaml
    subgraph: ../app/subgraph.yaml
    localEnvFile: ../.env
    cloudEnvFile: ../.env.cloud

A localEnvFile is required before setting the cloudEnvFile

A localEnvFile is required before setting the cloudEnvFile. Ensure your localEnvFile is set for the current context before initializing a new cloud project to avoid any deployment issues.

Next steps

Now that you have a better idea of configuring your project for various contexts, learn how to collaborate with others by adding collaborators and defining their roles.