Gadget framework
Glossary
FAQ

Gadget Framework 

Upgrade to Gadget framework v1

Gadget framework versions 0.3.1, 0.3, 0.2, and 0.1 have been deprecated and will be sunset on March 1, 2025. After this date, all apps on a v0 framework version will be auto-migrated to v1 and any production apps will be paused.

We recommend manually upgrading to Gadget Framework v1.x to test the changes, deploy to production, and take advantage of the latest features and improvements. Read the migration guide.

What is the Gadget framework? 

The Gadget framework is a powerful backend framework that utilizes Fastify to power all Gadget applications. It offers a serverless Node.js environment for running your JavaScript code, accompanied by Actions and HTTP routes that are used to execute and organize your backend code.

How to use the Gadget framework 

Actions

Primary tool used to execute serverless JavaScript functions inside the Gadget framework.

HTTP routes

Server-side functions used as an alternative option to Actions

How to change your application's framework version 

Existing applications can upgrade or downgrade their framework version in one click. New apps use the latest framework version by default but can be downgraded.

Follow the steps below to change your Gadget framework version:

  1. Head over to the Settings page within your application.

  2. Click the Upgrade button in the framework version section.

Setting page showing the framework version upgrade button

  1. You can now drop down the menu and select the framework version you prefer to change your application to use.

Change framework version page

  1. Now hit the Upgrade and run yarn button in the bottom right-hand corner (will be Downgrade and run yarn if you are downgrading your framework version).

Upgrade and run yarn to change framework version

Framework version changelog 

v1.3.0 

Breaking changes

Includes breaking changes to existing filters on belongs to relationships and GraphQL queries for namespaced models. See the migration guide for more information.

v1.2.0 

  • Upgrade to Vite 5.
  • New build script in package.json.

v1.1.0 

  • Node.js upgrade: node.js v20.9 => node.js v20.12

  • Realtime query support in imperative API clients. Read more.

  • Add models, fields, actions, and routes to your app from the command line using ggt add. Read more.

  • Namespace and nested folder support for models and actions.

  • The default value for connections.shopify.maxRetries changed from 6 to 2.

  • A smaller API client bundle size.

v1.0.0 

  • Unlimited development environments per app.

  • Git-based source control across your entire Gadget application's code, and configurations.

  • The file structure of your app has been updated:

    • The backend now uses an api folder for models, actions, and routes
    • Model-related files are reorganized under api/models
    • Global actions are reorganized under api/actions
    • The frontend folder is renamed to web
    • Access control is now represented as its own folder (accessControl) containing permissions (accessControl/permissions)

  • Your app's settings, permissions, and model schema are now represented in metadata files when you use GGT to clone your files.

  • Support for background action invocation.

  • Queues page: allowing users to view the status and progress of their background actions and Shopify webhooks.

v0.3.1 

Shopify connection

  • The shopifyShop model now has a field disabledWebhooks to allow shop-level control over webhook registration.

  • The scheduledShopifySync global action is added to give explicit control over when the Shopify daily sync is run.

For users upgrading older versions of their app to v0.3.1, it's important to note that the previous globalShopifySync still exists within your global actions, but it is safe to remove that because of its redundancy now that scheduledShopifySync can give you better control over the daily sync schedule of your app.

v0.3 

node.js v18.15 => node.js v20.9

  • New WebCrypto APIs added for cryptography matching the browser APIs.

  • V8 engine upgraded to version 11.3 for improved performance. Read more.

Fastify v3 => Fastify v4

  • Plugins have all been renamed from fastify-something to @fastify/something and versions have changed. Please verify any Fastify plugins are compatible with Fastify 4.

  • HTTP Route error handlers are now encapsulated. If any of your route plugins set error handlers, they will only apply to errors thrown by routes in that folder or a subfolder. Read more.

  • HTTP Route handlers now need to return the reply object if they will send a response later. Read more.

  • HTTP Route handlers for GET routes now expose a HEAD route automatically. Read more.

  • reply.res has been moved to reply.raw. Read more.

v0.2 

node.js v16.20 => node.js v18.15

  • fetch global function is now available.

  • V8 engine upgraded to version 10.1 for improved performance. Read more.

  • Support added for response streaming from Gadget routes. Read more.

Was this page helpful?