In order to allow you to safely change your application without impacting end-users, Gadget offers environments on all projects. Environments allow you to update and test your application in a Development environment before pushing the vetted changes to Production.

Think of Gadget's deployment workflow as a one-way push: you make changes in Development, then push them to Production. By default, all changes you make in the Gadget editor happen in the Development environment. This means that when you add models, update code files, or change configuration inside the editor, users won't immediately experience these changes. Once you're ready to release the changes you can click the Deploy button and ship them to users who access the Production environment.

Editing your application in different environments 

The Gadget editor comes with an environment toggle that allows you to view certain pages in Development, Production, or both. The environment toggle can be found in the header of your Gadget editor:

Selecting the environment on the Data Editor in Gadget

Every interface in the Gadget editor can view the contents of your application in the Development environment. Select interfaces, such as the Logs, Data, and API Playground pages, can be toggled to Production to see the logs and data in the production version of the app.

The data model structure page can only ever change the Development environment.

The data viewer page can be toggled between Development and Production environments to view their respective specific data records.

Some pages like the data viewer page can be toggled between development and production environments

To help you quickly distinguish which environment you're observing inside the Gadget editor, Production views are emphasized with a purple border.

Selecting the production environment on the Data Editor in Gadget

The Connections, Environment Variables, and API Keys pages within the Gadget editor show configuration values from both environments. Viewing and editing values for both Development and Production happens on the same page.

Connecting to different environments 

Your application has two different domains, one for the Development environment and one for the Production environment.

Development Domain
Production Domain

To view the development version of your application's frontend, ensure you use the Development domain.

To make requests to the GraphQL API, HTTP Routes, or otherwise access your app on each environment, send requests to that environment's domain. The Development environment's domain will always have the --development suffix in the subdomain.

Calling the Development GraphQL API is done by making requests to

Calling the Production GraphQL API is done by making requests to

Specifying environments using the API client 

The Gadget JS client has support for environments built right in.

To specify which environment to send requests to, pass the environment option to the Client constructor with the string "Development" or "Production".

For example, we can construct our client to always connect to Development:

Always connect to Development
import { Client } from "@gadget-client/example-app";
export const api = new Client({
environment: "Development",

For JS projects outside of Gadget, it's also quite convenient to configure the API client to send requests to the Development environment when in development, and to Production once deployed. We can do this easily with the NODE_ENV environment variable, which most deployment platforms will set to production when deployed.

By default, the API client will connect to the appropriate environment based on NODE_ENV. If NODE_ENV is not defined or a value that is not "development" or "production" then the API client will default to Development.

Default to NODE_ENV
import { Client } from "@gadget-client/example-app";
// Requests are sent to production if NODE_ENV=production.
// Requests are sent to development if NODE_ENV is set to any other value besides "production".
export const api = new Client();

Read more about installing the API Client package in the API Reference..

For more information on building frontend apps that use Gadget as a backend, see the Building Frontends guide.

Specifying environments using GraphQL 

If you're using fetch to make raw GraphQL requests to your app's GraphQL API, you can send them to Production when process.env["NODE_ENV"] == "production" by changing which endpoint you use when fetching.

Fetch based on NODE_ENV
1let endpoint;
2if (process.env["NODE_ENV"] == "production") {
3 endpoint = "";
4} else {
5 endpoint = "";
7const result = await fetch(endpoint, {
8 method: "POST",
9 headers: {
10 "Content-Type": "application/json",
11 },
12 body: JSON.stringify({
13 query: "query { gadgetMeta { applicationName } }",
14 }),

Read more about connecting to the GraphQL API for your application in the API Reference..

Deploying changes to Production 

Each change you make inside the Gadget editor is instantly available in your application's Development API. To make these changes available to end users, you need to deploy them to Production. In Gadget, deploying means clicking the Deploy button in the footer of the Gadget editor.

The deploy button

Once you click on deploy, Gadget will confirm that you wish to proceed with the changes.

The deploy confirmation popup

If you go to deploy broken code to Production, Gadget will display a modal presenting you with the errors and warnings from your Development environment that are about to be deployed to Production. You can choose to ignore them and proceed with deploying your changes or cancel the action and address the problems before re-attempting your deploy.

The deploy confirmation popup with errors

Production problems 

Much like the Development environment, errors may also exist in your Production environment. This can happen in one of two ways:

  • You deployed errors to Production (skipping the warnings when deploying)
  • You enabled and deployed a database with a Required or Uniqueness validation on a field when records in your Production database didn't meet those validations

If your Production environment has errors like this, Gadget will present a red icon next to the Deploy button. You can click on the icon to view the errors in your Production environment.

Errors in the production environment