npm install @withkoji/coreThe Koji platform is designed for developers like you to build and distribute customizable web apps for content creators. On Koji, creators can discover your apps, add them to their Link in Bio profiles, and share them on social media. As more creators use your Koji apps, you can make more revenue, reach more users, and build your business.
The following steps describe the general process for developing a customizable app on Koji and distributing it to content creators.
With the Koji platform, you don’t have to start from nothing. Instead, you can build on an existing project that already implements most of what you need, so that you can focus on what makes your app unique. For example, you might start from a developer scaffold that implements your favorite JavaScript framework, or from an app that already uses some desired functionality, such as a backend database.
To create a new project, fork an existing app.
In the App Store, find your desired starting app and click View.
|
Tip
|
To explore the source code for an app before forking it, click . If this option is not available, the app is not forkable. |
In the app’s detail page, click .
A copy of the project is created in your Koji account.
Decide how you want to edit your code.
Online – The Koji code editor is a browser-based integrated development environment (IDE) with built-in development, administration, and testing tools for Koji apps.
Learn more: editor.html
Locally – The Koji platform supports working locally in your preferred suite of development tools.
Learn more: local-development.html
At their core, Koji apps are full-stack, modern JavaScript applications. They are designed for in-app browsers, so that they are instantly available on all social platforms and on every device.
The @withkoji/core package enables apps to use core features of the Koji platform, so you can build any type of web application and enable creators to customize it.
In your application code, you must initialize the @withkoji/core package with the configuration data that the Koji platform needs to build, deploy, and run your app.
To define this data, most Koji projects include a koji.json file at the root of the project directory.
Define the instructions for building your code and deploying your app on the Koji platform.
Learn more: develop key, deploy key
If the app has customization options for creators, define the default values for those options and any placeholder values for new customized versions.
Learn more: remixData key, @@initialTransform key
Configure the entitlements for the Koji platform features in your app.
Learn more: entitlements.html
Follow these steps to use the @withkoji/core package in the frontend of your app.
|
Tip
|
Before you start developing your code, check for outdated dependencies in the forked app.
|
In your frontend directory, install or update the @withkoji/core package.
npm install @withkoji/coreIn your frontend code, import the package.
import Koji from '@withkoji/core';Use the Koji.config function to initialize the package with your app’s configuration data before any data in the application is rendered.
For example:
// Initialize
Koji.config(require('././koji.json'));
// render
render();Use the Koji.ready function to indicate that the application is ready to start receiving events.
Implement the desired core functionality. For example, you can provide customization options so creators can add their own content and branding to the app before adding it to their profiles.
If your app has a backend service, follow these steps to use the @withkoji/core package in it.
In your backend directory, install or update the @withkoji/core package.
npm install @withkoji/coreIn your backend code, import the package and your app’s configuration data.
import { KojiBackend } from '@withkoji/core';
import kojiConfig from '../../koji.json';|
Tip
|
To initialize the core package in your backend, the koji.json file must be bundled with the backend service during deployment of your app.
Many development frameworks won’t bundle this file by default because it is not in the same folder as the backend code.
To solve this problem, you can use a tool such as babel-plugin-inline-json-import to ensure the configuration data is available to your backend service.
|
Use KojiBackend.middleware to initialize the package with your app’s configuration data.
The middleware manages the scope for backend functionality, so that your code can support your initial app along with all of the custom 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.
For example, here is an implementation with a traditional Express application.
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');
});Implement the desired core functionality. For example, you can implement a Koji database to collect information in the app.
Learn more: core-backend-overview.html, add-service.html, koji-database.html
When you’re finished developing your app, you can deploy it to the Koji platform. Deployed apps are accessible at a permanent production URL.
Deploy your app from your development environment.
If you’re working in the Koji code editor, you can publish your app from there.
Learn more: Publishing your Koji app
If you’re working outside the editor, you must push your changes to your project’s origin repository.
Learn more: publish-locally-developed.html
After you publish the app, the Koji profiler checks for errors, generates metadata about it, and, if it is error-free, enables the platform entitlements.
To verify that your latest build was deployed, go to your developer portal and select the app. Then, click View Version History.
Learn more: Viewing version history
|
Tip
|
If you update your app and deploy it again, the new version of the app replaces the existing version at the production URL. |
The Koji platform provides a variety of tools for testing and debugging apps.
If you’re working in the Koji code editor, you can preview your app in different modes and on different devices.
If you’re working outside the editor, you can use your browser to verify the basic functionality. Then, you can point the Koji debugger to your localhost so that you can test all app functionality.
After you develop, deploy, and test your app, you can share it in any of these ways:
Share a direct link with specific people. This option lets your collaborators and customers use your app without allowing the general public to discover it on the Koji platform. It is useful for limited releases or testing.
To get the production URL of your app, go to your developer portal and select the app. Then, click View Published Koji, and copy the URL.
List it in the Koji App Store. This option reaches Koji’s global audience of content creators and lets them customize and add your app to their profiles. You can add marketing assets and documentation to attract more users to your app. You can also monetize it by setting a price for creators to use your app or by setting a transaction fee for in-app purchases.
Learn more: app-store.html
|
Tip
|
If you want to allow other developers to fork your app as their own starting point, be sure to select This template is open source in your app listing. |