Action API namespaces 

You can group related global 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.

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

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

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

Adding action namespaces 

Action namespaces are only supported for global actions.

Global action namespaces 

To create a new global action namespace:

1. Create a new folder that is a child of the api/actions folder
2. Add an action to the new folder

For example, to add a bar.js global action to a foo namespace:

• a foo folder is created at api/actions
• a bar.js global action is added to the foo folder

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

The bar action could then be called using:

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

1mutation {
2  foo {
3    bar {
4      success
5      errors
6      result
7    }
8  }
9}

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

Nested action namespaces 

Model and global 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 global action:

• a biz folder is created at api/actions/foo
• the bar.js global action is added to the biz folder

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

The bar global action could then be called using:

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

1mutation {
2  foo {
3    biz {
4      bar {
5        success
6        errors
7        result
8      }
9    }
10  }
11}

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

Shared namespaces 

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

1api/
2    models/
3      biz/ # shared namespace
4        shopifyProduct/
5          schema.gadget.ts
6          actions/
7            create.js # model action, JS example: `api.biz.shopifyProduct.create(...)`
8    actions/
9      biz/ # shared namespace
10        bar.js # global action, JS example: `api.biz.bar(...)`

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

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

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