Deploying to Production

In order to allow you to safely change your application without impacting end-users, Gadget offers environments on all projects outside of the Hobby plan. Environments allow you to update and test your application in a Development environment before pushing the vetted changes to the 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 the changes are finalized and tested, you can click the Deploy button, and ship them to users, who access the Production environment.

Hobby plan projects do not come with multiple environments. On the Hobby plan, each app has a single environment. Changes made inside the Gadget editor are instantly live and in production. We recommend using the Hobby plan for personal projects and keeping commercial projects on any plan which includes support for environments.

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.

Many pages like the model structure page are only edited in the development environment

The data viewer page however, 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
https://example-app--development.gadget.app
Production Domain
https://example-app.gadget.app

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 https://example-app--development.gadget.app/api/graphql

Calling the Production GraphQL API is done by making requests to https://example-app.gadget.app/api/graphql.

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
JavaScript
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
JavaScript
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 front-end apps that use Gadget as a backend, see the Building Frontends guide.

Specifying environments using GraphQL

For example, 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
JavaScript
1let endpoint;
2if (process.env["NODE_ENV"] == "production") {
3 endpoint = "https://example-app--development.gadget.app/api/graphql";
4} else {
5 endpoint = "https://example-app.gadget.app/api/graphql";
6}
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 }),
15});

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 the warnings on when deploying)
  • you enabled and deployed 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 that exist in your Production environment.

Errors in the production environment

When there are no errors in production, Gadget will display a muted checkmark to indicate that all is well in Production.

No errors in the production environment