Extending With Toolkit

Lucid provides a toolkit which allows you to programmatically call the client integration services within your application.

Custom Endpoint

When paired up with Fastify, you can create custom endpoints to better tailor Lucid to your needs. In the example bellow we are createing a custom endpoint to get a paginated list of documents that bellong to the page collection.

All services return errors as values giving you the flexibility to handle them as you see fit, however you can use the LucidAPIError class to throw them to Lucid which will handle the error appropriately and return a formatted error response to the client.

index.ts

import lucid, { toolkit } from "@lucidcms/core";
import { LucidAPIError, formatAPIResponse } from "@lucidcms/core/api";

lucid.fastify.get("/get-documents", async (request, reply) => {
  const PAGE = 1;
  const PER_PAGE = 10;

  const res = await toolkit.document.getMultiple({
    collectionKey: "page",
    query: {
      page: PAGE,
      perPage: PER_PAGE,
    },
  });
  if (res.error) throw new LucidAPIError(res.error);

  reply.send(
    formatAPIResponse(request, {
      data: res.data.data,
      pagination: {
        count: res.data.count,
        page: PAGE,
        perPage: PER_PAGE,
      },
    })
  );
});

lucid.start();

Toolkit Services

Currently the toolkit only supports a handful of services, but none the less, this is still a very powerful feature.

Here is the list of what is currently supported:

Documents

index.ts

const { error, data } = await toolkit.document.getSingle({
  collectionKey: "page",
  query: {
    filter: {
      fullSlug: {
        value: "/about",
      },
    },
  },
});

In this example, the fullSlug filter would be a custom field that has been added to the page collection.

index.ts

const { error, data } = await toolkit.document.getMultiple({
  collectionKey: "page",
  query: {
    filter: {
      documentId: {
        value: [1, 2, 3],
        operator: "in", // optional, defaults to '=', then 'in' if the value is an array
      },
    },
    page: 1,
    perPage: 10,
  },
});

All available document column filters are prefixed with document as to hopefully not conflict with the custom field keys.

Locales

index.ts

const { error, data } = await toolkit.locale.getAll();

Returns all locales that have been configured in your lucid.config.ts file.

Email

index.ts

const { error, data } = await toolkit.email.sendEmail({
  to: "[email protected]",
  subject: "Hello",
  template: "password-reset",
  data: {
    firstName: "William",
  },
});

You can use first party templates, though more likley you will want to use a custom template which you can do by adding a mjml file in a templates directory at the root of your project. Learn more about mjml here.