Description
The Invoke API is a typed RPC (Remote Procedure Call) client. It makes interacting programatically with loaders and actions safer and as easy as calling a function, abstracting away the details of the underlying network transport. A single invoke client can be used to interact with actions and loaders from your site and from any installed App. The Invoke client have ways to be used both from the Client and from the Server, and supports more complex patterns out of the box, like calling multiple loaders/actions in a single request (See Example 4: Batch Invoke), or sending files via a multipart request. A Invoke type signature will always be dynamic, and will be inferred based on the type of your manifest and the type of the action/loader you are calling: For example:Importing the API
Client-side usage
For client-side usage, the Invoke client is exported from theruntime.ts
file,
at the root of the project.
Below is an example of a typical runtime.ts
file, that creates a client for
interacting with actions and loaders from your site, and from two apps: VTEX and
Linx Impulse. All Apps can be used in the same way, since they all export a
Manifest
.
Server-side usage
For server-side usage, the Invoke client can always be accessed from the Application Context. This makes it easy to use invoke inside actions and loaders. Below is an example of a loader that uses the Invoke client to call another loader from the same application:Usage Examples
Example 1: Calling an Action or Loader from the Browser
Suppose we have a loader calledgetUser
, that returns a user object, based on
a given user id.
invoke
client exported
from the runtime.ts
file:
getUser
function is
automatically inferred, and the type of the user
variable is User
. All of
the parameter types are also inferred, so we get more confidence for interacting
with our APIs.
Important: This should only be used in the Browser. Trying to import and use
the Invoke client from the runtime.ts
file on the server-side will result in
an error. For calling actions/loaders from the server, refer to the next
section.
Example 2: Calling an Action or Loader on the Server
Suppose we are creating an action calledaddItem
, that adds an item to a cart.
Suppose we also already have a loader called cart
, that returns the current
cart for a given user, based on a session contained in the request cookies:
addItem
action, we can reuse the cart
loader to fetch
the current cart, and then add the item to the cart:
AppContext
type exported by convention from your site
app.
Example 3: Uploading a file to the Server
Suppose we have an action calleduploadFile
, that uploads a file to a given
destination. The action receives a file
property, which is a file object that
contains the file data, and a destination
property, which is a string that
specifies the destination path for where the file should be uploaded.
File
Web API as a prop type here, but this creates a problem:
The File
object is not serializable via JSON, but the Invoke client uses JSON
under the hood. This means that trying to pass a File
object as a prop to an
action will result in an error when trying to access the file
property.
To solve this, the Invoke client provides a way to upload files via a multipart
request, which is a nice way to send files to the server, using the FormData
API and the multipart/form-data
content type under the hood.
To make use of this, you only need to add a multipart: true
option to the
Invoke InvokerRequestInit
(Which is the second argument to any invoke call),
and the client will automatically use a custom protocol to send the payload via
multipart, thus making it possible to send files to the server.
We can now call this action from the Browser, using the invoke
client exported
from the runtime.ts
file:
file
property can be safely accessed in the action!
Important: When using the multipart
option, the Invoke client will send a
FormData object to the server, which only supports Files and strings. This means
that any property that is a number or a boolean will be converted to a string.