@withkoji/core

The @withkoji/core package enables you to implement core platform features in your Koji app, including customization, in-app purchases, UI controls, messaging, and identity services.

Note	The @withkoji/core package replaces several deprecated packages. If your Koji app’s code uses any of the deprecated packages, see migrate-koji-core.html.

Available features

This package provides client-side methods for use on the frontend of your Koji app and server-side methods for use in the backend services of your app. For example:

Dynamically get and set customized values.
Capture user input and present dialog boxes.
Define distinct experiences for different users and views of your Koji app.
Manage authentication and authorization for users of your Koji app.
Send push notifications to authorized users.
Implement in-app purchase transactions in your Koji app.
Implement a Koji database for the backend of your Koji app.
Track custom analytics events in your Koji app.
Implement real-time communication between connected clients in your Koji app.

Installation

Install the package in the frontend and backend services of your Koji project.

npm install @withkoji/core

Updates

Before updating to a newer version of this package, run the following utility in the root of your Koji project to identify deprecated functionality and breaking changes in your code.

npx @arist0tl3/koji-core-project-scan -i node_modules dist

The utility will log any uses of deprecated functionality and provide a link to the relevant release documentation. The output will look something like this example.

For a comprehensive list of changes and versions, see the package release notes in Github.

Basic use

The @withkoji/core package provides a set of modules that are specific to client and server behaviors. For a reference of all available functionality in these modules, see the Frontend and Backend modules.

Frontend

Import the package in your frontend code.

import Koji from '@withkoji/core';

Initialize the package with your configuration data.

// Initialize
Koji.config(require('././koji.json'));

// render
render();

Indicate that the application is ready to start receiving events.

Koji.ready();

Enable the user to upload an image from the frontend of the Koji app.

import Koji from '@withkoji/core';

const captureImage = async () => {
  const imageURL = await Koji.ui.capture.image();

  console.log(imageURL); // The publicly accessible, CDN-backed path of the user's uploaded image
}

Backend

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');
});