Namespacing global actions

Available in Gadget framework version 1.1+

API namespaces were added with Gadget framework version 1.1. If you're using an older version of Gadget, you'll need to upgrade your framework version to use action namespaces.

You can group related globally-scoped actions (and models) by adding namespaces to your API. Namespaces allow you to organize your actions and give you more control over the shape of your generated JavaScript and GraphQL API.

How action namespaces work

Namespacing in Gadget is folder-based, and action namespaces are added by creating folders in the api/actions directory. The folder name is used as the namespace in the generated API.

Namespaces can also be shared between actions and models, and nested.

Just want a folder without changing your API?

If you want to add a folder to organize actions without changing your API, you can put the folder name in parentheses (). If you already have an app that uses the API client, this is a great way to organize your files and folders without changing your API.

For example, adding a (notifications) folder to organize actions:

Add a (notifications) folder to organize actions without changing your API

api/ actions/ (notifications)/ # folder to organize actions, doesn't modify API sendEmail.js # actions within folder, JS example: `api.sendEmail(...)` sendSMS.js sendSlack.js

If you wanted to call the sendEmail action, you would use the JS client API call:

Example JS client API call with a (notifications) folder

JavaScript

// no namespace is added to the API await api.sendEmail();

Adding action namespaces

Action namespaces are only supported for globally-scoped actions.

Globally-scoped namespaces

To create a new globally-scoped action namespace:

Right click on the api/actions folder, and select 'new folder'
Add an action to the new folder

For example, to add a bar.js globally-scoped action to a foo namespace:

a foo folder is created at api/actions
a bar.js globally-scoped action is added to the foo folder

Example: adding a 'foo' globally-scoped action namespace

api/ actions/ foo/ # globally-scoped action namespace bar.js # globally-scoped action, JS example: `api.foo.bar(...)`

Which would look like this on Gadget's UI:

The bar action could then be called using:

Example: API calls with a 'foo' globally-scoped action namespace

// the 'foo' namespace included in the API path await api.foo.bar();

mutation { foo { bar { success errors result } } }

// the 'foo' namespace included in the API path await api.foo.bar();

Nested action namespaces

Model-scoped and globally-scoped action namespaces can be nested. To nest a namespace, add additional folders to an existing namespace folder.

For example, adding a biz namespace to a foo/bar.js globally-scoped action:

a biz folder is created at api/actions/foo
the bar.js globally-scoped action is added to the biz folder

Example: adding a nested 'biz' globally-scoped action namespace

api/ actions/ foo/ # globally-scoped action namespace biz/ # nested globally-scoped action namespace bar.js # globally-scoped action, JS example: `api.foo.biz.bar(...)`

The bar globally-scoped action could then be called using:

Example: API calls with a nested 'biz' globally-scoped action namespace

// the nested 'biz' namespace included in the API path await api.foo.biz.bar();

mutation { foo { biz { bar { success errors result } } } }

// the nested 'biz' namespace included in the API path await api.foo.biz.bar();

Shared namespaces

Globally-scoped actions and models can share namespaces. For example, if you wanted to add a biz namespace that contains both a globally-scoped action and a model's action:

Example: a shared 'biz' namespace

api/ models/ biz/ # shared namespace shopifyProduct/ schema.gadget.ts actions/ create.js # model-scoped action, JS example: `api.biz.shopifyProduct.create(...)` actions/ biz/ # shared namespace bar.js # globally-scoped action, JS example: `api.biz.bar(...)`

The bar globally-scoped action and shopifyProduct.create model-scoped action could then be called using the biz namespace:

Example: API calls with a shared 'biz' namespace