Start typing to search...


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.

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.


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

npm install @withkoji/core


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.

Core package versioning utility

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.


Import the package in your frontend code.

import Koji from '@withkoji/core';

Initialize the package with your configuration data.

// Initialize

// render

Indicate that the application is ready to start receiving events.


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


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

// Use express json

// Parse application/json

// Use Koji's middleware to handle scoping across your app's customized versions

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

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


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