@withkoji/core Backend

Exposes the KojiBackend variable, which provides server-side methods for use on the backend of your Koji app.

Note	All methods in the backend module are scoped for use only in backend services of Koji apps. If a method is invoked in a frontend environment, it returns an error message. All backend modules follow the same constructor pattern.

Basic use

To use backend methods, install the @withkoji/core package in the backend of your project.

Import the package in your backend code.

import { KojiBackend } from '@withkoji/core';

Initialize the package with your configuration data, and use KojiBackend.middleware to scope operations for each customized version of the app. Add routes for backend operations (for example, use a Koji database).

import { KojiBackend } from '@withkoji/core';
import cors from 'cors';
import express from 'express';
import bodyParser from 'body-parser';

// Import our configuration
import kojiConfig from '../../koji.json';

// Init
const app = express();

// Enable cors for preflight
app.options('*', cors());

// Whitelist all routes with cors
app.use(cors());

// Use express json
app.use(express.json());

// Parse application/json
app.use(bodyParser.json());

// Use Koji's middleware to handle scoping across your app's customized versions
app.use(KojiBackend.middleware(kojiConfig));

// Disable caching
app.use((req, res, next) => {
  res.header('Cache-Control', 'private, no-cache, no-store, must-revalidate');
  res.header('Expires', '-1');
  res.header('Pragma', 'no-cache');
  next();
});

// Add routes here - for example:
app.get('/data', (req, res, next) => {
  const database = new KojiBackend.Database({ res });

  // Look up an item in the items collection
  const item = await database.get('items', 'myItemId');

  res.status(200).json({
    item,
  });
});

// Start server
app.listen(process.env.PORT || 3333, null, async (err) => {
  if (err) {
    console.log(err.message);
  }
  console.log('[koji] backend started');
});

Types

Database

Database, Class that implements a Koji database on the backend of your Koji app.

Dispatch

Dispatch, Class that implements a dispatch system for real-time communication on the backend of your Koji app.

IAP

IAP, Class that manages in-app purchases on the backend of your Koji app.

Identity

Identity, Class that manages authentication and authorization on the backend of your Koji app.

Secret

Secret, Class that handles sensitive data used in your Koji app.

Utilities

Utilities, Class that provides utility methods for improving the performance and functionality of your Koji app.

middleware

Executes an Express middleware, making Koji-specific data available on the res.locals property.

The middleware manages the scope for backend functionality, so that your code can support your initial Koji app along with all of its customized versions. It works by parsing the request headers that the Koji platform uses to pass version-specific data to the backend.

You must apply this middleware before handling any routes. The middleware will transform res.locals, and then modules in KojiBackend will accept res as a configuration parameter.

Parameters

kojiConfig – KojiConfig, (Optional) Configuration data for the Koji app.

Example

const app = express();
app.use(Koji.middleware(require('koji.json')));

app.get('/data', (req, res, next) => {
  // Backend constructor
  const database = new KojiBackend.Database({ res });
  ...
});

Interfaces

KojiConfig

Configuration data for the Koji.

Properties

@@initialTransform – Any, (Optional) Placeholder values for new customized versions.
deploy – Any, (Optional) Instructions for deploying the services to production.
develop – Any, (Optional) Instructions for setting up the services in a development/editor environment.
metadata – KojiMetadata, (Optional) Metadata about the project and creator.
remixData – Any, (Optional) Default values for the configuration data.

KojiMetadata

Metadata about the project and creator. This information is provided by the platform but can be overridden when the Koji is initialized.

Properties

projectId – String, Unique identifier for the Koji.
creatorUsername – String, Creator’s username.
creatorProfilePicture – String, URL reference to the creator’s current profile picture.