Core Library

The StaticKit core library powers the environment-specific client libraries (HTML and React). If you are a library author or you are implementing your own low-level components that need to communicate with StaticKit, this might be the library for you.

Source on GitHub | npm package

Installation

Run the following to install the package:

npm install @statickit/core

Then, import the StaticKit constructor in your code:

import StaticKit from '@statickit/core';

// Constructs an instance of the client
const statickit = StaticKit();

The client listens for signals to sniff out bots and spammers, so it's best to instantiate the client upon page load and reuse it over the course of the browsing session.

Methods

submitForm(props)

An method that submits form data to the server and returns a Promise.

This method accepts the following properties:

The return value resolves to object containing a body field and a response field:

client.submitForm({ 
  id: formId, 
  data: formData
}).
  then(({ body, response }) => {
    switch (response.status) {
      case 200:
        // Submission succeeded
      
      case 422:
        // Validation errors occurred
      
      default:
        // Something unexpected happened
    }
  });

When the submission succeeds, the body will include a submission id and data:

{
  "id": "3ac1fb5d-259a-4af5-aac5-2ce53215b6c5",
  "data": {
    "email": "[email protected]"
  }
}

If there are validation errors, the body will include an array of errors:

{
  "errors": [{
    "code": "REQUIRED",
    "field": "email",
    "message": "is required"
  }]
}

Here's an example of submitting the data from a <form> node to StaticKit and awaiting the response:

import StaticKit from '@statickit/core';

// Instantiate the client
const client = StaticKit();

// Fetch the form element and its form data
const form = document.getElementById('my-form');
const formData = new FormData(form);

// Submit the data to StaticKit
const { body, response } = await client.submitForm({
  id: 'f7h7sfg08jff',
  data: formData
});

teardown()

This method cleans up resources used by the client.

For example, if you are instantiating the client in a React component, you should tear it down when the component unmounts:

import React, { useEffect, useRef } from 'react';

function MyForm() {
  const client = useRef(undefined);

  useEffect(() => {
    client.current = StaticKit();

    return () => {
      if (client.current) {
        client.current.teardown();
      }
    }
  }, []);

  // ...
}

SSR Support

Server-side rendering (SSR) is a technique used by static site generators like Next.js to improve site performance. Since the StaticKit client tracks behavior from the browser environment, the DOM must be available when the StaticKit() call happens.

For example, you cannot instantiate the client in the main body of a function React component:

import React from 'react';

function MyForm() {
  // This will throw an error at compile time
  const client = StaticKit();

  // ...

  return (
    <form>...</form>
  );
}

Instead, you must instantiate the client when the component is being mounted (such as componentWillMount or the useEffect hook) and store it in component state.

- import React from 'react';
+ import React, { useEffect, useRef } from 'react';

  function MyForm() {
-   const client = StaticKit();
+   const client = useRef(undefined);
+
+   useEffect(() => {
+     client.current = StaticKit();
+
+     return () => {
+       if (client.current) {
+         client.current.teardown();
+       }
+     }
+   }, []);

    // ...