Nhost uses a single configuration file to configure both cloud projects and the local development environment, ensuring a near-identical replica of the production environment. This approach also simplifies connecting a repository to multiple projects, keeping them in sync with minimal effort. However, in cases where minor differences need to be accommodated, Nhost offers overlays - files containing operations to modify the configuration file:
The overlay above will perform the following changes to the configuration file:
- Disable email verification
- Set the correct client URL for the staging environment
- Add the environment variable
Overlays are based on RFC6902
It's important to note that overlays in Nhost do not modify the original files, but rather manipulate the resulting configuration at runtime. This allows multiple environments to safely share the same base configuration and rely on the overlay to accommodate differences. Additionally, changes to the base configuration file will propagate to all environments unless an overlay operation prevents it, making overlays a convenient and efficient way to manage configuration differences.
You can create overlays with the CLI command
nhost config edit [--subdomain $SUBDOMAIN]:
If you need to create an overlay for your local development environment remember to use
local as subdomain
This will open an editor with the configuration for your
You can perform as many changes as needed using overlays. For example, you can add an environment variable, enable Hasura remote permissions, and change the client URL.
You can verify the overlay by checking the file
To verify that your final configuration is correct, you can use the command
nhost config show [--subdomain $SUBDOMAIN]. This command will apply the specified overlay (if it exists) and render the configuration using the local secrets.
Finally, you can validate your configuration overlay with the command
nhost config validate [--subdomain $SUBDOMAIN]