gadget-server 

The gadget-server package is an auto-generated package of utilities for implementing your Gadget app's backend.

logger 

An instance of the structured logger for your Gadget app.

1import { logger } from "gadget-server";
2
3// log at the info level
4logger.info("hello world");
5
6// log an error
7logger.error({ error: new Error("Something went wrong") });

1import { logger } from "gadget-server";
2
3// log at the info level
4logger.info("hello world");
5
6// log an error
7logger.error({ error: new Error("Something went wrong") });

Logs are viewable in the Log Viewer within Gadget.

api 

An instance of your Gadget app's API client.

import { api } from "gadget-server";

await api.widget.create({ title: "new widget " });

import { api } from "gadget-server";

await api.widget.create({ title: "new widget " });

This api client has the system-admin role and can perform any action in your Gadget app.

See the API Reference for more information on your app's API and the api client object.

trigger 

An instance of the triggers associated with your Gadget app's action. When an action is executed, it receives a trigger object containing information about the event that initiated the action. This object varies depending on the trigger type and includes a type property that specifies the kind of trigger.

export const run: ActionRun = async ({ logger, trigger }) => {
  // This logs an object providing details about the trigger
  // Output example: { "type": "api", "rootModel": "someModel", "rootAction": "someAction", ... }
  logger.info(trigger);
};

export const run: ActionRun = async ({ logger, trigger }) => {
  // This logs an object providing details about the trigger
  // Output example: { "type": "api", "rootModel": "someModel", "rootAction": "someAction", ... }
  logger.info(trigger);
};

For more information on triggers check out our guide here.

connections 

An object with utility functions for each of your app's connections to external systems. This object contains pre-configured clients for supported Gadget connections, such as Shopify, OpenAI, and Sentry.

For example, if you wanted to access your OpenAI connection in a Fastify boot plugin, you could do so like this:

1import { connections, Server } from "gadget-server";
2
3export default async function (server: Server) {
4  const openAIKey = connections.openai.apiKey;
5  // Do things with the key
6}

1import { connections, Server } from "gadget-server";
2
3export default async function (server: Server) {
4  const openAIKey = connections.openai.apiKey;
5  // Do things with the key
6}

For more information on the available connections for Gadget app check out the guide here.

connections.shopify 

If you have a Shopify connection configured, the connections object offers helpers for getting a Shopify API client to make calls to Shopify. All functions that create Shopify API clients create an instance of the client from the shopify-api-node package, pre-configured with the right credentials retrieved from the database.

For example, you can get a Shopify client instance for a given shop ID using connections.shopify.forShopId

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopId("12345");
5  logger.info(
6    await shopify.graphql(`
7      query {
8        shop {
9          name
10        }
11      }
12    `)
13  );
14};
15export default route;

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopId("12345");
5  logger.info(
6    await shopify.graphql(`
7      query {
8        shop {
9          name
10        }
11      }
12    `)
13  );
14};
15export default route;

connections.shopify.forShopId(shopId: bigint | string): Promise<ShopifyClient> 

Returns an instantiated Shopify API client from shopify-api-node ready for calling the given shop with the given shopId. Retrieves the credentials for this shop by by querying the shopifyShop model under the hood, and using the apiKey and accessToken fields to instantiate the client.

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopId("12345");
5
6  logger.info(
7    await shopify.graphql(`
8      query {
9        shop {
10          name
11        }
12      }
13    `)
14  );
15};
16export default route;

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopId("12345");
5
6  logger.info(
7    await shopify.graphql(`
8      query {
9        shop {
10          name
11        }
12      }
13    `)
14  );
15};
16export default route;

connections.shopify.forShopDomain(myshopifyDomain: string): Promise<ShopifyClient> 

Returns an instantiated Shopify API client from shopify-api-node ready for calling the shop with given myshopifyDomain. Retrieves the credentials for this shop by by querying the shopifyShop model under the hood, and using the apiKey and accessToken fields to instantiate the client.

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopDomain("snowdevil.myshopify.com");
5
6  logger.info(
7    await shopify.graphql(`
8      query {
9        shop {
10          name
11        }
12      }
13    `)
14  );
15};
16export default route;

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = await connections.shopify.forShopDomain("snowdevil.myshopify.com");
5
6  logger.info(
7    await shopify.graphql(`
8      query {
9        shop {
10          name
11        }
12      }
13    `)
14  );
15};
16export default route;

connections.shopify.current: ShopifyClient | undefined 

Returns an instantiated Shopify API client from shopify-api-node ready for calling the shop calling the current action or route, if there is one. The current shop is derived from the trigger running the current action or route. If the current shop is unknown, connections.shopify.current will be undefined.

For more information on calling your backend from your frontend and preserving authentication information, see the Shopify plugin guides.

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = connections.shopify.current;
5
6  if (!shopify) {
7    throw new Error("don't know the current shop for creating a shopify client");
8  }
9
10  logger.info(
11    await shopify.graphql(`
12      query {
13        shop {
14          name
15        }
16      }
17    `)
18  );
19};
20export default route;

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  const shopify = connections.shopify.current;
5
6  if (!shopify) {
7    throw new Error("don't know the current shop for creating a shopify client");
8  }
9
10  logger.info(
11    await shopify.graphql(`
12      query {
13        shop {
14          name
15        }
16      }
17    `)
18  );
19};
20export default route;

connections.shopify.setCurrentShop(shopId: bigint): Promise<void> 

Allows setting the currently authenticated shop for manually overriding Gadget's Shopify authentication.

Warning: This function is generally not used in the course of normal development with Gadget, as Gadget includes robust for automatically authenticating requests from Shopify as belonging to a particular shop. For frontends using the @gadgetinc/react-shopify-app-bridge library, or building Shopify extensions, Gadget passes headers from the frontend to the backend that securely authenticate shops and populate connections.shopify.current if possible. This function should only be used when you are building your own secure authentication mechanism, and you'd like your code to be able to use connections.shopify.current as you might otherwise.

For more information on calling your backend from your frontend and preserving authentication information, see the Shopify plugin guides.

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  // undefined for some reason where Gadget can't authenticate the request as coming from a particular shop
5  logger.info(connections.shopify.current);
6
7  // imperatively set the current shop ID
8  await connections.shopify.setCurrentShop("12345");
9
10  // undefined for some reason where Gadget can't authenticate the request as coming from a particular shop
11  const shopify = connections.shopify.current;
12
13  if (!shopify) {
14    throw new Error("don't know the current shop for creating a shopify client");
15  }
16
17  logger.info(
18    await shopify.graphql(`
19      query {
20        shop {
21          name
22        }
23      }
24    `)
25  );
26};
27export default route;

1import { RouteHandler } from "gadget-server";
2
3const route: RouteHandler = async ({ request, reply, connections, logger }) => {
4  // undefined for some reason where Gadget can't authenticate the request as coming from a particular shop
5  logger.info(connections.shopify.current);
6
7  // imperatively set the current shop ID
8  await connections.shopify.setCurrentShop("12345");
9
10  // undefined for some reason where Gadget can't authenticate the request as coming from a particular shop
11  const shopify = connections.shopify.current;
12
13  if (!shopify) {
14    throw new Error("don't know the current shop for creating a shopify client");
15  }
16
17  logger.info(
18    await shopify.graphql(`
19      query {
20        shop {
21          name
22        }
23      }
24    `)
25  );
26};
27export default route;

connections.shopify.currentShopId: string | undefined 

Returns the id of the currently authenticated shop, if it is set. Returns undefined otherwise.

connections.shopify.currentShopDomain: string | undefined 

Returns the myshopify domain (like snowdevil.myshopify.com) of the currently authenticated shop, if it is set. Returns undefined otherwise.

connections.shopify.currentClientId: string | undefined 

Returns the Client ID of the Shopify App that has authenticated the current request, if it is known. Returns undefined otherwise.

connections.shopify.currentClientSecret: string | undefined 

Returns the Client Secret of the Shopify App that has authenticated the current request, if it is known. Returns undefined otherwise.

connections.shopify.currentSession: { token: string, userId?: string } | undefined 

Returns the contents of the Shopify Session Token passed from the frontend if one was passed. Useful for manually inspecting the session token contents, or accessing the userId for Customer Account extensions that correctly pass a session token.

See the @gadgetinc/shopify-extensions docs for more info on authenticating extensions to your Gadget backend.

connections.bigcommerce 

If you have a BigCommerce connection configured, the connections object offers helpers for getting an API client to make calls to BigCommerce. All functions that create BigCommerce API clients create an instance of the client from the @space48/bigcommerce-api package, pre-configured with the right credentials retrieved from the database.

connections.bigcommerce.current: BigCommerceClient | undefined 

Returns an instantiated BigCommerce API client from @space48/bigcommerce-api package ready for calling the store calling the current action or route, if there is one. The current store is derived from the trigger running the current action or route. If the current store is unknown, connections.bigcommerce.current will be undefined.

For more information on calling your backend from your frontend and preserving authentication information, see the BigCommerce frontend guide.

1export const run: ActionRun = async ({ logger, connections }) => {
2  const bigcommerce = connections.bigcommerce.current;
3
4  if (!bigcommerce) {
5    throw new Error(
6      "don't know the current store for creating a bigcommerce client"
7    );
8  }
9
10  logger.info(
11    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
12    "read 1 bigcommerce product"
13  );
14};

1export const run: ActionRun = async ({ logger, connections }) => {
2  const bigcommerce = connections.bigcommerce.current;
3
4  if (!bigcommerce) {
5    throw new Error(
6      "don't know the current store for creating a bigcommerce client"
7    );
8  }
9
10  logger.info(
11    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
12    "read 1 bigcommerce product"
13  );
14};

connections.bigcommerce.forStoreHash(storeHash: string) : BigCommerceClient | undefined 

Returns an instantiated BigCommerce API client from @space48/bigcommerce-api package ready for calling the given store with the given storeHash. Retrieves the credentials for this store by by querying the bigcommerce/store model under the hood, and using the apiKey and accessToken fields to instantiate the client.

1// init BigCommerce API client using forStoreHash
2export const run: ActionRun = async ({ logger, connections }) => {
3  const bigcommerce = await connections.bigcommerce.forStoreHash(
4    "<add-your-store-hash>"
5  );
6
7  logger.info(
8    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
9    "read 1 bigcommerce product"
10  );
11};

1// init BigCommerce API client using forStoreHash
2export const run: ActionRun = async ({ logger, connections }) => {
3  const bigcommerce = await connections.bigcommerce.forStoreHash(
4    "<add-your-store-hash>"
5  );
6
7  logger.info(
8    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
9    "read 1 bigcommerce product"
10  );
11};

connections.bigcommerce.forStore(store: GadgetRecord<{storeHash: string, accessToken: string}>) : BigCommerceClient | undefined 

Returns an instantiated BigCommerce API client from @space48/bigcommerce-api package ready for calling the given store with the given bigcommerce/store record. Retrieves the credentials for this store by by querying the bigcommerce/store model under the hood, and using the apiKey and accessToken fields to instantiate the client.

forStore is an optimized way to initialize a BigCommerce API client, used when you already have a store record loaded in context and don't want to make another round trip to the database using other client initialization methods.

1// in init BigCommerce API client using forStore
2export const run: ActionRun = async ({ logger, connections }) => {
3  // read a store record from Gadget
4  const store = await api.internal.bigcommerce.store.findFirst({
5    filter: { storeHash: { equals: "<your-store-hash>" } },
6  });
7
8  const bigcommerce = await connections.bigcommerce.forStore(store);
9
10  logger.info(
11    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
12    "read 1 bigcommerce product"
13  );
14};

1// in init BigCommerce API client using forStore
2export const run: ActionRun = async ({ logger, connections }) => {
3  // read a store record from Gadget
4  const store = await api.internal.bigcommerce.store.findFirst({
5    filter: { storeHash: { equals: "<your-store-hash>" } },
6  });
7
8  const bigcommerce = await connections.bigcommerce.forStore(store);
9
10  logger.info(
11    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
12    "read 1 bigcommerce product"
13  );
14};

connections.bigcommerce.setCurrentStore(storeOrStoreHash: string | GadgetRecord<{storeHash: string, accessToken: string}>): Promise<void> 

Allows setting the currently authenticated store for manually overriding Gadget's BigCommerce authentication.

Warning: This function is generally not used in the course of normal development with Gadget, as Gadget includes robust for automatically authenticating requests from BigCommerce as belonging to a particular store. For frontends using the @gadgetinc/react-bigcommerce library, Gadget passes headers from the frontend to the backend that securely authenticate stores and populate connections.bigcommerce.current if possible. This function should only be used when you are building your own secure authentication mechanism, and you'd like your code to be able to use connections.bigcommerce.current as you might otherwise.

For more information on calling your backend from your frontend and preserving authentication information, see the BigCommerce plugin guides.

1// in example setting custom authentication using setCurrentStore
2export const run: ActionRun = async ({ logger, connections }) => {
3  // undefined for some reason where Gadget can't authenticate the request as coming from a particular store
4  logger.info(connections.bigcommerce.current);
5
6  // imperatively set the current store ID
7  await connections.bigcommerce.setCurrentStore("store_hash_here");
8
9  // defined now
10  const bigcommerce = connections.bigcommerce.current;
11
12  if (!bigcommerce) {
13    throw new Error(
14      "don't know the current store for creating a BigCommerce client"
15    );
16  }
17
18  logger.info(
19    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
20    "read 1 bigcommerce product"
21  );
22};

1// in example setting custom authentication using setCurrentStore
2export const run: ActionRun = async ({ logger, connections }) => {
3  // undefined for some reason where Gadget can't authenticate the request as coming from a particular store
4  logger.info(connections.bigcommerce.current);
5
6  // imperatively set the current store ID
7  await connections.bigcommerce.setCurrentStore("store_hash_here");
8
9  // defined now
10  const bigcommerce = connections.bigcommerce.current;
11
12  if (!bigcommerce) {
13    throw new Error(
14      "don't know the current store for creating a BigCommerce client"
15    );
16  }
17
18  logger.info(
19    await bigcommerce.v3.get("/catalog/products", { query: { limit: 1 } }),
20    "read 1 bigcommerce product"
21  );
22};

connections.bigcommerce.currentClientId : string | undefined 

Returns the Client ID of the BigCommerce app that has authenticated the current request, if it is known. Returns undefined otherwise.

connections.bigcommerce.currentSecret: string | undefined 

Returns the Client Secret of the BigCommerce app that has authenticated the current request, if it is known. Returns undefined otherwise.

connections.bigcommerce.currentStoreId: string | undefined 

Returns the unique Gadget-assigned id of the currently authenticated bigcommerce/store record, if it is set. Returns undefined otherwise.

connections.bigcommerce.currentStoreHash: string | undefined 

Returns the store hash of the currently authenticated BigCommerce store, if it is set. Returns undefined otherwise.

connections.bigcommerce.currentUserId: string | undefined 

Returns the user ID of the currently authenticated BigCommerce user stored in the session model, if it is set. Returns undefined otherwise.

connections.openai 

If you have configured an OpenAI connection with Gadget, connections.openai is an instance of the official OpenAI JavaScript client for making API calls to all of OpenAI's services. When using Gadget's built-in credentials for OpenAI, only some calls are available, but when using your own credentials, all API functionality is available.

See OpenAI's node documentation for more details on the OpenAI JavaScript client.

1export const run: ActionRun = async ({ connections }) => {
2  const chatCompletion = await connections.openai.chat.completions.create({
3    model: "gpt-4-turbo",
4    messages: [{ role: "user", content: "What are some synonyms for Gadget?" }],
5  });
6
7  return { message: chatCompletion.choices[0].message };
8};

1export const run: ActionRun = async ({ connections }) => {
2  const chatCompletion = await connections.openai.chat.completions.create({
3    model: "gpt-4-turbo",
4    messages: [{ role: "user", content: "What are some synonyms for Gadget?" }],
5  });
6
7  return { message: chatCompletion.choices[0].message };
8};

Model Actions 

save(record) 

Saves the given record to the database.

import { save } from "gadget-server";
export const run: ActionRun = async ({ record }) => {
  await save(record);
};

import { save } from "gadget-server";
export const run: ActionRun = async ({ record }) => {
  await save(record);
};

If the record is a new record, this will persist the record and assign it an ID. If the record is an existing record, this will update the database with any changed values from the record.

save will validate the record before persisting it. save persists the record to the database using your app's Internal API.

Returns 

Async function, which returns a Promise. Resolves to void. Any encountered validation errors will be thrown.

deleteRecord(record) 

Deletes the given record from the database.

import { deleteRecord } from "gadget-server";
export const run: ActionRun = async ({ record }) => {
  await deleteRecord(record);
};

import { deleteRecord } from "gadget-server";
export const run: ActionRun = async ({ record }) => {
  await deleteRecord(record);
};

delete removes the record from your database using your app's Internal API.

Returns 

Async function, which returns a Promise. Resolves to void.

applyParams(params, record) 

Sets incoming parameters onto a record object.

import { applyParams } from "gadget-server";
export const run: ActionRun = async ({ params, record }) => {
  applyParams(params, record);
  await save(record);
};

import { applyParams } from "gadget-server";
export const run: ActionRun = async ({ params, record }) => {
  applyParams(params, record);
  await save(record);
};

applyParams will set any incoming parameters onto the record. This is useful for updating a record with the parameters from an action or similar call. applyParams does not persist the record -- it just mutates the in-memory record object.

Parameters 

• params - The data passed to an action from API calls, webhook events, or direct user inputs, which include the fields of a record.
• record - Record to apply parameters to.

Returns 

Returns void.

Background actions 

enqueue(action, input, options) 

Enqueues a model or global action to run in the background.

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    { id: "background-action-1", priority: "HIGH" }
6  );
7};

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    { id: "background-action-1", priority: "HIGH" }
6  );
7};

Parameters 

• action - Any model or global action.
• input - Parameters or data to pass to an action.
• options (optional) - Options for governing how a background action is enqueued:
  • id - A unique identifier to use for the background action. Must be unique among all other background actions within its environment. If not set, a unique ID will be auto-generated and returned.
  • priority - How high to place this background action in its queue, HIGH priority actions will be executed before default priority actions, and those before LOW priority actions. If not set, the default priority will be used.
  • queue - A queue to put this background action in that limits the maximum concurrency of all actions in the queue. If not set, the action will go into the global queue, and won't be concurrency limited. For more info on queue options read the reference here.
  • retries - Configure how many times to retry the action if it fails, and how fast. For more info on the available retry options, see the retries reference.
  • startAt - The time to start running a background action. The time defined must be formatted as an ISO string.

Returns 

Returns void.

queue 

queue allows you to place the background action in a dedicated queue and also enables you to control the maximum concurrency of all actions in the queue.

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    {
6      queue: {
7        name: "my-queue",
8        maxConcurrency: 4,
9      },
10    }
11  );
12};

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    {
6      queue: {
7        name: "my-queue",
8        maxConcurrency: 4,
9      },
10    }
11  );
12};

• queue: The name of the queue.
• maxConcurrency: The maximum concurrency of all actions in the queue. If not set, the default will be set to 1

retries 

retries allows you to configure how fast and how many times to retry the background action if it fails.

retries can be set to an integer to make your background action retry that many times with the default retry schedule, or set to an object to configure exactly how many times and at what rate retries occur.

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    {
6      retries: {
7        retryCount: 5,
8        maxInterval: 60000,
9        backoffFactor: 2,
10        initialInterval: 1000,
11        randomizeInterval: true,
12      },
13      // OR simply retries: 5
14    }
15  );
16};

1export const run: ActionRun = async ({ api }) => {
2  await api.enqueue(
3    api.someModelOrGlobalAction,
4    {},
5    {
6      retries: {
7        retryCount: 5,
8        maxInterval: 60000,
9        backoffFactor: 2,
10        initialInterval: 1000,
11        randomizeInterval: true,
12      },
13      // OR simply retries: 5
14    }
15  );
16};

• retryCount: The maximum number of times to retry the operation if it keeps failing. The default is 6.
• maxInterval: The maximum amount of time to delay a retry while exponentially backing off. The default is not set, so the retry can backoff indefinitely.
• backoffFactor: The exponential backoff factor to use for calculating the retry delay for successive retries. Set this higher to delay longer. The default is 2.
• initialInterval: How long to initially delay the first retry, in milliseconds. The default is 1000 ms.
• randomizeInterval: Randomizes the delays between attempts by multiplying with a factor between 1 to 2. The default is false.

Shopify 

preventCrossShopDataAccess(params, record, options) 

Enforce that the given record is only accessible by the current shop. For multi-tenant Shopify applications, this is key for enforcing data can only be accessed by the shop that owns it.

1import { applyParams, save } from "gadget-server";
2import { preventCrossShopDataAccess } from "gadget-server/shopify";
3
4export const run: ActionRun = async ({ params, record, logger, api }) => {
5  applyParams(params, record);
6  await preventCrossShopDataAccess(params, record);
7  await save(record);
8};

1import { applyParams, save } from "gadget-server";
2import { preventCrossShopDataAccess } from "gadget-server/shopify";
3
4export const run: ActionRun = async ({ params, record, logger, api }) => {
5  applyParams(params, record);
6  await preventCrossShopDataAccess(params, record);
7  await save(record);
8};

• For existing records, this function verifies the record object has the same shopId as the shop in the current session, and throws if not.
• For new records, this function sets the record's shopId to the current session's shopId.

Parameters 

• params - Incoming parameters, validated against the current shopId
• record - Record to validate or set the shopId on
• options:
  • shopBelongsToField: Picks which belongs to relationship on a model is used for cross-shop validation. Must be the API identifier of a belongs to relationship to the shopifyShop model. If there are multiple relationships to the shopifyShop model on the passed-in record, this is a required parameter
  • customerBelongsToField: Picks which belongs to relationship on a model is used for cross-customer validation. Must be the API identifier of a belongs to relationship to the shopifyCustomer model. If there are multiple relationships to the shopifyCustomer model on the passed-in record, this is a required parameter
  • enforceCustomerTenancy: A boolean field that disables cross-customer validation. Defaults to true

Returns 

Returns void. Throws if the record is not accessible by the current shop.

finishBulkOperation(record) 

Updates the state of a bulkOperation record from Shopify when the operation completes.

1import { applyParams, save } from "gadget-server";
2import {
3  preventCrossShopDataAccess,
4  finishBulkOperation,
5} from "gadget-server/shopify";
6
7export const run: ActionRun = async ({ params, record, logger, api }) => {
8  applyParams(params, record);
9  await preventCrossShopDataAccess(params, record);
10  await finishBulkOperation(record);
11  await save(record);
12};

1import { applyParams, save } from "gadget-server";
2import {
3  preventCrossShopDataAccess,
4  finishBulkOperation,
5} from "gadget-server/shopify";
6
7export const run: ActionRun = async ({ params, record, logger, api }) => {
8  applyParams(params, record);
9  await preventCrossShopDataAccess(params, record);
10  await finishBulkOperation(record);
11  await save(record);
12};

Parameters 

• record - The bulkOperation record to update

globalShopifySync(params) 

Start running a global Shopify sync for all shops matching the params. This will create a shopifySync record and trigger a sync for each shop.

Parameters 

• params: The params object for the sync -apiKeys: the list of Shopify APP API keys to trigger a sync for, default: all enabled apps
  • syncSince: the start date to start syncing data from, default: all time
  • models: the list of model api identifiers to trigger syncs for, default: all enabled models
  • force: should Gadget still run actions for records where the updated_at timestamps match
  • startReason: a string reason to store on the created shopifySync records

returns 

Async function. Returns void.

BigCommerce 

BigCommerce functions can be imported from gadget-server/bigcommerce.

preventCrossStoreDataAccess(params, record, options) 

Enforce that the given record is only accessible by the current store. For multi-tenant BigCommerce applications, this is key for enforcing data can only be accessed by the store that owns it.

1import { applyParams, save } from "gadget-server";
2import { preventCrossStoreDataAccess } from "gadget-server/bigcommerce";
3
4export const run: ActionRun = async ({ params, record, logger, api }) => {
5  applyParams(params, record);
6  await preventCrossStoreDataAccess(params, record);
7  await save(record);
8};

1import { applyParams, save } from "gadget-server";
2import { preventCrossStoreDataAccess } from "gadget-server/bigcommerce";
3
4export const run: ActionRun = async ({ params, record, logger, api }) => {
5  applyParams(params, record);
6  await preventCrossStoreDataAccess(params, record);
7  await save(record);
8};

• For existing records, this function verifies the record object has the same storeId as the shop in the current session, otherwise an Error is thrown.
• For new records, this function sets the record's storeId to the current session's bigcommerceStore.

Parameters 

• params - Incoming parameters, validated against the current storeId
• record - Record to validate or set the storeId on
• options:
  • storeBelongsToField: Picks which belongs to relationship on a model is used for cross-shop validation. Must be the API identifier of a belongs to relationship to the bigcommerce/store model. If there are multiple relationships to the bigcommerce/store model on the passed-in record, this is a required parameter

Returns 

Returns void. Throws if the record is not accessible by the current shop.

OpenAI 

openAIResponseStream 

Converts the result returned when making a request using the OpenAI connection with stream: true into a readable stream that Fastify can respond with.

1import { openAIResponseStream } from "gadget-server/ai";
2
3// Using the openAIResponseStream function to convert an AsyncIterable into a Readable stream
4export const run: ActionRun = async ({ params, connections, logger, api }) => {
5  const stream = await connections.openai.chat.completions.create({
6    model: "gpt-3.5-turbo",
7    messages: [{ role: "user", content: "Hello!" }],
8    stream: true,
9  });
10
11  return openAIResponseStream(stream, {
12    onComplete: (content) => {
13      console.log(content);
14    },
15  });
16};

1import { openAIResponseStream } from "gadget-server/ai";
2
3// Using the openAIResponseStream function to convert an AsyncIterable into a Readable stream
4export const run: ActionRun = async ({ params, connections, logger, api }) => {
5  const stream = await connections.openai.chat.completions.create({
6    model: "gpt-3.5-turbo",
7    messages: [{ role: "user", content: "Hello!" }],
8    stream: true,
9  });
10
11  return openAIResponseStream(stream, {
12    onComplete: (content) => {
13      console.log(content);
14    },
15  });
16};

Parameters 

• stream - An AsyncIterable containing OpenAI response parts.

returns 

A Readable stream with the transformed content from the input stream.

Vite 

gadget Vite plugin 

gadget() is a Vite plugin that automatically detects the frontend framework type used in the Vite config. The plugin modifies Vite configuration parameters so your app frontend can be run and deployed properly in Gadget.

It is imported from gadget-server/vite.

1import react from "@vitejs/plugin-react-swc";
2import { defineConfig } from "vite";
3import { gadget } from "gadget-server/vite";
4
5export default defineConfig({
6  plugins: [gadget(), react()],
7  clearScreen: false,
8});

1import react from "@vitejs/plugin-react-swc";
2import { defineConfig } from "vite";
3import { gadget } from "gadget-server/vite";
4
5export default defineConfig({
6  plugins: [gadget(), react()],
7  clearScreen: false,
8});

Currently, the plugin detects if your app frontend is using Remix or Vite + React Router.

This plugin is needed in your Vite config starting framework version 1.2.

Injected configuration 

The gadget() plugin injects the following configuration into your Vite config, depending on the frontend framework type detected:

Vite + React Router config 

The following configuration is injected into your Vite config while developing:

gadget() output - Vite + React Router - developing
json
Copy
1{
2  "build": {
3    "manifest": true,
4    "outDir": "./.gadget/vite-dist",
5    "emptyOutDir": true
6  }
7}

When building for production, the following configuration is outputted:

gadget() output - Vite + React Router - building production bundle
json
Copy
1{
2  "build": {
3    "manifest": true,
4    "outDir": ".gadget/vite-dist",
5    "emptyOutDir": true
6  },
7  "base": "https://app-assets.gadget.dev/a/{applicationId}/{productionEnvironmentId}"
8}

Additional HTML tags are also outputted to help with setting up your app frontend.

While developing, a dev harness is injected into your app frontend so Gadget can show you errors and popups:

dev harness setup
html
Copy
1<script type="module">
2  if (false) {
3    false.on("gadget:viteError", (data) => {
4      const event = new CustomEvent("gadget:viteError", {
5        detail: data,
6      });
7      window.dispatchEvent(event);
8    });
9  }
10</script>
11<script async crossorigin src="https://app-assets.gadget.dev/assets/devHarness.min.js"></script>

When connecting to Shopify (AppBridge v4) or BigCommerce, additional scripts are added to your frontend while developing and bundling:

injected HTML scripts for connections
html
Copy
1<!-- If the app has a Shopify connection -->
2<!-- SHOPIFY_API_KEY is replaced with the actual API key when we serve the HTML file -->
3<script src="https://cdn.shopify.com/shopifycloud/app-bridge.js" data-api-key="%SHOPIFY_API_KEY%"></script>
4
5<!-- If the app has a BigCommerce connection -->
6<script src="https://cdn.bigcommerce.com/jssdk/bc-sdk.js"></script>

Remix config 

The following configuration is injected into your Vite config while developing:

gadget() output - Remix - developing
json
Copy
{
  "build": {
    "manifest": true
  }
}

When building for production, the following configuration is outputted:

gadget() output - Remix - building production bundle
json
Copy
1{
2  "build": {
3    "manifest": true
4  },
5  "base": "https://app-assets.gadget.dev/a/{applicationId}/{productionEnvironmentId}/"
6}

Remix 

remixViteOptions 

Gadget provides pre-defined Remix configuration in remixViteOptions to help set up your Vite app to work with Remix.

It is imported from gadget-server/remix.

1import { defineConfig } from "vite";
2import { gadget } from "gadget-server/vite";
3// import the pre-defined config
4import { remixViteOptions } from "gadget-server/remix";
5import { vitePlugin as remix } from "@remix-run/dev";
6
7export default defineConfig({
8  plugins: [
9    gadget(),
10    remix({
11      // pass the config to the remix plugin
12      ...remixViteOptions,
13    }),
14  ],
15});

1import { defineConfig } from "vite";
2import { gadget } from "gadget-server/vite";
3// import the pre-defined config
4import { remixViteOptions } from "gadget-server/remix";
5import { vitePlugin as remix } from "@remix-run/dev";
6
7export default defineConfig({
8  plugins: [
9    gadget(),
10    remix({
11      // pass the config to the remix plugin
12      ...remixViteOptions,
13    }),
14  ],
15});

remixViteOptions contains the following configuration:

remixViteOptions
json
Copy
1{
2  "buildDirectory": ".gadget/remix-dist/build",
3  "appDirectory": "web",
4  "future": {
5    "unstable_optimizeDeps": true
6  }
7}

We upload and serve the bundled Remix files inside the .gadget/remix-dist/build directory, so we need to specify the buildDirectory value from Remix.

appDirectory references the directory containing your frontend files, which is web by default.

Check out the Remix documentation for more information about these parameters.

Action Contexts 

Each Action and Global Action is passed a context object as its first and only argument. This context object contains all the inputs necessary for running an action, as well as some utilities.

The context object is usually destructured in the run or onSuccess function arguments with curly braces:

export const run: ActionRun = async ({ api, record, params, ...rest }) => {
  // ...
};