Functions

Functions are configurable server-side functions that you can call directly from your client-side JavaScript code. These are basic building blocks that give you even more flexibility than Forms in StaticKit.

How It Works

Suppose you are building a contact form and you would like to receive an email when it gets submitted. To do this, you can create a sendContactEmail function in your statickit.json file:

{
"functions": {
"sendContactEmail": {
"type": "sendNotification",
"to": "{your-email-address}"
}
}
}

When you deploy this config to StaticKit, we'll install a @statickit/functions npm package with your function definition. Then, you can call your sendContactEmail function in your JavaScript code:

import { createClient, sendContactEmail } from '@statickit/functions';
const client = createClient({ site: '{your-site-id}' });
const form = document.getElementById('myForm');
form.addEventListener('submit', async function(event) {
event.preventDefault();
let data = new FormData(form);
await sendContactEmail(client, {
subject: 'New contact submission',
fields: {
email: data.get('email'),
message: data.get('message')
}
});
});

That's it! You are free to mix and match different StaticKit function types to make your forms behave exactly how you need.

Types

AppTypeDescription
sendNotificationSends a notification email
convertkitapplyTagsCreates a subscriber and applies tags
mailchimpaddOrUpdateListMemberAdds or updates a list member
mailchimpcreateEventAdds or updates a contact and tracks an event
stripecreateChargeCreates a charge in Stripe
stripecreateCustomerCreates a customer in Stripe
stripecreateSubscriptionCreates a subscription in Stripe

Rules

You can provide one or more server-side rules when configurating individual functions. For example, you may want to require a message field for a contact form function:

{
"functions": {
"submitContactForm": {
"type": "sendNotification",
"to": "{your-email-address}",
"rules": [
{ "type": "required", "arg": "fields.message" }
]
}
}
}

With this rule, your function call will fail if message is not included in the fields object:

let { status } = await submitContactForm(client, {
email,
fields: {
// no `message` here!
}
});
// status == "argumentError"

Here are the available rule types:

AppTypeDescription
equalsValidates that an argument equals a given value
requiredValidates that a particular argument is set

Responses

At a minimum, function responses have a status property:

  • ok: The call succeeded
  • argumentError: Arguments were invalid, check the errors property
  • configError: Config was invalid, check the errors property
  • runtimeError: A runtime error occurred, check the message property

You can reliably check the status property to implement conditional logic:

try {
let resp = await sendEmail(client, { subject: 'You have mail!' });
switch (resp.status) {
case 'ok': // success
case 'argumentError': // arguments were invalid
case 'configError': // config was invalid
case 'runtimeError': // a runtime error occurred
}
} catch (e) {
// a network error occurred
}

Responses may contain additional properties, depending on the function type (see the specific function type documentation for details).

Validation Errors

If arguments or config are invalid, the response will include an array of errors with one or more error objects:

KeyDescription
fieldThe name of the field
messageA human-readable error message fragment (e.g. "is required")
codeA machine-friendly error code (e.g. "REQUIRED" or "EMAIL_FORMAT")
propertiesAn object containing various additional properties about the error

Runtime Errors

If a runtime error occurs, the response will include a message describing the error.

Using In React

Here is a quick guide on using StaticKit functions in your React components.