cardkit

CardKit

A simple, powerful and fully configurable image editor for web browers and servers. Optional UI included.

CardKit has three main parts:

• CardKit: The core library, that manages and maintains the configuration object which defines the structure and options of a card
• CardKitDOM: A DOM renderer, that takes an instance of CardKit and renders either a standalone image, or a pre-packaged UI for editing the image
• CardKitServer: A server renderer, that allows you to take an instance of CardKit and render it into an image on a Node.js server

Additionally, a base class allows you to create your own renderers. See more in the Custom Renderers section.

Installation

$ npm install cardkit --save

Usage

CardKit requires a configuration object in order to render an image. Each renderer (CardKitDOM and CardKitServer) uses this configuration and converts it into an output. Below are simple implementations for CardKit depending on your use case.

In addition to these, you may also want to try the CardKit Yeoman Generator, which can help you scaffold an entire project in just a few moments. It brings with it the latest version of CardKit, a recommended directory structure, and a build process that helps you get your CardKit project deployed. There is also a JSFiddle that you can fork and edit for quick in-browser testing without touching the command line.

Previous versions

For version 1, see the v1-main branch.

For version 2, see the v2-main branch.

Yeoman generator

$ npm install -g yo generator-cardkit
$ yo cardkit

Browser with Webpack / Browserify usage

…

Browser with `

#### Server usage

```js
// Require CardKit and CardKitServer
const CardKit = require("cardkit");
const CardKitServer = require("cardkit/server");

// Base configuration object - see `./examples/configurations` for examples
const configuration = {};

// Initialise CardKit
const cardkit = new CardKit(configuration);

// Initialise Renderer
var renderer = new CardKitServer(cardkit);

// Render to image
renderer
  .renderToImage(2)
  .then((image) => {
    // Do what you want with the image here...
    console.log('');
    process.exit();
  })
  .catch((e) => {
    console.log("[ERR]", e);
    process.exit();
  });

…

js
class CardKitCanvas extends CardKitRenderer {
  renderCard() {
    // Canvas-specific code here
  }

  rerender() {
    // A method that `CardKit` calls if the base configuration object is updated
    // Handle an update to the base configuration, e.g. you may want to re-render the canvas element here
  }

  yourCustomMethod() {
    // You can implement any custom methods here, for example you may wish to expose or manipulate the  element for other users to take advantage of
  }
}

const cardkit = new CardKit(configuration);

const renderer = new CardKitCanvas(cardkit);

renderer.yourCustomMethod();

Custom Fonts

CardKit allows you to load in custom fonts for use on your cards, see the Wiki for details. These need to be encoded into base64 format.

If you wish to use a Google font, you can use the googlefontcss64 library to generate a base64 version of any Google font. You can use this Node.js script to get all the details you need.

Once you have the base64 encoded version of your font, you can register it in your configuration object, like so:

var configuration = {
  // ...
  fonts: {
    MyCustomFontName: base64encodedFont,
  },
  layers: {
    text: {
      fontFamily: "MyCustomFontName",
    },
  },
  // ...
};

If you need to provide a specific format for your font, you can do the following:

var configuration = {
  // ...
  fonts: {
    MyCustomFontName: {
      src: base64encodedFont,
      format: "woff",
    },
  },
  layers: {
    text: {
      fontFamily: "MyCustomFontName",
    },
  },
  // ...
};

Running locally

CardKit currently requires Node.js 14, which you can install using nvm and running:

$ nvm use

To run a sample UI locally, run: $ npm start

You can optionally pass a port like so: $ npm start -- --port=8080

Tests

To trigger the test suite, run $ npm run test