Actions
Example: GIPHY Action
Actions can call third party services to do things such as processing a payment with Stripe. They can execute any JavaScript code and use any Node package as a dependency. They can interact with the database indirectly by calling queries and mutations.
Action names
Actions are defined in files inside the convex/actions/
directory.
They follow the same naming rules as
queries, but their name
always starts with the "actions/"
prefix:
// This action will be named "actions/myAction".
export default …;
The action
constructor
To declare an action in Convex you use the action constructor function and pass it an implementation function:
import { query } from "./_generated/server";
export default action(() => {
// implementation goes here
});
Action arguments and responses
Action arguments and responses follow the same rules as mutations:
import { action } from "./_generated/server";
export default action((_, { a, b }) => {
// do something with `a` and `b`
});
The first argument to the implementation function is reserved for the action context.
Action context
The action
constructor enables interacting with the database, and other Convex
features by passing an ActionCtx object to the
implementation function as the first argument:
import { action } from "./_generated/server";
export default action((actionCtx, { a, b }) => {
// Do something with `actionCtx`
});
Which part of that action context is used depends on what your Action needs to do:
-
To read data from the database use the
runQuery
field, and call a query that performs the read:convex/actions/myAction.jsexport default action(async ({ runQuery }, { a, b }) => {
const data = await runQuery("readData", { a });
// do something with `data`
});Use an internal query when you want to prevent users from calling the query directly.
-
To write data to the database use the
runMutation
field, and call a mutation that performs the write:convex/actions/myAction.jsexport default action(async ({ runMutation }, { a, b }) => {
await runMutation("writeData", { a });
// do something else
});Use an internal mutation when you want to prevent users from calling the mutation directly.
-
To check user authentication use the
auth
field. Auth is propagated automatically when calling queries and mutations from the action. Read on about Authentication.
Calling third-party APIs
You can use any Node.js package in actions, including libraries that make
requests to third party services. To use fetch
you'll need the node-fetch
library because actions run under Node.js 16 where native fetch
is not
available.
import { action } from "./_generated/server";
import fetch from "node-fetch";
export default action(async _ => {
const data = await fetch("https://api.thirdpartyservice.com");
// do something with data
});
Calling Actions from Clients
To call an action from React use the generated
useAction
hook:
import { useAction } from "../convex/_generated/react";
export function MyApp() {
const performSomeAction = useAction("someActionName");
const handleClick = () => {
performSomeAction({ a, b });
};
// pass `handleClick` to a button
…
See Client Libraries for all the ways Actions can be called from different clients.
Resource Limits
Actions time out after 2 minutes and they can use up to 512MB of memory. Please contact us if you have a use case that requires higher limits.
Error handling
Unlike Queries and Mutations, actions may have side-effects and therefore can't be automatically retried by Convex when errors occur. For example, say your action calls Stripe to send a customer invoice. If the HTTP request fails, Convex has no way of knowing if the invoice was already sent. Like in normal backend code, it is the responsibility of the caller to handle errors raised by actions and retry the action call if appropriate.
Make sure to await all promises created within an action. Async tasks still running when the function returns might or might not complete. In addition, since the Node.js execution environment might be reused between action calls, dangling promises might result in errors in subsequent action invocations.