Installing an API Client

Gadget provides an API client package for alida-quiz-app-2 in JavaScript and TypeScript. You can import the client, and then use it in browser and/or server-side JavaScript environments like node.js.

Direct Script Tag

Gadget generates JavaScript code directly for your web front-end for straightforward integrations into websites. This <script/> tag method is the simplest and easiest way to get started using alida-quiz-app-2's API.

html

1<script src="https://alida-quiz-app-2.gadget.app/api/client/web.min.js"></script>
2<script>
3  // create a new instance of the Gadget client at the `api` global connected to the Development environment
4  window.api = new Gadget({
5    environment: "Development"
6  })
7</script>

Once the above script tags have been included, you can access api to start making API calls! The generated code is cached on Gadget's CDN and is safe to include directly on high-traffic web properties like a Shopify store or a WordPress blog. We recommend this method of installation for websites when possible, as the client will update without you having to make changes to your code or manually sync with Gadget.

JavaScript

const results = await api.query(`
  query GetSomeData {
    # start writing GraphQL queries!
  }
`);

Node Module

To work with the Gadget API server-side from node.js, or to include generated Gadget code in a larger product with a JavaScript bundler like Webpack or Parcel, you can install the npm module for alida-quiz-app-2. Installing the alida-quiz-app-2 API client works just like any other NPM package Gadget, and works with any NPM-compatible package manager.

This installation method works by installing the package from Gadget's own npm registry, where we host, version, and update your API client.

To install the alida-quiz-app-2 node package, register the Gadget NPM registry for the @gadget-client package scope:

npm config set @gadget-client:registry https://registry.gadget.dev/npm

Then, install the alida-quiz-app-2 client package using your package manager:

npm install @gadget-client/alida-quiz-app-2

yarn add @gadget-client/alida-quiz-app-2

As you make changes to alida-quiz-app-2, Gadget will publish new versions of your API client to its NPM registry. See Client Regeneration for more details on when updates are necessary.

You must register the Gadget npm registry in all environments where you want to use this package, which would include production systems, continuous integration environments, or build steps like Vercel or Netlify's static site builders. This can be done using the above npm config command, or by writing out an .npmrc file in those environments that points to Gadget for the @gadget-client scope.

To indicate to hosting platforms where to find the @gadget-client/alida-quiz-app-2 package, create an .npmrc file in the web/frontend directory with the following content:

web/frontend/.npmrc

registry=https://registry.npmjs.org/
@gadget-client:registry=https://registry.gadget.dev/npm

After installation, the client module can be required and a client instance created:

JavaScript

import { Client } from "@gadget-client/alida-quiz-app-2";
export const api = new Client();

The api object is now ready for use!

JavaScript

const results = api.query(`
  query GetSomeData {
    # start writing GraphQL queries!
  }
`);

Gadget also makes a tarball of the latest version of the API client available for download.

Tarball Endpoint

https://alida-quiz-app-2--development.gadget.app/api/client/tarball

By default, the API Client will not have permission to access data within your application. You can use API Key authentication for server-side apps or Browser Session authentication for client side apps to grant a client access. For

React

If you'd like to build a Gadget app with React, see the Using with React documentation.

Gadget recommends using the npm package installation for the generated API client when building with React. However, you must re-install the Gadget client if you make breaking changes to the application after installing the client. See Client Regeneration for more details.

Connecting to a specific environment

Gadget backend apps support two different versions of the application: a version for developers constructing and testing their application, and a version for end users. The API client can be configured to connect to either environment by passing the environment option to the client constructor.

For example, we can always connect to the environment by passing the string "Development" to the environment option:

JavaScript

import { Client } from "@gadget-client/alida-quiz-app-2";
export const api = new Client({
  environment: "Development",
});
// all API calls will be made to the Development environment

You can also explicitly connect to the environment by passing the string "Production" to the environment option:

JavaScript

import { Client } from "@gadget-client/alida-quiz-app-2";
export const api = new Client({
  environment: "Production",
});
// all API calls will be made to the Production environment

or you can select which environment to connect to based on an environment variable

JavaScript

import { Client } from "@gadget-client/alida-quiz-app-2";
export const api = new Client({
  environment: process.env["IS_PRODUCTION"] == "true" ? "Production" : "Development",
});

By default if no environment is specified the client will set the environment based on NODE_ENV if it is set.

Type Safety

The Gadget client package includes TypeScript types and full type safety for all the high level JavaScript functions like find and findMany. No special installation steps are necessary to take advantage of the type information that the alida-quiz-app-2 has. For more information on using your client with TypeScript and the generated types, see Type Safety.

Client Regeneration

The API client source code changes as you make changes to your Gadget backend.

Because the web clients are generated on-demand, we recommend using these clients where possible. By sourcing it directly as a <script/> tag, your browser will fetch the most up to date code each time a page loads, and you'll always be working with a client guaranteed to work with the current API for the application. To preserve this fast refresh behavior, it is best to not cache the client with other infrastructure (like a proxy), or to save it to disk.

Updating the npm package

Gadget's npm registry will publish new versions of your package as changes are made to your Gadget app. You must install the new version of the API client package locally to reflect changes made in the Gadget editor. If a new model is added or removed, it will be available in the generated clients right away, but you need to update your local dependency version to fetch these changes.

To upgrade using npm, run:

Update to latest version with npm

npm install @gadget-client/[email protected]

To upgrade using yarn, run:

Update to latest version with yarn

yarn add @gadget-client/[email protected]

Updating to only the latest production version

Upgrading to the @latest version of the npm package will install the latest version for the environment. To upgrade to the latest version of the environment only, you can install the @latest-production version. This version of the API client will only reflect changes that have been deployed to , and will not show changes that are in but not yet deployed.

To upgrade to only the latest deployed changes using npm, run:

Update to most recent deployed changes with npm

npm install @gadget-client/[email protected]

To upgrade to only the latest deployed changes using npm, run:

Update to most recent deployed changes with yarn

yarn add @gadget-client/[email protected]

Once changes are deployed using the Deploy button, the @latest and @latest-production version of the packages will match.

Best Effort Functionality

If your client version is out of date, that version still makes a best effort to continue to work with new versions of the data model and GraphQL schema. If a breaking change is made however, the client may try to make requests which no longer work. This can always be remedied by updating any cached source code using npm or yarn, or by copying new files sourced from Gadget's web.js endpoint.

The following changes will break an out of date alida-quiz-app-2 client and cause it to issue invalid requests:

changing a model's apiIdentifier
changing an action's apiIdentifier
removing an action
removing a model completely